Skip to content

Troubleshooting

Jump to bottom
Deadbone edited this page Sep 29, 2026 · 8 revisions

Troubleshooting

English

No accessory appears

Check:

  • the platform is named SofaBatonX1S;
  • Homebridge restarted after configuration changes;
  • hubIp is configured when using automatic discovery;
  • discovery found activities, or manualActivities contains at least one fallback activity;
  • Homebridge logs do not show a configuration validation error.

The plugin intentionally does not publish empty activity accessories. If no activity can be discovered or configured, Homebridge can still publish the bridge, but Apple Home will not show SofaBaton activity switches behind it.

The accessory appears but the activity does not start

Check:

  • the X1S hub IP address is correct;
  • the X1S hub is powered and connected to Wi-Fi;
  • the activity works from the SofaBaton app;
  • the activity id is correct;
  • the Homebridge host can receive the X1S TCP callback;
  • no firewall blocks UDP to the hub or the local callback port.

Enable debugProtocol temporarily and restart Homebridge. If HomeKit does not follow changes made from the physical remote, confirm that the persistent TCP connection is established, that ACK_READY events are logged after activity changes, and that the follow-up activity synchronization returns activity rows.

The wrong activity starts

For automatically discovered activities, first make sure you are running the current stable homebridge-sofabaton-x1s package. Older prerelease builds before 0.1.0-alpha.8 could mismatch names and IDs when several catalog frames arrived together.

If the activity was manually configured, fix the id in manualActivities, restart Homebridge, then test again.

Accessories were recreated

HomeKit identity depends on:

  • hubId;
  • activity id;
  • accessory role.

Changing name is safe. Changing hubId or activity ids creates new accessories.

Docker issues

For the first validation, avoid Docker bridge networking. The X1S hub needs to connect back to Homebridge. If you must use Docker, use host networking or explicitly expose and route localListenPort.

Francais

Aucun accessoire n'apparait

Verifiez :

  • que la plateforme s'appelle SofaBatonX1S ;
  • que Homebridge a redemarre apres les changements de configuration ;
  • que hubIp est configure si vous utilisez la decouverte automatique ;
  • que la decouverte a trouve des activites, ou que manualActivities contient au moins une activite de secours ;
  • que les logs Homebridge n'affichent pas d'erreur de validation de configuration.

Le plugin ne publie volontairement pas d'accessoires d'activites vides. Si aucune activite n'est detectee ou configuree, Homebridge peut quand meme publier le pont, mais Apple Maison n'affichera pas d'interrupteurs SofaBaton derriere lui.

L'accessoire apparait mais l'activite ne demarre pas

Verifiez :

  • que l'adresse IP du hub X1S est correcte ;
  • que le hub X1S est alimente et connecte au Wi-Fi ;
  • que l'activite fonctionne depuis l'app SofaBaton ;
  • que l'identifiant d'activite est correct ;
  • que l'hote Homebridge peut recevoir le callback TCP du X1S ;
  • qu'aucun pare-feu ne bloque l'UDP vers le hub ou le port local de callback.

Activez temporairement debugProtocol puis redemarrez Homebridge. Si Maison ne suit pas les changements faits depuis la telecommande physique, verifiez que la connexion TCP persistante est etablie, que les evenements ACK_READY apparaissent apres les changements d'activite et que la synchronisation qui suit remonte des lignes d'activites.

La mauvaise activite demarre

Pour les activites detectees automatiquement, verifiez d'abord que vous utilisez le paquet stable courant homebridge-sofabaton-x1s. Les anciennes prereleases avant 0.1.0-alpha.8 pouvaient melanger les noms et les identifiants quand plusieurs trames de catalogue arrivaient ensemble.

Si l'activite est configuree manuellement, corrigez l'id dans manualActivities, redemarrez Homebridge, puis testez a nouveau.

Les accessoires ont ete recrees

L'identite HomeKit depend de :

  • hubId ;
  • l'identifiant d'activite ;
  • le role de l'accessoire.

Changer name est sans risque. Changer hubId ou les identifiants d'activites cree de nouveaux accessoires.

Problemes Docker

Pour la premiere validation, evitez le reseau bridge Docker. Le hub X1S doit pouvoir se reconnecter vers Homebridge. Si Docker est obligatoire, utilisez le mode host ou exposez et routez explicitement localListenPort.

Clone this wiki locally