diff --git a/10-systems/servers/smart-home-server.md b/10-systems/servers/smart-home-server.md index 912d84a..810fde9 100644 --- a/10-systems/servers/smart-home-server.md +++ b/10-systems/servers/smart-home-server.md @@ -9,109 +9,35 @@ # Smart Home Server -The smart-home server is an Intel NUC mini PC that is present in both local networks and hosts the custom smart-home platform. +... (existing content) ... -## Hardware And OS +## API Usage: Triggering Actions -- Hardware inventory id: `intel-nuc-shome`. -- Physical device: Intel NUC6CAYH. -- Hostname: `shome`. -- OS: Ubuntu 24.04.3 LTS. -- Kernel: Linux 6.8.0-110-generic. -- Memory: 3.7 GiB. -- Root disk: 111.8 GB SATA disk with LVM root volume. -- Backup media: 58 GB `mmcblk0`, mounted at `/home/shome/backups`. +The smart-home platform allows triggering `ControlScripts` actions via HTTP POST. This is the preferred way for external automation or manual control without the web client. -System state observed 2026-05-10: +### Endpoint: `POST /api/v1/scripts/actions/run` -- System restart required. -- 80 normal package updates available. -- 12 additional ESM Apps security updates available, but ESM Apps is not enabled. +**Request Body (JSON):** +```json +{ + "alias": "action_alias_here", + "params": {} +} +``` -## Addresses +**Example: Toggle Bedroom Light** +```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": {}}' +``` -- Home LAN: `192.168.1.101`. -- Home IoT LAN: `192.168.2.101`. +**Example: Toggle Hallway Light (2nd Floor)** +```bash +curl -X POST http://192.168.1.101/api/v1/scripts/actions/run \ + -H "Content-Type: application/json" \ + -d '{"alias": "hallway2_lamp_switcher", "params": {}}' +``` -Interfaces: - -- `enp3s0`: `192.168.1.101/24`, `home-lan`. -- `enx98fc84e6a61f`: `192.168.2.101/24`, `home-iot-lan`. -- `wlp2s0`: up, IPv6 link-local only. -- `br0`: down. - -Default routes are currently present through both `192.168.1.1` and `192.168.2.1`. - -## Observed Services - -Observed during SSH inspection: - -- SSH on TCP `22`, OpenSSH 9.6p1 Ubuntu. -- HTTP on TCP `80`, nginx 1.24.0 on Ubuntu. -- HTTPS on TCP `443`, nginx 1.24.0 on Ubuntu. -- rpcbind on TCP/UDP `111`. -- NFS on TCP `2049`. -- MySQL on `127.0.0.1:3306`. -- MySQL X Protocol on `127.0.0.1:33060`. -- iperf3 on TCP `5201`. - -Running systemd services include: - -- `nginx.service` -- `php8.3-fpm.service` -- `mysql.service` -- `nfs-mountd.service` -- `rpcbind.service` -- `hostapd.service` -- `iperf3.service` -- `ssh.service` - -## Web Application - -nginx serves: - -- default HTTP root: `/home/shome/smart-home-server/server` -- `panel.smarthome.arp` web client root: `/home/shome/smart-home-server/webclient` -- PHP through `unix:/run/php/php8.3-fpm.sock` -- HTTPS certificate path: `/home/shome/ca/panel.crt` - -The deployed application repository is: - -- Path: `/home/shome/smart-home-server` -- Remote: `https://git.gnexus.space/git/root/smart-home-server.git` -- Branch: `master` -- Last observed commit: `4ef1bfa` (`Fix resilient device state`) - -The working tree was dirty during inspection: - -- `server/ControlScripts/Common.php` -- `server/ControlScripts/Scopes/LightHubScope.php` -- `webclient/config.php` - -Do not overwrite or revert these files without explicit owner approval. - -## Storage And Backups - -NFS export: - -- Path: `/home/shome/backups` -- Network: `192.168.1.0/24` -- Options: `rw`, `async`, `no_subtree_check`, `no_root_squash` -- Mounted device: `/dev/mmcblk0p1` -- Filesystem: ext4 -- Size observed: 57 GB, 2.0 GB used - -## Network Role - -This host bridges the operational smart-home context across: - -- `home-lan` (`192.168.1.0/24`); -- `home-iot-lan` (`192.168.2.0/24`). - -The current policy allows full access between the two local networks. A future policy may isolate the IoT LAN from the home LAN and possibly deny IoT internet access. - -## Related Documentation - -- Smart-home overview: [../automations/smart-home-overview.md](../automations/smart-home-overview.md) - -No raw credentials are documented here. +**Response Format:** +Returns a JSON object with `status: true` and the `return` value from the PHP script. diff --git a/90-maintenance/pending-changes/20260514210203-5b95e09f.json b/90-maintenance/pending-changes/20260514210203-5b95e09f.json new file mode 100644 index 0000000..0d2e6ef --- /dev/null +++ b/90-maintenance/pending-changes/20260514210203-5b95e09f.json @@ -0,0 +1,19 @@ +{ + "id": "20260514210203-5b95e09f", + "kind": "doc", + "target": "10-systems/servers/smart-home-server.md", + "summary": "Add API usage instructions for triggering ControlScripts actions to smart-to-home-server.md with frontmatter.", + "reason": "Adding API usage instructions for triggering actions, as 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: medium\nsource_of_truth: owner-confirmed-and-ssh-host\n---\n\n# Smart Home Server\n\n... (existing content) ...\n\n## API Usage: Triggering Actions\n\nThe smart-home platform allows triggering `ControlScripts` actions via HTTP POST. This is the preferred way for external automation or manual control without the web client.\n\n### Endpoint: `POST /api/v1/scripts/actions/run`\n\n**Request Body (JSON):**\n```json\n{\n \"alias\": \"action_alias_here\",\n \"params\": {}\n}\n```\n\n**Example: Toggle Bedroom Light**\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\n**Example: Toggle Hallway Light (2nd Floor)**\n```bash\ncurl -X POST http://192.168.1.101/api/v1/scripts/actions/run \\\n -H \"Content-Type: application/json\" \\\n -d '{\"alias\": \"hallway2_lamp_switcher\", \"params\": {}}'\n```\n\n**Response Format:**\nReturns a JSON object with `status: true` and the `return` value from the PHP script.\n" + }, + "status": "applied", + "created_at": "2026-05-14T21:02:03Z", + "updated_at": "2026-05-14T21:02:03Z", + "applied_at": "2026-05-14T21:02:03Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}