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