Newer
Older
gnexus-book / 10-systems / automations / smart-home-control-playbook.md

owner: gmikcon status: active last_reviewed: 2026-09-04 review_interval: 90d confidence: high

source_of_truth: ssh-host-verified

Smart Home Control Playbook

Канонические пути управления умным домом для AI-агентов и внешней автоматизации. Цель — всегда действовать по готовому проверенному пути: без импровизации, без прямого управления устройствами без необходимости.

Политика управления (правило владельца, 2026-09-04)

  1. По умолчанию НЕ управлять устройствами напрямую (прямые POST/GET к ESP-устройствам) — только по явной просьбе владельца или острой необходимости (авария, сервер умного дома недоступен).
  2. Дефолтный паттерн: временный экшин/скрипт на сервере умного дома → запуск через штатный механизм → удаление временного артефакта после выполнения.
  3. Это совпадает с архитектурной политикой платформы (inventory smart-home-platform): «ControlScripts are the only intended place for device-control business logic»; устройства и веб-клиенты не должны управлять устройствами напрямую через внешние REST API.
  4. После любого прямого управления (если оно было оправдано) — отчёт владельцу.

Иерархия путей

# Путь Когда применять Требует
1 Существующий экшин через CLI (SSH) Дефолт: готовый алиас есть SSH-доступ
2 Существующий экшин через HTTP API Есть GAuth-сессия/Bearer GAuth scripts.run
3 Временный скрипт на сервере Готового алиаса нет SSH-доступ
4 Прямой device API Только по просьбе/острой нужде device Bearer

Path 1 — существующий экшин через CLI (предпочтительный)

Самый быстрый путь, GAuth не нужен.

  • SSH: shome@192.168.1.101, порт 22; пароль — gnexus-creds secret smart-home-server-creds (в отчёты не выводить).
  • Паттерн: PHP-скрипт с bootstrap fury_init("SHServ") (образец: /home/shome/smart-home-server/server/enable_global_scenes.php), вызов \SHServ\Middleware\ControlScripts::run_action_script('<alias>', []).
  • Живые алиасы (25, verified 2026-09-04): 10-systems/automations/smart-home-overview.md → «Current live actions». Включая сцены Tier 1: all_lights_off, goodnight, movie_mode, away_toggle, night_mode, guest_mode, hatch_status.
  • Мёртвые алиасы возвращают null — не использовать (overview → «Dead aliases»).

Path 2 — существующий экшин через HTTP API

POST http://192.168.1.101/api/v1/scripts/actions/run
Content-Type: application/json
{"alias": "<alias>", "params": {}}
  • Требует GAuth permission scripts.run (session или Bearer из shserv_sessions).
  • Ответ: JSON со status: true и return-значением скрипта.
  • Детали: 10-systems/servers/smart-home-server.md.

Path 3 — временный экшин/скрипт (когда готового нет)

Проверенный паттерн (так деплоился Tier 1):

  1. SSH на сервер (креды как в Path 1).
  2. Создать временный PHP-скрипт в /home/shome/smart-home-server/server/ (например tmp_<task>.php): bootstrap fury_init("SHServ"); внутри — серверные классы (ControlScripts, SHServ\Tools\DeviceAPI\Relay и т.п.), НЕ прямые HTTP-вызовы к устройствам.
  3. Выполнить php tmp_<task>.php, верифицировать результат (статус через серверные классы или read-only пути ниже).
  4. Удалить временный файл (или перенести в /home/shome/backups/).

  5. Перед изменениями кода — бэкап в /home/shome/backups/.

  6. Если экшин должен стать постоянным: регистрация в scope + Scripts::set_script_state("action", alias, true); нюансы в overview («Registration vs DB», «Scope gate» — новый scope требует двух CLI-проходов).

Path 4 — прямой device API (ограниченный)

Только по явной просьбе владельца или острой необходимости. Полный wire-формат: overview → «Device API Auth».

  • GET http://<device_ip>/status — Authorization: Bearer <device_token> (токен: DB shome.device_auth, device_id, status='active').
  • POST http://<device_ip>/action — {"action":"set_channel_state","channel":N,"state":"on"|"off"} / {"action":"set_state","state":"on"|"off"} / {"action":"toggle_channel","channel":N}. Поле action обязательно, иначе 400 IllegalActionOrParams.

Read-only статус (разрешён свободнее)

Чтение статуса не меняет состояние — допустимо для диагностики без спецразрешения, предпочтительно через сервер:

  • Сервер: GET http://192.168.1.101/api/v1/devices/id/{id}/status (GAuth Bearer).
  • Устройство: GET http://<device_ip>/status (device Bearer), GET /about (без auth).

Обязательные правила безопасности

  • Перед toggle — проверить текущее состояние (не гасить горящий свет); после действия — верифицировать ответом устройства/сервера.
  • fisrt_floor_big_relay — inverted=true (логический off = физически замкнуто).
  • Не трогать каналы с неподтверждённым назначением: fisrt_floor_big_relay:6 и :2.
  • hatch_open/hatch_close — dangerous: люк не двигать без явной просьбы.
  • Пароли/токены не хранить и не выводить в документах и отчётах — только ссылки на gnexus-creds (smart-home-server-creds).

Шпаргалка

Задача Путь Что нужно
Свет/сцены/режимы по алиасу Path 1 (CLI) SSH + алиас из overview
То же из внешней системы Path 2 (HTTP) GAuth Bearer
Нестандартное разовое действие Path 3 (временный скрипт) SSH
Прямая команда устройству Path 4 явная просьба / острая нужда
Узнать статус устройства Read-only GAuth или device Bearer

Связанные документы

  • 10-systems/automations/smart-home-overview.md — живые алиасы, режимы, устройства, wire-форматы
  • 10-systems/servers/smart-home-server.md — SSH-доступ, HTTP API, GAuth
  • 10-systems/automations/light_control_procedures.md — образец безопасной процедуры toggle