homebridge-tricom

Plugin Homebridge qui expose dans HomeKit les sorties d'une centrale domotique Tricom. Il s'agit d'une réécriture native (Node.js / TypeScript) du plugin Jeedom TricomPlugIn : la logique de dialogue avec la centrale est reprise telle quelle, mais l'interface Jeedom (PHP, base de données, widgets) est remplacée par le modèle d'accessoires HomeKit.

État du projet

Version 0.x : le plugin est publié tôt pour permettre les tests sur le terrain, et la forme de la configuration peut encore changer.

Vérifié contre une centrale TriCom réelle : le dialogue HTTP, la construction des URL, l'authentification par clé API, la détection des réponses d'erreur, et la lecture complète de l'état des sorties.

Pas encore vérifié sur du matériel : l'écriture d'une sortie (exoOutputValue), et la sémantique des valeurs — le 255 envoyé à l'allumage, la correspondance entre le pourcentage HomeKit et la valeur brute d'un variateur. Ces points sont repris tels quels du plugin Jeedom d'origine, faute d'avoir eu des modules EXO câblés à disposition. Si vous en avez, la sortie de tricom-probe --watch sur une issue est précisément ce qui manque pour les confirmer.

Comment ça marche

Le plugin Jeedom communiquait avec un serveur HTTP « jeedom » exposé par la Tricom via deux appels, que ce plugin reproduit à l'identique :

• Lecture de l'état de toutes les sorties : GET http://<ip>:<port>/jeedom/allExosOutputsValues?apikey=<clé> qui renvoie un JSON de la forme { "<adresseEXO>": { "<numéroSortie>": <valeur> } }.
• Écriture d'une sortie : GET http://<ip>:<port>/jeedom/exoOutputValue?exo=<adresseEXO>&output=<numéroSortie>&value=<valeur>&apikey=<clé>.

Chaque équipement du plugin Jeedom correspondait à une sortie d'un module « EXO », identifiée par une adresse EXO et un numéro de sortie. Ici, chaque sortie devient un accessoire HomeKit : un interrupteur (Switch), une lumière on/off (Lightbulb) ou un variateur (Lightbulb + luminosité).

Le plugin interroge la centrale à intervalle régulier (5 s par défaut) pour tenir HomeKit à jour, exactement comme le faisait le cron du plugin Jeedom.

Installation

npm install -g homebridge-tricom

Ou, depuis les sources :

npm install
npm run build

La clé API

La clé n'est pas générée par ce plugin : c'est un secret partagé que la centrale vérifie à chaque requête. Elle se saisit côté centrale, dans le logiciel de programmation TRINITY d'AnB-Rimex. Vous mettez ensuite la même valeur dans apikey.

Dans le montage d'origine, Jeedom générait sa propre clé (jeedom::getApiKey(), 64 caractères) et l'installateur la recopiait dans TRINITY. Sans Jeedom, c'est vous qui choisissez la valeur. Le champ de TRINITY a été limité à 50 caractères jusqu'à une mise à jour de janvier 2023 — en cas de doute, restez sur 50.

Quand la clé ne convient pas, la centrale répond HTTP 200 avec le corps ERROR 9001 — jamais un 401 ou un 403. Le plugin détecte ce cas et le signale explicitement dans le journal Homebridge ; le plugin Jeedom d'origine ne le testait pas, ce qui transformait une clé refusée en erreur PHP obscure dans sa boucle cron.

AnB-Rimex ne publie pas la table de ses codes ERROR. L'option --codes de tricom-probe compare les réponses de la centrale à plusieurs clés (absente, trop courte, fausse mais de bonne longueur…) ainsi qu'à un endpoint inconnu, puis en tire une conclusion :

npx tricom-probe --ip 192.168.1.50 --apikey VOTRE_CLE --codes

Ce mode ne fait que des lectures, rien n'est écrit sur la centrale.

Ce qu'on sait de ERROR 9001

Mesuré sur une centrale réelle : une clé absente, une clé de 4 caractères, et des clés fausses de 50 comme de 64 caractères donnent toutes le même ERROR 9001. La centrale ne distingue donc ni l'absence de clé ni sa longueur — le code veut simplement dire « clé non reconnue ». La seule correction est de programmer la bonne clé dans TRINITY.

Utile à savoir aussi : un endpoint inconnu (/jeedom/nimportequoi) renvoie la page d'accueil du serveur, <h1>Server start success if you see this message</h1>, sans vérifier la clé. C'est un test de vie du serveur HTTP qui ne demande aucune clé — si vous obtenez cette page, la centrale est joignable et son serveur tourne.

Trouver ses sorties avec tricom-probe

Le plugin ne peut pas découvrir les équipements tout seul : la centrale n'expose pas de liste, il faut déclarer chaque sortie à la main. L'outil tricom-probe, installé avec le plugin, sert à repérer quelle sortie correspond à quel équipement.

# État de toutes les sorties de la centrale
npx tricom-probe --ip 192.168.1.50 --apikey VOTRE_CLE

Centrale http://192.168.1.50:9000

  EXO  Sortie   Valeur  État
  ---  ------   ------  ----
    1       1        0  off
    1       2      255  ON
    2       1       40  ON

  3 sortie(s) sur 2 module(s) EXO.

La centrale expose tout son espace d'adressage — typiquement 16 modules EXO de 8 sorties, soit 128 lignes — qu'un équipement soit câblé ou non. Une lecture simple ne dit donc pas quelles sorties existent réellement. C'est le mode suivi qui répond à cette question.

Mode suivi — la méthode recommandée. Lancez-le, faites le tour de l'installation en actionnant vos équipements un par un, puis quittez par Ctrl+C : le bloc de configuration est construit à partir des seules sorties qui ont bougé.

npx tricom-probe --ip 192.168.1.50 --apikey VOTRE_CLE --watch

[14:32:07] EXO 1 sortie 2 : 0 → 255  (ON)
[14:32:11] EXO 2 sortie 1 : 0 → 40   (ON)
[14:32:14] EXO 2 sortie 1 : 40 → 80  (ON)
^C
3 sortie(s) ont bougé. Bloc à coller dans votre config.json, à renommer selon les pièces :

Les types sont déduits de ce qui a été observé, pas devinés : une sortie vue à deux états est un interrupteur, et son onValue est repris tel quel s'il ne vaut pas 255 ; une sortie vue à plusieurs niveaux est un variateur, dont l'échelle (maxValue 100 ou 255) se déduit des valeurs atteintes. Pour un variateur, balayez toute la plage : la configuration n'en sera que plus juste.

Bloc de configuration à partir d'une lecture simple — utile seulement si des équipements sont déjà allumés au moment du relevé, puisque les types sont alors devinés d'après une valeur unique.

npx tricom-probe --ip 192.168.1.50 --apikey VOTRE_CLE --config

Écrire une valeur — pour vérifier l'échelle d'un variateur sans passer par HomeKit :

npx tricom-probe --ip 192.168.1.50 --apikey VOTRE_CLE --set 2:1=128

Si la sortie s'allume à mi-puissance, l'échelle est 0–255 (maxValue: 255). Si elle est à fond, l'échelle est 0–100 (maxValue: 100).

Toutes les options : npx tricom-probe --help.

Configuration

Le plus simple est de passer par l'interface Homebridge Config UI X (le formulaire est fourni par config.schema.json). Sinon, ajoutez une plateforme dans votre config.json (voir aussi config.sample.json) :

{
  "platforms": [
    {
      "platform": "Tricom",
      "name": "Tricom",
      "ip": "192.168.1.50",
      "port": 9000,
      "apikey": "VOTRE_CLE_API",
      "pollInterval": 5,
      "timeout": 5,
      "accessories": [
        {
          "name": "Plafonnier salon",
          "type": "light",
          "exoAddress": 1,
          "outputNbr": 1
        },
        {
          "name": "Prise bureau",
          "type": "switch",
          "exoAddress": 1,
          "outputNbr": 2
        },
        {
          "name": "Éclairage cuisine",
          "type": "dimmer",
          "exoAddress": 2,
          "outputNbr": 1,
          "maxValue": 100
        }
      ]
    }
  ]
}

Paramètres de la plateforme

| Clé | Requis | Défaut | Description | | --- | --- | --- | --- | | ip | oui | 127.0.0.1 | Adresse IP de la centrale Tricom | | port | oui | 9000 | Port du serveur « jeedom » de la Tricom | | apikey | oui | — | Clé API attendue par le serveur (équivalent de jeedom::getApiKey()) | | pollInterval | non | 5 | Intervalle d'interrogation en secondes (min. 2) | | timeout | non | 5 | Timeout des requêtes HTTP en secondes | | accessories | oui | — | Liste des sorties à exposer |

Paramètres d'un accessoire

| Clé | Requis | Défaut | Description | | --- | --- | --- | --- | | name | oui | — | Nom affiché dans HomeKit | | type | oui | switch | switch, light ou dimmer | | exoAddress | oui | — | Adresse du module EXO | | outputNbr | oui | — | Numéro de la sortie sur ce module | | onValue | non | 255 | Valeur envoyée à l'allumage (interrupteur / lumière). Le template Jeedom utilisait 255. | | maxValue | non | 100 | Valeur correspondant à 100 % de luminosité (variateur) |

Note importante sur les valeurs

Dans le plugin Jeedom, l'allumage d'un interrupteur envoyait la valeur 255 et l'extinction 0 ; l'état était considéré « allumé » dès que la valeur lue était supérieure à 0. Ce comportement est repris tel quel.

Pour les variateurs, la correspondance entre le pourcentage de luminosité HomeKit (0–100 %) et la valeur brute envoyée à la Tricom dépend de votre matériel. Par défaut, maxValue vaut 100 (mapping direct 0–100). Si vos sorties de variation attendent une échelle 0–255, réglez maxValue à 255. Ajustez ce paramètre en observant les valeurs renvoyées par allExosOutputsValues.

Dépannage

| Symptôme | Piste | | --- | --- | | ERROR 9001 dans le journal, ou au lancement de tricom-probe | La centrale refuse la clé API. Vérifiez la valeur saisie dans TRINITY, et sa longueur (50 caractères si TRINITY n'est pas à jour). | | Les accessoires restent « Sans réponse » dans HomeKit | La centrale est injoignable ou la clé API est refusée. Vérifiez avec tricom-probe : il utilise exactement les mêmes appels que le plugin. | | Un accessoire ne réagit pas | Mauvais couple adresse EXO / numéro de sortie. Utilisez --watch et actionnez l'équipement pour retrouver le bon. | | Un variateur saute à 100 % dès qu'on le bouge | L'échelle ne correspond pas. Essayez maxValue: 255 (ou testez avec --set). | | Un interrupteur s'allume mais HomeKit le croit éteint | La centrale renvoie 0 pour cette sortie. Vérifiez la valeur lue avec tricom-probe. | | Journal muet | Activez le mode debug dans Homebridge : le plugin trace chaque écriture et chaque échec d'interrogation. |

Développement

npm install          # installe les dépendances
npm run build        # compile TypeScript -> dist/
npm run watch        # recompilation à la volée
npm run lint         # ESLint
npm test             # suite de tests (vitest)
npm run test:coverage  # tests + couverture
npm run check        # lint + build + tests, comme la CI

Les tests tournent contre un faux serveur Tricom et un HAP simulé : aucune centrale n'est nécessaire pour les lancer.

Contribuer

Les rapports de bug et les demandes de fonctionnalité passent par les issues GitHub. Joignez la sortie de tricom-probe : c'est ce qui permet de savoir ce que la centrale renvoie réellement.

Différences avec le plugin Jeedom

Ce qui a été repris : la couche de communication HTTP avec la centrale, le modèle adresse EXO + numéro de sortie, la sémantique des valeurs (255 / 0, état binaire, niveau de variation), et l'interrogation périodique de l'état.

Ce qui a été abandonné (spécifique à Jeedom, sans équivalent HomeKit) : l'interface web de configuration, la base de données et l'historique, les scénarios, le daemon socket demond.py (qui était un simple squelette de template), et toute la couche PHP côté serveur.

Licence

AGPL-3.0, comme le plugin Jeedom d'origine.