AntoineVe/snmp2mqtt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
23 Commits 6 Branches 1 Tag
main
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

snmp2mqtt

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 (version 7.x) pour la récupération asynchrone des données SNMP avec get_cmd, SnmpEngine et UdpTransportTarget
  • 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

Dépendances principales

  • pysnmp >= 7.0.0 : Bibliothèque SNMP avec nouvelle API asynchrone
  • paho-mqtt >= 2.0.0 : Client MQTT pour la communication avec le broker
  • PyYAML >= 6.0.0 : Parsing des fichiers de configuration YAML

⚠️ Notes importantes sur les versions :

  • pysnmp 7.x : Changements d'API incompatibles avec les versions 6.x et antérieures. L'ancienne classe Slim a été supprimée au profit de get_cmd() avec des objets SnmpEngine, UdpTransportTarget, etc.
  • paho-mqtt 2.x : Nouvelle API de callbacks (VERSION2) qui remplace l'ancienne API deprecated (VERSION1). Les signatures des callbacks ont changé.

Configuration de l'environnement

# 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 :

# 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

# 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

# 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

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

Topics de découverte (Discovery)

Chaque capteur génère un topic de configuration individuel :

homeassistant/{platform}/{node_id}/{object_id}/config

Exemples :

# Capteur de trafic réseau
homeassistant/sensor/mikrotik_hex/mikrotik_hex_starlink_in/config

# Statut de connectivité  
homeassistant/binary_sensor/mikrotik_hex/mikrotik_hex_starlink_status/config

Topics de données

  • État : SNMP/{device_name}/state - Données JSON des capteurs
  • Disponibilité : SNMP/{device_name}/availability - Statut online/offline

Configuration automatique des capteurs

Chaque capteur est configuré avec :

{
  "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

# 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

  5. Erreurs liées à PySNMP

    • "ModuleNotFoundError: No module named 'pysnmp.hlapi.asyncio.slim'" : Vous utilisez une version pysnmp 6.x. Mettez à jour vers >= 7.0.0
    • "Please call .create() to construct UdpTransportTarget object" : Erreur corrigée dans cette version, utilisez pip install -r requirements.txt
    • Erreurs d'importation SNMP : Assurez-vous d'avoir pysnmp 7.x avec pip show pysnmp

  6. Erreurs liées à Paho MQTT

    • "DeprecationWarning: Callback API version 1 is deprecated" : Vous utilisez une version paho-mqtt < 2.0. Mettez à jour vers >= 2.0.0
    • Erreurs de callback MQTT : La nouvelle API VERSION2 change la signature des callbacks (ex: on_connect reçoit maintenant 5 paramètres)
    • Vérification version : pip show paho-mqtt pour confirmer la version installée

Commandes de test utiles

# 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

Le script supporte nativement la surveillance simultanée de plusieurs équipements grâce à une architecture multi-threading :

Fonctionnement

  • Thread indépendant pour chaque équipement configuré
  • Surveillance parallèle : tous les équipements sont surveillés simultanément
  • Isolation des erreurs : la défaillance d'un équipement n'affecte pas les autres
  • Clients MQTT séparés : chaque thread utilise son propre client MQTT
  • Arrêt gracieux : tous les threads s'arrêtent proprement sur signal

Avantages

  • ⚡ Performance optimale : pas de blocage entre équipements
  • 🔄 Traitement parallèle : requêtes SNMP simultanées
  • 🛡️ Robustesse : isolation des défaillances
  • 📊 Scalabilité : facilement extensible à des dizaines d'équipements
  • 🔧 Maintenance : logs clairement identifiés par équipement

Configuration multi-équipements

devices:
  routeur_principal:
    ip: "192.168.10.1"
    snmp_community: "public"
    oids:
      # ... configuration OID ...
  
  switch_bureau:
    ip: "192.168.10.5"
    snmp_community: "public" 
    oids:
      # ... configuration OID ...
  
  point_acces_wifi:
    ip: "192.168.10.10"
    snmp_community: "private"
    oids:
      # ... configuration OID ...

Logs multi-threading

Chaque thread est clairement identifié dans les logs :

(INFO) [Device-routeur_principal] Starting monitoring thread
(INFO) [Device-switch_bureau] MQTT client connected
(DEBUG) [Device-point_acces_wifi] Published state to SNMP/point_acces_wifi/state

Gestion des ressources

  • Clients MQTT uniques : ID client basé sur le nom de l'équipement
  • Topics séparés : chaque équipement a ses propres topics MQTT
  • Discovery HA indépendante : configuration Home Assistant par équipement
  • Disponibilité individuelle : statut online/offline par équipement

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.

Description
Script python pour relayer les infos snmp en mqtt
Readme MIT 128 KiB
Releases 1
Version 1.0.0 Latest
2025-08-24 16:50:04 +02:00
Languages
Python 100%