Merge branch 'ha-mqtt-autodiscovery'

Fusion du README pour l'autodiscovery HA

README.md

@@ -156,21 +156,136 @@ python snmp2mqtt.py -c config.yaml
 
 ## Intégration Home Assistant
 
+### MQTT Discovery (Découverte automatique)
+
+Le script implémente le protocole **MQTT Discovery** de Home Assistant pour une intégration transparente et automatique. Aucune configuration manuelle n'est nécessaire dans Home Assistant.
+
+#### Fonctionnement de l'autodécouverte
+
+1. **Au démarrage** : Publication des configurations de découverte
+2. **Pendant l'exécution** : Mise à jour continue des états des capteurs
+3. **Surveillance** : Gestion des statuts de disponibilité (online/offline)
+
 ### Topics MQTT générés
 
-Le script génère automatiquement les topics MQTT suivants :
+#### Topics de découverte (Discovery)
+Chaque capteur génère un topic de configuration individuel :
+```
+homeassistant/{platform}/{node_id}/{object_id}/config
+```
 
-- **Configuration** : `homeassistant/device/{device_id}/config`
+**Exemples** :
-- **État** : `SNMP/{device_name}/state`
+```bash
+# Capteur de trafic réseau
+homeassistant/sensor/mikrotik_hex/mikrotik_hex_starlink_in/config
 
-### Découverte automatique
+# Statut de connectivité  
+homeassistant/binary_sensor/mikrotik_hex/mikrotik_hex_starlink_status/config
+```
 
-Les équipements et capteurs sont automatiquement découverts dans Home Assistant via MQTT Discovery. Chaque équipement apparaîtra avec :
+#### Topics de données
+- **État** : `SNMP/{device_name}/state` - Données JSON des capteurs
+- **Disponibilité** : `SNMP/{device_name}/availability` - Statut online/offline
 
-- Un identifiant unique basé sur le nom et l'IP
+### Configuration automatique des capteurs
-- Des capteurs groupés par équipement
+
-- Des icônes et unités appropriées selon la classe d'équipement
+Chaque capteur est configuré avec :
-- Des modèles de valeurs JSON pour extraire les données
+
+```json
+{
+  "name": "mikrotik_hex starlink_in",
+  "unique_id": "mikrotik_hex_192_168_10_2_starlink_in",
+  "state_topic": "SNMP/mikrotik_hex/state",
+  "value_template": "{{ value_json.starlink_in }}",
+  "device_class": "data_size",
+  "unit_of_measurement": "bit",
+  "icon": "mdi:network",
+  "device": {
+    "identifiers": ["snmp2mqtt_mikrotik_hex_192_168_10_2"],
+    "name": "mikrotik_hex",
+    "model": "SNMP Device",
+    "manufacturer": "Network Equipment"
+  },
+  "availability": {
+    "topic": "SNMP/mikrotik_hex/availability",
+    "payload_available": "online",
+    "payload_not_available": "offline"
+  }
+}
+```
+
+### Découverte automatique dans Home Assistant
+
+#### Regroupement par équipement
+Tous les capteurs d'un même équipement sont automatiquement regroupés sous une seule carte d'équipement :
+
+- **Identifiant unique** basé sur `device_name` + `ip`
+- **Nom d'affichage** basé sur le nom de l'équipement
+- **Métadonnées** : modèle, fabricant, version du logiciel
+
+#### Types de capteurs supportés
+
+| Type HA | Platform | Description | Icône |
+|---------|----------|-------------|-------|
+| `sensor` | `sensor` | Valeurs numériques (trafic, CPU, etc.) | Selon device_class |
+| `binary_sensor` | `binary_sensor` | États binaires (online/offline, actif/inactif) | mdi:network-outline |
+
+#### Classes d'équipements et icônes
+
+| Device Class | Utilisation | Icône Auto | Unité Suggérée |
+|--------------|-------------|------------|----------------|
+| `data_size` | Trafic réseau, volumes de données | mdi:network | bit, byte, MB, GB |
+| `connectivity` | Statut des interfaces, connexions | mdi:network-outline | - |
+| `power_factor` | Pourcentages (CPU, mémoire) | mdi:gauge | % |
+| `temperature` | Températures d'équipements | mdi:thermometer | °C, °F |
+| `signal_strength` | Qualité des signaux | mdi:signal | dBm, % |
+
+### Surveillance de disponibilité
+
+#### Statuts de disponibilité
+- **Online** : Équipement accessible et données mises à jour
+- **Offline** : Équipement inaccessible ou erreurs SNMP
+
+#### Mécanisme de heartbeat
+- Mise à jour du statut à chaque cycle de surveillance
+- Marquage offline automatique en cas d'erreur
+- Statut offline lors de l'arrêt du script
+
+### Persistance et redémarrages
+
+#### Configuration Discovery retenue
+- **Flag retain=true** sur les topics de configuration
+- **Redécouverte automatique** après redémarrage de Home Assistant
+- **Pas de perte de configuration** lors des redémarrages
+
+#### Données d'état temps réel
+- **Flag retain=false** sur les données d'état  
+- **Données fraîches uniquement** après redémarrage
+- **Historique préservé** par Home Assistant
+
+### Intégration dans l'interface Home Assistant
+
+Après démarrage du script, vous verrez automatiquement :
+
+1. **Page Équipements** : Nouveaux équipements SNMP avec leurs capteurs
+2. **États et Historiques** : Données temps réel et graphiques
+3. **Cartes automatiques** : Ajout facile aux tableaux de bord
+4. **Notifications** : Alertes sur les changements d'état
+5. **Automations** : Utilisation des capteurs dans les règles
+
+### Exemple d'équipement découvert
+
+```
+📱 mikrotik_hex (SNMP Device)
+├── 📊 mikrotik_hex starlink_in (123.45 MB)
+├── 📊 mikrotik_hex starlink_out (67.89 MB)  
+├── 🔌 mikrotik_hex starlink_status (Online)
+├── 📊 mikrotik_hex lan_bridge_in (234.56 MB)
+├── 📊 mikrotik_hex lan_bridge_out (78.90 MB)
+└── 🔌 mikrotik_hex lan_bridge_status (Online)
+
+Statut: Online | Dernière mise à jour: il y a 2 secondes
+```
 
 ## Exemple de configuration complète
 

snmp2mqtt.py

@@ -51,40 +51,56 @@ class DeviceMonitorThread(threading.Thread):
         logging.info(f"Starting monitoring thread for device: {self.device_name} ({self.device_config['ip']})")
         
         try:
-            # Setup MQTT connection and Home Assistant config
+            # Setup MQTT connection
-            ha_config = ha_create_config(self.req)
             client = connect_mqtt(self.mqtt_config)
             client.loop_start()
             
-            config_topic = f"homeassistant/device/{ha_config['dev']['ids']}/config"
+            state_topic = f"SNMP/{self.device_name}/state"
-            state_topic = ha_config['state_topic']
+            availability_topic = f"SNMP/{self.device_name}/availability"
             
-            logging.info(f"[{self.device_name}] MQTT client connected, starting monitoring loop")
+            logging.info(f"[{self.device_name}] MQTT client connected")
             
+            # Publish Home Assistant autodiscovery configuration (only once on startup)
+            publish_ha_autodiscovery_config(client, self.req)
+            
+            # Mark device as available
+            publish(availability_topic, client, "online", True, 1)
+            
+            logging.info(f"[{self.device_name}] Starting monitoring loop")
+            
+            # Main monitoring loop
             while not shutdown_event.is_set():
                 try:
-                    # Publish Home Assistant configuration
-                    publish(config_topic, client, ha_config, True, 0)
-                    logging.debug(f"[{self.device_name}] Published config to {config_topic}")
-                    
                     # Get SNMP data and publish state
                     state = asyncio.run(get_snmp(self.req))
                     publish(state_topic, client, state, False, 0)
                     logging.debug(f"[{self.device_name}] Published state to {state_topic}: {json.dumps(state)}")
                     
+                    # Update availability (heartbeat)
+                    publish(availability_topic, client, "online", False, 1)
+                    
                 except Exception as e:
                     logging.error(f"[{self.device_name}] Error in monitoring loop: {e}")
+                    # Mark as offline on error
+                    publish(availability_topic, client, "offline", False, 1)
                 
                 # Wait for next iteration or shutdown signal
                 shutdown_event.wait(timeout=self.sleep_interval)
             
-            # Cleanup
+            # Cleanup - mark device as offline
+            publish(availability_topic, client, "offline", True, 1)
             client.loop_stop()
             client.disconnect()
             logging.info(f"[{self.device_name}] Monitoring thread stopped gracefully")
             
         except Exception as e:
             logging.error(f"[{self.device_name}] Fatal error in monitoring thread: {e}")
+            # Try to mark as offline on fatal error
+            try:
+                publish(availability_topic, client, "offline", True, 1)
+                client.disconnect()
+            except:
+                pass
         
         logging.info(f"[{self.device_name}] Thread {self.name} finished")
 
@@ -174,7 +190,11 @@ def connect_mqtt(mqtt_config):
 
 
 def publish(topic, client, data, retain, qos):
+    if isinstance(data, str):
+        msg = data
+    else:
         msg = json.dumps(data)
+    
     result = client.publish(topic=topic, payload=msg, qos=qos, retain=bool(retain))
     status = result[0]
     if status == 0:
@@ -217,38 +237,93 @@ async def get_snmp(req):
     return data
 
 
-def ha_create_config(req):
+def create_ha_device_info(req):
-    ha_config = {}
+    """Create device information for Home Assistant MQTT Discovery"""
-    device = {
+    return {
-            "ids": f"{req['device_name']}_{req['ip']}".replace(".", "_"),
+        "identifiers": [f"snmp2mqtt_{req['device_name']}_{req['ip']}".replace(".", "_")],
         "name": req['device_name'],
+        "model": "SNMP Device",
+        "manufacturer": "Network Equipment",
+        "via_device": "snmp2mqtt"
     }
-    origin = {
+
-            "name": "snmp2mqtt"
+
-            }
+def create_ha_sensor_config(req, oid):
-    ha_config.update({"dev": device, "o": origin})
+    """Create Home Assistant MQTT Discovery configuration for a single sensor"""
-    ha_config.update({"state_topic": f"SNMP/{req['device_name']}/state"})
+    device_info = create_ha_device_info(req)
-    ha_config.update({"qos": 2})
+    sensor_id = f"{req['device_name']}_{req['ip']}_{oid['name']}".replace(".", "_")
-    cmps = {}
+    
-    for oid in req['oids']:
+    config = {
-        cmps.update(
+        "name": f"{req['device_name']} {oid['name']}",
-                {
+        "unique_id": sensor_id,
-                    f"{req['device_name']}_{req['ip']}_{oid['name']}".replace(".", "_"):
+        "state_topic": f"SNMP/{req['device_name']}/state",
-                    {
-                        "p": oid['HA_platform'],
-                        "device_class": oid['HA_device_class'],
         "value_template": f"{{{{ value_json.{oid['name']} }}}}",
-                        "unique_id": f"{req['device_name']}_{req['ip']}_{oid['name']}".replace(".", "_"),
+        "device": device_info,
-                        "name": oid['name']
+        "origin": {
+            "name": "snmp2mqtt",
+            "sw_version": "1.0.0",
+            "support_url": "https://git.antoineve.me/AntoineVe/snmp2mqtt"
         }
-                    })
+    }
-        if "HA_unit" in oid.keys():
+    
-            cmps.update(
+    # Add device class if specified
-                 {f"{req['device_name']}_{req['ip']}_{oid['name']}".replace(".", "_"):
+    if 'HA_device_class' in oid:
-                    {"unit_of_measurement": oid['HA_unit']}})
+        config['device_class'] = oid['HA_device_class']
-    ha_config.update({"cmps": cmps})
+    
-    logging.debug(f"config : {json.dumps(ha_config)}")
+    # Add unit of measurement if specified
-    return ha_config
+    if 'HA_unit' in oid:
+        config['unit_of_measurement'] = oid['HA_unit']
+    
+    # Add icon based on device class
+    icon_mapping = {
+        'data_size': 'mdi:network',
+        'connectivity': 'mdi:network-outline',
+        'power_factor': 'mdi:gauge',
+        'temperature': 'mdi:thermometer',
+        'signal_strength': 'mdi:signal'
+    }
+    if 'HA_device_class' in oid and oid['HA_device_class'] in icon_mapping:
+        config['icon'] = icon_mapping[oid['HA_device_class']]
+    
+    # Add availability topic
+    config['availability'] = {
+        "topic": f"SNMP/{req['device_name']}/availability",
+        "payload_available": "online",
+        "payload_not_available": "offline"
+    }
+    
+    return config
+
+
+def get_ha_discovery_topic(req, oid):
+    """Get the correct Home Assistant MQTT Discovery topic for a sensor"""
+    platform = oid['HA_platform']  # 'sensor' or 'binary_sensor'
+    node_id = req['device_name']
+    object_id = f"{req['device_name']}_{oid['name']}".replace(".", "_")
+    
+    # Format: homeassistant/<platform>/<node_id>/<object_id>/config
+    return f"homeassistant/{platform}/{node_id}/{object_id}/config"
+
+
+def publish_ha_autodiscovery_config(client, req):
+    """Publish Home Assistant MQTT Discovery configuration for all sensors of a device"""
+    logging.info(f"[{req['device_name']}] Publishing Home Assistant autodiscovery configuration")
+    
+    # Publish availability as online
+    availability_topic = f"SNMP/{req['device_name']}/availability"
+    publish(availability_topic, client, "online", True, 1)
+    
+    # Publish discovery configuration for each OID/sensor
+    for oid in req['oids']:
+        config = create_ha_sensor_config(req, oid)
+        topic = get_ha_discovery_topic(req, oid)
+        
+        # Publish with retain=True so HA discovers it after restarts
+        publish(topic, client, config, True, 1)
+        logging.info(f"[{req['device_name']}] Published discovery config for {oid['name']} to {topic}")
+        
+        # Small delay to avoid overwhelming the broker
+        time.sleep(0.1)
 
 
 def signal_handler(signum, frame):