cleanup cli, configs, systemd and readme

2026-04-02 01:18:15 +03:00
parent 7a86519314
commit 50961eb3fc
17 changed files with 741 additions and 294 deletions
--- a/README.md
+++ b/README.md
@@ -1,244 +1,530 @@
 # Alice Stations Plugin

-Standalone-плагин для управления Яндекс Станциями, генерации шаблонов Loxone / wb-rules и web UI.
+Плагин для поиска Яндекс Станций, сохранения токена, генерации конфигов для Loxone и wb-rules и запуска web UI.

-## Содержимое репозитория
+## Содержание

- `yastation.py` - демон управления колонками (локальный API: `127.0.0.1:9123`, HTTP API: `:9124`).
- `alice_plugin.py` - CLI и web API для списка колонок, генерации шаблонов и установки wb-rules.
- `web/index.html` - web-интерфейс.
- `loxone/` - выходные файлы шаблонов и ZIP-архивы.
- `data/` - рабочие данные (`stations.json`, `config.json`).
- `systemd/*.service` - юниты сервисов.
- `cmd_*.sh` - готовые команды для типовых действий.
+- [Что умеет плагин](#что-умеет-плагин)
+- [Что не умеет и слабые места](#что-не-умеет-и-слабые-места)
+- [Структура проекта](#структура-проекта)
+- [Куда устанавливать](#куда-устанавливать)
+- [Быстрый старт](#быстрый-старт)
+- [Полная установка](#полная-установка)
+- [Токен](#токен)
+- [CLI](#cli)
+- [Прямые Python-команды](#прямые-python-команды)
+- [Web UI](#web-ui)
+- [Systemd](#systemd)
+- [Где лежат файлы](#где-лежат-файлы)
+- [Диагностика и логи](#диагностика-и-логи)
+- [Частые ошибки](#частые-ошибки)
+- [Удаление](#удаление)

-## Требования
+## Что умеет плагин

-Минимум для Debian/Ubuntu, Wiren Board, Raspberry Pi OS:
+- сохранить OAuth-токен Яндекса;
+- получить список станций из облака и сопоставить его с локальным mDNS-поиском;
+- сохранить итоговый список в `data/stations.json`;
+- сгенерировать конфиги для `configs/loxone`;
+- сгенерировать конфиги для `configs/wb-rules`;
+- скачать ZIP-архивы через web UI;
+- на Wiren Board установить `wb-rules` шаблоны прямо из web UI или CLI;
+- поднять web UI для первичной настройки.
+
+## Что не умеет и слабые места
+
+- без валидного OAuth-токена обновление списка станций не работает;
+- если станции и контроллер находятся в разных сетях, локальные IP могут не определиться;
+- web UI не исправляет проблемы сети или токена, он только показывает состояние и запускает команды;
+- генерация шаблонов зависит от `data/stations.json`, поэтому сначала всегда нужен поиск колонок;
+- `wb-install` имеет смысл только на Wiren Board или на системе, где есть `/etc/wb-rules`.
+
+## Структура проекта
+
+```text
+alice/
+├── alice_plugin.py
+├── cli.sh
+├── configs/
+│   ├── loxone/
+│   └── wb-rules/
+├── data/
+├── install.sh
+├── README.md
+├── requirements.txt
+├── start.sh
+├── start_plugin_web.sh
+├── systemd/
+│   ├── shd-alice-plugin.service
+│   └── shd-alice.service
+├── web/
+│   └── index.html
+└── yastation.py
+```
+
+Назначение файлов:
+
+- `alice_plugin.py` — CLI и backend для web UI;
+- `yastation.py` — демон управления станциями и HTTP API на `:9124`;
+- `cli.sh` — основной способ работы из терминала;
+- `start.sh` — запуск демона для systemd;
+- `start_plugin_web.sh` — запуск web UI для systemd;
+- `install.sh` — установка в `/opt/shd/plugins/alice`, создание `.venv`, каталогов и systemd-юнитов.
+
+## Куда устанавливать
+
+Штатный путь проекта зафиксирован:
+
+```text
+/opt/shd/plugins/alice
+```
+
+`install.sh` сам синхронизирует текущий каталог в этот путь. После установки основной рабочий каталог должен быть именно таким:
+
+```bash
+/opt/shd/plugins/alice
+```
+
+## Быстрый старт
+
+```bash
+cd /путь/к/распакованному/репозиторию
+chmod +x *.sh
+./install.sh
+
+printf %s 'YANDEX_OAUTH_TOKEN' > /opt/shd/plugins/alice/token.txt
+chmod 600 /opt/shd/plugins/alice/token.txt
+
+cd /opt/shd/plugins/alice
+./cli.sh columns
+./cli.sh loxone
+./cli.sh wb-rules
+./cli.sh web
+```
+
+После этого web UI обычно доступен по адресу:
+
+```text
+http://<ip-устройства>:9140/
+```
+
+## Полная установка
+
+### 1. Установить системные зависимости

 ```bash
 sudo apt update
 sudo apt install -y python3 python3-venv python3-pip
 ```

-Важно:
- команды установки и запуска нужно выполнять из каталога проекта;
- если нет `python3-venv`, `install.sh` завершится ошибкой и сервисы не установятся.
+Для более удобной синхронизации в `/opt` желателен `rsync`, но без него установка тоже работает.

-## Рекомендуемая структура на контроллере
-
-```text
-/home/shd/scripts/alice
-```
-
-Если репозиторий скопирован в другое место, нужно скорректировать пути в `systemd/*.service`.
-
-## Установка (пошагово)
-
-1. Скопировать проект:
+### 2. Распаковать проект и запустить установку

 ```bash
-mkdir -p /home/shd/scripts
-cd /home/shd/scripts
-cp -a alice_station_plugin_repo alice
-```
-
-2. Установить зависимости Python и systemd-сервисы:
-
-```bash
-cd /home/shd/scripts/alice
+cd /путь/к/распакованному/репозиторию
 chmod +x *.sh
 ./install.sh
 ```

-3. Сохранить OAuth-токен:
+Что делает `install.sh`:
+
+- копирует проект в `/opt/shd/plugins/alice`;
+- создаёт `.venv`, если его нет;
+- ставит зависимости из `requirements.txt`;
+- создаёт каталоги `data/`, `configs/loxone/`, `configs/wb-rules/`;
+- копирует systemd-юниты в `/etc/systemd/system/`;
+- выполняет `systemctl daemon-reload` и `systemctl enable` для сервисов.
+
+### 3. Сохранить токен
+
+Через файл:

 ```bash
-printf %s 'YANDEX_OAUTH_TOKEN' > /home/shd/scripts/alice/token.txt
-chmod 600 /home/shd/scripts/alice/token.txt
+printf %s 'YANDEX_OAUTH_TOKEN' > /opt/shd/plugins/alice/token.txt
+chmod 600 /opt/shd/plugins/alice/token.txt
 ```

-4. Включить и запустить сервисы:
+Или через CLI/web-команду:
+
+```bash
+cd /opt/shd/plugins/alice
+./cli.sh web --token 'YANDEX_OAUTH_TOKEN'
+```
+
+### 4. Обновить список станций
+
+```bash
+cd /opt/shd/plugins/alice
+./cli.sh columns
+```
+
+### 5. Сгенерировать конфиги
+
+```bash
+./cli.sh loxone
+./cli.sh wb-rules
+```
+
+### 6. Включить сервисы

 ```bash
-sudo systemctl daemon-reload
 sudo systemctl enable --now shd-alice.service shd-alice-plugin.service
 ```

-## Проверка после установки
+## Токен

-Проверка сервисов:
+Проект ищет токен в таком порядке:
+
+1. аргумент `--token`;
+2. переменная окружения `YANDEX_TOKEN`;
+3. файл `token.txt`;
+4. `data/config.json`.
+
+Надёжнее всего использовать `token.txt`:

 ```bash
-sudo systemctl status shd-alice.service --no-pager
-sudo systemctl status shd-alice-plugin.service --no-pager
+/opt/shd/plugins/alice/token.txt
 ```

-Проверка web API:
-
-```bash
-curl -s http://127.0.0.1:9140/api/status
-```
-
-Web UI:
+Если токен неверный, при обновлении списка станций будет ошибка:

 ```text
-http://<controller-ip>:9140/
+YANDEX_OAUTH_TOKEN invalid: update token and retry
 ```

-## Обязательные команды (CLI)
+## CLI

-| Команда | Что делает | Входы | Выходы |
-|---|---|---|---|
-| `./cmd_1_get_columns.sh` | Обновляет список колонок (`stations-refresh`) | OAuth-токен: `token.txt` или `YANDEX_TOKEN` | `data/stations.json`, JSON в stdout (`ok`, `stations`, `cloud_total`, `local_total`) |
-| `./cmd_2_get_loxone_templates.sh` | Генерирует шаблоны Loxone (`templates-loxone`) | `data/stations.json` (должен быть заполнен), `ALICE_CONTROLLER_HOST` (опц.) | Файлы в `loxone/`, архив `loxone/loxone_templates.zip`, JSON в stdout |
-| `./cmd_3_get_wb_rules_templates.sh` | Генерирует шаблоны wb-rules (`templates-wb-rules`) | `data/stations.json` (должен быть заполнен), `ALICE_CONTROLLER_HOST` (опц.) | Файлы в `loxone/`, архив `loxone/wb_rules_templates.zip`, JSON в stdout |
+Основной интерфейс из терминала — `cli.sh`.

-Примеры запуска:
+Перед использованием:

 ```bash
-cd /home/shd/scripts/alice
-./cmd_1_get_columns.sh
-./cmd_2_get_loxone_templates.sh
-./cmd_3_get_wb_rules_templates.sh
+cd /opt/shd/plugins/alice
 ```

-### Команды `yastation.py` (daemon/client)
-
-Примеры:
+### Поиск колонок

 ```bash
-# локальные станции (mDNS)
-/home/shd/scripts/alice/.venv/bin/python3 /home/shd/scripts/alice/yastation.py --timeout 3 list
-
-# запуск daemon
-/home/shd/scripts/alice/.venv/bin/python3 /home/shd/scripts/alice/yastation.py --token "$YANDEX_TOKEN" serve --host 127.0.0.1 --port 9123 --http-host 0.0.0.0 --http-port 9124
-
-# tts
-/home/shd/scripts/alice/.venv/bin/python3 /home/shd/scripts/alice/yastation.py client --host 127.0.0.1 --port 9123 --station "M00..." tts --text "Проверка"
-
-# command
-/home/shd/scripts/alice/.venv/bin/python3 /home/shd/scripts/alice/yastation.py client --host 127.0.0.1 --port 9123 --station "M00..." command --text "включи музыку"
-
-# player pause
-/home/shd/scripts/alice/.venv/bin/python3 /home/shd/scripts/alice/yastation.py client --host 127.0.0.1 --port 9123 --station "M00..." player --cmd pause
-
-# volume
-/home/shd/scripts/alice/.venv/bin/python3 /home/shd/scripts/alice/yastation.py client --host 127.0.0.1 --port 9123 --station "M00..." volume --level 20
-
-# raw
-/home/shd/scripts/alice/.venv/bin/python3 /home/shd/scripts/alice/yastation.py client --host 127.0.0.1 --port 9123 --station "M00..." raw --payload '{"command":"setVolume","volume":0.2}'
+./cli.sh columns
 ```

-Для станции в шаблоне есть:
- `VirtualOut` команды: `TTS`, `Command`, `Play`, `Pause`, `Stop`, `Next`, `Prev`, `Volume`, `Raw`.
- `VirtualIn` статусы: `Daemon OK`, `WS Running`, `Playing`, `Volume`.
+С токеном напрямую:

-## Работа через web UI
+```bash
+./cli.sh --token 'YANDEX_OAUTH_TOKEN' columns
+```

-На странице можно:
- сохранить OAuth-токен;
- найти/обновить список колонок;
+С таймаутом локального поиска:
+
+```bash
+./cli.sh columns --timeout 5
+```
+
+Что делает команда:
+
+- проверяет токен;
+- читает облачный список устройств;
+- делает локальный mDNS-поиск;
+- объединяет результаты;
+- пишет `data/stations.json`.
+
+### Генерация Loxone
+
+```bash
+./cli.sh loxone
+```
+
+С ручным IP контроллера:
+
+```bash
+./cli.sh loxone --controller-host 192.168.1.50
+```
+
+Что создаётся:
+
+- каталоги по станциям в `configs/loxone/`;
+- `VO.xml`;
+- `VI.xml`;
+- `README.md` по каждой станции;
+- `configs/loxone/loxone_templates.zip`.
+
+### Генерация wb-rules
+
+```bash
+./cli.sh wb-rules
+```
+
+С ручным IP контроллера:
+
+```bash
+./cli.sh wb-rules --controller-host 192.168.1.50
+```
+
+Что создаётся:
+
+- каталоги по станциям в `configs/wb-rules/`;
+- `wb-rules-station.js`;
+- `README.md` по каждой станции;
+- `configs/wb-rules/wb_rules_templates.zip`.
+
+### Установка wb-rules в систему
+
+```bash
+./cli.sh wb-install
+```
+
+Для одной станции:
+
+```bash
+./cli.sh wb-install --station-id <station_id>
+```
+
+Что делает команда:
+
+- берёт файлы из `configs/wb-rules/`;
+- копирует их в `/etc/wb-rules/`;
+- перезапускает `wb-rules`.
+
+### Запуск web UI
+
+```bash
+./cli.sh web
+```
+
+С токеном при первом запуске:
+
+```bash
+./cli.sh --token 'YANDEX_OAUTH_TOKEN' web
+```
+
+С другим адресом и портом:
+
+```bash
+./cli.sh web --host 0.0.0.0 --port 9140
+```
+
+## Прямые Python-команды
+
+Все публичные Python-команды задокументированы ниже. Их можно использовать напрямую, но штатный способ — `cli.sh`.
+
+### Обновить станции
+
+```bash
+python3 alice_plugin.py --token 'YANDEX_OAUTH_TOKEN' stations-refresh
+```
+
+Дополнительно:
+
+```bash
+python3 alice_plugin.py --token 'YANDEX_OAUTH_TOKEN' stations-refresh --timeout 5
+```
+
+### Сгенерировать Loxone
+
+```bash
+python3 alice_plugin.py templates-loxone
+```
+
+С ручным IP контроллера:
+
+```bash
+python3 alice_plugin.py templates-loxone --controller-host 192.168.1.50
+```
+
+### Сгенерировать wb-rules
+
+```bash
+python3 alice_plugin.py templates-wb-rules
+```
+
+С ручным IP контроллера:
+
+```bash
+python3 alice_plugin.py templates-wb-rules --controller-host 192.168.1.50
+```
+
+### Установить wb-rules
+
+```bash
+python3 alice_plugin.py wb-install
+```
+
+Для одной станции:
+
+```bash
+python3 alice_plugin.py wb-install --station-id <station_id>
+```
+
+### Запустить web UI
+
+```bash
+python3 alice_plugin.py --token 'YANDEX_OAUTH_TOKEN' web
+```
+
+На другом адресе/порту:
+
+```bash
+python3 alice_plugin.py web --host 0.0.0.0 --port 9140
+```
+
+## Web UI
+
+Web UI умеет:
+
+- сохранить токен;
+- сохранить IP контроллера;
+- обновить список колонок;
 - скачать ZIP для Loxone;
 - скачать ZIP для wb-rules;
- на Wiren Board доступны кнопки установки wb-rules в `/etc/wb-rules`.
+- на Wiren Board установить `wb-rules` по кнопке.

-## Установка wb-rules из CLI
-
-Установить все станции:
-
-```bash
-cd /home/shd/scripts/alice
-.venv/bin/python3 alice_plugin.py wb-install
-```
-
-Установить только одну станцию:
-
-```bash
-cd /home/shd/scripts/alice
-.venv/bin/python3 alice_plugin.py wb-install --station-id <station_id>
-```
-
-## Сервисы и управление
-
- Демон Alice: `shd-alice.service`
- Web UI: `shd-alice-plugin.service`
-
-Перезапуск:
-
-```bash
-sudo systemctl restart shd-alice.service shd-alice-plugin.service
-```
-
-Остановка:
-
-```bash
-sudo systemctl stop shd-alice.service shd-alice-plugin.service
-```
-
-## Типовые ошибки и решения
-
-### `Unit shd-alice.service not found`
-
-Причина: `install.sh` не завершился успешно, поэтому юниты не были скопированы в `/etc/systemd/system`.
-
-Что делать:
-1. Исправить ошибку установки (часто это отсутствие `python3-venv`).
-2. Снова запустить:
-
-```bash
-cd /home/shd/scripts/alice
-./install.sh
-sudo systemctl daemon-reload
-sudo systemctl enable --now shd-alice.service shd-alice-plugin.service
-```
-
-### `The virtual environment was not created successfully because ensurepip is not available`
-
-Причина: отсутствует пакет `python3-venv`.
-
-Решение:
-
-```bash
-sudo apt update
-sudo apt install -y python3-venv python3-pip
-cd /home/shd/scripts/alice
-./install.sh
-```
-
-### `./install.sh: No such file or directory`
-
-Причина: команда выполняется не из каталога проекта.
-
-Решение:
-
-```bash
-cd /home/shd/scripts/alice
-./install.sh
-```
-
-### Токен не подхватывается
-
-Проверь, что файл существует именно по пути:
+Страница лежит по адресу:

 ```text
-/home/shd/scripts/alice/token.txt
+http://<ip-устройства>:9140/
 ```

-А не в `/home/shd/scripts/token.txt`.
+Если станции ещё не найдены, страница покажет пустой список и предложит сначала сохранить токен и нажать кнопку поиска.

-## Переменные окружения (опционально)
+## Systemd

- `YANDEX_TOKEN` - OAuth токен (если не используется `token.txt`).
- `ALICE_CONTROLLER_HOST` - host/IP, который вставляется в шаблоны.
- `ALICE_PLUGIN_WEB_PORT` - порт web UI (по умолчанию `9140`).
+В проекте есть два сервиса:

-## Удаление с контроллера
+- `shd-alice.service` — основной демон `yastation.py`;
+- `shd-alice-plugin.service` — web UI.
+
+Юниты используют фиксированный путь:
+
+```text
+/opt/shd/plugins/alice
+```
+
+Проверка состояния:

 ```bash
-sudo systemctl stop shd-alice.service shd-alice-plugin.service
-sudo systemctl disable shd-alice.service shd-alice-plugin.service
-sudo rm -f /etc/systemd/system/shd-alice.service /etc/systemd/system/shd-alice-plugin.service
-sudo systemctl daemon-reload
-sudo rm -rf /home/shd/scripts/alice
+sudo systemctl status shd-alice.service
+sudo systemctl status shd-alice-plugin.service
+```
+
+Логи:
+
+```bash
+journalctl -u shd-alice.service -f
+journalctl -u shd-alice-plugin.service -f
+```
+
+Ручной запуск:
+
+```bash
+cd /opt/shd/plugins/alice
+./start.sh
+./start_plugin_web.sh
+```
+
+## Где лежат файлы
+
+```text
+/opt/shd/plugins/alice/
+├── token.txt
+├── data/
+│   ├── config.json
+│   └── stations.json
+└── configs/
+    ├── loxone/
+    │   └── loxone_templates.zip
+    └── wb-rules/
+        └── wb_rules_templates.zip
+```
+
+Ключевые файлы:
+
+- `token.txt` — OAuth-токен;
+- `data/config.json` — сохранённый IP контроллера и служебные настройки;
+- `data/stations.json` — найденные станции;
+- `configs/loxone/loxone_templates.zip` — ZIP для Loxone;
+- `configs/wb-rules/wb_rules_templates.zip` — ZIP для wb-rules.
+
+## Диагностика и логи
+
+Проверить, что Python и зависимости в порядке:
+
+```bash
+cd /opt/shd/plugins/alice
+.venv/bin/python3 -m py_compile alice_plugin.py yastation.py
+```
+
+Проверить web API:
+
+```bash
+curl http://127.0.0.1:9140/api/status
+```
+
+Проверить список станций руками:
+
+```bash
+./cli.sh columns
+```
+
+Проверить генерацию шаблонов:
+
+```bash
+./cli.sh loxone
+./cli.sh wb-rules
+```
+
+## Частые ошибки
+
+### `YANDEX_OAUTH_TOKEN invalid: update token and retry`
+
+Токен неверный или протух. Перезапиши `token.txt` и повтори поиск колонок.
+
+### `stations.json is empty, run station refresh first`
+
+Сначала выполни:
+
+```bash
+./cli.sh columns
+```
+
+### `No stations found`
+
+Локальный поиск ничего не нашёл. Проверь:
+
+- что станции в той же сети;
+- что mDNS не режется роутером/VLAN;
+- что токен валиден и облачный список вообще отдаётся.
+
+### `No such file or directory` в systemd
+
+Обычно проект лежит не в `/opt/shd/plugins/alice`. Перезапусти установку:
+
+```bash
+./install.sh
+```
+
+### `/etc/wb-rules not found`
+
+Команда `wb-install` запускается не на Wiren Board и не на системе с установленным `wb-rules`.
+
+## Удаление
+
+Остановить сервисы:
+
+```bash
+sudo systemctl disable --now shd-alice.service shd-alice-plugin.service
+```
+
+Удалить юниты:
+
+```bash
+sudo rm -f /etc/systemd/system/shd-alice.service
+sudo rm -f /etc/systemd/system/shd-alice-plugin.service
+sudo systemctl daemon-reload
+```
+
+Удалить каталог проекта:
+
+```bash
+sudo rm -rf /opt/shd/plugins/alice
 ```