owner: gmikcon status: active last_reviewed: 2026-09-04 review_interval: 90d confidence: high
Канонические пути управления умным домом для AI-агентов и внешней автоматизации. Цель — всегда действовать по готовому проверенному пути: без импровизации, без прямого управления устройствами без необходимости.
smart-home-platform): «ControlScripts are the only intended place for device-control business logic»; устройства и веб-клиенты не должны управлять устройствами напрямую через внешние REST API.| # | Путь | Когда применять | Требует |
|---|---|---|---|
| 1 | Существующий экшин через CLI (SSH) | Дефолт: готовый алиас есть | SSH-доступ |
| 2 | Существующий экшин через HTTP API | Есть GAuth-сессия/Bearer | GAuth scripts.run |
| 3 | Временный скрипт на сервере | Готового алиаса нет | SSH-доступ |
| 4 | Прямой device API | Только по просьбе/острой нужде | device Bearer |
Самый быстрый путь, GAuth не нужен.
shome@192.168.1.101, порт 22; пароль — gnexus-creds secret smart-home-server-creds (в отчёты не выводить).fury_init("SHServ") (образец: /home/shome/smart-home-server/server/enable_global_scenes.php), вызов \SHServ\Middleware\ControlScripts::run_action_script('<alias>', []).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.POST http://192.168.1.101/api/v1/scripts/actions/run
Content-Type: application/json
{"alias": "<alias>", "params": {}}
scripts.run (session или Bearer из shserv_sessions).status: true и return-значением скрипта.10-systems/servers/smart-home-server.md.Проверенный паттерн (так деплоился Tier 1):
/home/shome/smart-home-server/server/ (например tmp_<task>.php): bootstrap fury_init("SHServ"); внутри — серверные классы (ControlScripts, SHServ\Tools\DeviceAPI\Relay и т.п.), НЕ прямые HTTP-вызовы к устройствам.php tmp_<task>.php, верифицировать результат (статус через серверные классы или read-only пути ниже).Удалить временный файл (или перенести в /home/shome/backups/).
Перед изменениями кода — бэкап в /home/shome/backups/.
Scripts::set_script_state("action", alias, true); нюансы в overview («Registration vs DB», «Scope gate» — новый scope требует двух CLI-проходов).Только по явной просьбе владельца или острой необходимости. Полный 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.Чтение статуса не меняет состояние — допустимо для диагностики без спецразрешения, предпочтительно через сервер:
GET http://192.168.1.101/api/v1/devices/id/{id}/status (GAuth Bearer).GET http://<device_ip>/status (device Bearer), GET /about (без auth).fisrt_floor_big_relay — inverted=true (логический off = физически замкнуто).fisrt_floor_big_relay:6 и :2.hatch_open/hatch_close — dangerous: люк не двигать без явной просьбы.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, GAuth10-systems/automations/light_control_procedures.md — образец безопасной процедуры toggle