From 0391f918094683bbad6e7d24e4db7e79b3628ea4 Mon Sep 17 00:00:00 2001
From: Antoine Van Elstraete <antoine@van-elstraete.net>
Date: Sat, 23 Aug 2025 20:17:34 +0200
Subject: [PATCH] Agent WARP

---
 WARP.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 WARP.md

diff --git a/WARP.md b/WARP.md
new file mode 100644
index 0000000..e76d5e6
--- /dev/null
+++ b/WARP.md
@@ -0,0 +1,112 @@
+# 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