localhorst/TTN-VEGAPULS-Air-exporter
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity
Files
8423227ae29128873e02290c547fd2c3f9f62847
TTN-VEGAPULS-Air-exporter/README.md
localhorst 8423227ae2 cleanup
2026-01-04 11:32:33 +01:00

10 KiB
Raw Blame History

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

Metric Type Description Example Value
vegapulsair_exporter_uptime_seconds gauge Exporter uptime in seconds 506
vegapulsair_exporter_requests_total counter Total number of metrics requests 39
vegapulsair_devices_total gauge Total number of known devices 1
vegapulsair_devices_online gauge Number of currently online devices 1

Per-Device Metrics

All device metrics include a device_id label (e.g., device_id="eui-04c46100008f6ffe").

Status Metrics

Metric Type Description Example Value
vegapulsair_device_online{device_id="..."} gauge Device online status (1=online, 0=offline) 1
vegapulsair_last_uplink_seconds_ago{device_id="..."} gauge Seconds since last uplink 4

Sensor Measurements

Metric Type Description Example Value
vegapulsair_distance_mm{device_id="..."} gauge Distance measurement in millimeters 0.788
vegapulsair_temperature_celsius{device_id="..."} gauge Temperature in Celsius 190
vegapulsair_inclination_degrees{device_id="..."} gauge Inclination in degrees 3
vegapulsair_linear_percent{device_id="..."} gauge Linear percentage (0-10000, divide by 100 for %) 4743
vegapulsair_percent{device_id="..."} gauge Percentage value (0-10000, divide by 100 for %) 4743
vegapulsair_scaled_value{device_id="..."} gauge Scaled measurement value 1423.024
vegapulsair_scaled_unit{device_id="..."} gauge Unit code for scaled value 41
vegapulsair_packet_identifier{device_id="..."} counter Packet sequence identifier 12
vegapulsair_battery_percent{device_id="..."} gauge Remaining battery percentage 99
vegapulsair_unit{device_id="..."} gauge Unit code for distance measurement 45
vegapulsair_temperature_unit{device_id="..."} gauge Unit code for temperature 32

LoRaWAN Metadata

Metric Type Description Example Value
vegapulsair_rssi_dbm{device_id="..."} gauge RSSI in dBm (signal strength) 42
vegapulsair_channel_rssi_dbm{device_id="..."} gauge Channel RSSI in dBm 42
vegapulsair_snr_db{device_id="..."} gauge Signal-to-Noise Ratio in dB 4.2

Example Output

vegapulsair_exporter_uptime_seconds 506
vegapulsair_exporter_requests_total 39
vegapulsair_devices_total 1
vegapulsair_devices_online 1
vegapulsair_device_online{device_id="eui-04c46100008f6ffe"} 1
vegapulsair_last_uplink_seconds_ago{device_id="eui-04c46100008f6ffe"} 4
vegapulsair_distance_mm{device_id="eui-04c46100008f6ffe"} 0.788
vegapulsair_temperature_celsius{device_id="eui-04c46100008f6ffe"} 190
vegapulsair_inclination_degrees{device_id="eui-04c46100008f6ffe"} 3
vegapulsair_linear_percent{device_id="eui-04c46100008f6ffe"} 4743
vegapulsair_percent{device_id="eui-04c46100008f6ffe"} 4743
vegapulsair_scaled_value{device_id="eui-04c46100008f6ffe"} 1423.024
vegapulsair_scaled_unit{device_id="eui-04c46100008f6ffe"} 41
vegapulsair_packet_identifier{device_id="eui-04c46100008f6ffe"} 12
vegapulsair_battery_percent{device_id="eui-04c46100008f6ffe"} 99
vegapulsair_unit{device_id="eui-04c46100008f6ffe"} 45
vegapulsair_temperature_unit{device_id="eui-04c46100008f6ffe"} 32
vegapulsair_rssi_dbm{device_id="eui-04c46100008f6ffe"} 42
vegapulsair_channel_rssi_dbm{device_id="eui-04c46100008f6ffe"} 42
vegapulsair_snr_db{device_id="eui-04c46100008f6ffe"} 4.2

Metric Notes

  • Percentage values (linear_percent, percent): These are stored as integers 0-10000. To get actual percentage, divide by 100:
    • Example: 4743 / 100 = 47.43%
  • Unit codes: VEGAPULS Air uses numeric codes to indicate measurement units. Refer to VEGAPULS Air documentation for unit code meanings.
  • RSSI: Typical values range from -120 dBm (very weak) to -30 dBm (excellent)
  • SNR: Positive values indicate good signal quality. Values below -15 dB may indicate issues.

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-vegapulsair-exporter.py  /opt/ttn-vegapulsair-exporter
sudo cp config.py /opt/ttn-vegapulsair-exporter/
sudo chmod +x /opt/ttn-vegapulsair-exporter/ttn-vegapulsair-exporter.py 
sudo chmod +x /opt/ttn-vegapulsair-exporter/config.py

  4. Configure the exporter:

    sudo nano /opt/ttn-vegapulsair-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-vegapulsair-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.