All guides

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.

topics
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
TopicDirection and access
.../stateYou publish. OBSERVE and CONTROL. Device state and health.
.../telemetryYou publish. OBSERVE and CONTROL. The grid view of the same measurement.
.../helloYou publish. The local connector handshake. Accepted only from CONTROL.
.../receiptYou publish. CONTROL only. Command execution stages.
.../commandsYou 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.

state · 1.0 · BESS
{
  "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.

NameMeaning
stateMust contain online and data_quality. If online is true, all measurements are required and must be finite numbers. An offline state may omit measurements.
telemetryContains 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.
timestampNo older than 30 seconds and no more than 2 seconds in the future. A profile can lower the 30 seconds.
sizeMessages 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.

lab-command-1
{
  "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.

lab-receipt-1
{
  "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>"
}
NameMeaning
stageACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_REQUESTED, RESTORE_EXECUTED, RESTORED or REJECTED.
orderEXECUTED needs ACKNOWLEDGED, MEASURED needs EXECUTED. RESTORE_EXECUTED needs RESTORE_REQUESTED, RESTORED needs RESTORE_EXECUTED. Time never goes backwards.
MEASURED, RESTOREDRefer to a canonical observation: online, data_quality GOOD, at most 5 seconds before the receipt, power matching applied_power_kw.
TTLACKNOWLEDGED, 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.

lab-evidence-ack-1
{
  "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

NameMeaning
OBSERVEThe default level. Publishes state, telemetry and hello. Issued by an Owner, Admin or Developer.
CONTROLAlso 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.
lifetime60 seconds to 7 days. Default 1 day.
rotationThe old credential is revoked before the new one is issued. The new one has a new ID, user name, secret and topic space.
revokeOwner 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

CodeWhat happened
LAB_TOPIC_REQUIREDThe topic is not in the Lab form.
RETAINED_MESSAGE_REJECTEDThe message had the retain flag.
PAYLOAD_TOO_LARGEOver 64 KiB.
CANONICAL_CONTRACT_INVALIDThe JSON or contract failed validation.
OBSERVATION_STALE_OR_FUTUREtimestamp outside the freshness window.
CREDENTIAL_AUTHORITY_DENIEDThe credential is expired, revoked, or the role no longer allows it.
CANONICAL_REGISTRY_SCOPE_DENIEDThe site, edge or asset ID, or the topic, does not match.
STATE_HEALTH_REQUIREDThe state lacks online or data_quality.
LOCAL_POWER_BOUND_EXCEEDEDPower outside the source limits.
LOAD_POLICY_MISMATCHbaseline_kw, power_floor_kw or power_cap_kw do not match the policy.
PAIRED_MEASUREMENT_CONFLICTstate and telemetry with the same time have different measurements.