diff --git a/10-systems/automations/smart-home-overview.md b/10-systems/automations/smart-home-overview.md index dc8a951..423c570 100644 --- a/10-systems/automations/smart-home-overview.md +++ b/10-systems/automations/smart-home-overview.md @@ -13,7 +13,7 @@ ## 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). Each class extends `ControlScripts` and registers actions in `register_actions_scripts()` via helpers from the `Common` trait: +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 @@ -22,11 +22,13 @@ **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 (18, verified 2026-09-04) +### Current live actions (25, verified 2026-09-04) | Alias | Description | Target | | --- | --- | --- | @@ -48,16 +50,27 @@ | `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 — backlog, owner decision pending. +- ~~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, главный сан узел, подвал, чердак, хоз домик. @@ -72,16 +85,16 @@ - `POST /api/v1/modes/{tag}/enable` — enable tag (`tag`: `^[a-z0-9_]{1,32}$`) - `POST /api/v1/modes/{tag}/disable` — disable tag -Note: no automation currently reacts to mode tags — enabling a tag only flips runtime state until scopes start consuming modes. +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); actions cover only `:0` (kitchen1) and `:1` (kitchen2). Channels `:2`–`:7` have no actions; `:2` and `:6` were observed ON with no sync-map entry — purpose unconfirmed. +- `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:2..7` (no actions), `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. +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) @@ -96,5 +109,5 @@ - `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: 39 action (18 live, 17 enabled-but-dead, 3 disabled: `front_spotlight_off`, `kitchen1_on`, `kitchen2_on`) + 1 regular disabled (`spotlights_by_time`) + 12 scope rows (only 8 have PHP files in `automation/Scopes/`; `SleepScope`, `LightHubScope`, `SpotlightsScope`, `TestScriptsScope` rows are dead — no code). +- `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. diff --git a/90-maintenance/pending-changes/20260904174036-1711f5fe.json b/90-maintenance/pending-changes/20260904174036-1711f5fe.json new file mode 100644 index 0000000..8f86803 --- /dev/null +++ b/90-maintenance/pending-changes/20260904174036-1711f5fe.json @@ -0,0 +1,19 @@ +{ + "id": "20260904174036-1711f5fe", + "kind": "doc", + "target": "10-systems/automations/smart-home-overview.md", + "summary": "Tier 1 deployed: GlobalScenesScope with 7 scene actions; live actions 18→25; all-lights-off gap resolved; scope-gate two-pass activation documented; DB counters corrected (45 action / 14 scope rows).", + "reason": "Tier 1 scenes deployed and live-verified on shome: GlobalScenesScope with 7 actions (all_lights_off, goodnight, movie_mode, away_toggle, hatch_status, night_mode, guest_mode). Counters re-verified in DB: 45 action rows (42 enabled), 14 scope rows. Coverage gap \"no all lights off\" resolved.", + "payload": { + "content": "---\nowner: gmikcon\nstatus: active\nlast_reviewed: 2026-09-04\nreview_interval: 90d\nconfidence: high\nsource_of_truth: ssh-host-verified\n---\n\n# Smart Home Overview\n\n... (existing content) ...\n\n## Automation Actions (verified 2026-09-04)\n\nActions 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:\n\n- `add_toggle_action(alias, name, relay_alias, channel, attrs)` — single relay toggle\n- `add_group_toggle_action(alias, name, [\"device:channel\", ...], attrs)` — multi-relay toggle\n- `add_action_script(attrs, callable)` — custom action (attrs: `alias`, `name`, `description`, `icon`, `author`, `danger_level` safe/cautious/dangerous, `state_callback`, `params_schema`)\n- `add_off_action(...)`, `add_hatch_action(...)` — specialized helpers\n\n**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`).\n\n**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`).\n\n### Trigger via API\n\n`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.\n\n### Current live actions (25, verified 2026-09-04)\n\n| Alias | Description | Target |\n| --- | --- | --- |\n| `master_toggle` | Вкл/Выкл. свет в спальне | `light_hub_1:1` |\n| `hall1_toggle` | Вкл/Выкл. свет в нижнем холле | `light_hub_1:3` |\n| `hall2_toggle` | Вкл/Выкл. свет в холле 2 эт | `light_hub_1:2` |\n| `office_main_toggle` | Вкл/Выкл. основной свет в кабинете | `light_hub_1:0` |\n| `bathroom_light_switch` | Вкл/Выкл. свет в ванной (2 сан узел) | `bathroom_2_light:0` |\n| `kitchen1_toggle` | Вкл/Выкл. свет на кухне 1 | `fisrt_floor_big_relay:0` |\n| `kitchen2_toggle` | Вкл/Выкл. свет на кухне 2 | `fisrt_floor_big_relay:1` |\n| `computer_table_lamp_switch` | Вкл/Выкл. настольную компьютерную лампу | `computer_table_lamp:0` |\n| `craft_table_lamp_switch` | Вкл/Выкл. лампу в мастерской | `craft_table_lamp:0` |\n| `plants_room_light_switch` | Вкл/Выкл. свет в комнате растений | `plants_room_light:0` |\n| `italy_lamp_switch` | Вкл/Выкл. Italy лампу | `italy_lamp_relay:0` |\n| `floor_lamp_switch` | Вкл/Выкл. торшер | `floor_lamp_relay:0` |\n| `server_room_light_switch` | Вкл/Выкл. свет в серверной | `server_room_light:0` |\n| `front_spotlight_toggle` | Вкл/Выкл. передний прожектор | `spotlight_main_front_1:0` |\n| `back_spotlight_1_toggle` | Вкл/Выкл. прожектор на заднем дворе | `spotlight_main_back_1:0` |\n| `back_spotlight_2_toggle` | Вкл/Выкл. боковой уличный прожектор | `spotlight_main_back_2:0` |\n| `hatch_open` | Открыть люк в подвал | `kitchen_hatch` (dangerous) |\n| `hatch_close` | Закрыть люк в подвал | `kitchen_hatch` (dangerous) |\n| `all_lights_off` | Весь свет выкл (21 канал) | GlobalScenesScope (safe) |\n| `goodnight` | Спокойной ночи: свет выкл + люк закрыт + sleep | GlobalScenesScope (cautious) |\n| `movie_mode` | Toggle режима movie | GlobalScenesScope (safe) |\n| `away_toggle` | Toggle home/away; при уходе гасит свет | GlobalScenesScope (cautious) |\n| `hatch_status` | Статус кухонного люка (read-only) | GlobalScenesScope (safe) |\n| `night_mode` | Toggle режима night | GlobalScenesScope (safe) |\n| `guest_mode` | Toggle режима guest | GlobalScenesScope (safe) |\n\nThe 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).\n\n### Tier 1 scenes (deployed 2026-09-04, GlobalScenesScope)\n\nNew 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/`.\n\n### Dead aliases (do not use)\n\nLegacy 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`.\n\n### Known coverage gaps (as of 2026-09-04)\n\n- ~~No global \"all lights off\" action~~ — RESOLVED 2026-09-04: `all_lights_off` in GlobalScenesScope.\n- ~17 legacy dead rows in `scripts` DB table — cleanup pending (backlog).\n- `light_hub_1:3` has no sync-map connection (physical button in lower hall, if any, is not synchronized with API toggles).\n- No relay hardware for: гостинная, гостевая спальня, vika_room, главный сан узел, подвал, чердак, хоз домик.\n\n## Modes System (verified 2026-09-04)\n\nRuntime 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.\n\nREST API (reads require `scripts.view`, writes require `scripts.edit`):\n- `GET /api/v1/modes/list` — all modes + total\n- `GET /api/v1/modes/active` — currently active tags\n- `POST /api/v1/modes/{tag}/enable` — enable tag (`tag`: `^[a-z0-9_]{1,32}$`)\n- `POST /api/v1/modes/{tag}/disable` — disable tag\n\nSince 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)`.\n\n## Device & Channel Inventory (verified 2026-09-04)\n\n29 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):\n\n- `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`).\n- `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).\n\nUncovered 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.\n\n## Device API Auth (verified 2026-09-04)\n\nESP devices require `Authorization: Bearer ` 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.\n\n## Sensor Firmware Capabilities (verified 2026-09-04, from devices/ firmware)\n\nSensor 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).\n\n## Empty Subsystems (verified 2026-09-04)\n\n- `shserv_timers`: 0 rows (platform cron tasks `status-update-scanning`, `regular-scripts`, `run-timers` exist; no timers registered).\n- `groups` and `shserv_group_members`: empty (groups are user groups, not device groups; no device grouping in use).\n- `logs`: empty — no event/telemetry history.\n- `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).\n- `params_schema` is empty for all action rows." + }, + "status": "applied", + "created_at": "2026-09-04T17:40:36Z", + "updated_at": "2026-09-04T17:40:37Z", + "applied_at": "2026-09-04T17:40:37Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}