Importer vos appareils Elark dans Home Assistant

1. Comment ça marche ?

Home Assistant supporte un standard ouvert appelé MQTT Discovery : lorsqu’un message JSON est publié sur un topic homeassistant/<component>/<node>/<object>/config, HA crée automatiquement l’entité correspondante avec sonstate_topic, son command_topic, et tous les attributs nécessaires (unités, classes…).

Elark expose deux endpoints pour générer ces messages à partir de votre workspace, sans coupler les deux plateformes : Elark reste maître de vos appareils, HA n’agit que comme observateur/écouteur sur le broker MQTT.

• GET /workspaces/<id>/ha-discovery-export — retourne un JSON listant les topics et payloads à publier. Idéal pour les utilisateurs avancés qui veulent copier-coller dans leur propre outil.
• POST /workspaces/<id>/ha-discovery-publish — publie directement chaque message sur le broker MQTT Elark avec retain=true (comme l’exige HA), sans que vous ayez à manipuler un client MQTT.

2. Prérequis

• Une instance Home Assistant avec l’intégration MQTT installée et connectée au même broker que celui qu’utilise Elark (broker Mosquitto Elark sur mqtt.elark.cloud:8883 en TLS, ou votre broker local si vous self-hostez).
• Un compte HA avec des identifiants MQTT autorisés à souscrire au préfixe homeassistant/# (par défaut, HA souscrit automatiquement à ce préfixe).
• Sur Elark : un workspace dont vous êtes au moins technicien (rôle ≥ technician). La publication directe nécessite le rôle administrateur.

3. Méthode 1 — Publication automatique (recommandée)

1. Ouvrez votre dashboard Elark, sélectionnez le workspace contenant les appareils à exporter via le sélecteur en haut à droite.
2. Direction Paramètres › Intégrations › Home Assistant.
3. Cliquez sur Publier vers Home Assistant. Elark publie un message retained par entité Elark : dans la seconde, vos appareils apparaissent dans HA sous Paramètres › Appareils et services › Découvert.
4. Acceptez chaque appareil dans HA pour le déplacer dans une aire (pièce). L’association est définitive : si vous renommez un appareil dans Elark, l’unique_idreste le même et HA met à jour le nom au prochain export.

Chaque publication est tracée dans le journal d’audit du workspace (WorkspaceAuditLog, action ha_discovery_published) — vous pouvez auditer qui a déclenché un export et quand.

4. Méthode 2 — Export JSON pour copy-paste

Si vous préférez contrôler manuellement ce qui atterrit dans HA (par exemple parce que vous avez plusieurs instances ou que vous n’utilisez pas le broker Elark), utilisez l’endpoint GET :

curl -H "Authorization: Bearer $ELARK_JWT" \
     https://api.elark.cloud/workspaces/$WS_ID/ha-discovery-export

La réponse a la forme :

{
  "workspace_id": "...",
  "count": 12,
  "devices": [
    {
      "topic": "homeassistant/switch/salon_prise/relay_1/config",
      "payload": {
        "name": "relay_1",
        "state_topic": "t/<ws>/d/salon-prise/switch/relay_1/state",
        "command_topic": "t/<ws>/d/salon-prise/switch/relay_1/command",
        "unique_id": "elark_<device_id>_<entity_id>",
        "device": {"identifiers": ["elark_<device_id>"], "manufacturer": "Elark", ...}
      }
    },
    ...
  ]
}

Vous pouvez ensuite publier chaque entrée avec votre client MQTT favori (mosquitto_pub, MQTT Explorer, script Node-RED…) : n’oubliez pas le flag -r (retain) sinon HA oubliera les configurations au redémarrage.

5. Types d’entités supportés

6. Limitations et bonnes pratiques

• L’identifiant unique(unique_id) est stable et basé sur l’UUID interne du device + de l’entité. Si vous régénérez le claim_code d’un appareil, son unique_id ne change pas — HA ne crée pas de doublons.
• Elark reste la source de vérité. Toute modification dans HA (changement de nom, classification d’une aire…) reste locale à HA. Pour qu’Elark sache que l’appareil bouge, modifiez-le côté Elark puis republiez.
• Pour retirer un appareil de HA, publiez un message vide et retained sur son topic discovery (cf. doc HA). Un endpoint unpublish Elark arrivera dans une prochaine version.
• La publication n’expose pas votre broker à HA : ce dernier doit déjà avoir accès au même broker MQTT pour souscrire aux topics scopés t/<workspace>/d/<device>/…. Si vous utilisez le broker hébergé Elark, créez d’abord un compte MQTT dédié pour HA depuis Paramètres › Broker MQTT › Tiers.

7. Dépannage

• Mes appareils n’apparaissent pas dans HA : vérifiez dans Paramètres › Logs MQTT que HA reçoit bien des messages sur homeassistant/+/+/+/config. Si non, le client HA n’est pas connecté au même broker qu’Elark.
• Erreur 404 sur l’endpoint : vous n’êtes pas membre du workspace ou votre rôle est inférieur à technicien. Demandez à un administrateur du workspace de vous inviter.
• HA crée des doublons après une régénération firmware : ne devrait jamais arriver — les unique_id sont stables. Si c’est le cas, ouvrez un ticket support.