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

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

Create installation directory:

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

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

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

Set permissions:

sudo useradd -r -s /bin/false prometheus  # If user doesn't exist
sudo chown -R prometheus:prometheus /opt/ttn-vegapulsair-exporter/

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

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

Log in to TTN Console
Select your application
Go to Integrations → MQTT
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

Check MQTT connection:
```
sudo journalctl -u ttn-vegapuls-exporter.service | grep MQTT
```
You should see: Successfully connected to TTN MQTT broker
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
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

Verify devices are sending uplinks:
- Check TTN Console → Applications → Your App → Live Data
- Ensure devices are joined and transmitting
Check user ID:
- ttn_user must match your TTN application ID exactly
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.