New MQTT adaption

2026-01-04 11:07:38 +01:00
parent b28da4739f
commit 16cc9c1cb4
9 changed files with 1135 additions and 243 deletions
--- a/README.md
+++ b/README.md
@ -1,15 +1,232 @@
-# The Things Network Exporter for VEGAPULS Air
+# TTN VEGAPULS Air Prometheus Exporter

-Export metrics of a VEGAPULS Air connected via TTN as a prometheus service.
+A robust Prometheus exporter for VEGAPULS Air sensors connected via The Things Network (TTN). This exporter provides reliable monitoring with automatic reconnection, uplink caching, and timeout detection.

-## Install ##
+## Features

- `zypper install python311-paho-mqtt`
- `mkdir /opt/ttn-vegapulsair-exporter/`
- `cd /opt/ttn-vegapulsair-exporter/`
- import `ttn-vegapulsair-exporter.py` and `config.py`
- Set the constants in `config.py`
- `chmod +x /opt/ttn-vegapulsair-exporter/ttn-vegapulsair-exporter.py` 
- `chown -R prometheus /opt/ttn-vegapulsair-exporter/`
- `nano /etc/systemd/system/ttn-vegapulsair-exporter.service`
- `systemctl daemon-reload && systemctl enable --now ttn-vegapulsair-exporter.service`
+- **Uplink Caching**: Stores historical data with timestamps for each device
+- **Timeout Detection**: Automatically detects offline sensors (configurable, default 19 hours)
+- **Better Error Handling**: Comprehensive logging and error recovery
+- **Multiple Device Support**: Automatically handles multiple sensors
+
+## Metrics Exported
+
+### Exporter Metrics
+- `vegapulsair_exporter_uptime_seconds` - Exporter uptime in seconds
+- `vegapulsair_exporter_requests_total` - Total number of metrics requests
+- `vegapulsair_devices_total` - Total number of known devices
+- `vegapulsair_devices_online` - Number of currently online devices
+
+### Per-Device Metrics
+All device metrics include a `device_id` label:
+
+#### Status Metrics
+- `vegapulsair_device_online{device_id="..."}` - Device online status (1=online, 0=offline)
+- `vegapulsair_last_uplink_seconds_ago{device_id="..."}` - Seconds since last uplink
+
+#### Sensor Measurements
+- `vegapulsair_distance_mm{device_id="..."}` - Distance measurement in millimeters
+- `vegapulsair_temperature_celsius{device_id="..."}` - Temperature in Celsius
+- `vegapulsair_inclination_degrees{device_id="..."}` - Inclination in degrees
+- `vegapulsair_linear_percent{device_id="..."}` - Linear percentage
+- `vegapulsair_percent{device_id="..."}` - Percentage value
+- `vegapulsair_scaled_value{device_id="..."}` - Scaled measurement value
+- `vegapulsair_battery_percent{device_id="..."}` - Remaining battery percentage
+
+#### LoRaWAN Metadata
+- `vegapulsair_rssi_dbm{device_id="..."}` - RSSI in dBm
+- `vegapulsair_channel_rssi_dbm{device_id="..."}` - Channel RSSI in dBm
+- `vegapulsair_snr_db{device_id="..."}` - Signal-to-Noise Ratio in dB
+
+## Requirements
+
+- Python 3.7 or higher
+- `paho-mqtt` library
+
+## Installation
+
+### Option 1: Manual Installation
+
+1. **Install Python dependencies:**
+   ```bash
+   pip install paho-mqtt --break-system-packages
+   # Or use a virtual environment:
+   python3 -m venv venv
+   source venv/bin/activate
+   pip install paho-mqtt
+   ```
+
+2. **Create installation directory:**
+   ```bash
+   sudo mkdir -p /opt/ttn-vegapuls-exporter
+   cd /opt/ttn-vegapuls-exporter
+   ```
+
+3. **Copy files:**
+   ```bash
+   sudo cp ttn-vegapuls-exporter.py /opt/ttn-vegapuls-exporter/
+   sudo cp config.py /opt/ttn-vegapuls-exporter/
+   sudo chmod +x /opt/ttn-vegapuls-exporter/ttn-vegapuls-exporter.py
+   ```
+
+4. **Configure the exporter:**
+   ```bash
+   sudo nano /opt/ttn-vegapuls-exporter/config.py
+   ```
+   
+   Set the following required parameters:
+   - `ttn_user`: Your TTN application ID (format: `your-app-id@ttn`)
+   - `ttn_key`: Your TTN API key (get from TTN Console)
+   - `ttn_region`: Your TTN region (EU1, NAM1, AU1, etc.)
+
+5. **Set permissions:**
+   ```bash
+   sudo useradd -r -s /bin/false prometheus  # If user doesn't exist
+   sudo chown -R prometheus:prometheus /opt/ttn-vegapuls-exporter
+   ```
+
+6. **Install systemd service:**
+   ```bash
+   sudo cp ttn-vegapuls-exporter.service /etc/systemd/system/
+   sudo systemctl daemon-reload
+   sudo systemctl enable ttn-vegapuls-exporter.service
+   sudo systemctl start ttn-vegapuls-exporter.service
+   ```
+
+7. **Check status:**
+   ```bash
+   sudo systemctl status ttn-vegapuls-exporter.service
+   sudo journalctl -u ttn-vegapuls-exporter.service -f
+   ```
+
+### Option 2: Docker Installation
+See `docker-compose.yml`.
+
+## Configuration
+
+Edit `config.py` to customize the exporter:
+
+```python
+# HTTP Server configuration
+hostName = "0.0.0.0"  # Listen address
+serverPort = 9106      # Port for metrics endpoint
+
+# TTN Configuration
+ttn_user = "your-app@ttn"
+ttn_key = "NNSXS...."  # From TTN Console
+ttn_region = "EU1"
+
+# Timeout configuration
+sensor_timeout_hours = 19  # Mark sensor offline after N hours
+
+# Logging
+log_level = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+```
+
+### Getting TTN Credentials
+
+1. Log in to [TTN Console](https://console.cloud.thethings.network/)
+2. Select your application
+3. Go to **Integrations** → **MQTT**
+4. Copy the following:
+   - **Username**: Your application ID (format: `your-app-id@ttn`)
+   - **Password**: Generate an API key with "Read application traffic" permission
+   - **Region**: Your cluster region (visible in the URL, e.g., `eu1`)
+
+## Prometheus Configuration
+
+Add to your `prometheus.yml`:
+
+```yaml
+scrape_configs:
+  - job_name: 'vegapuls-air'
+    static_configs:
+      - targets: ['localhost:9106']
+    scrape_interval: 60s
+    scrape_timeout: 10s
+```
+
+### Example Prometheus Alerts
+
+See `prometheus-alerts.yml`.
+
+## Troubleshooting
+
+### No Metrics Appearing
+
+1. **Check MQTT connection:**
+   ```bash
+   sudo journalctl -u ttn-vegapuls-exporter.service | grep MQTT
+   ```
+   
+   You should see: `Successfully connected to TTN MQTT broker`
+
+2. **Verify TTN credentials:**
+   - Ensure `ttn_user` format is correct: `your-app-id@ttn`
+   - Verify API key has "Read application traffic" permission
+   - Check region matches your TTN cluster
+
+3. **Test metrics endpoint:**
+   ```bash
+   curl http://localhost:9106/metrics
+   ```
+
+### MQTT Disconnections
+
+The exporter now handles disconnections automatically with exponential backoff. Check logs:
+
+```bash
+sudo journalctl -u ttn-vegapuls-exporter.service -f
+```
+
+If disconnections persist:
+- Check network connectivity to TTN
+- Verify firewall allows outbound port 8883
+- Ensure system time is correct (TLS certificates)
+
+### Devices Not Appearing
+
+1. **Verify devices are sending uplinks:**
+   - Check TTN Console → Applications → Your App → Live Data
+   - Ensure devices are joined and transmitting
+
+2. **Check user ID:**
+   - `ttn_user` must match your TTN application ID exactly
+
+3. **Verify payload decoder:**
+   - Devices must have decoded payload in TTN
+   - Check TTN Payload Formatter is configured
+
+### Debug Mode
+
+Enable debug logging in `config.py`:
+
+```python
+log_level = "DEBUG"
+```
+
+This will show:
+- All MQTT messages received
+- Cache updates
+- Device status changes
+- Detailed error information
+
+### Data Flow
+
+```
+VEGAPULS Air Sensor
+    ↓
+LoRaWAN Gateway
+    ↓
+The Things Network
+    ↓
+MQTT Broker (TLS)
+    ↓
+Exporter (caches data)
+    ↓
+Prometheus (scrapes metrics)
+```
+
+## License
+
+See [LICENSE](LICENSE) file for details.