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

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

source_of_truth: ssh-host-verified

Smart Home Overview

... (existing content) ...

Automation Actions (verified 2026-09-04)

Actions are implemented as PHP Scope classes in /home/shome/smart-home-server/automation/Scopes/ (Bathroom, Hall, Kitchen, MasterBedroom, Office, Outdoor, PlantsRoom, ServerRoom, GlobalScenes). Each class extends ControlScripts and registers actions in register_actions_scripts() via helpers from the Common trait:

  • add_toggle_action(alias, name, relay_alias, channel, attrs) — single relay toggle
  • add_group_toggle_action(alias, name, ["device:channel", ...], attrs) — multi-relay toggle
  • add_action_script(attrs, callable) — custom action (attrs: alias, name, description, icon, author, danger_level safe/cautious/dangerous, state_callback, params_schema)
  • add_off_action(...), add_hatch_action(...) — specialized helpers

Registration vs DB (important, corrected 2026-09-04): code registration does NOT auto-create rows in the scripts DB table. run_action_script resolves the alias from the runtime registry AND requires an enabled row in scripts (Scripts::script_state), otherwise returns null. To activate a newly registered action, call Scripts::set_script_state("action", alias, true) — via CLI bootstrap (fury_init("SHServ"), same path as CronController timers) or HTTP API with a GAuth session. Aliases removed from code are dead even if still enabled in the DB. Code changes are picked up without restart (opcache.validate_timestamps=1).

Scope gate (verified 2026-09-04): a scope's constructor registers NOTHING unless Scripts::script_state("scope", ShortClassName) is enabled. Deploying a new scope file therefore requires TWO CLI passes: first enable the scope row, then (on a fresh fury_init, which re-runs constructors) enable its actions. Reference implementation: /home/shome/smart-home-server/server/enable_global_scenes.php (phases: scope / actions / status).

Trigger via API

POST http://192.168.1.101/api/v1/scripts/actions/run with {"alias": "...", "params": {}} — requires GAuth permission scripts.run (session or Bearer from shserv_sessions). CLI equivalent: \SHServ\Middleware\ControlScripts::run_action_script(alias, []) via fury_init("SHServ") bootstrap.

Current live actions (25, verified 2026-09-04)

Alias Description Target
master_toggle Вкл/Выкл. свет в спальне light_hub_1:1
hall1_toggle Вкл/Выкл. свет в нижнем холле light_hub_1:3
hall2_toggle Вкл/Выкл. свет в холле 2 эт light_hub_1:2
office_main_toggle Вкл/Выкл. основной свет в кабинете light_hub_1:0
bathroom_light_switch Вкл/Выкл. свет в ванной (2 сан узел) bathroom_2_light:0
kitchen1_toggle Вкл/Выкл. свет на кухне 1 fisrt_floor_big_relay:0
kitchen2_toggle Вкл/Выкл. свет на кухне 2 fisrt_floor_big_relay:1
computer_table_lamp_switch Вкл/Выкл. настольную компьютерную лампу computer_table_lamp:0
craft_table_lamp_switch Вкл/Выкл. лампу в мастерской craft_table_lamp:0
plants_room_light_switch Вкл/Выкл. свет в комнате растений plants_room_light:0
italy_lamp_switch Вкл/Выкл. Italy лампу italy_lamp_relay:0
floor_lamp_switch Вкл/Выкл. торшер floor_lamp_relay:0
server_room_light_switch Вкл/Выкл. свет в серверной server_room_light:0
front_spotlight_toggle Вкл/Выкл. передний прожектор spotlight_main_front_1:0
back_spotlight_1_toggle Вкл/Выкл. прожектор на заднем дворе spotlight_main_back_1:0
back_spotlight_2_toggle Вкл/Выкл. боковой уличный прожектор spotlight_main_back_2:0
hatch_open Открыть люк в подвал kitchen_hatch (dangerous)
hatch_close Закрыть люк в подвал kitchen_hatch (dangerous)
all_lights_off Весь свет выкл (21 канал) GlobalScenesScope (safe)
goodnight Спокойной ночи: свет выкл + люк закрыт + sleep GlobalScenesScope (cautious)
movie_mode Toggle режима movie GlobalScenesScope (safe)
away_toggle Toggle home/away; при уходе гасит свет GlobalScenesScope (cautious)
hatch_status Статус кухонного люка (read-only) GlobalScenesScope (safe)
night_mode Toggle режима night GlobalScenesScope (safe)
guest_mode Toggle режима guest GlobalScenesScope (safe)

The 5 toggles added on 2026-09-04 (front/back spotlights individually, hall1, office main) were verified live: each ran on→off→on cycles with state confirmed via device GET /status; group spotlight aliases were removed the same day (owner decision: individual control instead of group).

Tier 1 scenes (deployed 2026-09-04, GlobalScenesScope)

New scope automation/Scopes/GlobalScenesScope.php adds 7 system-wide scene actions (table above). all_lights_off covers 21 confirmed light channels (all of light_hub_1, 7 of 8 fisrt_floor_big_relay channels — :6 excluded, purpose unconfirmed — plus all single-channel light relays and spotlights). goodnight = all lights off + hatch close + mode sleep on + movie/guest off. away_toggle = home/away flip; on leaving it also kills all lights and reports hatch state (does not move the hatch). Mode toggles expose state_callback indicators. Deployment verified: all 7 aliases enabled in scripts and present in the runtime registry; backups in /home/shome/backups/tier1-deploy/.

Dead aliases (do not use)

Legacy rows remain in the scripts DB table but are NOT registered by code and return null: master_room_lamp_switcher, hallway2_lamp_switcher, bathroom2_lamp_switcher, main_lamps_switcher, hall1_light_switcher, kitchen_light_switcher, all_hub_toggle, spotlights_on/off, computer/craft_table_lamp_on/off, front_spotlight_on, stand_relay_toggle, spotlights_by_time, all_spotlights_off, back_spotlights_off, front_spotlight_off (group spotlight actions removed 2026-09-04). Docs referencing master_room_lamp_switch/_switcher are outdated — the bedroom action is master_toggle.

Known coverage gaps (as of 2026-09-04)

  • No global "all lights off" action — RESOLVED 2026-09-04: all_lights_off in GlobalScenesScope.
  • ~17 legacy dead rows in scripts DB table — cleanup pending (backlog).
  • light_hub_1:3 has no sync-map connection (physical button in lower hall, if any, is not synchronized with API toggles).
  • No relay hardware for: гостинная, гостевая спальня, vika_room, главный сан узел, подвал, чердак, хоз домик.

Modes System (verified 2026-09-04)

Runtime state lives in DB table shserv_modes (tag PK, is_active, updated_at); tag definitions are in automation/ModesRegistry.php. Tags are boolean context flags, not mutually exclusive states; tags are lazily synced from the registry. Registered tags: home (Дома), away (Не дома), night (Ночь), sleep (Сон), movie (Кино), guest (Гости). All tags were is_active=0 at verification time.

REST API (reads require scripts.view, writes require scripts.edit):

  • GET /api/v1/modes/list — all modes + total
  • GET /api/v1/modes/active — currently active tags
  • POST /api/v1/modes/{tag}/enable — enable tag (tag: ^[a-z0-9_]{1,32}$)
  • POST /api/v1/modes/{tag}/disable — disable tag

Since 2026-09-04 GlobalScenesScope consumes and flips mode tags (movie_mode, night_mode, guest_mode toggles; goodnight enables sleep; away_toggle flips home/away). No event-driven automation reacts to tags yet — scopes can query via $this->mode()->is(tag).

Device & Channel Inventory (verified 2026-09-04)

29 active devices in DB shome.devices (status != removed/freezed): 11 relay, 16 button, 1 hatch, 1 sensor. Device fields: id, area_id, alias, name, device_type, device_ip, connection_status, status, firmware_version, last_contact. 26 areas. Relay channel maps (live-verified via GET /status with device Bearer token):

  • light_hub_1 (id 13, 192.168.2.32): 4 channels, inverted=false; all four channels are covered by actions (office :0, master bedroom :1, hall 2nd floor :2, lower hall :3).
  • fisrt_floor_big_relay (id 31, 192.168.2.124): 8 channels, inverted=true (logical off = physically closed); individual actions cover :0 (kitchen1) and :1 (kitchen2); all_lights_off/goodnight/away_toggle additionally switch :2–:5 and :7 off. Channels :2 and :6 were observed ON with no sync-map entry — purpose unconfirmed (:6 deliberately excluded from scene targets).

Uncovered control points: fisrt_floor_big_relay:6 (no actions, purpose unconfirmed), light_hub_1:3 (no sync-map — physical lower-hall button, if any, is not synchronized with API toggles). Button blocks exist for rooms without relay hardware (e.g. buttons_living_room, гостинная) — see coverage gaps above.

Device API Auth (verified 2026-09-04)

ESP devices require Authorization: Bearer <device_token> for GET /status. Tokens (one active 16-hex token per device) live in DB table device_auth (device_id, device_token, status active/killed). GET /about is open without auth and returns device_name, device_type, firmware_version, core_version, device_id, server, status, ip, mac, wifi_signal, uptime, channels. Relay device API (SHServ/Tools/DeviceAPI/Relay.php): toggle_channel(channel), set_state(on|off), set_channel_state(state, channel) via POST /action on the device.

Exact wire format (live-verified 2026-09-04 on light_hub_1): POST http://<device_ip>/action with Authorization: Bearer <device_token> and JSON body {"action":"set_channel_state","channel":N,"state":"on"|"off"}; also valid: {"action":"set_state","state":"on"|"off"} (all channels) and {"action":"toggle_channel","channel":N}. The action field is mandatory — bodies without it (e.g. {"channel":N,"state":"on"}) return HTTP 400 IllegalActionOrParams ("Action is required"); unknown action values return 400 "Unknown action". Allowed actions per relay firmware (devices/relay/relay.ino, deviceHandleAction): set_state, set_channel_state, toggle_channel. Success response: HTTP 200 {"status":"ok","message":"Action executed"}.

Sensor Firmware Capabilities (verified 2026-09-04, from devices/ firmware)

Sensor firmware supports: BH1750 (illuminance), BME280 (temperature/humidity/pressure), LD2420 (presence radar), MAX4466 (noise/mic). Only one sensor is deployed: office_main_sensore (id 30, 192.168.2.111) — connection_status=lost, HTTP unresponsive at verification. No telemetry history exists: the logs table is empty; Sensor.php device API class is an empty Base extension (metrics format is defined by device firmware).

Empty Subsystems (verified 2026-09-04)

  • shserv_timers: 0 rows (platform cron tasks status-update-scanning, regular-scripts, run-timers exist; no timers registered).
  • groups and shserv_group_members: empty (groups are user groups, not device groups; no device grouping in use).
  • logs: empty — no event/telemetry history.
  • scripts DB rows (post Tier-1 deploy): 45 action (25 live, 17 enabled-but-dead, 3 disabled: front_spotlight_off, kitchen1_on, kitchen2_on) + 1 regular disabled (spotlights_by_time) + 14 scope rows (9 have PHP files in automation/Scopes/ incl. GlobalScenesScope; SleepScope, LightHubScope, SpotlightsScope, TestScriptsScope, OfficeRoomScope rows are dead — no code).
  • params_schema is empty for all action rows.