Fork: 0
root / gnexus-book
Transfer to URL with SHA Find file
Newer
Older
gnexus-book / 10-systems / automations / smart-home-overview.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 1 day ago 5 KB Document smart home server platform
Raw Blame History

owner: gmikcon status: active last_reviewed: 2026-05-10 review_interval: 90d confidence: high

source_of_truth: owner-described-and-ssh-host

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.

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

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:

  • 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 <token>;
  • 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.