# 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

```prometheus
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:**
   ```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-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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   sudo cp ttn-vegapulsair-exporter.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable ttn-vegapulsair-exporter.service
   sudo systemctl start ttn-vegapulsair-exporter.service
   ```

7. **Check status:**
   ```bash
   sudo systemctl status ttn-vegapulsair-exporter.service
   sudo journalctl -u ttn-vegapulsair-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.