Alice Stations Plugin

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

Содержание

• Что умеет плагин
• Что не умеет и слабые места
• Структура проекта
• Куда устанавливать
• Быстрый старт
• Полная установка
• Токен
• CLI
• Прямые Python-команды
• Web UI
• 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.

Структура проекта

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-юнитов.

Куда устанавливать

Штатный путь проекта зафиксирован:

/opt/shd/plugins/alice

install.sh сам синхронизирует текущий каталог в этот путь. После установки основной рабочий каталог должен быть именно таким:

/opt/shd/plugins/alice

Быстрый старт

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 обычно доступен по адресу:

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

Полная установка

1. Установить системные зависимости

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

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

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

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. Сохранить токен

Через файл:

printf %s 'YANDEX_OAUTH_TOKEN' > /opt/shd/plugins/alice/token.txt
chmod 600 /opt/shd/plugins/alice/token.txt

Или через CLI/web-команду:

cd /opt/shd/plugins/alice
./cli.sh web --token 'YANDEX_OAUTH_TOKEN'

4. Обновить список станций

cd /opt/shd/plugins/alice
./cli.sh columns

5. Сгенерировать конфиги

./cli.sh loxone
./cli.sh wb-rules

6. Включить сервисы

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:

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

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

YANDEX_OAUTH_TOKEN invalid: update token and retry

CLI

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

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

cd /opt/shd/plugins/alice

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

./cli.sh columns

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

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

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

./cli.sh columns --timeout 5

Что делает команда:

• проверяет токен;
• читает облачный список устройств;
• делает локальный mDNS-поиск;
• объединяет результаты;
• пишет data/stations.json.

Генерация Loxone

./cli.sh loxone

С ручным IP контроллера:

./cli.sh loxone --controller-host 192.168.1.50

Что создаётся:

• каталоги по станциям в configs/loxone/;
• VO.xml;
• VI.xml;
• README.md по каждой станции;
• configs/loxone/loxone_templates.zip.

Генерация wb-rules

./cli.sh wb-rules

С ручным IP контроллера:

./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 в систему

./cli.sh wb-install

Для одной станции:

./cli.sh wb-install --station-id <station_id>

Что делает команда:

• берёт файлы из configs/wb-rules/;
• копирует их в /etc/wb-rules/;
• перезапускает wb-rules.

Запуск web UI

./cli.sh web

С токеном при первом запуске:

./cli.sh --token 'YANDEX_OAUTH_TOKEN' web

С другим адресом и портом:

./cli.sh web --host 0.0.0.0 --port 9140

Прямые Python-команды

Все публичные Python-команды задокументированы ниже. Их можно использовать напрямую, но штатный способ — cli.sh.

Обновить станции

python3 alice_plugin.py --token 'YANDEX_OAUTH_TOKEN' stations-refresh

Дополнительно:

python3 alice_plugin.py --token 'YANDEX_OAUTH_TOKEN' stations-refresh --timeout 5

Сгенерировать Loxone

python3 alice_plugin.py templates-loxone

С ручным IP контроллера:

python3 alice_plugin.py templates-loxone --controller-host 192.168.1.50

Сгенерировать wb-rules

python3 alice_plugin.py templates-wb-rules

С ручным IP контроллера:

python3 alice_plugin.py templates-wb-rules --controller-host 192.168.1.50

Установить wb-rules

python3 alice_plugin.py wb-install

Для одной станции:

python3 alice_plugin.py wb-install --station-id <station_id>

Запустить web UI

python3 alice_plugin.py --token 'YANDEX_OAUTH_TOKEN' web

На другом адресе/порту:

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 по кнопке.

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

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

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

Systemd

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

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

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

/opt/shd/plugins/alice

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

sudo systemctl status shd-alice.service
sudo systemctl status shd-alice-plugin.service

Логи:

journalctl -u shd-alice.service -f
journalctl -u shd-alice-plugin.service -f

Ручной запуск:

cd /opt/shd/plugins/alice
./start.sh
./start_plugin_web.sh

Где лежат файлы

/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 и зависимости в порядке:

cd /opt/shd/plugins/alice
.venv/bin/python3 -m py_compile alice_plugin.py yastation.py

Проверить web API:

curl http://127.0.0.1:9140/api/status

Проверить список станций руками:

./cli.sh columns

Проверить генерацию шаблонов:

./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

Сначала выполни:

./cli.sh columns

No stations found

Локальный поиск ничего не нашёл. Проверь:

• что станции в той же сети;
• что mDNS не режется роутером/VLAN;
• что токен валиден и облачный список вообще отдаётся.

No such file or directory в systemd

Обычно проект лежит не в /opt/shd/plugins/alice. Перезапусти установку:

./install.sh

/etc/wb-rules not found

Команда wb-install запускается не на Wiren Board и не на системе с установленным wb-rules.

Удаление

Остановить сервисы:

sudo systemctl disable --now shd-alice.service shd-alice-plugin.service

Удалить юниты:

sudo rm -f /etc/systemd/system/shd-alice.service
sudo rm -f /etc/systemd/system/shd-alice-plugin.service
sudo systemctl daemon-reload

Удалить каталог проекта:

sudo rm -rf /opt/shd/plugins/alice