All guides

Explanations · 4 min

How a bounded command works

A bounded command asks a device to change its power briefly, within strict limits, and then return. Each step has its own evidence.

What a bounded command is

It is a single power command with four fields: , power, duration and .

request
POST /v1/lab/assets/{asset_id}/commands
{
  "idempotency_key": "3f0c2a7e-5b1d-4c39-9a51-2b6f0e8d7c10",
  "power_kw": 0.5,
  "duration_seconds": 10,
  "ttl_seconds": 15
}

The reference check for a battery: +0.5 kW for 10 seconds with a 15-second TTL, then back to zero. For a load: -5 kW baseline, curtailment to -3 kW, then a measured return to baseline.

Sign: for a battery, plus is discharge and minus is charge. For a load, consumption is negative.

Limits

power_kw is accepted from -10 to 10 kW. Then the strictest limit applies: the global Lab limit, the profile limits and the source's local limit.

For a battery, power also cannot exceed the available charge or discharge power. SOC must be within the profile limits. The Lab budgets energy for the whole TTL, not only the duration, and checks that SOC stays within limits.

For a load, the target must lie between the power floor and the power cap. The server also checks minimum on and off times.

Duration and TTL

duration_seconds is how long the change lasts. ttl_seconds is how long the command stays valid. Both are 1 to 60 seconds, within the profile limits. The duration cannot be longer than the TTL.

After the duration, the device returns. After the TTL, the command can no longer execute. The connector's local watchdog runs independently of the connection and restores on disconnect, loss of permission, fault, end of duration or TTL.

Idempotency key

idempotency_key is 1 to 128 characters: Latin letters, digits and . _ : -. The key is unique per asset.

The same key with the same request returns the same command, not a new one. The same key with a different request gives 409.

Preconditions

  1. Role

    An Owner, Admin, Developer or Operator can send.

  2. Explicit consent

    An Owner or Admin enabled bounded control and confirmed local writes. Every source starts as observe only.

  3. A live connector

    For MQTT and Home Assistant: a fresh local connector handshake, no older than 5 seconds, with local writes on.

  4. Fresh, healthy state

    Telemetry within freshness, online, no alarms, data quality GOOD, finite numbers. A battery must be idle, at 0 power.

  5. A free slot

    No active or unknown command. No more than 5 new commands per asset per minute.

ReasonWhat it means
WRITE_PERMISSION_REQUIREDControl or local write consent is missing.
STALE_OR_FUTURE_TELEMETRYData is stale or from the future.
DEVICE_NOT_READYThe device is offline, has an alarm, or data quality is not GOOD.
RESTORE_BEFORE_COMMANDThe battery is not at zero yet.
POWER_LIMIT_EXCEEDEDPower is outside the limits.
SOC_OUTSIDE_BOUNDS, SOC_ENERGY_LIMIT_EXCEEDEDSOC is already outside limits, or would leave them within the TTL.
INVALID_DURATION_OR_TTLDuration or TTL out of range, or duration longer than TTL.
MINIMUM_ON_OFF_NOT_METThe load switched too recently.

Separate evidence

REQUESTED and ACCEPTED are cloud facts: the request was admitted. After that, each stage proves something different and has its own source.

StageWhat it proves
ACKNOWLEDGEDThe connector or simulator accepted the command. Power may not have changed yet.
EXECUTEDThe setpoint was actually written to the device.
MEASUREDA separate canonical observation showed the new power.
RESTORE_EXECUTEDThe restore was written to the device. RESTORE_REQUESTED comes before it.
RESTOREDA separate observation showed the return: 0 for a battery, the power measured before the command for a load.

No stage can stand in for another. A measurement does not replace an acknowledgement, and a broker PUBACK is not proof of execution. If state is missing or invalid, the command becomes UNKNOWN and blocks new commands.

Evidence can be exported as a manifest with a SHA-256. It is marked LAB, production_eligible false and physical_qualification UNVERIFIED.

Abort

POST /v1/lab/assets/{asset_id}/commands/{command_id}/abort asks to stop an active command. Turning control off does the same for all active commands.

An accepted abort is not yet a restore. Wait for RESTORED and the measured restore power.

Why nothing is retried automatically

A timeout does not mean rejection. The device may already have changed its power. An automatic retry could apply the command twice.

So the Lab publishes each nonzero frame only once. After a reconnect or restart, a completed command is not replayed. A saved nonzero setpoint is never restored.

If the response is uncertain, check the command history first. To retry safely, send the same request with the same key: the Lab returns the existing command. Create a new key only when the previous command has definitely finished.