release

2026-03-07 22:43:08 +03:00
parent 61e7e3af56
commit 7a86519314
17 changed files with 2316 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,244 @@
-# local-yandex-station
+# Alice Stations Plugin

+Standalone-плагин для управления Яндекс Станциями, генерации шаблонов 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` - готовые команды для типовых действий.
+
+## Требования
+
+Минимум для Debian/Ubuntu, Wiren Board, Raspberry Pi OS:
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-venv python3-pip
+```
+
+Важно:
+- команды установки и запуска нужно выполнять из каталога проекта;
+- если нет `python3-venv`, `install.sh` завершится ошибкой и сервисы не установятся.
+
+## Рекомендуемая структура на контроллере
+
+```text
+/home/shd/scripts/alice
+```
+
+Если репозиторий скопирован в другое место, нужно скорректировать пути в `systemd/*.service`.
+
+## Установка (пошагово)
+
+1. Скопировать проект:
+
+```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
+chmod +x *.sh
+./install.sh
+```
+
+3. Сохранить OAuth-токен:
+
+```bash
+printf %s 'YANDEX_OAUTH_TOKEN' > /home/shd/scripts/alice/token.txt
+chmod 600 /home/shd/scripts/alice/token.txt
+```
+
+4. Включить и запустить сервисы:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now shd-alice.service shd-alice-plugin.service
+```
+
+## Проверка после установки
+
+Проверка сервисов:
+
+```bash
+sudo systemctl status shd-alice.service --no-pager
+sudo systemctl status shd-alice-plugin.service --no-pager
+```
+
+Проверка web API:
+
+```bash
+curl -s http://127.0.0.1:9140/api/status
+```
+
+Web UI:
+
+```text
+http://<controller-ip>:9140/
+```
+
+## Обязательные команды (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 |
+
+Примеры запуска:
+
+```bash
+cd /home/shd/scripts/alice
+./cmd_1_get_columns.sh
+./cmd_2_get_loxone_templates.sh
+./cmd_3_get_wb_rules_templates.sh
+```
+
+### Команды `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}'
+```
+
+Для станции в шаблоне есть:
+- `VirtualOut` команды: `TTS`, `Command`, `Play`, `Pause`, `Stop`, `Next`, `Prev`, `Volume`, `Raw`.
+- `VirtualIn` статусы: `Daemon OK`, `WS Running`, `Playing`, `Volume`.
+
+## Работа через web UI
+
+На странице можно:
+- сохранить OAuth-токен;
+- найти/обновить список колонок;
+- скачать ZIP для Loxone;
+- скачать ZIP для wb-rules;
+- на Wiren Board доступны кнопки установки wb-rules в `/etc/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
+```
+
+А не в `/home/shd/scripts/token.txt`.
+
+## Переменные окружения (опционально)
+
+- `YANDEX_TOKEN` - OAuth токен (если не используется `token.txt`).
+- `ALICE_CONTROLLER_HOST` - host/IP, который вставляется в шаблоны.
+- `ALICE_PLUGIN_WEB_PORT` - порт web UI (по умолчанию `9140`).
+
+## Удаление с контроллера
+
+```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
+```