Довідка · 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 облікових даних.
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 сайту, шлюзу й активу беріть із налаштування джерела.
{
"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 тривалість не більша за це вікно.
{
"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.
{
"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>"
}| Назва | Значення |
|---|---|
| stage | ACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_REQUESTED, RESTORE_EXECUTED, RESTORED або REJECTED. |
| order | EXECUTED потребує ACKNOWLEDGED, MEASURED потребує EXECUTED. RESTORE_EXECUTED потребує RESTORE_REQUESTED, RESTORED потребує RESTORE_EXECUTED. Час не йде назад. |
| MEASURED, RESTORED | Посилаються на канонічне спостереження: online, data_quality GOOD, не старше 5 секунд від квитанції, потужність збігається з applied_power_kw. |
| TTL | ACKNOWLEDGED, EXECUTED і MEASURED після valid_until відхиляються. Після RESTORE_EXECUTED нових позитивних етапів немає. |
Коли Lab зберіг квитанцію, він надсилає у commands підтвердження доказу з receipt_id і хешем точного вмісту. Лише після нього конектор прибирає квитанцію зі своєї черги.
{
"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_INVALID | JSON чи контракт не пройшли перевірку. |
| OBSERVATION_STALE_OR_FUTURE | timestamp поза вікном свіжості. |
| CREDENTIAL_AUTHORITY_DENIED | Облікові дані прострочені, відкликані або роль більше не дозволяє. |
| CANONICAL_REGISTRY_SCOPE_DENIED | ID сайту, шлюзу чи активу або топік не збігаються. |
| STATE_HEALTH_REQUIRED | У state немає online чи data_quality. |
| LOCAL_POWER_BOUND_EXCEEDED | Потужність поза межами джерела. |
| LOAD_POLICY_MISMATCH | baseline_kw, power_floor_kw чи power_cap_kw не збігаються з політикою. |
| PAIRED_MEASUREMENT_CONFLICT | state і telemetry з тим самим часом мають різні виміри. |