diff --git a/.gitignore b/.gitignore index f568ea2..c2d9205 100644 --- a/.gitignore +++ b/.gitignore @@ -172,3 +172,4 @@ cython_debug/ #.idea/ +WARP.md diff --git a/WARP.md b/WARP.md deleted file mode 100644 index e76d5e6..0000000 --- a/WARP.md +++ /dev/null @@ -1,112 +0,0 @@ -# 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 -```bash -# Activate virtual environment -source bin/activate - -# Install dependencies (if needed) -pip install pysnmp paho-mqtt - -# Check installed packages -pip list -``` - -### Running the Application -```bash -# 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 -```bash -# 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