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