TTN-VEGAPULS-Air-exporter/README.md

# TTN VEGAPULS Air Prometheus Exporter

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.

## Features

- **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.