[2026-09-14] eagle: family/plans/t610-addons-deployment.md

2026-09-14 09:06:53 +06:00
parent 867aa78743
commit cfa3a9f62e
1 changed files with 32 additions and 30 deletions
@@ -16,7 +16,7 @@ related:
 ---
 # t610 — развёртывание через HA-аддоны

-> **Статус (2026-09-14): Этап 1 ✅. Этап 2 ✅ (все 3 USB подключены, привязка by-path + `uart: true`, z2m работает — 16 устройств, mbusd работает — порт 502, modbus-bridge собран и запущен, ⏳ ждёт `HA_TOKEN` + MQTT-пароль). Следующий шаг — вписать `ha_token`/`mqtt_password` в modbus-bridge, затем Этап 3 (перенос HA-конфига).**
+> **Статус (2026-09-14): Этап 1 ✅. Этап 2 ✅ ПОЛНОСТЬЮ (все 3 USB подключены, привязка by-path + `uart: true`, z2m работает — 16 устройств, mbusd работает — порт 502, modbus-bridge работает — MQTT + HA-опрос, в HA добавлена MQTT-интеграция). Следующий шаг — Этап 3 (перенос HA-конфига).**
 > Родительский план: [[family/plans/home-automation-migration-t610]] (Шаг 3 в нём заменяется на этот документ).
 > Доступ к хосту, CLI и питфоллы: [[family/how-to/t610-access]].

@@ -55,7 +55,8 @@ related:
 | File editor | `core_configurator` | Official | ✅ установлен, `started` |
 | **Zigbee2MQTT** | `45df7312_zigbee2mqtt` | Community repo | ✅ **установлен, работает — 16 устройств** |
 | **mbusd** | `local_mbusd` | Local add-on (`/addons/mbusd`) | ✅ **установлен, работает — порт 502** |
-| **modbus-bridge** | `local_modbus-bridge` | Local add-on (`/addons/modbus-bridge`) | ✅ установлен, запущен — ⏳ ждёт `HA_TOKEN` + MQTT-пароль |
+| **modbus-bridge** | `local_modbus-bridge` | Local add-on (`/addons/modbus-bridge`) | ✅ **установлен, работает — MQTT + HA-опрос** |
+| **MQTT-интеграция в HA** | `mqtt` | Config entry | ✅ **добавлена 2026-09-14** (была ОТСУТСТВОВАЛА → 22 сущности; стало 104, 69 Zigbee) |

 ### Про Zigbee2MQTT
 В официальном сторе z2m нет (есть только deCONZ `core_deconz` и `core_silabs_multiprotocol`).
@@ -151,7 +152,7 @@ z2m: Connected to MQTT server
 4. [ ] **Samba share** (`core_samba`) — установлен, но `stopped`: требует задать `password` (по умолчанию `null`) → логин `homeassistant`. Задать в UI: Settings → Apps → Samba → Configuration
 5. [x] **File editor** (`core_configurator`) — установлен, `started`
 6. [x] Репозиторий Zigbee2MQTT добавлен: `ha store add https://github.com/zigbee2mqtt/hassio-zigbee2mqtt` → появился как `Home Assistant App: Zigbee2MQTT` (slug `45df7312`)
-7. [ ] HA MQTT-интеграция на `core-mosquitto` — проверить/настроить после переноса конфига
+7. [x] ✅ **HA MQTT-интеграция на `core-mosquitto` — ДОБАВЛЕНА 2026-09-14** (её не было → z2m/bridge не создавали сущности). Сущностей: 22 → **104** (69 Zigbee). Рецепт — §«HA MQTT-интеграция» ниже.

 **Питфоллы, выявленные при установке:**
 - **`ha apps` НЕ имеет команды для изменения опций** (только install/start/stop/restart/logs/info/update/uninstall). Настройка опций — только через **UI** или **Supervisor API** (`POST http://supervisor/addons/<slug>/options`).
@@ -179,36 +180,36 @@ ha apps restart "$SLUG"
 11. [x] **СПОСОБ ПРИВЯЗКИ РЕШЁН 2026-09-14** — привязка по **`by-path`**, никаких udev-алиасов. Механизм: флаг `uart: true` в манифесте аддона даёт доступ ко **всем** serial включая `/dev/serial/by-path/` (проверено на живом t610: `core_ssh` uart:true видит все by-path; z2m тоже uart:true). `devices:` прописывать не надо. Подробности: [[family/how-to/t610-access]] §USB. **Блокер снят.**
 12. [x] ✅ **z2m-аддон УСТАНОВЛЕН И РАБОТАЕТ (2026-09-14)** — аддон `45df7312_zigbee2mqtt` v2.14.1-1, serial по by-id, база перенесена 1:1, **16 устройств на месте, переспаривание не потребовалось.** Подробности — §«z2m на t610 (ВЫПОЛНЕНО)» выше.
 13. [x] ✅ **mbusd local add-on СОБРАН И РАБОТАЕТ (2026-09-14)** — slug `local_mbusd`, порт **502 открыт** (проверено `nc` с Mac), устройство by-path CH340 #2 (порт 4). Подробности — §«Local add-ons mbusd / modbus-bridge» ниже.
-14. [x] ✅ **modbus-bridge local add-on СОБРАН И ЗАПУЩЕН (2026-09-14)** — slug `local_modbus-bridge`, устройство by-path CH340 #1 (порт 3), конфиг валиден, **MQTT подключён, 13 discovery-сообщений ушли**, sniffer работает. ⏳ **HA-опрос даёт HTTP 401** — нужен корректный long-lived token от ЭТОГО инстанса HA (см. питфолл ниже).
+14. [x] ✅ **modbus-bridge local add-on РАБОТАЕТ (2026-09-14)** — slug `local_modbus-bridge`, устройство by-path CH340 #1 (порт 3), конфиг валиден, **MQTT подключён, 13 discovery-сообщений, HA-опрос работает** (`HA poll -> sensor..._temperature = 73.454`). Плюс в HA добавлена **MQTT-интеграция** (её НЕ БЫЛО) — см. §«HA MQTT-интеграция» ниже.

-#### ⚠️ ПИТФОЛЛ: HA-токен с чужим `iss` отвергается (401)
+#### ✅ HA MQTT-интеграция + `ha.url` для modbus-bridge (2026-09-14)

-Первый присланный `ha_token` (от Alex) при обращении к API давал **401 и с Mac, и из аддона**. Токен синтаксически валиден (payload: `iss`/`iat`/`exp` до 2036), НО:
+**Симптомы по цепочке:** HTTP **401** при `ha.url = http://supervisor/core` → HTTP **404** при `http://192.168.2.176:80` → в HA всего **22 сущности**, Zigbee нет.

-| | Значение |
-|---|---|
-| `iss` в токене | `76e344271cb74a2098c6de2839a79f0f` |
-| **`instance_id` этого HA** (`/config/.storage/core.uuid`) | **`d3b24dad8c684291a31b687cff7f9d30`** |
+**Причины (по порядку):**
+1. **`http://supervisor/core` НЕ принимает пользовательский long-lived token** — эндпоинт рассчитан на внутренний `SUPERVISOR_TOKEN`. С пользовательским токеном → **401**.
+   ✅ **Правильный адрес: `http://192.168.2.176:80`** (прямой HA Core). Проверено curl'ом из аддона: `supervisor/core` → 401, `192.168.2.176:80` → **200**.
+2. **404** — не из-за адреса, а из-за **отсутствия MQTT-интеграции в HA**: discovery-сообщения z2m/bridge не превращались в сущности (было 22 системные сущности).
+3. После добавления MQTT-интеграции → сущностей **104** (69 Zigbee), опрос пошёл, 404 исчез.

-→ Токен выпущен **другим инстансом** (старый HA на TrueNAS / другая установка). HA проверяет `iss` и отвергает чужой токен.
-
-**Как проверить токен перед вставкой:**
+**Рецепт добавления MQTT-интеграции (Config Entry Flow API):**
 ```bash
-# payload токена (base64url, средняя часть)
-echo '<PAYLOAD_PART>' | base64 -D
-# сравнить "iss" с instance_id:
-ssh ... root@192.168.2.176 'jq -r .data.uuid /config/.storage/core.uuid'
+T=<long-lived token>
+BASE="http://192.168.2.176/api/config/config_entries/flow"
+FID=$(curl -s -X POST -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
+  -d '{"handler":"mqtt","show_advanced_options":false}' "$BASE" | jq -r .flow_id)
+curl -s -X POST -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
+  -d '{"next_step_id":"addon"}' "$BASE/$FID"     # → "type":"create_entry" = готово
 ```
-**Создавать токен только на http://192.168.2.176** → профиль `ha_admin` → Security → Long-lived access tokens.
-**Быстрая проверка:** `curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer <TOKEN>" http://192.168.2.176/api/` → должно быть **200** (401 = токен не от этого инстанса).
+Проверка: `jq -r '.data.entries[].domain' /config/.storage/core.config_entries | grep mqtt` → `mqtt`.
+Скрипт: `~/tmp-t610/setup_mqtt_integration.sh`.

-**Что уже подтверждено работоспособным (не зависит от токена):**
- MQTT-подключение к `core-mosquitto` ✓
- Публикация discovery-сообщений (13 шт: dining kids bedroom × co2/formaldehyde/tvoc/pm2.5/pm10/temp/humidity) ✓
- Serial sniffing на CH340 порт 3 (шина ZONT) ✓
- HA poller запускается, но получает 401
-
-**Настройка токена через Supervisor API (рабочий рецепт):** см. `~/tmp-t610/set_bridge_opts.sh`. ⚠️ Значения токена **маскируются** при прогоне через bash-переменную/`echo` — записывать токен в JSON-файл на t610 через `jq --arg` из env, НЕ подставлять в строку через `echo`/`sed`.
+**⚠️ ПИТФОЛЛ: токен маскируется при подстановке в bash-переменную**
+- Любая подстановка токена в `echo`/`sed`/переменную окружения давала в опциях заглушку `<len 13>` вместо токена.
+- **Рабочий способ:** записать токен в **файл** → `scp` на t610 (`/tmp/ha_token.txt`) → читать на месте `TOK=$(tr -d '\n\r' < /tmp/ha_token.txt)` → подавать через `jq --arg t "$TOK"`. Не интерполировать в строки.
+- **Проверка токена:** `curl -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $T" http://192.168.2.176/api/` → **200** ок, **401** — токен от другого пользователя.
+- ⚠️ **Ложный след (не повторять):** гипотеза «`iss` в JWT должен равняться `core.uuid`» — **НЕВЕРНА**. У рабочего токена `iss=e75d1d6f...`, `core.uuid=d3b24dad...` — не совпадают, и это норма. Единственный надёжный тест — HTTP-код на `/api/`.
+- Скрипты: `~/tmp-t610/{apply_token2.sh,setup_mqtt_integration.sh,verify_token.sh}`, токен: `~/tmp-t610/ha_token.txt`.

 ### ✅ Local add-ons mbusd / modbus-bridge — ВЫПОЛНЕНО (2026-09-14)

@@ -228,9 +229,10 @@ ssh ... root@192.168.2.176 'jq -r .data.uuid /config/.storage/core.uuid'

 **modbus-bridge (`local_modbus-bridge`):**
 - База: `python:3.11-alpine` + `pyserial paho-mqtt py3-yaml py3-requests`; `uart: true`, `host_network: true`.
- `run.sh`: из `/data/options.json` берёт `device`/`baudrate`/`ha_token`/`mqtt_user`/`mqtt_password`, генерирует runtime `/app/config.yml` из шаблона (`ha.url` → `http://supervisor/core`, `mqtt.broker` → `core-mosquitto`), экспортит env `HA_TOKEN`/`MQTT_USER`/`MQTT_PASS` и запускает `modbus_ha_bridge.py`.
- Опции: `device` = `/dev/serial/by-path/pci-0000:00:12.0-usb-0:3:1.0-port0`, baudrate 9600.
- ✅ Конфиг валиден, serial открыт, sniffer работает. ⏳ Нужны `ha_token` и `mqtt_password`.
+- `run.sh`: из `/data/options.json` берёт `device`/`baudrate`/`ha_token`/`mqtt_user`/`mqtt_password`, генерирует runtime `/app/config.yml` из шаблона (`ha.url` → **`http://192.168.2.176:80`**, `mqtt.broker` → `core-mosquitto`), экспортит env `HA_TOKEN`/`MQTT_USER`/`MQTT_PASS` и запускает `modbus_ha_bridge.py`.
+- Опции: `device` = `/dev/serial/by-path/pci-0000:00:12.0-usb-0:3:1.0-port0`, baudrate 9600, `ha_token` (183 симв.), `mqtt_user` = `zont`, `mqtt_password`.
+- ✅ Конфиг валиден, serial открыт, sniffer работает, **MQTT подключён, HA-опрос `= 73.454` без ошибок**.
+- ⚠️ `ha.url` ОБЯЗАН быть `http://192.168.2.176:80` — НЕ `http://supervisor/core` (тот требует `SUPERVISOR_TOKEN` и даёт 401 с пользовательским токеном).

 **Питфоллы local add-ons (HA OS 18.2) — важные:**
 - **`${BUILD_FROM}` в Dockerfile пустой**, если нет `build.yaml` с базовыми образами по arch. Решения: (a) добавить `build.yaml` c `build_from: {amd64: ..., aarch64: ...}`, либо (b) **взять готовый образ напрямую** (`FROM 3cky/mbusd:latest`) — тогда `build.yaml` не нужен.
@@ -270,7 +272,7 @@ ssh ... root@192.168.2.176 'jq -r .data.uuid /config/.storage/core.uuid'
 - [x] ✅ **РЕШЕНО 2026-09-14 — куда переносить данные z2m:** `data_path` аддона = **`/config/zigbee2mqtt`** (внутри HA-конфига), НЕ `/addon_configs/`. Туда залиты `database.db` и `configuration.yaml`.
 - [x] ✅ **Проверено 2026-09-14 — совместимость community-repo z2m с HA OS 18.2 / Core 2026.9.2:** работает (v2.14.1-1, координатор EmberZNet 7.4.5, 16 устройств).
 - [x] ✅ **РЕШЕНО 2026-09-14 — `uart: true` для local add-ons:** подтверждено на mbusd/modbus-bridge — в их манифестах `uart: true`, by-path виден, устройства открываются (mbusd порт 502, bridge sniffer на шине ZONT). Тот же механизм, что у z2m и core_ssh.
- [ ] modbus-bridge: вписать `ha_token` (long-lived token из HA UI) и `mqtt_password` → убрать `MQTT connection failed code 5` и включить HA poller. Единственный незакрытый пункт Этапа 2.
+- [x] ✅ **РЕШЕНО 2026-09-14 — modbus-bridge `ha_token`/`mqtt_password`:** вписаны, MQTT + HA-опрос работают. Ключевой момент — `ha.url` = `http://192.168.2.176:80` (не `supervisor/core`), + в HA добавлена MQTT-интеграция. **Этап 2 закрыт полностью.**
 - [ ] Камера (§8 родительского плана) — не аддон, разбираться отдельно

 ## Связанные заметки