# 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