Reference · 6 min
MQTT topics and messages
Topics, messages, acknowledgements and access rules for an MQTT source in the Lab. Everything here is for the LAB environment only.
Connecting to the broker
The Lab broker is separate from production MQTT. The source setup shows its address and port. The default port is 8883.
Connections use TLS 1.2 or later only. The client checks the broker certificate against the trusted CA and checks the host name. There is no anonymous login, plain text, untrusted CA or other host name.
Login uses the user name and password from the Lab credential. Client certificates (mTLS) are not issued with Lab credentials today. The Lab uses MQTT 5.
The password is shown once, in the issuance response. The Lab keeps only its hash. Keep the credential file local; on POSIX with mode 0600.
Topics
Each credential has its own exact topic space. It is built from the workspace ID, the canonical asset ID and the credential ID.
lab/v1/workspaces/{workspace_uuid}/assets/{canonical_asset_id}/credentials/{credential_uuid}/state
lab/v1/workspaces/{workspace_uuid}/assets/{canonical_asset_id}/credentials/{credential_uuid}/telemetry
lab/v1/workspaces/{workspace_uuid}/assets/{canonical_asset_id}/credentials/{credential_uuid}/hello
lab/v1/workspaces/{workspace_uuid}/assets/{canonical_asset_id}/credentials/{credential_uuid}/receipt
lab/v1/workspaces/{workspace_uuid}/assets/{canonical_asset_id}/credentials/{credential_uuid}/commands| Topic | Direction and access |
|---|---|
| .../state | You publish. OBSERVE and CONTROL. Device state and health. |
| .../telemetry | You publish. OBSERVE and CONTROL. The grid view of the same measurement. |
| .../hello | You publish. The local connector handshake. Accepted only from CONTROL. |
| .../receipt | You publish. CONTROL only. Command execution stages. |
| .../commands | You subscribe. CONTROL only. Command frames and evidence acknowledgements from the Lab. |
Publish with QoS 1 and retain false. Retained messages are disabled on the Lab broker, and the Lab rejects any retained message.
State and telemetry
state and telemetry are the platform's canonical contracts. For a battery, version 1.0. For a controllable load, version 1.1 with asset_type, baseline_kw, power_floor_kw, power_cap_kw and last_transition_at. Take the site, edge and asset IDs from the source setup.
{
"schema_version": "1.0",
"site_id": "<site_id from setup>",
"edge_id": "<edge_id from setup>",
"asset_id": "<asset_id from setup>",
"timestamp": "2026-10-20T09:00:00+00:00",
"online": true,
"asset_active_power_kw": 0,
"soc_pct": 50,
"soh_pct": 100,
"available_charge_power_kw": 10,
"available_discharge_power_kw": 10,
"alarm_state": "NONE",
"data_quality": "GOOD"
}Units: power in kW, energy in kWh, SOC and SOH in percent. Asset power is positive when discharging and negative when charging. Grid power is positive on import and negative on export.
| Name | Meaning |
|---|---|
| state | Must contain online and data_quality. If online is true, all measurements are required and must be finite numbers. An offline state may omit measurements. |
| telemetry | Contains grid_active_power_kw and site_load_kw. It has the same timestamp as the state for the same measurement. Arrival order does not matter. |
| timestamp | No older than 30 seconds and no more than 2 seconds in the future. A profile can lower the 30 seconds. |
| size | Messages up to 64 KiB. No repeated JSON keys and no NaN. |
An exact duplicate creates no new observation. A stale or conflicting state with the same time stays in history but does not overwrite the current state.
Command frame
The Lab sends a frame to the commands topic. action is SET_POWER, RESTORE_ZERO (battery) or RESTORE_BASELINE (load). power_kw is -10 to 10. issued_at to valid_until is at most 60 seconds. For SET_POWER the duration fits inside that window.
{
"protocol": "lab-command-1",
"environment": "LAB",
"production_eligible": false,
"workspace_id": "<uuid>", "asset_id": "<asset_id>",
"credential_id": "<uuid>", "session_id": "<uuid>", "original_session_id": "<uuid>",
"command_id": "<uuid>", "dispatch_token": "<uuid>",
"capability_kind": "BESS",
"action": "SET_POWER",
"power_kw": 0.5,
"duration_seconds": 10,
"issued_at": "2026-10-20T09:00:00+00:00",
"valid_until": "2026-10-20T09:00:15+00:00",
"policy_hash": "<64 hex>", "source_hash": "<64 hex>"
}A frame always carries environment LAB and production_eligible false. The Lab publishes each nonzero frame once and never republishes it.
Acknowledgements and evidence
A broker PUBACK only means the broker received the message. It is not proof of execution on the device, nor proof that the Lab accepted the data.
After the hello handshake and write consent, the connector reports each stage as a separate receipt on the receipt topic.
{
"protocol": "lab-receipt-1",
"receipt_id": "<uuid>", "command_id": "<uuid>", "dispatch_token": "<uuid>",
"session_id": "<uuid>", "original_session_id": "<uuid>",
"timestamp": "2026-10-20T09:00:01+00:00",
"stage": "MEASURED",
"applied_power_kw": 0.5,
"observation_fingerprint": "<64 hex>"
}| Name | Meaning |
|---|---|
| stage | ACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_REQUESTED, RESTORE_EXECUTED, RESTORED or REJECTED. |
| order | EXECUTED needs ACKNOWLEDGED, MEASURED needs EXECUTED. RESTORE_EXECUTED needs RESTORE_REQUESTED, RESTORED needs RESTORE_EXECUTED. Time never goes backwards. |
| MEASURED, RESTORED | Refer to a canonical observation: online, data_quality GOOD, at most 5 seconds before the receipt, power matching applied_power_kw. |
| TTL | ACKNOWLEDGED, EXECUTED and MEASURED after valid_until are rejected. After RESTORE_EXECUTED there are no new positive stages. |
Once the Lab has stored a receipt, it sends an evidence acknowledgement to commands with the receipt_id and a hash of the exact payload. Only then does the connector remove the receipt from its queue.
{
"protocol": "lab-evidence-ack-1",
"workspace_id": "<uuid>", "asset_id": "<asset_id>", "credential_id": "<uuid>",
"receipt_id": "<uuid>", "payload_hash": "<64 hex>"
}hello carries the session ID, profile, policy, the connector source and model hashes and the local write consent. The Lab checks that the source and policy hashes match. A fresh connector boot turns cloud writes off until an Owner or Admin consents again.
Access rules
| Name | Meaning |
|---|---|
| OBSERVE | The default level. Publishes state, telemetry and hello. Issued by an Owner, Admin or Developer. |
| CONTROL | Also publishes receipt and receives its own commands topic. Only an Owner or Admin issues it, with explicit confirmation. On its own it does not enable commands. |
| lifetime | 60 seconds to 7 days. Default 1 day. |
| rotation | The old credential is revoked before the new one is issued. The new one has a new ID, user name, secret and topic space. |
| revoke | Owner or Admin only. REVOKING means Lab access is already closed but broker cleanup is not confirmed yet. |
No credential can read another asset or workspace, subscribe to #, reach $CONTROL or write production topics. The Lab checks authority on every message, even before broker cleanup.
Rejection reasons
| Code | What happened |
|---|---|
| LAB_TOPIC_REQUIRED | The topic is not in the Lab form. |
| RETAINED_MESSAGE_REJECTED | The message had the retain flag. |
| PAYLOAD_TOO_LARGE | Over 64 KiB. |
| CANONICAL_CONTRACT_INVALID | The JSON or contract failed validation. |
| OBSERVATION_STALE_OR_FUTURE | timestamp outside the freshness window. |
| CREDENTIAL_AUTHORITY_DENIED | The credential is expired, revoked, or the role no longer allows it. |
| CANONICAL_REGISTRY_SCOPE_DENIED | The site, edge or asset ID, or the topic, does not match. |
| STATE_HEALTH_REQUIRED | The state lacks online or data_quality. |
| LOCAL_POWER_BOUND_EXCEEDED | Power outside the source limits. |
| LOAD_POLICY_MISMATCH | baseline_kw, power_floor_kw or power_cap_kw do not match the policy. |
| PAIRED_MEASUREMENT_CONFLICT | state and telemetry with the same time have different measurements. |