Як зробити · 10 хв
Підключити Home Assistant
Локальний конектор читає Home Assistant через його REST API на вашому комп’ютері і надсилає канонічні дані в Lab через MQTT. Адреса HA і токен ніколи не залишають вашу машину.
Як це працює
У Lab ви описуєте лише декларативну мапу: які сутності HA відповідають потужності, SOC, стану зв’язку тощо. Конектор на вашому боці читає ці сутності, перевіряє одиниці й свіжість і публікує стан і телеметрію у топіки ваших облікових даних.
Через Home Assistant зараз підтримується лише BESS. Кероване навантаження через HA не кваліфіковане, а EV / V2X Lab працює тільки із симулятором. Тести проходять на симульованих сутностях HA, а не на фізичному обладнанні.
Підключення крок за кроком
Додайте джерело Home Assistant
У робочому просторі на панелі «Підключити джерело» оберіть тип активу BESS, тип підключення Home Assistant і натисніть «Додати джерело».
Заповніть мапу сутностей
На сторінці джерела відкрийте «Мапер Home Assistant». Назви в полях — лише приклади. Для кожного числового поля вкажіть свій entity_id, одиницю і знак. Окремо задайте сутності online, fault, write_consent, sample_timestamp і write_target, одиницю й знак запису та граничну давність (1–30 секунд).
Перевірте мапу
Натисніть «Перевірити декларативну мапу». Lab перевіряє лише форму і показує статус та SHA256 мапи. Чи існують сутності і чи свіжі вони, перевіряє вже локальний конектор. Ця перевірка не дає права на запис.
Завантажте мапу
Натисніть «Завантажити мапу». Збережіть lab-ha-mapping.json поруч із конектором.
Створіть приватний файл HA
Локально створіть ha-private.json з home_assistant_url і access_token. На POSIX дайте йому права 0600. Не завантажуйте його в портал і не вписуйте в профіль.
ha-private.json { "home_assistant_url": "<your Home Assistant address>", "access_token": "<your long-lived access token>" }Видайте облікові дані CONTROL
Локальний конектор працює лише з активними обліковими даними CONTROL. Їх видає власник або адміністратор: оберіть CONTROL, позначте «Надаю цьому конектору право отримувати обмежені Lab-команди», натисніть «Видати дані один раз» і «Завантажити приватний файл».
Запустіть конектор
Команду з вашими файлами показує панель «Запуск локального конектора». Потрібні обидва файли: мапа і приватна конфігурація HA.
local_cli python -m services.platform.app.lab.local_cli \ --credential-file lab-credential.json \ --journal lab-journal.sqlite \ --ca-file lab-ca.crt \ --ha-mapping lab-ha-mapping.json \ --ha-private-config ha-private.jsonПеревірте дані
У панелі «Налаштування вихідного конектора» дивіться наступну дію і блокери, а в панелі «Телеметрія» — нові спостереження.
Поля мапи
| Поле | Що вказати |
|---|---|
| active_power | Незалежний вимірювач потужності активу. W або кВт, знак +1 чи −1. |
| soc, soh | Відсотки, знак лише +1. |
| available_charge, available_discharge | Доступна потужність заряду й розряду. W або кВт. |
| grid_power, site_load | Потужність мережі та навантаження об’єкта. W або кВт. |
| online, fault, write_consent | Сутності binary_sensor або input_boolean. |
| sample_timestamp | Сутність sensor з часом вимірювання. |
| write_target | Сутність number або input_number, у яку конектор пише уставку. Має відрізнятися від active_power. |
| freshness_seconds | Від 1 до 30 секунд. Кожна сутність і час вимірювання мають бути не старшими. |
Числові сутності — sensor, number або input_number. Значення unknown, unavailable, нескінченні, застарілі чи поза межами конектор відхиляє.
Запис і керування
Конектор пише лише в оголошену write_target. Він локально перевіряє її одиницю, межі й крок, зокрема чи можна записати нуль. Підтверджений запис — це доказ виконання; доказ виміряної реакції дає лише незалежний вимірювач.
Для запису потрібні дві речі: прапорець --allow-local-writes і ввімкнена сутність write_consent. Після свіжого старту конектора власник чи адміністратор прив’язує профіль і окремо вмикає обмежене керування в Lab.
Токен HA тримайте лише локально. Відновлення до нуля конектор пробує навіть після зняття локального дозволу. Якщо читання чи запис не вдалися, результат лишається невідомим, і нові команди заблоковані.
Профіль для Home Assistant
Профіль з конектором HOME_ASSISTANT має містити home_assistant_mapping — ту саму мапу, що й у конектора. Токенів і URL у профілі бути не може. Тести такого профілю використовують внутрішні макети HA, і звіт це позначає.
Типові проблеми
| Причина | Що робити |
|---|---|
| INDEPENDENT_POWER_MEASUREMENT_REQUIRED | active_power і write_target — одна сутність. Вкажіть окремий вимірювач. |
| POWER_UNIT_REQUIRED | Для полів потужності оберіть W або кВт. |
| SOC_SOH_PERCENT_REQUIRED | Для soc і soh потрібні % і знак +1. |
| HOME_ASSISTANT_MAPPING_REQUIRED | У профілі HA немає home_assistant_mapping. Додайте перевірену мапу. |
| LOAD_HOME_ASSISTANT_NOT_QUALIFIED | Кероване навантаження через HA не кваліфіковане. Використайте симулятор або MQTT. |
| Local Lab connector stopped | Перевірте, що вказані обидва файли HA, файли мають права 0600, а облікові дані — активні CONTROL і не прострочені. |
| FRESH_CANONICAL_TELEMETRY_REQUIRED | Свіжих даних немає. Перевірте, що сутності оновлюються частіше за граничну давність. |