diff --git a/10-systems/automations/smart-home-overview.md b/10-systems/automations/smart-home-overview.md index bb68706..dc8a951 100644 --- a/10-systems/automations/smart-home-overview.md +++ b/10-systems/automations/smart-home-overview.md @@ -61,3 +61,40 @@ - ~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 + +Note: no automation currently reacts to mode tags — enabling a tag only flips runtime state until scopes start consuming modes. + +## 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. + +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. + +## Device API Auth (verified 2026-09-04) + +ESP 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. + +## 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: 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). +- `params_schema` is empty for all action rows. diff --git a/90-maintenance/pending-changes/20260904162939-344949c4.json b/90-maintenance/pending-changes/20260904162939-344949c4.json new file mode 100644 index 0000000..db836f5 --- /dev/null +++ b/90-maintenance/pending-changes/20260904162939-344949c4.json @@ -0,0 +1,19 @@ +{ + "id": "20260904162939-344949c4", + "kind": "doc", + "target": "10-systems/automations/smart-home-overview.md", + "summary": "Add verified modes system, device/channel inventory, device API auth, sensor capabilities, and empty-subsystem facts to smart-home overview", + "reason": "Live read-only recon of shome@192.168.1.101 (2026-09-04): modes system and REST API, device/channel inventory, device Bearer auth, sensor firmware capabilities, empty subsystems — none of this was documented.", + "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). 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### 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 (18, 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\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### 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 — backlog, owner decision pending.\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\nNote: no automation currently reacts to mode tags — enabling a tag only flips runtime state until scopes start consuming modes.\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); 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.\n\nUncovered 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.\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: 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).\n- `params_schema` is empty for all action rows." + }, + "status": "applied", + "created_at": "2026-09-04T16:29:39Z", + "updated_at": "2026-09-04T16:29:40Z", + "applied_at": "2026-09-04T16:29:40Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}