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

Як зробити · 10 хв

Підключити Home Assistant

Локальний конектор читає Home Assistant через його REST API на вашому комп’ютері і надсилає канонічні дані в Lab через MQTT. Адреса HA і токен ніколи не залишають вашу машину.

Як це працює

У Lab ви описуєте лише декларативну мапу: які сутності HA відповідають потужності, SOC, стану зв’язку тощо. Конектор на вашому боці читає ці сутності, перевіряє одиниці й свіжість і публікує стан і телеметрію у топіки ваших облікових даних.

Через Home Assistant зараз підтримується лише BESS. Кероване навантаження через HA не кваліфіковане, а EV / V2X Lab працює тільки із симулятором. Тести проходять на симульованих сутностях HA, а не на фізичному обладнанні.

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

  1. Додайте джерело Home Assistant

    У робочому просторі на панелі «Підключити джерело» оберіть тип активу BESS, тип підключення Home Assistant і натисніть «Додати джерело».

  2. Заповніть мапу сутностей

    На сторінці джерела відкрийте «Мапер Home Assistant». Назви в полях — лише приклади. Для кожного числового поля вкажіть свій entity_id, одиницю і знак. Окремо задайте сутності online, fault, write_consent, sample_timestamp і write_target, одиницю й знак запису та граничну давність (1–30 секунд).

  3. Перевірте мапу

    Натисніть «Перевірити декларативну мапу». Lab перевіряє лише форму і показує статус та SHA256 мапи. Чи існують сутності і чи свіжі вони, перевіряє вже локальний конектор. Ця перевірка не дає права на запис.

  4. Завантажте мапу

    Натисніть «Завантажити мапу». Збережіть lab-ha-mapping.json поруч із конектором.

  5. Створіть приватний файл 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>"
    }
  6. Видайте облікові дані CONTROL

    Локальний конектор працює лише з активними обліковими даними CONTROL. Їх видає власник або адміністратор: оберіть CONTROL, позначте «Надаю цьому конектору право отримувати обмежені Lab-команди», натисніть «Видати дані один раз» і «Завантажити приватний файл».

  7. Запустіть конектор

    Команду з вашими файлами показує панель «Запуск локального конектора». Потрібні обидва файли: мапа і приватна конфігурація 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
  8. Перевірте дані

    У панелі «Налаштування вихідного конектора» дивіться наступну дію і блокери, а в панелі «Телеметрія» — нові спостереження.

Поля мапи

ПолеЩо вказати
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_REQUIREDactive_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Свіжих даних немає. Перевірте, що сутності оновлюються частіше за граничну давність.