local_yandex_station/README.md

# Alice Stations Plugin

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

## Содержание

- [Что умеет плагин](#что-умеет-плагин)
- [Что не умеет и слабые места](#что-не-умеет-и-слабые-места)
- [Структура проекта](#структура-проекта)
- [Куда устанавливать](#куда-устанавливать)
- [Быстрый старт](#быстрый-старт)
- [Полная установка](#полная-установка)
- [Токен](#токен)
- [CLI](#cli)
- [Примеры wb-rules](#примеры-wb-rules)
- [Прямые Python-команды](#прямые-python-команды)
- [Web UI](#web-ui)
- [Systemd](#systemd)
- [Где лежат файлы](#где-лежат-файлы)
- [Диагностика и логи](#диагностика-и-логи)
- [Частые ошибки](#частые-ошибки)
- [Удаление](#удаление)

## Что умеет плагин

- сохранить 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
```

Для более удобной синхронизации в `/opt` желателен `rsync`, но без него установка тоже работает.

### 2. Распаковать проект и запустить установку

```bash
cd /путь/к/распакованному/репозиторию
chmod +x *.sh
./install.sh
```

Что делает `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' > /opt/shd/plugins/alice/token.txt
chmod 600 /opt/shd/plugins/alice/token.txt
```

Или через 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 enable --now shd-alice.service shd-alice-plugin.service
```

## Токен

Проект ищет токен в таком порядке:

1. аргумент `--token`;
2. переменная окружения `YANDEX_TOKEN`;
3. файл `token.txt`;
4. `data/config.json`.

Надёжнее всего использовать `token.txt`:

```bash
/opt/shd/plugins/alice/token.txt
```

Если токен неверный, при обновлении списка станций будет ошибка:

```text
YANDEX_OAUTH_TOKEN invalid: update token and retry
```

## CLI

Основной интерфейс из терминала — `cli.sh`.

Перед использованием:

```bash
cd /opt/shd/plugins/alice
```

### Поиск колонок

```bash
./cli.sh columns
```

С токеном напрямую:

```bash
./cli.sh --token 'YANDEX_OAUTH_TOKEN' columns
```

С таймаутом локального поиска:

```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
```

## Примеры wb-rules

Есть готовый файл:

```text
configs/wb-rules/wb-rules-examples.js
```

- `wb-rules-examples.js`:
- примеры действий для одной колонки:
- `player` (`play`, `stop`, `next`, `prev`);
- `tts`;
- `command`;
- `audio + tts` (через параметры `tts_audio` + `text`).

Как привязать к конкретной колонке:

1. возьми `id` нужной станции из `data/stations.json`;
2. подставь его в строку:

```js
var STATION = "PUT_EXACT_STATION_ID_HERE";
```

3. скопируй файл в `/etc/wb-rules/` и перезапусти `wb-rules`.

## Прямые 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` по кнопке.

Страница лежит по адресу:

```text
http://<ip-устройства>:9140/
```

Если станции ещё не найдены, страница покажет пустой список и предложит сначала сохранить токен и нажать кнопку поиска.

## Systemd

В проекте есть два сервиса:

- `shd-alice.service` — основной демон `yastation.py`;
- `shd-alice-plugin.service` — web UI.

Юниты используют фиксированный путь:

```text
/opt/shd/plugins/alice
```

Проверка состояния:

```bash
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-examples.js
        └── wb_rules_templates.zip
```

Ключевые файлы:

- `token.txt` — OAuth-токен;
- `data/config.json` — сохранённый IP контроллера и служебные настройки;
- `data/stations.json` — найденные станции;
- `configs/wb-rules/wb-rules-examples.js` — примеры `player/tts/command/audio+tts` для одной станции;
- `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
```