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:

   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:

   sudo mkdir -p /opt/ttn-vegapuls-exporter
   cd /opt/ttn-vegapuls-exporter
   

3. Copy files:

   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:

   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:

   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:

   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:

   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:

# 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
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:

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:

   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:

   curl http://localhost:9106/metrics
   

MQTT Disconnections

The exporter now handles disconnections automatically with exponential backoff. Check logs:

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:

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 file for details.