snmp2mqtt/WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

snmp2mqtt is a Python script that bridges SNMP network device monitoring with MQTT messaging for Home Assistant integration. It specifically monitors a MikroTik router (Hex) and publishes network interface statistics and status information to MQTT topics for Home Assistant discovery.

Architecture

Core Components

• SNMP Client: Uses pysnmp.hlapi.asyncio.slim for asynchronous SNMP data retrieval from network devices
• MQTT Publisher: Uses paho.mqtt.client to publish data to an MQTT broker
• Home Assistant Integration: Generates device discovery configuration compatible with Home Assistant MQTT Discovery
• Data Processing: Converts SNMP OID values to appropriate data types (int, bool) for Home Assistant sensors

Key Functions

• get_snmp(req): Asynchronously retrieves SNMP data from configured OIDs
• connect_mqtt(mqtt_config): Establishes MQTT broker connection
• publish(topic, client, data, retain, qos): Publishes JSON data to MQTT topics
• ha_create_config(req): Generates Home Assistant device discovery configuration
• send_to_mqtt(): Main loop that continuously publishes config and state data

Configuration Structure

The script uses two main configuration dictionaries:

• req: Defines the target device, SNMP community, and monitored OIDs with Home Assistant metadata
• mqtt_config: MQTT broker connection parameters

Common Development Commands

Environment Setup

# Activate virtual environment
source bin/activate

# Install dependencies (if needed)
pip install pysnmp paho-mqtt

# Check installed packages
pip list

Running the Application

# Run the main script
python snmp2mqtt.py

# Run with Python 3 explicitly
python3 snmp2mqtt.py

# Run from virtual environment
./bin/python snmp2mqtt.py

Development and Testing

# Test SNMP connectivity to device
# (Manual SNMP walk example)
snmpwalk -v2c -c public 192.168.10.2 1.3.6.1.2.1.2.2.1.10

# Monitor MQTT messages (if mosquitto-clients available)
mosquitto_sub -h 192.168.10.202 -u snmp2mqtt -P 'snmp_2_MQTT' -t 'homeassistant/device/+/config'
mosquitto_sub -h 192.168.10.202 -u snmp2mqtt -P 'snmp_2_MQTT' -t 'SNMP/+/state'

# Check network connectivity
ping 192.168.10.2
ping 192.168.10.202

Configuration Notes

Device Configuration

• Hardcoded to monitor MikroTik Hex router at IP 192.168.10.2
• SNMP community: public
• Monitors interfaces: Starlink (index 1), LAN bridge (index 6), VPN (index 12)

MQTT Configuration

• Broker: 192.168.10.202:1883
• Credentials: snmp2mqtt / snmp_2_MQTT
• Config topic: homeassistant/device/{device_id}/config
• State topic: SNMP/{device_name}/state

Monitored Metrics

For each interface:

• Incoming bytes (oid: .1.3.6.1.2.1.2.2.1.10.X) - Published as data_size sensor
• Outgoing bytes (oid: .1.3.6.1.2.1.2.2.1.16.X) - Published as data_size sensor
• Interface status (oid: .1.3.6.1.2.1.2.2.1.8.X) - Published as connectivity binary_sensor

Customization Points

Adding New Devices

1. Create new req configuration dictionary with device details
2. Update mqtt_config if different broker needed
3. Configure appropriate SNMP OIDs for the device type

Adding New OIDs

Each OID entry requires:

• name: Unique identifier for Home Assistant
• oid: SNMP Object Identifier
• type: Python type conversion (int, bool)
• HA_platform: Home Assistant platform (sensor, binary_sensor)
• HA_device_class: Device class for proper Home Assistant categorization
• HA_unit: (optional) Unit of measurement

Home Assistant Integration

The script automatically creates Home Assistant MQTT Discovery configuration with:

• Device identification and grouping
• Sensor types and units appropriate for network monitoring
• Value templates for JSON data extraction