snmp2mqtt/GEMINI.md

Fichier d'aide pour Gemini

Ce document fournit un résumé concis du projet snmp2mqtt pour aider au développement et à la maintenance assistés par l'IA.

1. Objectif du Projet

Le projet snmp2mqtt est une passerelle écrite en Python qui a pour but de :

1. Interroger des équipements réseau (routeurs, switchs, etc.) via le protocole SNMP.
2. Récupérer des métriques spécifiques (trafic, statut des ports, etc.) définies par des OIDs.
3. Publier ces données sur un broker MQTT.
4. S'intégrer automatiquement avec Home Assistant grâce au mécanisme de "MQTT Discovery", permettant de créer des capteurs sans configuration manuelle côté Home Assistant.

2. Architecture et Technologies

• Langage : Python 3
• Dépendances principales (requirements.txt) :
  • pysnmp>=7.0.0 : Pour la communication SNMP asynchrone.
  • paho-mqtt>=2.0.0 : Pour la communication avec le broker MQTT.
  • PyYAML>=6.0.0 : Pour le parsing du fichier de configuration.
• Configuration : Un unique fichier config.yaml centralise tous les paramètres (MQTT, appareils, OIDs).
• Exécution : Le script utilise le multi-threading. Un thread est démarré pour chaque appareil défini dans la configuration, ce qui permet une surveillance parallèle et isolée.

3. Structure du Code (snmp2mqtt.py)

Le script principal est organisé de la manière suivante :

1. main() : Point d'entrée. Il parse les arguments (--config), charge la configuration et appelle process_devices().
2. process_devices(config) :
   • Orchestre le lancement des threads.
   • Crée et démarre une instance de DeviceMonitorThread pour chaque appareil.
   • Gère l'arrêt propre (graceful shutdown) en attendant que tous les threads se terminent.
3. DeviceMonitorThread(threading.Thread) :
   • Classe qui encapsule la logique de surveillance pour un seul appareil.
   • run() : méthode principale du thread.
     • Établit la connexion MQTT.
     • Publie la configuration de découverte automatique pour Home Assistant (une seule fois au démarrage).
     • Entre dans une boucle infinie qui :
       • Appelle get_snmp() pour récupérer les données.
       • Publie l'état des capteurs et le statut de disponibilité (online/offline) sur MQTT.
       • Attend un intervalle (sleep_interval) avant la prochaine interrogation.
4. get_snmp(req) :
   • Fonction async qui utilise pysnmp pour exécuter les requêtes GET SNMP pour tous les OIDs d'un appareil.
   • Retourne un dictionnaire contenant les valeurs formatées.
5. Fonctions de configuration et MQTT :
   • load_config() : Charge et valide le fichier config.yaml.
   • connect_mqtt() : Initialise le client MQTT.
   • publish() : Wrapper pour publier les messages MQTT.
   • publish_ha_autodiscovery_config() : Construit et publie les messages de configuration pour Home Assistant MQTT Discovery.

4. Flux de Données

[Appareil SNMP] <--- (Requête SNMP GET) --- [snmp2mqtt.py / Thread]
       |
       | (Réponse SNMP)
       v
[snmp2mqtt.py / Thread] --- (Publication MQTT) ---> [Broker MQTT]
                                                          |
                                                          | (MQTT Discovery & State)
                                                          v
                                                  [Home Assistant]

5. Comment développer

• Environnement :
  1. Créer un environnement virtuel : python3 -m venv .venv
  2. Activer l'environnement : source .venv/bin/activate
  3. Installer les dépendances : pip install -r requirements.txt
• Configuration :
  • Copier et modifier config.yaml pour pointer vers un broker MQTT de test et un appareil SNMP accessible.
• Lancement :
  • python snmp2mqtt.py --config config.yaml
• Points clés à modifier :
  • Pour ajouter une nouvelle fonctionnalité à un capteur Home Assistant, modifier create_ha_sensor_config().
  • Pour changer la logique de récupération SNMP, modifier get_snmp().
  • Pour ajouter de nouveaux paramètres de configuration, mettre à jour load_config() pour la validation.