Усі посібники

Довідка · 6 хв

MQTT топіки й повідомлення

Топіки, повідомлення, підтвердження і правила доступу для MQTT-джерела в Lab. Усе тут — лише для середовища LAB.

Підключення до брокера

Брокер Lab окремий від виробничого MQTT. Адресу і порт показує налаштування джерела. Типовий порт — 8883.

З’єднання лише через TLS 1.2 або новіший. Клієнт перевіряє сертифікат брокера за довіреним CA та ім’я хоста. Анонімного входу, відкритого тексту, чужого CA чи іншого імені хоста немає.

Вхід — за ім’ям користувача і паролем з облікових даних Lab. Клієнтські сертифікати (mTLS) в облікових даних Lab зараз не видаються. Lab використовує MQTT 5.

Пароль показується один раз, у відповіді на видачу. Lab зберігає лише його хеш. Тримайте файл облікових даних локально; на POSIX з правами 0600.

Топіки

Кожні облікові дані мають свій точний простір топіків. Його складають ID робочого простору, канонічний ID активу і 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
ТопікНапрям і доступ
.../stateВи публікуєте. OBSERVE і CONTROL. Стан і здоров’я пристрою.
.../telemetryВи публікуєте. OBSERVE і CONTROL. Погляд мережі на той самий вимір.
.../helloВи публікуєте. Рукостискання локального конектора. Приймається лише від CONTROL.
.../receiptВи публікуєте. Лише CONTROL. Етапи виконання команди.
.../commandsВи підписуєтесь. Лише CONTROL. Кадри команд і підтвердження доказів від Lab.

Публікуйте з QoS 1 і retain false. Retained-повідомлення на брокері Lab вимкнені, а Lab відхиляє будь-яке retained-повідомлення.

Стан і телеметрія

state і telemetry — канонічні контракти платформи. Для батареї версія 1.0. Для керованого навантаження версія 1.1 з asset_type, baseline_kw, power_floor_kw, power_cap_kw і last_transition_at. ID сайту, шлюзу й активу беріть із налаштування джерела.

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"
}

Одиниці: потужність у кВт, енергія в кВт·год, SOC і SOH у відсотках. Потужність активу додатна при розряді й від’ємна при заряді. Потужність мережі додатна при імпорті й від’ємна при експорті.

НазваЗначення
stateМає містити online і data_quality. Якщо online true, потрібні всі виміри, і вони мають бути скінченними числами. Офлайн-стан може бути без вимірів.
telemetryМістить grid_active_power_kw і site_load_kw. Має той самий timestamp, що й state для того самого виміру. Порядок приходу не важливий.
timestampНе старше 30 секунд і не більше ніж на 2 секунди в майбутньому. Профіль може зменшити 30 секунд.
sizeПовідомлення до 64 KiB. Без повторених ключів JSON і без NaN.

Точний дублікат не створює нового спостереження. Застарілий або суперечливий стан з тим самим часом лишається в історії, але не перезаписує поточний стан.

Кадр команди

Lab надсилає кадр у топік commands. action — SET_POWER, RESTORE_ZERO (батарея) або RESTORE_BASELINE (навантаження). power_kw від -10 до 10. Між issued_at і valid_until — не більше 60 секунд. Для SET_POWER тривалість не більша за це вікно.

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>"
}

Кадр завжди несе environment LAB і production_eligible false. Lab публікує кожен ненульовий кадр лише раз і ніколи не повторює його.

Підтвердження і докази

PUBACK брокера означає лише, що брокер отримав повідомлення. Це не доказ виконання на пристрої і не доказ, що Lab прийняв дані.

Після рукостискання hello і дозволу на запис конектор повідомляє кожен етап окремою квитанцією в топік receipt.

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>"
}
НазваЗначення
stageACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_REQUESTED, RESTORE_EXECUTED, RESTORED або REJECTED.
orderEXECUTED потребує ACKNOWLEDGED, MEASURED потребує EXECUTED. RESTORE_EXECUTED потребує RESTORE_REQUESTED, RESTORED потребує RESTORE_EXECUTED. Час не йде назад.
MEASURED, RESTOREDПосилаються на канонічне спостереження: online, data_quality GOOD, не старше 5 секунд від квитанції, потужність збігається з applied_power_kw.
TTLACKNOWLEDGED, EXECUTED і MEASURED після valid_until відхиляються. Після RESTORE_EXECUTED нових позитивних етапів немає.

Коли Lab зберіг квитанцію, він надсилає у commands підтвердження доказу з receipt_id і хешем точного вмісту. Лише після нього конектор прибирає квитанцію зі своєї черги.

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 несе ID сесії, профіль, політику, хеш коду конектора й моделі та стан локального дозволу на запис. Lab перевіряє, що хеш коду й політики збігаються з очікуваними. Нове завантаження конектора вимикає запис із хмари, доки власник чи адміністратор знову не дасть згоду.

Правила доступу

НазваЗначення
OBSERVEТиповий рівень. Публікує state, telemetry і hello. Видають власник, адміністратор або розробник.
CONTROLЩе публікує receipt і отримує свій топік commands. Видають лише власник або адміністратор з явним підтвердженням. Сам по собі не вмикає команди.
lifetimeВід 60 секунд до 7 днів. Типово 1 день.
rotationСтарі дані відкликаються до видачі нових. Нові мають новий ID, ім’я, секрет і простір топіків.
revokeЛише власник або адміністратор. REVOKING означає, що доступ у Lab уже закрито, а очищення на брокері ще не підтверджене.

Жодні облікові дані не читають інший актив чи робочий простір, не підписуються на #, не мають доступу до $CONTROL і не пишуть у виробничі топіки. Lab перевіряє права на кожне повідомлення, навіть до очищення на брокері.

Причини відхилення

КодЩо сталося
LAB_TOPIC_REQUIREDТопік не має форми Lab.
RETAINED_MESSAGE_REJECTEDПовідомлення мало прапорець retain.
PAYLOAD_TOO_LARGEБільше 64 KiB.
CANONICAL_CONTRACT_INVALIDJSON чи контракт не пройшли перевірку.
OBSERVATION_STALE_OR_FUTUREtimestamp поза вікном свіжості.
CREDENTIAL_AUTHORITY_DENIEDОблікові дані прострочені, відкликані або роль більше не дозволяє.
CANONICAL_REGISTRY_SCOPE_DENIEDID сайту, шлюзу чи активу або топік не збігаються.
STATE_HEALTH_REQUIREDУ state немає online чи data_quality.
LOCAL_POWER_BOUND_EXCEEDEDПотужність поза межами джерела.
LOAD_POLICY_MISMATCHbaseline_kw, power_floor_kw чи power_cap_kw не збігаються з політикою.
PAIRED_MEASUREMENT_CONFLICTstate і telemetry з тим самим часом мають різні виміри.