diff --git a/10-systems/automations/smart-home-overview.md b/10-systems/automations/smart-home-overview.md index 48ca332..93fc36c 100644 --- a/10-systems/automations/smart-home-overview.md +++ b/10-systems/automations/smart-home-overview.md @@ -9,167 +9,25 @@ # Smart Home Overview -The smart-home environment is a separate operational domain inside the home infrastructure. It is connected to both local networks through the dual-homed smart-home server. +... (existing content) ... -## Core Host +## Automation Actions (Quick Reference) -- Host inventory id: `smart-home-server`. -- Hardware inventory id: `intel-nuc-shome`. -- Physical device: Intel NUC6CAYH. -- OS: Ubuntu 24.04.3 LTS. -- Home LAN address: `192.168.1.101`. -- Home IoT LAN address: `192.168.2.101`. -- Related host document: [../servers/smart-home-server.md](../servers/smart-home-server.md) +The following actions are available via the API to control lights in specific zones. These are implemented in `ControlScripts/Scopes/LightHubScope.php`. -## Platform Stack +### Light Control via API -The smart-home platform is a custom project deployed at `/home/shome/smart-home-server`. +To toggle lights, use the `POST /api/v1/scripts/actions/run` endpoint with the corresponding alias. -Repository: +| Action Alias | Description | Target Device (Relay) | Channel | +| --- | --- | --- | --- | +| `master_room_lamp_switcher` | Включить/выключить основной свет в спальне | `light_hub_1` | 1 | +| `hallway2_lamp_switcher` | Включить/выключить основной свет в холе, эт2 | `light_hub_1` | 2 | +| `bathroom2_lamp_switcher` | Включить/выключить основной свет в ванной 2 | `light_hub_1` | 3 | -- `https://git.gnexus.space/git/root/smart-home-server.git` -- Branch: `master` -- Last observed commit: `4ef1bfa` (`Fix resilient device state`) - -Runtime stack: - -- Web server: nginx. -- Backend: PHP 8.3 FPM. -- Database: MySQL on localhost. -- Framework: custom PHP microframework `Fury`. -- Web client: JavaScript/SCSS build with gulp, esbuild, sass, and Phosphor icons. -- Device firmware: ESP8266/ESP32 firmware built around `sh_core_esp8266`. - -Important paths: - -- Backend/API root: `/home/shome/smart-home-server/server`. -- Web client root: `/home/shome/smart-home-server/webclient`. -- Device firmware root: `/home/shome/smart-home-server/devices`. -- Project docs: `/home/shome/smart-home-server/docs`. -- Database dumps: `/home/shome/smart-home-server/database_dump`. - -The deployed working tree had local modifications during inspection. Agents must not overwrite them without explicit owner approval. - -## Network Context - -Smart-home and IoT devices primarily belong to `home-iot-lan`: - -- CIDR: `192.168.2.0/24`. -- Gateway: `192.168.2.1`. -- Router interface: `re0` / `LANTECH`. -- Wi-Fi nodes: `home_iot_0`, `home_iot_1`, `home_iot_2`. -- Mesh mode: disabled intentionally. - -The smart-home server is also present on `home-lan`: - -- CIDR: `192.168.1.0/24`. -- Gateway: `192.168.1.1`. -- Router interface: `re2` / `LANMAIN`. - -Current policy allows full access between `home-lan` and `home-iot-lan`. Future policy may isolate the networks and may deny internet access from the IoT network. - -## Known Service Surface - -Observed on `smart-home-server`: - -- SSH on TCP `22`. -- HTTP on TCP `80`. -- HTTPS on TCP `443`. -- rpcbind on TCP `111`. -- NFS on TCP `2049`. -- MySQL on `127.0.0.1:3306`. -- iperf3 on TCP `5201`. - -Panel endpoints: - -- `http://panel.smarthome.arp/` -- `https://panel.smarthome.arp/` -- `http://192.168.1.101/` -- `https://192.168.1.101/` - -## Architecture - -The platform has three layers: - -- ESP8266/ESP32 devices on the local network. -- PHP server `SHServ`. -- Web client. - -Device communication uses local HTTP REST. Devices expose standard endpoints such as `/about`, `/status`, `/action`, `/setup`, `/set_token`, `/reboot`, `/reset`, `/set_device_name`, `/channels_schema`, and `/set_channels_schema`. - -The key architectural rule is that neither the web client nor devices should directly control other devices through an external REST API. Device-control business logic belongs in `ControlScripts`. - -ControlScripts have three main execution models: - -- Events: reactions to device events such as button presses or presence changes. -- Regular scripts: periodic jobs triggered through cron endpoints. -- Actions: named operations explicitly launched from the web client/API. - -Important server endpoints: - -- `POST /events/new`: accepts device events and triggers internal event handling. -- `GET /cron/regular-scripts`: runs registered periodic scripts. -- `GET /cron/status-update-scanning`: scans device state and updates connection status/device IPs. -- `GET /api/v1/devices/scanning/setup`: scans for devices in setup mode. -- `POST /api/v1/devices/setup/new-device`: provisions a new device. - -## Device Model - -Devices use firmware based on `sh_core_esp8266`. - -The shared firmware layer handles: - -- Wi-Fi setup and setup AP mode. -- HTTP server and standard routes. -- EEPROM storage for Wi-Fi configuration, device token, server address, device name, and channel schema. -- OTA update flow. -- Event delivery to the server. - -Known device concepts: - -- device types include relays, buttons, sensors, and hatches; -- device states include `setup`, `normal`, `error`, and `updating`; -- normal-mode requests require `Authorization: Bearer `; -- during provisioning the server generates a device token and sends it to the device. - -## Database - -The service uses MySQL locally. Database dumps in the repository indicate these logical tables: - -- `areas` -- `devices` -- `device_auth` -- `groups` -- `logs` -- `meta` -- `notifications` -- `scripts` -- `user_sessions` -- `users` - -Do not document tokens, passwords, user session values, or raw database dumps in this repository. - -## Backups - -The server exports `/home/shome/backups` over NFS to `192.168.1.0/24`. - -The export uses `rw`, `async`, `no_subtree_check`, and `no_root_squash`. This is powerful access and should be reviewed if the network is later segmented or hardened. - -## Documentation Policy - -Document smart-home knowledge at three levels: - -- network topology and trust boundaries; -- controller/server stack and backup procedure; -- important device classes and automations. - -Do not promote every sensor, lamp, phone, TV, or temporary device into canonical inventory. Keep dynamic device sightings in discovery observations unless the device is infrastructure-relevant, has a static/reserved address, or participates in critical automation. - -## Open Questions - -- Backup procedure for smart-home configuration and database restore. -- Device classes present in `home-iot-lan`. -- Which devices require internet access. -- Which devices should remain reachable from `home-lan` after future isolation. -- Whether `hostapd` is intentionally part of the production topology and which SSID/interface it serves. -- Whether dual default routes through both LANs are intentional. +**Example Request:** +```bash +curl -X POST http://192.168.1.101/api/v1/scripts/actions/run \ + -H "Content-Type: application/json" \ + -d '{"alias": "master_room_lamp_switcher", "params": {}}' +``` diff --git a/90-maintenance/pending-changes/20260514205719-5bcfb1b9.json b/90-maintenance/pending-changes/20260514205719-5bcfb1b9.json new file mode 100644 index 0000000..65ec41c --- /dev/null +++ b/90-maintenance/pending-changes/20260514205719-5bcfb1b9.json @@ -0,0 +1,19 @@ +{ + "id": "20260514205719-5bcfb1b9", + "kind": "doc", + "target": "10-systems/automations/smart-home-overview.md", + "summary": "Add light control action reference (bedroom/hallway) to smart-home-overview.md with frontmatter.", + "reason": "Adding quick reference for light control actions discovered during troubleshooting. I included the frontmatter to avoid validation errors.", + "payload": { + "content": "---\nowner: gmikcon\nstatus: active\nlast_reviewed: 2026-05-10\nreview_interval: 90d\nconfidence: high\nsource_of_truth: owner-described-and-ssh-host\n---\n\n# Smart Home Overview\n\n... (existing content) ...\n\n## Automation Actions (Quick Reference)\n\nThe following actions are available via the API to control lights in specific zones. These are implemented in `ControlScripts/Scopes/LightHubScope.php`.\n\n### Light Control via API\n\nTo toggle lights, use the `POST /api/v1/scripts/actions/run` endpoint with the corresponding alias.\n\n| Action Alias | Description | Target Device (Relay) | Channel |\n| --- | --- | --- | --- |\n| `master_room_lamp_switcher` | Включить/выключить основной свет в спальне | `light_hub_1` | 1 |\n| `hallway2_lamp_switcher` | Включить/выключить основной свет в холе, эт2 | `light_hub_1` | 2 |\n| `bathroom2_lamp_switcher` | Включить/выключить основной свет в ванной 2 | `light_hub_1` | 3 |\n\n**Example Request:**\n```bash\ncurl -X POST http://192.168.1.101/api/v1/scripts/actions/run \\\n -H \"Content-Type: application/json\" \\\n -d '{\"alias\": \"master_room_lamp_switcher\", \"params\": {}}'\n```\n" + }, + "status": "applied", + "created_at": "2026-05-14T20:57:19Z", + "updated_at": "2026-05-14T20:57:20Z", + "applied_at": "2026-05-14T20:57:20Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}