| 
						 
							
							
							
						 
					 | 
				
			
			 | 
			 | 
			
				@@ -0,0 +1,77 @@
 | 
			
		
		
	
		
			
				 | 
				 | 
			
			 | 
			 | 
			
				# 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.
 |