Довідка · 8 хв
Поля профілю пристрою
Повний перелік полів схеми lab-device-profile-1: що означає кожне поле, які в нього межі і як виправити помилки валідації.
Загальні правила
Профіль — це лише дані. У ньому немає адрес, паролів, скриптів чи коду. Невідоме поле — це помилка схеми.
Обмеження файлу: до 64 KiB канонічного JSON, без повторених ключів, без NaN та Infinity. Числа пишіть як числа JSON, а не рядки. true і false — без лапок. Ціле поле не приймає 60.0.
Валідація має чотири етапи: SCHEMA, SEMANTIC, SAFETY і EXECUTION. Кожен звітує окремо. Тести виконуються лише тоді, коли SCHEMA і SEMANTIC пройшли.
Загальна межа Lab: 10 кВт, 20 кВт·год, SOC 10–95%, TTL до 60 секунд, свіжість до 30 секунд. Профіль може лише звузити ці межі.
Ідентифікація і версія
| Поле | Значення і межі |
|---|---|
| schema_version | Завжди "lab-device-profile-1". |
| profile_id | Великі латинські літери, цифри й дефіс. Починається з літери. Від 3 до 128 символів. |
| profile_version | Версія X.Y.Z, можна із суфіксом, наприклад 1.2.0-beta.1. До 64 символів. |
| status | DRAFT, VALIDATING, VALIDATED або VALIDATION_FAILED. |
| manufacturer, model | Виробник і модель. Від 1 до 128 символів. |
| description | Необов’язково. До 2000 символів. |
| asset_type | BATTERY, CONTROLLABLE_LOAD, EV_CHARGER або GENERIC_GENERATOR. Тестові набори є лише для BATTERY і CONTROLLABLE_LOAD. |
| supported_firmware | Умови через пробіл, усі мають виконуватись: ">=1.0.0 <2.0.0". Оператори >=, <=, >, <, =. До 256 символів. |
| created_by | Автор. Від 1 до 128 символів. |
| created_at, updated_at | Дата й час ISO 8601 з часовим поясом. |
Хеш визначення рахується без status і updated_at. Порожні необов’язкові поля в нього теж не входять. Тож зміна статусу не змінює хеш.
Lab тестує лише еталонну прошивку 1.0.0. Якщо ваш діапазон її не містить, звіт отримає блокер REFERENCE_FIRMWARE_OUTSIDE_DECLARED_RANGE. Інші версії прошивки у звіті мають статус UNKNOWN.
Підключення
| Поле | Значення і межі |
|---|---|
| connection | SIMULATOR, MQTT або HOME_ASSISTANT. |
| home_assistant_mapping | Потрібне для HOME_ASSISTANT і заборонене для інших. Описує сутності HA: active_power, soc, soh, available_charge, available_discharge, grid_power, site_load, online, fault, write_consent, sample_timestamp, write_target, write_unit, write_sign, freshness_seconds. |
Відповідність HA не містить токена чи URL. write_target не може бути тією самою сутністю, що й active_power: вимір має бути незалежним.
CONTROLLABLE_LOAD через HOME_ASSISTANT поки не кваліфіковано. Такий профіль не пройде валідацію. Для навантажень використовуйте SIMULATOR або MQTT.
Телеметрія
telemetry — список від 1 до 7 відповідностей. Кожна каже, як значення пристрою стає канонічним полем Lab.
| Поле | Значення і межі |
|---|---|
| field | Канонічне поле: asset_active_power_kw, soc_pct, soh_pct, available_charge_power_kw, available_discharge_power_kw, grid_active_power_kw, site_load_kw, baseline_kw, power_floor_kw, power_cap_kw. |
| source_key | Ключ у даних пристрою. Приймає ті самі канонічні назви. |
| unit | W, кВт або %. Значення у W ділиться на 1000. |
| scale | Множник, більше 0 і не більше 1000. Типово 1. |
| sign | Ціле 1 або -1. Типово 1. Перевертає знак, якщо пристрій рахує навпаки. |
Знаки в Lab: потужність активу додатна при розряді й від’ємна при заряді. Потужність мережі додатна при імпорті й від’ємна при експорті. Споживання навантаження — від’ємна потужність.
Обов’язкові поля для BATTERY: asset_active_power_kw, soc_pct, available_charge_power_kw, available_discharge_power_kw. Для CONTROLLABLE_LOAD: asset_active_power_kw, baseline_kw, power_floor_kw, power_cap_kw. Навантаження не може мати SOC, SOH чи доступну потужність заряду й розряду.
Команди
| Поле | Значення і межі |
|---|---|
| types | Рівно ["SET_ACTIVE_POWER"]. |
| writable | Рівно ["asset_active_power_kw"]. |
| target_field | "asset_active_power_kw". |
| protected_configuration_writable | Типово false. Значення true не проходить SAFETY. |
Межі: батарея
| Поле | Значення і межі |
|---|---|
| max_charge_kw, max_discharge_kw | Більше 0, не більше 10. |
| capacity_kwh | Більше 0, не більше 20. |
| soc_min_pct, soc_max_pct | Від 10 до 95. Мінімум має бути менший за максимум. |
| max_duration_seconds | Від 1 до 60. Не більше max_ttl_seconds. |
| max_ttl_seconds | Від 1 до 60. |
| freshness_seconds | Від 1 до 30. Старіші дані блокують команди. |
| baseline_kw | Необов’язково, від -10 до 10, типово 0. |
| minimum_on_seconds, minimum_off_seconds | Необов’язково, від 0 до 60, типово 0. |
Межі: кероване навантаження
Для CONTROLLABLE_LOAD constraints має інший набір полів. Усі обов’язкові. Потужності тут — додатні величини споживання в кВт.
| Поле | Значення і межі |
|---|---|
| baseline_kw | Від 0 до 10. Звичне споживання без команди. |
| power_floor_kw | Від 0 до 10. Найменше дозволене споживання. |
| power_cap_kw | Більше 0, не більше 10. Найбільше дозволене споживання. |
| max_duration_seconds, max_ttl_seconds | Від 1 до 60. Тривалість не більша за TTL. |
| freshness_seconds | Від 1 до 30. |
| minimum_on_seconds, minimum_off_seconds | Від 0 до 60. Скільки секунд навантаження має пробути ввімкненим чи вимкненим перед перемиканням. |
Має виконуватись power_floor_kw <= baseline_kw <= power_cap_kw. Поля батареї, як-от capacity_kwh чи soc_min_pct, тут заборонені.
Безпека
| Поле | Значення і межі |
|---|---|
| ttl_required, fail_closed | Мають бути true. |
| restore_after_ttl, restore_on_disconnect, abort_restores | Мають бути true: повернення після TTL, при розриві зв’язку і при скасуванні. |
| replay_completed | Має бути false. Завершену команду ніколи не повторюють. |
| restore_power_kw | Від -10 до 10. Для батареї 0. Для навантаження дорівнює -baseline_kw. |
| stale_policy, offline_policy | REJECT або IGNORE. Проходить лише REJECT. |
Гнучкість і докази
| Поле | Значення і межі |
|---|---|
| available_up_kw | Від 0 до 10. Батарея: не більше max_discharge_kw. Навантаження: не більше baseline_kw - power_floor_kw. |
| available_down_kw | Від 0 до 10. Батарея: не більше max_charge_kw. Навантаження: не більше power_cap_kw - baseline_kw. |
| response_time_ms | Ціле від 0 до 3000. |
| evidence | Список усіх п’яти етапів: ACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_EXECUTED, RESTORED. |
Власні тестові вектори
tests — до 32 векторів. Вони додаються до стандартного набору. У звіті вектор має назву custom_<vector_id>. Разом прогін має не більше 96 тестів.
| Поле | Значення і межі |
|---|---|
| schema_version | "lab-test-vector-1". |
| vector_id | Малі латинські літери, цифри й _. Починається з літери, до 64 символів. Унікальний. |
| vector_version | Версія X.Y.Z. |
| target_kw | Від -100 до 100. Понад ±10 кВт команда відхиляється, тож очікуйте REJECTED. |
| duration_seconds | Від 1 до 60. |
| ttl_seconds | Від 0 до 60. Значення 0 дає вже прострочену команду. |
| fault | NONE або один збій: INTERNET_DISCONNECT, CONNECTOR_DISCONNECT, TELEMETRY_TIMEOUT, STALE_TIMESTAMP, MALFORMED_TELEMETRY, OUT_OF_RANGE_TELEMETRY, DEVICE_FAULT, METER_UNAVAILABLE, ACK_TIMEOUT, EXECUTION_TIMEOUT, RECONNECT, DUPLICATE_ACK, DELAYED_TELEMETRY, CLOCK_SKEW. |
| expected_status | RESTORED, REJECTED, EXPIRED або UNKNOWN. |
| initial_soc_pct | Лише для батареї, і там обов’язкове. Від 10 до 95. У векторі навантаження заборонене. |
{
"schema_version": "lab-test-vector-1",
"vector_id": "short_discharge",
"vector_version": "1.0.0",
"target_kw": 2,
"duration_seconds": 10,
"ttl_seconds": 30,
"fault": "NONE",
"expected_status": "RESTORED",
"initial_soc_pct": 50
}Приклад
Це еталонний профіль батареї з Lab. Він навчальний і не описує реальний продукт.
{
"schema_version": "lab-device-profile-1",
"profile_id": "WF-PROFILE-LAB-BATTERY-001",
"profile_version": "0.1.0",
"status": "DRAFT",
"manufacturer": "Wesfin Lab",
"model": "Deterministic reference BESS",
"asset_type": "BATTERY",
"supported_firmware": "1.0.0",
"created_by": "lab-author",
"created_at": "2026-10-20T09:00:00+00:00",
"updated_at": "2026-10-20T09:00:00+00:00",
"connection": "SIMULATOR",
"telemetry": [
{"field": "asset_active_power_kw", "source_key": "asset_active_power_kw", "unit": "kW"},
{"field": "soc_pct", "source_key": "soc_pct", "unit": "%"},
{"field": "soh_pct", "source_key": "soh_pct", "unit": "%"},
{"field": "available_charge_power_kw", "source_key": "available_charge_power_kw", "unit": "kW"},
{"field": "available_discharge_power_kw", "source_key": "available_discharge_power_kw", "unit": "kW"},
{"field": "grid_active_power_kw", "source_key": "grid_active_power_kw", "unit": "kW"},
{"field": "site_load_kw", "source_key": "site_load_kw", "unit": "kW"}
],
"commands": {"types": ["SET_ACTIVE_POWER"], "writable": ["asset_active_power_kw"], "target_field": "asset_active_power_kw"},
"constraints": {"max_charge_kw": 10, "max_discharge_kw": 10, "capacity_kwh": 20,
"soc_min_pct": 10, "soc_max_pct": 95, "max_duration_seconds": 60,
"max_ttl_seconds": 60, "freshness_seconds": 30},
"safety": {"ttl_required": true, "fail_closed": true, "restore_after_ttl": true,
"restore_on_disconnect": true, "abort_restores": true, "replay_completed": false,
"restore_power_kw": 0, "stale_policy": "REJECT", "offline_policy": "REJECT"},
"flexibility": {"available_up_kw": 10, "available_down_kw": 10, "response_time_ms": 1000},
"evidence": ["ACKNOWLEDGED", "EXECUTED", "MEASURED", "RESTORE_EXECUTED", "RESTORED"],
"tests": []
}Для навантаження змінюються тип, телеметрія, межі, потужність відновлення і гнучкість:
"asset_type": "CONTROLLABLE_LOAD",
"telemetry": [
{"field": "asset_active_power_kw", "source_key": "asset_active_power_kw", "unit": "kW"},
{"field": "baseline_kw", "source_key": "baseline_kw", "unit": "kW"},
{"field": "power_floor_kw", "source_key": "power_floor_kw", "unit": "kW"},
{"field": "power_cap_kw", "source_key": "power_cap_kw", "unit": "kW"}
],
"constraints": {"baseline_kw": 5, "power_floor_kw": 0, "power_cap_kw": 10,
"max_duration_seconds": 60, "max_ttl_seconds": 60, "freshness_seconds": 30,
"minimum_on_seconds": 2, "minimum_off_seconds": 2},
"safety": { ... "restore_power_kw": -5 ... },
"flexibility": {"available_up_kw": 5, "available_down_kw": 5, "response_time_ms": 1000}Помилки валідації
SCHEMA показує шлях до поля і тип помилки, наприклад missing, extra_forbidden, literal_error, string_pattern_mismatch чи less_than_equal. Показується до 32 помилок. Невідповідність типу активу і меж чи векторів теж падає тут з типом value_error.
| Код | Що виправити |
|---|---|
| INVALID_PROFILE_DATA | Файл не читається як JSON, більший за 64 KiB, має повторений ключ або NaN. Виправте сам JSON. |
| FIRMWARE_RANGE_EMPTY | Жодна версія не задовольняє всі умови supported_firmware. Розширте діапазон. |
| HOME_ASSISTANT_MAPPING_REQUIRED | Додайте home_assistant_mapping або змініть connection. |
| HOME_ASSISTANT_MAPPING_CONNECTOR_MISMATCH | Приберіть home_assistant_mapping: він лише для HOME_ASSISTANT. |
| DUPLICATE_TELEMETRY_MAPPING | Кожне field і кожне source_key має бути лише раз. |
| SAFETY_TELEMETRY_MISSING | Додайте обов’язкові поля телеметрії для свого типу активу. |
| LOAD_BATTERY_TELEMETRY_FORBIDDEN | Приберіть soc_pct, soh_pct і доступну потужність заряду й розряду з навантаження. |
| LOAD_HOME_ASSISTANT_NOT_QUALIFIED | Для навантаження оберіть SIMULATOR або MQTT. |
| MAPPING_DIMENSION_MISMATCH | Відсоток можна зіставити лише з відсотком, потужність — з потужністю. |
| PERCENT_MAPPING_INVALID | Для полів _pct: unit "%", scale 1, sign 1. |
| POWER_MAPPING_UNIT_INVALID | Для полів потужності unit має бути W або кВт. |
| CONSTRAINT_ORDER_INVALID | Перевірте: soc_min_pct < soc_max_pct, тривалість <= TTL, power_floor_kw <= baseline_kw <= power_cap_kw. |
| FLEXIBILITY_EXCEEDS_DEVICE_LIMIT | Зменште available_up_kw чи available_down_kw до меж пристрою. |
| DUPLICATE_TEST_VECTOR | Дайте кожному вектору свій vector_id. |
| ttl_required, fail_closed, restore_after_ttl, restore_on_disconnect, abort_restores | SAFETY називає поле, яке не true. Встановіть true. |
| UNSAFE_RECOVERY_POLICY | replay_completed false, обидві політики REJECT, restore_power_kw 0 для батареї або -baseline_kw для навантаження. |
| PROTECTED_CONFIGURATION_WRITE | Встановіть protected_configuration_writable у false. |
| DISTINCT_EVIDENCE_REQUIRED | Вкажіть усі п’ять етапів у evidence. |
| ASSET_TYPE_PACK_NOT_QUALIFIED | Для EV_CHARGER і GENERIC_GENERATOR тестового набору ще немає. Профіль не стане VALIDATED. |
| REFERENCE_FIRMWARE_OUTSIDE_DECLARED_RANGE | Включіть 1.0.0 у supported_firmware. |
Якщо впав тест на етапі EXECUTION, блокером стає назва тесту. Відкрийте його у звіті: там є вхідні дані, очікування, спостереження і причина.