diff --git a/10-systems/automations/smart-home-overview.md b/10-systems/automations/smart-home-overview.md index 423c570..6987eaf 100644 --- a/10-systems/automations/smart-home-overview.md +++ b/10-systems/automations/smart-home-overview.md @@ -100,6 +100,8 @@ 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. +Exact wire format (live-verified 2026-09-04 on `light_hub_1`): `POST http:///action` with `Authorization: Bearer ` 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). diff --git a/90-maintenance/pending-changes/20260904184827-b323a52e.json b/90-maintenance/pending-changes/20260904184827-b323a52e.json new file mode 100644 index 0000000..2aa8577 --- /dev/null +++ b/90-maintenance/pending-changes/20260904184827-b323a52e.json @@ -0,0 +1,19 @@ +{ + "id": "20260904184827-b323a52e", + "kind": "doc", + "target": "10-systems/automations/smart-home-overview.md", + "summary": "Add exact POST /action wire format for relay devices (live-verified on light_hub_1): mandatory action field, allowed actions set_state/set_channel_state/toggle_channel, 400 without action.", + "reason": "Обнаружено при живом включении каналов light_hub_1: три формата тела POST /action без поля \"action\" отклонены устройством (400 IllegalActionOrParams); рабочий формат найден в исходнике прошивки devices/relay/relay.ino (deviceHandleAction). Фиксирую точный wire-формат, чтобы будущие агенты не тратили попытки на подбор.", + "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\nExact wire format (live-verified 2026-09-04 on `light_hub_1`): `POST http:///action` with `Authorization: Bearer ` 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\"}`.\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-04T18:48:27Z", + "updated_at": "2026-09-04T18:48:28Z", + "applied_at": "2026-09-04T18:48:28Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}