All guides

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

  1. 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.

  2. 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.

  3. 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.

  4. 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”.

  5. 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.

  6. 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.

  7. 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”.

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
TopicWho does what
stateYou publish device state. OBSERVE and CONTROL.
telemetryYou publish telemetry with the grid view. OBSERVE and CONTROL.
helloYou publish the connector boot message. Both may, but only CONTROL can establish write authority.
receiptYou publish command execution receipts. CONTROL only.
commandsYou 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

QuantityRule
Asset powerkW; positive is discharge, negative is charge.
Load powerFor a controllable load, consumption is negative.
Grid powerkW; positive is import, negative is export.
EnergykWh.
SOC / SOHPercent.
timestampNo 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.

local_cli
python -m services.platform.app.lab.local_cli \
  --credential-file lab-credential.json \
  --journal lab-journal.sqlite \
  --ca-file lab-ca.crt

On 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 seeWhat to do
LAB_BROKER_REQUIREDThe Lab broker is not configured. Credentials cannot be issued; contact the Lab administrator.
TLS / CACheck the CA file and that you connect to exactly the host from the connector setup.
telemetry: 0The 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_REQUIREDNo fresh state and telemetry. Send them regularly, within the freshness limit.
active credential exists; explicitly rotate itActive 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.