All guides

How-to guides · 10 min

Connect Home Assistant

A local connector reads Home Assistant through its REST API on your machine and sends canonical data to the Lab over MQTT. The HA address and token never leave your machine.

How it works

In the Lab you only describe a declarative mapping: which HA entities stand for power, SOC, online state and so on. The connector on your side reads those entities, checks units and freshness, and publishes state and telemetry to your credential's topics.

Over Home Assistant only BESS is supported for now. A controllable load over HA is not qualified, and EV / V2X Lab works with the simulator only. Tests run against simulated HA entities, not physical equipment.

Step by step

  1. Add a Home Assistant source

    In the workspace, on the “Connect a source” panel, pick asset type BESS, connection type Home Assistant and click “Add source”.

  2. Fill in the entity mapping

    On the source page open “Home Assistant mapper”. The names in the fields are only examples. For each numeric field set your own entity_id, unit and sign. Separately set the online, fault, write_consent, sample_timestamp and write_target entities, the write unit and sign, and the freshness limit (1–30 seconds).

  3. Validate the mapping

    Click “Validate declarative mapping”. The Lab checks only the shape and shows the status and the mapping SHA256. Whether entities exist and are fresh is checked by the local connector. This validation grants no write permission.

  4. Download the mapping

    Click “Download mapping”. Keep lab-ha-mapping.json next to the connector.

  5. Create the private HA file

    Locally create ha-private.json with home_assistant_url and access_token. On POSIX give it mode 0600. Never upload it to the portal or put it in a profile.

    ha-private.json
    {
      "home_assistant_url": "<your Home Assistant address>",
      "access_token": "<your long-lived access token>"
    }
  6. Issue CONTROL credentials

    The local connector runs only with active CONTROL credentials. An Owner or Admin issues them: choose CONTROL, tick “I authorize this connector to receive bounded Lab commands”, click “Issue one-time credentials” and “Download private file”.

  7. Start the connector

    The “Start the local connector” panel shows the command with your files. Both files are required: the mapping and the private HA configuration.

    local_cli
    python -m services.platform.app.lab.local_cli \
      --credential-file lab-credential.json \
      --journal lab-journal.sqlite \
      --ca-file lab-ca.crt \
      --ha-mapping lab-ha-mapping.json \
      --ha-private-config ha-private.json
  8. Check the data

    In “Outbound connector setup” watch the next action and blockers, and in “Telemetry” the new observations.

Mapping fields

FieldWhat to set
active_powerAn independent asset power meter. W or kW, sign +1 or −1.
soc, sohPercent, sign +1 only.
available_charge, available_dischargeAvailable charge and discharge power. W or kW.
grid_power, site_loadGrid power and site load. W or kW.
online, fault, write_consentbinary_sensor or input_boolean entities.
sample_timestampA sensor entity with the sample time.
write_targetA number or input_number entity the connector writes the setpoint to. It must differ from active_power.
freshness_seconds1 to 30 seconds. Every entity and the sample time must be no older.

Numeric entities are sensor, number or input_number. The connector rejects unknown, unavailable, non-finite, stale and out-of-bounds values.

Writes and control

The connector writes only to the declared write_target. It checks its unit, limits and step locally, including whether zero can be set. A confirmed write is execution evidence; only the independent meter gives measured-response evidence.

Writes need two things: the --allow-local-writes flag and the write_consent entity switched on. After a fresh connector boot an Owner/Admin binds the profile and separately enables bounded control in the Lab.

Keep the HA token local only. The connector attempts restoration to zero even after local consent is withdrawn. If a read or write fails, the outcome stays unknown and new commands are blocked.

A profile for Home Assistant

A profile with connector HOME_ASSISTANT must contain home_assistant_mapping, the same mapping the connector uses. A profile cannot contain tokens or URLs. Tests for such a profile use in-process HA mocks, and the report says so.

Common problems

ReasonWhat to do
INDEPENDENT_POWER_MEASUREMENT_REQUIREDactive_power and write_target are the same entity. Point to a separate meter.
POWER_UNIT_REQUIREDChoose W or kW for power fields.
SOC_SOH_PERCENT_REQUIREDsoc and soh need % and sign +1.
HOME_ASSISTANT_MAPPING_REQUIREDThe HA profile lacks home_assistant_mapping. Add the validated mapping.
LOAD_HOME_ASSISTANT_NOT_QUALIFIEDA controllable load over HA is not qualified. Use the simulator or MQTT.
Local Lab connector stoppedCheck that both HA files are given, the files have mode 0600, and the credentials are active CONTROL and not expired.
FRESH_CANONICAL_TELEMETRY_REQUIREDNo fresh data. Check that the entities update more often than the freshness limit.