diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d42fd25 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +## [0.1.0] - 2026-07-21 + +### Added + +- Configuration depuis l’interface Home Assistant. +- Connexion locale au proxy Arkteos sur le port 9641. +- Client TCP asynchrone strictement en lecture seule. +- Extraction incrémentale des trames. +- Prise en charge des trames metadata, frigo et regulation. +- Capteur de connectivité. +- Capteurs natifs Home Assistant. +- Diagnostics avec masquage de l’hôte. +- Prise en charge de la reconfiguration. +- Tests hors ligne avec fixtures réelles. +- Préparation HACS. + +### Known limitations + +- Protocole non officiellement documenté. +- Absence de checksum démontré. +- Aucune commande ou écriture vers la PAC. +- Compatibilité réelle encore à valider en parallèle de Node-RED. diff --git a/README.md b/README.md index 63060e9..5de32f7 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,108 @@ -# Arkteos +# Arkteos pour Home Assistant -Intégration custom Home Assistant en lecture seule pour une PAC Arkteos Zuran -4. Elle expose les données décodées du protocole REG3 par des entités natives -Home Assistant. +## Présentation -L’intégration se connecte exclusivement au proxy Arkteos fourni par l’addon -Home Assistant séparé. Elle ne se connecte jamais directement à la PAC et -n’envoie aucune commande. Le port du proxy est configurable ; sa valeur par -défaut est `9641`. +Arkteos est une intégration Home Assistant personnalisée pour une PAC Arkteos +Zuran 4. Elle lit localement les données du proxy Arkteos, selon un protocole +REG3 observé à partir de captures réelles et du flow Node-RED de référence. + +L’intégration est strictement en lecture seule : elle n’envoie aucune commande +à la PAC et ne contacte jamais directement celle-ci. Elle ne dépend ni de MQTT, +ni de Node-RED une fois la migration terminée. + +## État du projet + +- Version actuelle : `0.1.0`. +- Statut : expérimental. +- Testée avec les captures d’une Arkteos Zuran 4. +- Le protocole n’est pas officiellement documenté. +- Conserve Node-RED en parallèle pendant la validation sur l’installation + réelle. + +## Prérequis + +- Home Assistant. +- HACS pour l’installation recommandée. +- Un proxy Arkteos accessible sur le réseau. +- Le port par défaut du proxy est `9641`. +- La PAC ne doit pas être contactée directement. +- Le proxy conserve la connexion unique vers la PAC et accepte les clients. ## Installation avec HACS -1. Dans HACS, ouvre **Intégrations** puis le menu à trois points. -2. Choisis **Dépôts personnalisés**. -3. Ajoute `https://gitea.i-host.fr/raph666/home-assistant-arkteos` avec la - catégorie **Intégration**. -4. Installe **Arkteos**. -5. Redémarre Home Assistant. -6. Ajoute l’intégration dans **Paramètres > Appareils et services**. +1. Ouvre HACS. +2. Va dans **Intégrations**. +3. Ouvre le menu **Dépôts personnalisés**. +4. Ajoute l’URL du miroir GitHub : + `https://github.com/raph666/home-assistant-arkteos`. +5. Choisis la catégorie **Intégration**. +6. Installe **Arkteos**. +7. Redémarre Home Assistant. +8. Va dans **Paramètres > Appareils et services**. +9. Ajoute **Arkteos**. +10. Saisis l’hôte du proxy et le port `9641`. -Le proxy Arkteos doit être disponible avant la configuration de l’intégration. +Le miroir GitHub sert à l’installation HACS. -## Migration et validation +## Configuration -Conserve temporairement le flow Node-RED existant pendant la comparaison des -valeurs publiées. Il reste la référence fonctionnelle actuelle des champs -décodés. +La configuration demande l’hôte et le port du proxy. Elle est validée par une +connexion au proxy et la réception d’une trame valide. La reconfiguration est +possible depuis Home Assistant. -Le protocole REG3 est observé depuis des captures et le flow Node-RED de -référence ; aucune documentation officielle complète du protocole n’est -actuellement disponible. Les champs et les règles de découpage sont limités à -ce qui est démontré par ces références. +## Entités exposées + +L’intégration expose des entités natives Home Assistant pour : + +- la connectivité ; +- le groupe frigorifique ; +- la régulation ; +- le circuit primaire ; +- l’eau chaude sanitaire ; +- les statuts et diagnostics. + +Certaines entités de diagnostic sont désactivées par défaut. + +## Diagnostics + +Les diagnostics sont téléchargeables depuis Home Assistant. L’hôte est masqué +et aucune trame brute, socket ou donnée interne sensible n’est exposée. + +## Validation parallèle avec Node-RED + +Le flow Node-RED doit rester actif au début. Compare les anciennes entités MQTT +avec les nouvelles entités natives, puis retire Node-RED uniquement après une +validation des valeurs en conditions réelles. + +## Limites connues + +- Le protocole est déduit de captures. +- Aucun checksum n’est démontré. +- Seules les trames observées de 95, 163 et 227 octets sont reconnues. +- L’intégration est en lecture seule et ne permet aucune commande de pilotage. +- La compatibilité est confirmée uniquement avec la configuration testée. +- Arkteos ne fournit aucun support officiel pour cette intégration. ## Développement -- `references/arkteos_nodered_flow.json` : flow Node-RED de référence. -- `references/proxy_protocol_notes.md` : contexte connu sur le proxy. -- `tests/fixtures/` : trames réelles anonymisées utilisées par les tests. +```bash +python3 -m venv .venv +source .venv/bin/activate +python3 -m pip install -r requirements_test.txt +python3 -m pytest -v +python3 -m compileall custom_components/arkteos +``` -Les captures privées et les informations de connexion ne doivent pas être -versionnées. +## Licence + +MIT — Copyright (c) 2026 Raph666 + +## Support + +Tant que le dépôt principal reste sur Gitea, utilise ces URLs pour le code et +les tickets : + +- Dépôt : https://gitea.i-host.fr/raph666/home-assistant-arkteos +- Tickets : https://gitea.i-host.fr/raph666/home-assistant-arkteos/issues + +Le miroir GitHub sert à l’installation HACS.