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