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

Довідка · 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 символів.
statusDRAFT, VALIDATING, VALIDATED або VALIDATION_FAILED.
manufacturer, modelВиробник і модель. Від 1 до 128 символів.
descriptionНеобов’язково. До 2000 символів.
asset_typeBATTERY, 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.

Підключення

ПолеЗначення і межі
connectionSIMULATOR, 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Ключ у даних пристрою. Приймає ті самі канонічні назви.
unitW, кВт або %. Значення у 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_policyREJECT або 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 дає вже прострочену команду.
faultNONE або один збій: 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_statusRESTORED, REJECTED, EXPIRED або UNKNOWN.
initial_soc_pctЛише для батареї, і там обов’язкове. Від 10 до 95. У векторі навантаження заборонене.
tests[0] · BATTERY
{
  "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. Він навчальний і не описує реальний продукт.

lab-device-profile-1 · BATTERY
{
  "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": []
}

Для навантаження змінюються тип, телеметрія, межі, потужність відновлення і гнучкість:

CONTROLLABLE_LOAD
"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_restoresSAFETY називає поле, яке не true. Встановіть true.
UNSAFE_RECOVERY_POLICYreplay_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, блокером стає назва тесту. Відкрийте його у звіті: там є вхідні дані, очікування, спостереження і причина.