MQTT sensor subscription

Receive real-time sensor measurements from StekkerEdge devices via MQTT. This is useful when you want to monitor energy consumption in real-time without polling.

Connection details

Setting	Value
Host	`mqtt.stekker.app`
Port	`8883` (MQTT over TLS)
Protocol	MQTT 3.1.1 or 5.0
TLS	Required

Contact Stekker to receive your credentials and get your resource IDs whitelisted.

Topics

Subscribe to sensor data using this topic pattern:

stekker/resources/{resource_id}/{message_type}

Message type	Topic	Frequency
`measurement`	`.../measurements`	~10 seconds
`heartbeat`	`.../heartbeats`	1 minute
`boot_notification`	`.../boot_notifications`	On device startup (retained)
`network_scan`	`.../network_scans`	On change (retained)

SUBSCRIBEstekker/resources/{id}/measurements

Message: measurement

Readings from connected energy meters, published approximately every 10 seconds.

Example payload

{
  "message_type": "measurement",
  "resource_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "organization_id": "12345678-abcd-4ef0-9876-543210fedcba",
  "data": {
    "sampled_at": "2026-02-05T14:08:55.563571783Z",
    "metrics": [
      {"name": "active_energy_import", "unit": "Wh", "value": 131850280},
      {"name": "total_active_power", "unit": "W", "value": 677909.8125}
    ]
  }
}

The metrics array contains one or more measurements. Common metric names:

total_active_power - Current power consumption (W)
active_energy_import - Total energy imported (Wh)

SUBSCRIBEstekker/resources/{id}/heartbeats

Message: heartbeat

Periodic signal indicating the device is online, published every minute.

Example payload

{
  "message_type": "heartbeat",
  "resource_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "organization_id": "12345678-abcd-4ef0-9876-543210fedcba",
  "published_at": "2026-02-05T14:08:55.563Z"
}

Quick start

Subscribe using mosquitto

# Install: brew install mosquitto (macOS) or apt install mosquitto-clients (Ubuntu)

mosquitto_sub \
  -h mqtt.stekker.app \
  -p 8883 \
  -u "YOUR_USERNAME" \
  -P "YOUR_PASSWORD" \
  --capath /etc/ssl/certs \
  -t "stekker/resources/YOUR_RESOURCE_ID/#" \
  -v

Timestamps

All timestamps are ISO 8601 format (RFC 3339) with UTC timezone:

2026-02-05T14:08:55.563571783Z

JSON Schemas

All messages are validated against JSON Schema (Draft 2020-12).

measurement.schema.json

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Measurement",
  "type": "object",
  "additionalProperties": false,
  "required": ["message_type", "resource_id", "organization_id", "data"],
  "properties": {
    "message_type": { "const": "measurement" },
    "resource_id": { "type": "string", "format": "uuid" },
    "organization_id": { "type": "string", "format": "uuid" },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": ["sampled_at", "metrics"],
      "properties": {
        "sampled_at": { "type": "string", "format": "date-time" },
        "metrics": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["name", "value", "unit"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "value": { "type": "number" },
              "unit": { "type": "string", "minLength": 1 }
            }
          }
        }
      }
    }
  }
}

heartbeat.schema.json

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Heartbeat",
  "type": "object",
  "additionalProperties": false,
  "required": ["message_type", "resource_id", "organization_id", "published_at"],
  "properties": {
    "message_type": { "const": "heartbeat" },
    "resource_id": { "type": "string", "format": "uuid" },
    "organization_id": { "type": "string", "format": "uuid" },
    "published_at": { "type": "string", "format": "date-time" }
  }
}