How-to guides · 10 min
Connect a device over MQTT
This guide takes you from a new MQTT source to the first telemetry in the Lab. You issue credentials, connect to the Lab broker over TLS and publish state and telemetry to your own topics.
Before you start
An Owner, Admin or Developer role in the workspace. A device or gateway that speaks MQTT over TLS 1.2 or later and verifies the broker certificate and hostname.
The Lab broker is isolated from production. There is no anonymous, plaintext or unverified-certificate login.
The Lab is a test environment only. Connecting to it gives no access to production, the market or real Wesfin Flex sites.
Step by step
Add an MQTT source
In the workspace, on the “Connect a source” panel, click “Create project”. Then under “Add a source” pick the asset type BESS or “Controllable load”, connection type MQTT, and click “Add source”. EV / V2X Lab works with the simulator only.
Open the Connector section
On the source page, the “Outbound connector setup” panel shows the TLS broker (host and port), the Asset / Site / Edge IDs, the next action and blockers. Use exactly this host and port. If it says “Not configured”, no broker is set up for this Lab and credentials cannot be issued.
Issue credentials
On the “Connector credentials” panel keep the capability OBSERVE, set a lifetime from 60 to 604800 seconds (default 86400, one day) and click “Issue one-time credentials”. See the credentials guide for details.
Save the private file
Click “Download private file”. lab-credential.json holds the username, password, broker host and port, your topics and the canonical IDs. The password is never shown again. Then click “Dismiss and clear secret”.
Connect to the broker
Connect over TLS with the username and password from the file. The client must trust the Lab broker CA and verify the hostname.
Publish state and telemetry
Publish the canonical state and telemetry v1.0 contracts (v1.1 for a controllable load) to your state and telemetry topics. Take the IDs from the connector setup. Do not set the retain flag.
Check the result
On the source page the “Telemetry” panel shows observations, and “Data” in the top strip shows freshness. If nothing appears, see “Common problems” below.
Your topics
Each credential has its own set of topics. The exact paths are in the private file and in “This connector's 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| Topic | Who does what |
|---|---|
| state | You publish device state. OBSERVE and CONTROL. |
| telemetry | You publish telemetry with the grid view. OBSERVE and CONTROL. |
| hello | You publish the connector boot message. Both may, but only CONTROL can establish write authority. |
| receipt | You publish command execution receipts. CONTROL only. |
| commands | You subscribe to and receive Lab commands. CONTROL only. |
Subscribing to #, topics of another asset or workspace, and any production topic are denied.
Units, signs and time
| Quantity | Rule |
|---|---|
| Asset power | kW; positive is discharge, negative is charge. |
| Load power | For a controllable load, consumption is negative. |
| Grid power | kW; positive is import, negative is export. |
| Energy | kWh. |
| SOC / SOH | Percent. |
| timestamp | No older than 30 seconds and no more than 2 seconds in the future. |
State and telemetry for one sample share the timestamp and BESS readings. Arrival order does not matter. Exact duplicates do not create a new observation.
A broker acknowledgement (PUBACK) does not mean the Lab accepted the sample. Look at the “Telemetry” panel.
The reference local connector
Instead of your own client you can run the reference connector. It needs CONTROL credentials, a local journal and the broker CA certificate. The “Start the local connector” panel shows the command.
python -m services.platform.app.lab.local_cli \
--credential-file lab-credential.json \
--journal lab-journal.sqlite \
--ca-file lab-ca.crtOn POSIX the credential file must have mode 0600. Local writes are off by default; the --allow-local-writes flag is a separate explicit local consent.
Add --allow-local-writes only after checking the limits. Even then, commands flow only after an Owner/Admin separately enables bounded control in the Lab. Reference tests do not qualify physical devices.
Common problems
| What you see | What to do |
|---|---|
| LAB_BROKER_REQUIRED | The Lab broker is not configured. Credentials cannot be issued; contact the Lab administrator. |
| TLS / CA | Check the CA file and that you connect to exactly the host from the connector setup. |
| telemetry: 0 | The sample was rejected. Check the device clock (30 s / 2 s), topic and IDs, units, power limits, the retain flag, duplicate JSON keys and NaN. |
| FRESH_CANONICAL_TELEMETRY_REQUIRED | No fresh state and telemetry. Send them regularly, within the freshness limit. |
| active credential exists; explicitly rotate it | Active credentials already exist. Tick rotation or revoke the old ones first. |
| Local Lab connector stopped (CREDENTIAL_EXPIRED) | The lifetime has ended. Issue new credentials and restart the connector. |