Ajouter un nouvel appareil

Comment ça marche en réalité ?

Chaque appareil est identifié par un claim_code public (format elark-XXXX-XXXX). C’est lui qui sert d’identifiant MQTT et qui rattache l’ESP à votre compte. Le claim_code est généré par le serveur au moment où vous créez la fiche de l’appareil dans l’app — vous ne le saisissez jamais à la main.

Une fois ce code injecté dans le firmware (champ mqtt_user du secrets.yaml), l’ESP se connecte au broker MQTT Elark avec ce code comme identité, et la fiche bascule automatiquement « en ligne » dans l’app. Pas de pairing manuel, pas de scan : le rattachement est implicite.

Un browser ne peut pas faire de découverte mDNS (l’API n’existe pas en Web). Et même sur l’app mobile, un scan ne donnerait qu’une IP — pas le claim_code. La création se fait donc toujours côté serveur en premier.

Méthode A — Tout-en-un depuis le Marketplace (recommandée)

C’est la méthode la plus simple pour un ESP neuf ou non flashé. L’app s’occupe de tout : création de la fiche, injection du claim_code dans le firmware, et téléchargement d’un bundle prêt à flasher.

1. Ouvrez Marketplace et choisissez le modèle (volet roulant, prise connectée, sonde DS18B20, etc.).
2. Cliquez sur « Configurer ». Renseignez le nom de l’appareil et les variables techniques (GPIO, temps de course…). Le SSID Wi-Fi est pré-rempli depuis vos identifiants par défaut, vous pouvez le modifier ponctuellement si besoin.
3. Les credentials MQTT sont gérés automatiquement par la plateforme : le broker (mqtt.elark.cloud), l’identifiant (le claim_code du device) et le mot de passe (généré à la création de la fiche) sont injectés au backend dans le secrets.yaml. Vous n’avez aucun champ MQTT à saisir.
4. Cliquez sur « Télécharger le bundle ZIP ». Vous recevez 4 fichiers : main.yaml, secrets.yaml (déjà rempli), base.yaml et README.txt.
5. Dézippez puis flashez :

   pip install esphome
   esphome run main.yaml

   ou utilisez la web tool officielle web.esphome.io.
6. Au démarrage, l’ESP rejoint votre WiFi puis publie sur le broker Elark. La fiche bascule « en ligne » en moins de 30 secondes.

Méthode B — Vous avez déjà un firmware ESPHome personnalisé

Si vous écrivez votre propre YAML ESPHome (configuration sur mesure, carte exotique, modèle non couvert par le Marketplace), créez d’abord la fiche dans l’app pour obtenir le claim_code, puis injectez-le dans votre secrets.yaml.

1. Dans l’app, Mes appareils › + Ajouter.
2. Saisissez un nom (ex. « Volet salon »). Validez.
3. La modale affiche le claim_code. Cliquez sur « Copier ».
4. Dans votre secrets.yaml, mettez :

   mqtt_broker: "mqtt.elark.cloud"
   mqtt_port: 8883
   mqtt_user: "elark-XXXX-XXXX"   # le claim_code collé ici
   mqtt_password: "<votre mot de passe MQTT>"
   wifi_ssid: "<votre SSID>"
   wifi_password: "<votre mot de passe Wi-Fi>"

5. Dans votre main.yaml ou équivalent, incluez la section MQTT standard :

   mqtt:
     broker: !secret mqtt_broker
     port: !secret mqtt_port
     username: !secret mqtt_user
     password: !secret mqtt_password
     ssl: true
     topic_prefix: devices/${device_id}

6. esphome run main.yaml. L’ESP se connecte et la fiche passe « en ligne ».

Vous pouvez aussi partir du base.yaml Elark (fourni dans chaque bundle Marketplace) qui contient déjà tous les blocswifi, mqtt, web_server, ota, api correctement configurés.

Méthode C — Ré-appairer un appareil existant

Si un ESP était rattaché à un autre compte (changement de propriétaire, revente), ou si vous l’avez flashé avec un firmware générique sans Elark dedans :

1. Créez une nouvelle fiche dans l’app (méthode B). Récupérez le claim_code.
2. Connectez-vous au web_server de l’ESP en local (http://<ip-esp>) avec votre login/mot de passe ESPHome.
3. Dans l’interface, remplacez les valeurs MQTT par celles d’Elark (broker mqtt.elark.cloud:8883, user = nouveau claim_code, password = votre mot de passe MQTT Elark). Sauvegardez.
4. L’ESP redémarre et se rattache au nouveau compte.

Choisir une pièce

Une fois l’appareil rattaché, attribuez-lui une pièce (Salon, Chambre, Garage…). Vous pouvez créer une nouvelle pièce depuis l’écran de l’appareil ou depuis Ma maison.

Cloud actif ou non ?

Par défaut, l’accès cloud est désactivé sur chaque nouvel appareil créé via le bundle Marketplace standard : l’ESP est joignable uniquement sur votre LAN (web_server ESPHome). C’est le comportement le plus respectueux de la vie privée.

Pour activer l’accès à distance, ouvrez l’appareil dans l’app et basculez l’interrupteur « Accès Cloud ». L’ESP commence alors à publier ses états sur le broker MQTT Elark et devient joignable depuis n’importe où.

Et la découverte mDNS dont parlent les autres docs ?

Le scan mDNS (_esphomelib._tcp) est prévu dans la future app mobile Flutter, mais uniquement pour accélérer la communication LAN d’appareils déjà rattachés : si un ESP a son IP locale qui change, l’app la retrouve via mDNS et passe en LAN prioritaire plutôt que via le cloud. Ce n’est jamais un mécanisme d’ajout — l’ajout se fait toujours par création de fiche + injection du claim_code dans le firmware.

Vérification finale

1. L’appareil apparaît dans Mes appareils avec une pastille verte « En ligne ».
2. Cliquez dessus → vous voyez la liste des entités (switch, sensor, light…).
3. Testez une commande (toggle d’un relais par exemple). La réponse doit être instantanée (< 1 s en LAN, < 3 s en cloud).

Supprimer un appareil

Pour retirer définitivement un appareil de votre compte, ouvrez sa fiche depuis Mes appareils puis cliquez sur le bouton « Supprimer cet appareil » dans la section « Zone dangereuse » de la colonne de droite. Une confirmation est demandée.

La suppression entraîne :

• la suppression du device et de toutes ses entités (relais, capteurs, lumières…) ;
• la suppression de l’historique et des sauvegardes liées ;
• la révocation des credentials MQTT du device — l’ESP physique ne pourra plus se connecter au broker.

L’ESP n’est pas effacé physiquement : il continue de tenter de se connecter avec ses anciens credentials mais sera systématiquement refusé par le broker. Pour le réutiliser ailleurs, re-flashez-le avec un nouveau bundle Elark (ou un autre firmware).

En cas de souci, consultez le guide de dépannage.