AntoineVe/snmp2mqtt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
083cfcce1d5fd3594313a9374fb394a6746d3add
snmp2mqtt/README.md

8.9 KiB
Raw Blame History

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.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

# 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

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

# 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

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