Fichier README

README.md

@@ -1,3 +1,280 @@
 # snmp2mqtt
 
-Script python pour relayer les infos snmp en mqtt
+Passerelle SNMP vers MQTT pour l'intégration Home Assistant. Ce script Python surveille les équipements réseau via SNMP et publie les données vers un broker MQTT pour une découverte automatique dans Home Assistant.
+
+## Fonctionnalités
+
+- 🔧 **Configuration YAML flexible** : Tous les paramètres dans un fichier de configuration
+- 📡 **Support multi-équipements** : Surveillez plusieurs périphériques réseau
+- 🏠 **Intégration Home Assistant** : Découverte automatique des capteurs
+- ⚡ **SNMP asynchrone** : Requêtes SNMP non-bloquantes pour de meilleures performances
+- 🔄 **Surveillance en temps réel** : Mise à jour continue des métriques réseau
+- 📊 **Métriques réseau** : Trafic entrant/sortant et statut des interfaces
+
+## Architecture
+
+### Composants principaux
+
+- **Client SNMP** : Utilise `pysnmp.hlapi.asyncio.slim` pour la récupération asynchrone des données SNMP
+- **Publisher MQTT** : Utilise `paho.mqtt.client` pour publier les données vers un broker MQTT
+- **Intégration Home Assistant** : Génère la configuration de découverte automatique compatible avec Home Assistant MQTT Discovery
+- **Traitement des données** : Convertit les valeurs des OID SNMP vers les types appropriés (int, bool) pour les capteurs Home Assistant
+
+## Installation
+
+### Prérequis
+
+- Python 3.7 ou supérieur
+- Accès réseau aux équipements SNMP à surveiller
+- Broker MQTT accessible
+
+### Configuration de l'environnement
+
+```bash
+# Cloner le repository
+git clone <url-du-repo>
+cd snmp2mqtt
+
+# Créer un environnement virtuel
+python -m venv venv
+source venv/bin/activate  # Sur Linux/Mac
+# ou
+venv\Scripts\activate     # Sur Windows
+
+# Installer les dépendances
+pip install -r requirements.txt
+```
+
+## Configuration
+
+### Structure du fichier config.yaml
+
+Le script utilise un fichier de configuration YAML avec la structure suivante :
+
+```yaml
+# Configuration du broker MQTT
+mqtt:
+  broker: "192.168.10.202"     # Adresse IP du broker MQTT
+  port: 1883                    # Port du broker MQTT
+  user: "snmp2mqtt"             # Nom d'utilisateur MQTT
+  password: "votre_mot_de_passe" # Mot de passe MQTT
+
+# Intervalle entre les requêtes SNMP (optionnel, défaut: 2 secondes)
+sleep_interval: 2
+
+# Configuration des équipements
+devices:
+  nom_equipement:
+    ip: "192.168.1.1"           # Adresse IP de l'équipement
+    snmp_community: "public"    # Communauté SNMP
+    oids:                       # Liste des OID à surveiller
+      - name: "interface_in"    # Nom unique du capteur
+        oid: ".1.3.6.1.2.1.2.2.1.10.1"  # OID SNMP
+        type: "int"             # Type de données (int, bool, str)
+        HA_device_class: "data_size"      # Classe d'équipement HA
+        HA_platform: "sensor"             # Plateforme HA
+        HA_unit: "bit"                    # Unité (optionnel)
+```
+
+### Paramètres de configuration détaillés
+
+#### Section `mqtt`
+
+| Paramètre | Type | Obligatoire | Description |
+|-----------|------|-------------|-------------|
+| `broker` | string | ✅ | Adresse IP ou nom d'hôte du broker MQTT |
+| `port` | integer | ✅ | Port du broker MQTT (généralement 1883) |
+| `user` | string | ✅ | Nom d'utilisateur pour l'authentification MQTT |
+| `password` | string | ✅ | Mot de passe pour l'authentification MQTT |
+
+#### Section `devices`
+
+Chaque équipement est défini par une clé (nom de l'équipement) et les paramètres suivants :
+
+| Paramètre | Type | Obligatoire | Description |
+|-----------|------|-------------|-------------|
+| `ip` | string | ✅ | Adresse IP de l'équipement SNMP |
+| `snmp_community` | string | ✅ | Communauté SNMP (généralement "public") |
+| `oids` | liste | ✅ | Liste des OID SNMP à surveiller |
+
+#### Configuration des OID
+
+Chaque OID dans la liste `oids` doit contenir :
+
+| Paramètre | Type | Obligatoire | Description |
+|-----------|------|-------------|-------------|
+| `name` | string | ✅ | Identifiant unique pour ce capteur |
+| `oid` | string | ✅ | Identifiant d'objet SNMP |
+| `type` | string | ✅ | Type de conversion Python ("int", "bool", "str") |
+| `HA_device_class` | string | ✅ | Classe d'équipement Home Assistant |
+| `HA_platform` | string | ✅ | Plateforme Home Assistant ("sensor", "binary_sensor") |
+| `HA_unit` | string | ❌ | Unité de mesure pour le capteur |
+
+### Classes d'équipements Home Assistant courantes
+
+- `data_size` : Pour les données de trafic réseau
+- `connectivity` : Pour le statut des interfaces
+- `power_factor` : Pour les pourcentages (CPU, utilisation)
+- `temperature` : Pour les températures
+- `signal_strength` : Pour la qualité du signal
+
+### OID SNMP couramment utilisés
+
+```yaml
+# Interfaces réseau (remplacez X par l'index de l'interface)
+- ".1.3.6.1.2.1.2.2.1.10.X"  # Octets entrants sur l'interface X
+- ".1.3.6.1.2.1.2.2.1.16.X"  # Octets sortants sur l'interface X
+- ".1.3.6.1.2.1.2.2.1.8.X"   # Statut opérationnel (1=actif, 2=inactif)
+- ".1.3.6.1.2.1.2.2.1.2.X"   # Description de l'interface
+
+# MikroTik spécifique
+- ".1.3.6.1.4.1.14988.1.1.3.14.0"  # Utilisation CPU
+- ".1.3.6.1.4.1.14988.1.1.6.1.0"   # Température
+```
+
+## Utilisation
+
+### Lancement du script
+
+```bash
+# Activer l'environnement virtuel
+source venv/bin/activate
+
+# Lancer avec le fichier de configuration
+python snmp2mqtt.py --config config.yaml
+
+# Ou avec la forme courte
+python snmp2mqtt.py -c config.yaml
+```
+
+### Options en ligne de commande
+
+| Option | Description |
+|--------|-------------|
+| `--config`, `-c` | Chemin vers le fichier de configuration YAML (obligatoire) |
+| `--help`, `-h` | Affiche l'aide |
+
+## Intégration Home Assistant
+
+### Topics MQTT générés
+
+Le script génère automatiquement les topics MQTT suivants :
+
+- **Configuration** : `homeassistant/device/{device_id}/config`
+- **État** : `SNMP/{device_name}/state`
+
+### Découverte automatique
+
+Les équipements et capteurs sont automatiquement découverts dans Home Assistant via MQTT Discovery. Chaque équipement apparaîtra avec :
+
+- Un identifiant unique basé sur le nom et l'IP
+- Des capteurs groupés par équipement
+- Des icônes et unités appropriées selon la classe d'équipement
+- Des modèles de valeurs JSON pour extraire les données
+
+## Exemple de configuration complète
+
+```yaml
+# Configuration MQTT
+mqtt:
+  broker: "192.168.10.202"
+  port: 1883
+  user: "snmp2mqtt"
+  password: "mon_mot_de_passe"
+
+# Intervalle de surveillance
+sleep_interval: 5
+
+# Équipements à surveiller
+devices:
+  # Routeur MikroTik Hex
+  mikrotik_hex:
+    ip: "192.168.10.2"
+    snmp_community: "public"
+    oids:
+      # Interface Starlink
+      - name: "starlink_in"
+        oid: ".1.3.6.1.2.1.2.2.1.10.1"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "starlink_out"
+        oid: ".1.3.6.1.2.1.2.2.1.16.1"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "starlink_status"
+        oid: ".1.3.6.1.2.1.2.2.1.8.1"
+        type: "bool"
+        HA_device_class: "connectivity"
+        HA_platform: "binary_sensor"
+  
+  # Switch réseau
+  switch_bureau:
+    ip: "192.168.10.5"
+    snmp_community: "public"
+    oids:
+      - name: "port1_status"
+        oid: ".1.3.6.1.2.1.2.2.1.8.1"
+        type: "bool"
+        HA_device_class: "connectivity"
+        HA_platform: "binary_sensor"
+```
+
+## Dépannage
+
+### Problèmes courants
+
+1. **Erreur "Configuration file not found"**
+   - Vérifiez le chemin vers le fichier config.yaml
+   - Assurez-vous que le fichier existe et est lisible
+
+2. **Erreur de connexion MQTT**
+   - Vérifiez les paramètres du broker (IP, port, credentials)
+   - Testez la connectivité réseau vers le broker
+
+3. **Pas de données SNMP**
+   - Vérifiez que l'équipement supporte SNMP
+   - Testez avec `snmpwalk` : `snmpwalk -v2c -c public IP_EQUIPEMENT`
+   - Vérifiez les OID utilisés
+
+4. **Capteurs non découverts dans Home Assistant**
+   - Vérifiez que MQTT Discovery est activé dans Home Assistant
+   - Surveillez les logs MQTT avec `mosquitto_sub`
+
+### Commandes de test utiles
+
+```bash
+# Test SNMP manuel
+snmpwalk -v2c -c public 192.168.10.2 1.3.6.1.2.1.2.2.1.10
+
+# Surveillance des messages MQTT
+mosquitto_sub -h 192.168.10.202 -u snmp2mqtt -P 'mot_de_passe' -t 'homeassistant/device/+/config'
+mosquitto_sub -h 192.168.10.202 -u snmp2mqtt -P 'mot_de_passe' -t 'SNMP/+/state'
+
+# Test de connectivité
+ping 192.168.10.2
+ping 192.168.10.202
+```
+
+## Support multi-équipements
+
+**Note** : Le support complet multi-équipements nécessite une implémentation avec threading/multiprocessing. Actuellement, le script traite le premier équipement de la liste et affiche un avertissement pour les autres.
+
+## Logs et debugging
+
+Le script utilise le module `logging` de Python avec le niveau DEBUG par défaut. Les logs incluent :
+
+- Chargement de la configuration
+- Connexions MQTT
+- Requêtes SNMP et leurs résultats
+- Publication des messages MQTT
+- Erreurs et avertissements
+
+## Licence
+
+Ce projet est distribué sous licence libre. Consultez le fichier LICENSE pour plus de détails.

config.yaml

@@ -0,0 +1,111 @@
+# SNMP2MQTT Configuration File
+# This file contains the configuration for the SNMP to MQTT bridge
+
+# MQTT Broker Configuration
+mqtt:
+  broker: "192.168.10.202"
+  port: 1883
+  user: "snmp2mqtt"
+  password: "snmp_2_MQTT"
+
+# Optional: Sleep interval between SNMP polls (default: 2 seconds)
+sleep_interval: 2
+
+# Device Configurations
+# You can define multiple devices here. Each device will be monitored independently.
+devices:
+  # Device name (used for MQTT topics and Home Assistant device identification)
+  mikrotik_hex:
+    ip: "192.168.10.2"
+    snmp_community: "public"
+    oids:
+      # Starlink VPN interface (interface index 12)
+      - name: "stln_vpn_in"
+        oid: ".1.3.6.1.2.1.2.2.1.10.12"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "stlon_vpn_out"
+        oid: ".1.3.6.1.2.1.2.2.1.16.12"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "stln_vpn_status"
+        oid: ".1.3.6.1.2.1.2.2.1.8.12"
+        type: "bool"
+        HA_device_class: "connectivity"
+        HA_platform: "binary_sensor"
+      
+      # LAN Bridge interface (interface index 6)
+      - name: "lan_bridge_in"
+        oid: ".1.3.6.1.2.1.2.2.1.10.6"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "lan_bridge_out"
+        oid: ".1.3.6.1.2.1.2.2.1.16.6"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "lan_bridge_status"
+        oid: ".1.3.6.1.2.1.2.2.1.8.6"
+        type: "bool"
+        HA_device_class: "connectivity"
+        HA_platform: "binary_sensor"
+      
+      # Starlink interface (interface index 1)
+      - name: "starlink_in"
+        oid: ".1.3.6.1.2.1.2.2.1.10.1"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "starlink_out"
+        oid: ".1.3.6.1.2.1.2.2.1.16.1"
+        type: "int"
+        HA_device_class: "data_size"
+        HA_platform: "sensor"
+        HA_unit: "bit"
+      
+      - name: "starlink_status"
+        oid: ".1.3.6.1.2.1.2.2.1.8.1"
+        type: "bool"
+        HA_device_class: "connectivity"
+        HA_platform: "binary_sensor"
+
+# Example of how to add another device:
+#  another_device:
+#    ip: "192.168.10.3"
+#    snmp_community: "public"
+#    oids:
+#      - name: "cpu_usage"
+#        oid: ".1.3.6.1.4.1.14988.1.1.3.14.0"  # MikroTik CPU usage
+#        type: "int"
+#        HA_device_class: "power_factor"
+#        HA_platform: "sensor"
+#        HA_unit: "%"
+
+# OID Configuration Reference:
+# - name: Unique identifier for this metric (used in MQTT topics and Home Assistant)
+# - oid: SNMP Object Identifier
+# - type: Python type for value conversion ("int", "bool", "str")
+# - HA_device_class: Home Assistant device class for proper icon/categorization
+#   Common classes: data_size, connectivity, power_factor, temperature, etc.
+# - HA_platform: Home Assistant platform type ("sensor", "binary_sensor")
+# - HA_unit: (optional) Unit of measurement for the sensor
+#   Common units: "bit", "byte", "%", "°C", "°F", etc.
+
+# Common SNMP OIDs for network interfaces:
+# - .1.3.6.1.2.1.2.2.1.10.X = Incoming bytes on interface X
+# - .1.3.6.1.2.1.2.2.1.16.X = Outgoing bytes on interface X
+# - .1.3.6.1.2.1.2.2.1.8.X  = Interface operational status (1=up, 2=down)
+# - .1.3.6.1.2.1.2.2.1.2.X  = Interface description

requirements.txt

@@ -0,0 +1,11 @@
+# SNMP2MQTT Python Dependencies
+# Install with: pip install -r requirements.txt
+
+# SNMP library for asynchronous SNMP operations
+pysnmp>=6.0.0
+
+# MQTT client library for connecting to MQTT brokers
+paho-mqtt>=1.6.0
+
+# YAML configuration file parsing
+PyYAML>=6.0.0

snmp2mqtt.py

@@ -7,6 +7,10 @@ import random
 from paho.mqtt import client as mqtt_client
 import json
 from time import sleep
+import yaml
+import argparse
+import sys
+import os
 
 logging.basicConfig(
         format='(%(levelname)s) %(message)s',
@@ -14,6 +18,77 @@ logging.basicConfig(
         )
 
 
+def parse_arguments():
+    """Parse command line arguments"""
+    parser = argparse.ArgumentParser(description='SNMP to MQTT bridge for Home Assistant')
+    parser.add_argument('--config', '-c', required=True, 
+                       help='Path to YAML configuration file')
+    return parser.parse_args()
+
+
+def load_config(config_path):
+    """Load and validate YAML configuration file"""
+    if not os.path.exists(config_path):
+        logging.error(f"Configuration file not found: {config_path}")
+        sys.exit(1)
+    
+    try:
+        with open(config_path, 'r') as file:
+            config = yaml.safe_load(file)
+    except yaml.YAMLError as e:
+        logging.error(f"Error parsing YAML configuration: {e}")
+        sys.exit(1)
+    except Exception as e:
+        logging.error(f"Error reading configuration file: {e}")
+        sys.exit(1)
+    
+    # Validate required configuration sections
+    if 'mqtt' not in config:
+        logging.error("Missing 'mqtt' section in configuration")
+        sys.exit(1)
+    
+    if 'devices' not in config:
+        logging.error("Missing 'devices' section in configuration")
+        sys.exit(1)
+    
+    # Validate MQTT configuration
+    required_mqtt_fields = ['broker', 'port', 'user', 'password']
+    for field in required_mqtt_fields:
+        if field not in config['mqtt']:
+            logging.error(f"Missing required MQTT field: {field}")
+            sys.exit(1)
+    
+    # Validate device configurations
+    for device_name, device_config in config['devices'].items():
+        required_device_fields = ['ip', 'snmp_community', 'oids']
+        for field in required_device_fields:
+            if field not in device_config:
+                logging.error(f"Missing required field '{field}' in device '{device_name}'")
+                sys.exit(1)
+        
+        # Validate OID configurations
+        for oid in device_config['oids']:
+            required_oid_fields = ['name', 'oid', 'type', 'HA_device_class', 'HA_platform']
+            for field in required_oid_fields:
+                if field not in oid:
+                    logging.error(f"Missing required OID field '{field}' in device '{device_name}'")
+                    sys.exit(1)
+            
+            # Convert type string to actual Python type
+            if oid['type'] == 'int':
+                oid['type'] = int
+            elif oid['type'] == 'bool':
+                oid['type'] = bool
+            elif oid['type'] == 'str':
+                oid['type'] = str
+            else:
+                logging.error(f"Unsupported type '{oid['type']}' for OID '{oid['name']}' in device '{device_name}'")
+                sys.exit(1)
+    
+    logging.info(f"Configuration loaded successfully from {config_path}")
+    return config
+
+
 def connect_mqtt(mqtt_config):
     def on_connect(client, userdata, flags, rc):
         if rc == 0:
@@ -105,105 +180,81 @@ def ha_create_config(req):
     return ha_config
 
 
-def send_to_mqtt():
+def send_to_mqtt(device_name, device_config, mqtt_config, sleep_interval=2):
+    """Send SNMP data to MQTT for a single device"""
+    # Create device request object
+    req = {
+        "device_name": device_name,
+        "ip": device_config["ip"],
+        "snmp_community": device_config["snmp_community"],
+        "oids": device_config["oids"]
+    }
+    
     config = ha_create_config(req)
     client = connect_mqtt(mqtt_config)
     client.loop_start()
     config_topic = f"homeassistant/device/{config['dev']['ids']}/config"
     state_topic = config['state_topic']
+    
     while True:
         try:
             publish(config_topic, client, config, True, 0)
             logging.info(f"{config_topic} -> {config}")
         except Exception as e:
-            logging.error(e)
+            logging.error(f"Error publishing config for {device_name}: {e}")
             pass
         try:
             state = asyncio.run(get_snmp(req))
             publish(state_topic, client, state, False, 0)
             logging.info(f"{state_topic} -> {state}")
         except Exception as e:
-            logging.error(e)
+            logging.error(f"Error getting SNMP data for {device_name}: {e}")
             pass
-        sleep(2)
+        sleep(sleep_interval)
 
 
-req = {
-        "device_name": "mikrotik_hex",
-        "ip": "192.168.10.2",
-        "snmp_community": "public",
-        "oids": [
-            {"name": "stln_vpn_in",
-             "oid": ".1.3.6.1.2.1.2.2.1.10.12",
-             "type": int,
-             "HA_device_class": "data_size",
-             "HA_platform": "sensor",
-             "HA_unit": "bit"
-             },
-            {"name": "stlon_vpn_out",
-             "oid": ".1.3.6.1.2.1.2.2.1.16.12",
-             "type": int,
-             "HA_device_class": "data_size",
-             "HA_platform": "sensor",
-             "HA_unit": "bit"
-             },
-            {"name": "stln_vpn_status",
-             "oid": ".1.3.6.1.2.1.2.2.1.8.12",
-             "type": bool,
-             "HA_device_class": "connectivity",
-             "HA_platform": "binary_sensor",
-             },
-            {"name": "lan_bridge_in",
-             "oid": ".1.3.6.1.2.1.2.2.1.10.6",
-             "type": int,
-             "HA_device_class": "data_size",
-             "HA_platform": "sensor",
-             "HA_unit": "bit"
-             },
-            {"name": "lan_bridge_out",
-             "oid": ".1.3.6.1.2.1.2.2.1.16.6",
-             "type": int,
-             "HA_device_class": "data_size",
-             "HA_platform": "sensor",
-             "HA_unit": "bit"
-             },
-            {"name": "lan_bridge_status",
-             "oid": ".1.3.6.1.2.1.2.2.1.8.6",
-             "type": bool,
-             "HA_device_class": "connectivity",
-             "HA_platform": "binary_sensor",
-             },
-            {"name": "starlink_in",
-             "oid": ".1.3.6.1.2.1.2.2.1.10.1",
-             "type": int,
-             "HA_device_class": "data_size",
-             "HA_platform": "sensor",
-             "HA_unit": "bit"
-             },
-            {"name": "starlink_out",
-             "oid": ".1.3.6.1.2.1.2.2.1.16.1",
-             "type": int,
-             "HA_device_class": "data_size",
-             "HA_platform": "sensor",
-             "HA_unit": "bit"
-             },
-            {"name": "starlink_status",
-             "oid": ".1.3.6.1.2.1.2.2.1.8.1",
-             "type": bool,
-             "HA_device_class": "connectivity",
-             "HA_platform": "binary_sensor",
-             }
+def process_devices(config):
+    """Process multiple devices from configuration"""
+    mqtt_config = config['mqtt'].copy()
+    mqtt_config['client_id'] = f"snmp-mqtt-{random.randint(0, 1000)}"
     
-            ]
-        }
+    # Get sleep interval from config or use default
+    sleep_interval = config.get('sleep_interval', 2)
     
-mqtt_config = {
-        "broker": "192.168.10.202",
-        "port": 1883,
-        "client_id": f"snmp-mqtt-{random.randint(0, 1000)}",
-        "user": "snmp2mqtt",
-        "password": "snmp_2_MQTT"
-        }
+    if len(config['devices']) == 1:
+        # Single device mode - run directly
+        device_name = list(config['devices'].keys())[0]
+        device_config = config['devices'][device_name]
+        logging.info(f"Starting monitoring for single device: {device_name}")
+        send_to_mqtt(device_name, device_config, mqtt_config, sleep_interval)
+    else:
+        # Multiple devices mode - would need threading/multiprocessing
+        # For now, let's process the first device and warn about others
+        logging.warning(f"Multiple devices detected ({len(config['devices'])}), but only processing the first one")
+        logging.warning("Multi-device support will require threading implementation")
+        
+        device_name = list(config['devices'].keys())[0]
+        device_config = config['devices'][device_name]
+        logging.info(f"Starting monitoring for device: {device_name}")
+        send_to_mqtt(device_name, device_config, mqtt_config, sleep_interval)
 
 
-send_to_mqtt()
+def main():
+    """Main entry point"""
+    args = parse_arguments()
+    config = load_config(args.config)
+    
+    logging.info("Starting snmp2mqtt bridge...")
+    logging.info(f"Configured devices: {list(config['devices'].keys())}")
+    
+    try:
+        process_devices(config)
+    except KeyboardInterrupt:
+        logging.info("Shutdown requested by user")
+    except Exception as e:
+        logging.error(f"Unexpected error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()