arkteos-proxy-addon/README.md

Arkteos Proxy — Home Assistant Addon

Proxy TCP pour PAC Arkteos REG3 (Zuran 4, Baguio 4, etc.). Il maintient une connexion unique vers la PAC et partage son flux avec plusieurs clients TCP locaux. Les écritures client sont désactivées par défaut.

Installation

1. Dans Home Assistant : Paramètres → Modules complémentaires → trois points → Dépôts
2. Ajoute l'URL de ce repo : https://github.com/raph666/arkteos-proxy-addon
3. Installe l'addon Arkteos Proxy
4. Configure l'IP de ta PAC dans les options
5. Configure le port exposé dans la section Network (défaut : 9641) et clique Save
6. Démarre l'addon

Configuration

Option	Description	Défaut
pac_host	Adresse IP de la PAC	192.168.X.X
pac_port	Port TCP de la PAC	9641
proxy_port	Port d'écoute interne du proxy	9641
allow_client_writes	Autorise le relais des données clients vers la PAC	false

Fonctionnement du proxy

Le proxy se connecte à la PAC avec pac_host et pac_port. Il écoute les clients TCP sur toutes les interfaces réseau, avec proxy_port.

Les données reçues de la PAC sont distribuées à tous les clients connectés. Par défaut, les données reçues d’un client sont ignorées : le client reste connecté et peut continuer à recevoir le flux de la PAC.

Active allow_client_writes uniquement si un client de confiance doit écrire vers la PAC. Dans ce mode bidirectionnel, les données client sont relayées telles quelles, sans filtrage ni validation ; les écritures vers la PAC sont sérialisées.

Un keepalive composé d’un octet nul est envoyé toutes les 300 secondes à la PAC afin de maintenir la connexion. Le code n’établit pas le rôle exact de cet octet pour la PAC.

Robustesse de la connexion

L’établissement de la connexion vers la PAC est limité dans le temps. Le proxy se reconnecte automatiquement après une coupure ou lorsqu’aucun octet n’est reçu de la PAC pendant une période prolongée, même si la socket reste ouverte.

Lors d’un arrêt, d’une mise à jour ou d’un redémarrage de l’add-on, le proxy arrête les reconnexions et ferme proprement le serveur, les clients et la connexion PAC. Ces mécanismes ne garantissent pas la disponibilité de la PAC ou du réseau.

Clients TCP

Les clients TCP utilisent le port du proxy pour recevoir le flux binaire de la PAC. Aucun client particulier n’est requis pour le fonctionnement de l’add-on.

Sécurité réseau

Ne pas exposer le port du proxy sur Internet. Limite l’accès au réseau local ou à des clients de confiance : lorsque allow_client_writes est activée, un client qui accède au proxy peut potentiellement transmettre des données à la PAC.

Le proxy ne met en œuvre ni authentification, ni filtrage protocolaire, ni contrôle d’accès. Il ne doit donc pas être considéré comme une barrière de contrôle d’accès, particulièrement en mode bidirectionnel.

Protocole

La PAC Arkteos REG3 expose un flux binaire TCP (serial-over-IP) sur le port 9641 (IHM). Trois types de trames sont émises en continu à environ 1 trame/seconde :

Taille	Type	Contenu
163 bytes	Frigo	Données groupe frigorifique Mitsubishi
227 bytes	Régulation	Données régulation, températures, ECS
95 bytes	Réseau	Métadonnées de connexion (IP PAC, etc.)

Toutes les trames commencent par le magic bytes 0x55 0x00.