Remove WARP.md from repo
This commit is contained in:
1
.gitignore
vendored
1
.gitignore
vendored
@@ -172,3 +172,4 @@ cython_debug/
|
|||||||
#.idea/
|
#.idea/
|
||||||
|
|
||||||
|
|
||||||
|
WARP.md
|
||||||
|
112
WARP.md
112
WARP.md
@@ -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
|
|
Reference in New Issue
Block a user