diff --git a/10-systems/automations/smart-home-overview.md b/10-systems/automations/smart-home-overview.md index 791f8f8..48ca332 100644 --- a/10-systems/automations/smart-home-overview.md +++ b/10-systems/automations/smart-home-overview.md @@ -3,8 +3,8 @@ status: active last_reviewed: 2026-05-10 review_interval: 90d -confidence: medium -source_of_truth: owner-described-and-nmap-observed +confidence: high +source_of_truth: owner-described-and-ssh-host --- # Smart Home Overview @@ -14,10 +14,42 @@ ## Core Host - 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) +## Platform Stack + +The smart-home platform is a custom project deployed at `/home/shome/smart-home-server`. + +Repository: + +- `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`: @@ -44,8 +76,84 @@ - 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`. -The exact smart-home application stack still needs to be documented. +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 @@ -59,8 +167,9 @@ ## Open Questions -- Exact smart-home platform and version. -- Backup procedure for smart-home configuration. +- 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. diff --git a/10-systems/servers/smart-home-server.md b/10-systems/servers/smart-home-server.md index 0f0ac03..912d84a 100644 --- a/10-systems/servers/smart-home-server.md +++ b/10-systems/servers/smart-home-server.md @@ -4,26 +4,102 @@ last_reviewed: 2026-05-10 review_interval: 90d confidence: medium -source_of_truth: owner-confirmed-and-nmap-observed +source_of_truth: owner-confirmed-and-ssh-host --- # Smart Home Server -The smart-home server is present in both local networks. +The smart-home server is an Intel NUC mini PC that is present in both local networks and hosts the custom smart-home platform. + +## Hardware And OS + +- 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`. + +System state observed 2026-05-10: + +- System restart required. +- 80 normal package updates available. +- 12 additional ESM Apps security updates available, but ESM Apps is not enabled. ## Addresses - Home LAN: `192.168.1.101`. - Home IoT LAN: `192.168.2.101`. +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 on `192.168.1.101` during local network discovery: +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 `111`. +- 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 diff --git a/40-inventory/backups.yml b/40-inventory/backups.yml index bdf8013..c0fd53e 100644 --- a/40-inventory/backups.yml +++ b/40-inventory/backups.yml @@ -1,3 +1,29 @@ # Backup policies and restore targets. --- -[] +- id: smart-home-nfs-backups + name: Smart Home NFS Backups + type: nfs-export + status: active + target: smart-home-platform + method: NFS export and project database dumps + frequency: unknown + retention: unknown + storage: /home/shome/backups + restore_runbook: not documented yet + host: smart-home-server + path: /home/shome/backups + mounted_device: /dev/mmcblk0p1 + filesystem: ext4 + size: 57G + used: 2.0G + export: + network: 192.168.1.0/24 + options: + - rw + - async + - no_subtree_check + - no_root_squash + related_service: smart-home-platform + docs: ../10-systems/servers/smart-home-server.md + last_reviewed: 2026-05-10 + source_of_truth: ssh-host diff --git a/40-inventory/databases.yml b/40-inventory/databases.yml index 38763a5..8e60ebe 100644 --- a/40-inventory/databases.yml +++ b/40-inventory/databases.yml @@ -1,3 +1,29 @@ # Database instances and logical databases. --- -[] +- id: smart-home-mysql + name: Smart Home MySQL + engine: mysql + status: active + host: smart-home-server + used_by: + - smart-home-platform + backup_policy: smart-home-nfs-backups + listen: + host: 127.0.0.1 + port: 3306 + related_service: smart-home-platform + known_tables_from_dump: + - areas + - devices + - device_auth + - groups + - logs + - meta + - notifications + - scripts + - user_sessions + - users + dump_location: /home/shome/smart-home-server/database_dump + docs: ../10-systems/automations/smart-home-overview.md + last_reviewed: 2026-05-10 + source_of_truth: ssh-host-file-layout diff --git a/40-inventory/endpoints.yml b/40-inventory/endpoints.yml index f8e5b06..9dc7b0f 100644 --- a/40-inventory/endpoints.yml +++ b/40-inventory/endpoints.yml @@ -106,11 +106,12 @@ host: 192.168.1.101 port: 80 owner_host: smart-home-server - purpose: Smart-home server web endpoint on the home LAN. + service: smart-home-platform + purpose: Smart-home panel and API endpoint on the home LAN. auth: required docs: ../10-systems/servers/smart-home-server.md last_reviewed: 2026-05-10 - source_of_truth: nmap-observed-and-owner-confirmed + source_of_truth: ssh-nginx-and-owner-confirmed - id: smart-home-panel-https name: Smart Home Panel HTTPS @@ -122,11 +123,46 @@ host: 192.168.1.101 port: 443 owner_host: smart-home-server - purpose: Smart-home server HTTPS endpoint on the home LAN. + service: smart-home-platform + purpose: HTTPS endpoint for panel.smarthome.arp. auth: required docs: ../10-systems/servers/smart-home-server.md last_reviewed: 2026-05-10 - source_of_truth: nmap-observed-and-owner-confirmed + source_of_truth: ssh-nginx-and-owner-confirmed + +- id: smart-home-panel-hostname-http + name: Smart Home Panel hostname HTTP + type: smart-home-ui + status: active + exposure: local + url: http://panel.smarthome.arp/ + protocol: http + host: panel.smarthome.arp + port: 80 + owner_host: smart-home-server + service: smart-home-platform + purpose: Hostname-based HTTP endpoint for the smart-home web client. + auth: required + docs: ../10-systems/automations/smart-home-overview.md + last_reviewed: 2026-05-10 + source_of_truth: ssh-nginx + +- id: smart-home-panel-hostname-https + name: Smart Home Panel hostname HTTPS + type: smart-home-ui + status: active + exposure: local + url: https://panel.smarthome.arp/ + protocol: https + host: panel.smarthome.arp + port: 443 + owner_host: smart-home-server + service: smart-home-platform + purpose: Hostname-based HTTPS endpoint for the smart-home web client using a local certificate. + auth: required + docs: ../10-systems/automations/smart-home-overview.md + last_reviewed: 2026-05-10 + source_of_truth: ssh-nginx - id: klipper-printer-mainsail name: Klipper Printer Mainsail UI diff --git a/40-inventory/hardware.yml b/40-inventory/hardware.yml index bd59cda..be4fa6c 100644 --- a/40-inventory/hardware.yml +++ b/40-inventory/hardware.yml @@ -158,3 +158,43 @@ docs: ../10-systems/hardware/3d-printers.md last_reviewed: 2026-05-10 source_of_truth: owner-described + +- id: intel-nuc-shome + name: Intel NUC Smart Home Server + type: mini-pc + status: active + location: home + vendor: Intel Corporation + model: NUC6CAYH + firmware_version: AYAPLCEL.86A.0043.2017.1123.1559 + hardware_role: + - smart-home-controller + - dual-homed-network-host + - nfs-backup-target + os: Ubuntu 24.04.3 LTS + kernel: 6.8.0-110-generic + resources: + memory: 3.7GiB + root_disk: 111.8GB SATA disk with LVM root volume + backup_media: 58GB mmcblk0 mounted at /home/shome/backups + network_interfaces: + - name: enp3s0 + role: home-lan + ipv4: 192.168.1.101/24 + status: active + - name: enx98fc84e6a61f + role: home-iot-lan + ipv4: 192.168.2.101/24 + status: active + - name: wlp2s0 + role: wifi + ipv4: none + status: active + - name: br0 + role: bridge + status: down + runs_hosts: + - smart-home-server + docs: ../10-systems/servers/smart-home-server.md + last_reviewed: 2026-05-10 + source_of_truth: ssh-host diff --git a/40-inventory/hosts.yml b/40-inventory/hosts.yml index 99cd572..3d95c8f 100644 --- a/40-inventory/hosts.yml +++ b/40-inventory/hosts.yml @@ -66,7 +66,10 @@ environment: production provider: local location: home - os: Ubuntu + hardware_node: intel-nuc-shome + os: Ubuntu 24.04.3 LTS + kernel: 6.8.0-110-generic + hostname: shome addresses: home-lan: - 192.168.1.101 @@ -75,9 +78,30 @@ roles: - smart-home - dual-homed-host + - php-application-host + - mysql-host + - nfs-backup-host + active_services: + - nginx.service + - php8.3-fpm.service + - mysql.service + - nfs-mountd.service + - rpcbind.service + - hostapd.service + - iperf3.service + - ssh.service + listening_ports: + tcp: + - 22 + - 80 + - 443 + - 111 + - 2049 + - 3306 + - 5201 docs: ../10-systems/servers/smart-home-server.md last_reviewed: 2026-05-10 - source_of_truth: owner-confirmed-and-nmap-observed + source_of_truth: owner-confirmed-and-ssh-host - id: gbook name: gbook diff --git a/40-inventory/projects.yml b/40-inventory/projects.yml index 5c6bc16..a57d1f5 100644 --- a/40-inventory/projects.yml +++ b/40-inventory/projects.yml @@ -47,3 +47,41 @@ docs: ../10-systems/applications/gnexus-ui-kit.md last_reviewed: 2026-05-10 source_of_truth: owner-confirmed-and-local-repository + +- id: smart-home-server-project + name: Smart Home Server + status: active + type: smart-home-platform + description: Custom smart-home platform with PHP backend, web client, ESP device firmware, and ControlScripts automation layer. + repositories: + - name: smart-home-server + url: https://git.gnexus.space/git/root/smart-home-server.git + path: /home/shome/smart-home-server + role: deployed-source-repository + host: smart-home-server + branch: master + last_observed_commit: 4ef1bfa + last_observed_commit_summary: Fix resilient device state + working_tree_status: dirty + dirty_files: + - server/ControlScripts/Common.php + - server/ControlScripts/Scopes/LightHubScope.php + - webclient/config.php + documentation: + - label: Architecture + path: /home/shome/smart-home-server/docs/architecture.md + role: upstream-docs + - label: Device API spec + path: /home/shome/smart-home-server/docs/device-spec.md + role: upstream-docs + - label: Server API spec + path: /home/shome/smart-home-server/docs/server-spec.md + role: upstream-docs + related_services: + - smart-home-platform + related_hosts: + - smart-home-server + related_domains: [] + docs: ../10-systems/automations/smart-home-overview.md + last_reviewed: 2026-05-10 + source_of_truth: ssh-host-and-repository diff --git a/40-inventory/services.yml b/40-inventory/services.yml index 0c3f24b..d26423f 100644 --- a/40-inventory/services.yml +++ b/40-inventory/services.yml @@ -120,7 +120,23 @@ controlled_device_scope: - smart-home-devices - iot-devices + stack: + backend: PHP 8.3 FPM + web_server: nginx + database: MySQL + framework: Fury custom PHP microframework + frontend: JavaScript/SCSS build with gulp/esbuild/sass + device_firmware: ESP8266/ESP32 firmware using sh_core_esp8266 + application_paths: + repository: /home/shome/smart-home-server + backend_root: /home/shome/smart-home-server/server + webclient_root: /home/shome/smart-home-server/webclient + devices_root: /home/shome/smart-home-server/devices + docs_root: /home/shome/smart-home-server/docs + architecture_policy: + automation_logic: ControlScripts are the only intended place for device-control business logic. + device_control: Devices and web clients should not directly control other devices through external REST APIs. docs: ../10-systems/automations/smart-home-overview.md runbook: "" last_reviewed: 2026-05-10 - source_of_truth: owner-described-and-nmap-observed + source_of_truth: owner-described-and-ssh-host