Home API Reference Telemetry Monitor API

Telemetry Monitor API

API Reference monitor alerts telemetry battery snr rssi temperature threshold rules watchdog notification

Threshold-based alerting — watch node metrics and automatically send mesh messages when conditions are met.

The Telemetry Monitor watches node metrics on a schedule and sends a Meshtastic text message when a threshold condition is triggered. Rules are stored in the main database (DB_PATH). All endpoints are mounted at /api/alerts.

Alert Rule Data Model

id (int)

Auto-incremented primary key.

name (str, required)

Human-readable label for this rule.

target_node (str, required)

Node ID to monitor. E.g. !aabbccdd.

metric (str, required)

Metric to watch. See supported metrics below.

condition (str, required)

below | above | equals

threshold (float, required)

The value to compare against.

check_interval_minutes (int, required)

How often to evaluate this rule. Also acts as the alert cooldown period.

dest_node (str, required)

Node ID to send the alert to. Use ^all to broadcast.

dest_channel (int)

Channel index for the alert message. Default: 0.

is_active (bool)

Whether this rule is enabled. Default: true.

last_checked (float)

Unix timestamp of the last evaluation. Read-only.

last_alerted (float)

Unix timestamp of the last triggered alert. Read-only.

Supported Metrics

metric value	Source field	Unit
`battery_level`	`deviceMetrics.batteryLevel`	%
`voltage`	`deviceMetrics.voltage`	V
`channel_utilization`	`deviceMetrics.channelUtilization`	%
`air_util_tx`	`deviceMetrics.airUtilTx`	%
`snr`	`node.snr`	dB
`rssi`	`node.rssi`	dBm
`temperature`	`environmentMetrics.temperature`	°C
`humidity`	`environmentMetrics.relativeHumidity`	%RH
`pressure`	`environmentMetrics.barometricPressure`	hPa

List All Rules

GET /api/alerts/rules

GET /api/alerts/rules
→ Array of all alert rules

Create Rule

POST /api/alerts/rules

Example: Alert when node !aabbccdd's battery drops below 20%, send to channel 0 every 30 minutes:

POST /api/alerts/rules
Content-Type: application/json

{
  "name": "Low Battery Alert",
  "target_node": "!aabbccdd",
  "metric": "battery_level",
  "condition": "below",
  "threshold": 20.0,
  "check_interval_minutes": 30,
  "dest_node": "^all",
  "dest_channel": 0,
  "is_active": true
}

Returns the created rule with its id, last_checked: 0, and last_alerted: 0.

Update Rule

PUT /api/alerts/rules/{rule_id}

PUT /api/alerts/rules/1
Content-Type: application/json

{
  "name": "Critical Battery",
  "target_node": "!aabbccdd",
  "metric": "battery_level",
  "condition": "below",
  "threshold": 10.0,
  "check_interval_minutes": 15,
  "dest_node": "!mymainnode",
  "dest_channel": 0,
  "is_active": true
}

→ {"status": "success", "id": 1}

Delete Rule

DELETE /api/alerts/rules/{rule_id}

DELETE /api/alerts/rules/1
→ {"status": "deleted", "id": 1}

Test Alert

POST /api/alerts/rules/{rule_id}/test

Sends a test message immediately, bypassing threshold and cooldown checks. Useful for verifying the destination node and channel are correct before deploying a rule.

POST /api/alerts/rules/1/test
→ {
    "status": "test_sent",
    "message": "🧪 TEST ALERT for Low Battery Alert: ALPH monitor is active."
  }

Returns 404 if the rule is not found.

How the Monitor Works

A background asyncio worker (monitor_worker()) runs continuously, sleeping 60 seconds between evaluation cycles. For each active rule it:

Checks if enough time has passed since last_checked (i.e. now - last_checked >= check_interval_minutes * 60)
Looks up the target node in the in-memory node dict
Extracts the metric value using the nested field path
Evaluates the condition: below, above, or equals
If triggered AND the cooldown has elapsed since last_alerted, sends the alert message via the radio connection manager
Updates last_checked (always) and last_alerted (only if fired)

The worker only runs when the radio is connected (connection_manager.is_ready must be set). Rules will not fire when the radio is offline.

Alert message format:

🚨 MONITOR ALERT: ALPH BATTERY_LEVEL is 15.0 (below 20.0)

Core API Endpoints Plugin API