Installer guide

This is the working order we have used to bring the system up on sites and the order we test it in without hardware. It is not a list of promises: every step says what you see on the screen once it is done.

1 · Survey and documents

Before any cable: which devices, in which rooms, over which transports, which scenarios you want. For KNX — the installation project with the group addresses; for Modbus — the register map from the device documentation; for cameras — brands, models and whether RTSP exists; for the network — whether the LAN has IPv6 (for Matter) and whether the router holds client isolation. Models are confirmed here, not on a website.

2 · Running it in simulation

VITE_HOME_DRIVER=mock (the default) gives a local simulation with physics: a solar curve, the energy balance, zone timers, devices that change every 3 s. On this mode you check the interface, the rules, the scenarios and the permissions — with no server and no devices. The server-side simulator (bridge/simulator.mjs) follows the same MQTT path, so the contract is tested without hardware too.

3 · The server in the network

node bridge/server.mjs with PORT (8787 by default) and BRIDGE_TOKEN. The machine has a static IP or an internal DNS name — there is no auto-discovery. For autonomous start: two systemd services with Restart=always on Linux, a task in Task Scheduler on Windows; the recipes are documented but have not been run on a real device. The check is GET /api/health and then GET /api/state with the token.

4 · The kiosk against the server

VITE_HOME_DRIVER=bridge + VITE_HOME_BRIDGE_URL=http://<IP>:8787 + VITE_HOME_BRIDGE_TOKEN. These variables are build-time — after a change the dev server restarts and the production build is rebuilt. If bridge is selected with no address, the kiosk falls back to simulation with a visible warning in the status chip: a broken deployment never stays invisible. Then: manifest + standalone on the tablet, kiosk mode, auto-lock after 3 minutes.

5 · Profiles and permissions

On first start the bridge creates bridge/users.json from KIOSK_ADMIN_PIN, KIOSK_USER_PIN and KIOSK_GUEST_PIN — those are used only when the file is created, and afterwards the PINs are changed through /api/users (behind the config permission). The roles: administrator, resident (no config and no debug), guest (lights and scenes). Check the four answers: 401 without a session, 403 without permission, 409 for a critical action without confirm: true, 429 after 5 wrong PINs.

6 · Devices, rooms, scenes, rules

The device registry keeps name, kind, room, vendor, protocol, availability and criticality. Rooms (bridge/rooms.json) and scenes (bridge/scenes.json) are server configuration, not tablet configuration. The rules live in bridge/automations.json — trigger, conditions, exceptions, forMs, cooldown and schedules; the "Automations" screen edits them and the executions show up in the log with an explanation. Test: a rule that turns the lights off at a specific hour, and a restriction that keeps the water heater outside the night window.

7 · Integrations and pairing

An integration is described with POST /api/integrations (the config permission): a label, a transport and public settings such as host and port; secrets are stored but never returned and are never entered on the tablet. The step wizard against POST /api/pair runs "network kind → device → test request → result": Matter returns 201 and pairs for real, while Modbus/KNX/ONVIF/HTTP return 200 with paired: false, because those are leads with a TCP check, not a finished read (more).

8 · Final check

"Ready" means one thing for us: a device changed state from the kiosk. Check GET /api/history?period=day&metric=energy for the hourly points; stop the server and see whether the chip moves to "Recovering…" with the age marked; let one sample go silent and expect telemetry-silent, and expect transport-down for a stopped transport; cut the internet and confirm the rules keep running. The log must show every sign-in, every refusal and every executed rule.

What is not installed yet: a real broker with devices, the Modbus/KNX/ONVIF drivers, HTTPS, and secrets through the interface.