#!/usr/bin/env bash # GetHome Hub installer for Linux (Raspberry Pi OS, Debian, Ubuntu, …). # # curl -fsSL https://raw.githubusercontent.com/gethome-inc/gethome-hub/main/deploy/install.sh | bash # # Options (pass after `bash -s --`): # --zigbee /dev/ttyACM0 use this adapter instead of detecting one # --dir /opt/gethome install directory (default /opt/gethome) # --branch main branch to install from (default main) # --build build from source even when a bundle exists # # The script is idempotent: re-running updates the install and restarts the # services. It is also what the GetHome Studio app streams over SSH. # # ── There is no Docker here, on purpose ──────────────────────────────────── # The hub used to run as four containers with Postgres underneath. On a # Raspberry Pi Zero 2 W that is ~130 MB of Docker daemon and ~130 MB of # database before the hub itself has started, out of 512 MB total — the board # ran out of memory and the OOM killer took the hub down somewhere between the # install finishing and the user pressing Claim. Everything now runs as systemd # units against an SQLite file. systemd also gives us what `restart: # unless-stopped` gave us and more: a runaway Zigbee2MQTT cannot take the hub # with it — through `MemoryMax` where the kernel's memory cgroup is available, # and through `OOMScoreAdjust` everywhere. There are two mechanisms rather than # one because Raspberry Pi OS ships that cgroup switched off in `cmdline.txt`, # so for most of this project's life the caps were not in force at all. # # Studio follows progress through structured markers on stdout (keep them # stable — the install screen is driven by them): # @@STEP:@@ a phase begins # (ids: system, runtime, download, zigbee, start, # autostart, health) # @@ERROR:@@ a human-readable failure reason (last one wins) # @@WARN:@@ something worth telling the user; the install continues # @@BOARD:@@ the machine this is running on # @@ZIGBEE_FOUND:@@ the coordinator that will be used # @@ZIGBEE_MAYBE:@@ a USB serial device that might be a coordinator # but doesn't identify itself as one # @@ROLLBACK:@@ the new build wouldn't answer, so the hub was put back # on this one. It is followed by @@ERROR@@ and a non-zero # exit like any other failure, which is exactly why it # exists: without it "rolled back and healthy" and "the # hub is down" are the same two signals. # @@PAIRING:@@ the pairing code, when the hub is unclaimed # @@RADIO_BUDGET:@@ how many radios this board was measured for. # Advice, not a ceiling: `one` is the board on which # running both is an owner's informed choice, and it is # printed early so an installer UI can say so before the # hub exists to be asked. # @@CAPABILITIES:@@ what this hub ended up able to talk to, e.g. # "Zigbee, Wi-Fi and MQTT" — a 512 MB board runs one # radio at a time, so this is not the same on every # machine # @@DONE@@ the install finished successfully # # The same vocabulary is reused by both of GetHome Studio's install paths. Each # writes a small script that logs its own steps before handing over to this # installer, and reads the whole log back over SSH: # network waiting for the Pi to get online (SD-card path only) # installer downloading this script (both paths) # They are separate on purpose — a Pi that never joined the Wi-Fi and one that # joined and was refused the download are different failures with different # fixes. The SSH path skips `network` because its preflight has already watched # the machine reach the internet. Both are step ids in that stream, so don't # reuse either here for something else. set -euo pipefail REPO_SLUG="gethome-inc/gethome-hub" REPO_URL="https://github.com/${REPO_SLUG}.git" INSTALL_DIR="/opt/gethome" BRANCH="main" ZIGBEE_ADAPTER="" FORCE_BUILD="" NODE_VERSION="22.22.2" Z2M_VERSION="2" DATA_DIR="/var/lib/gethome/data" Z2M_DATA_DIR="/var/lib/gethome/zigbee2mqtt" CONF_DIR="/etc/gethome" SERVICE_USER="gethome" while [[ $# -gt 0 ]]; do case "$1" in --zigbee) ZIGBEE_ADAPTER="$2"; shift 2 ;; --dir) INSTALL_DIR="$2"; shift 2 ;; --branch) BRANCH="$2"; shift 2 ;; --build) FORCE_BUILD=1; shift ;; *) echo "Unknown option: $1" >&2; exit 1 ;; esac done # One directory per installed build, and a symlink saying which one runs. # # This is how the hub gets versioning and rollback without a container runtime. # An update unpacks beside the running build and flips `current`; the systemd # unit points at the symlink, so the switch is one atomic rename. If the new # build doesn't answer, the flip goes back — which a `docker pull` into the # same tag cannot do, and which matters far more on a machine nobody is sitting # in front of. RELEASES_DIR="$INSTALL_DIR/releases" HUB_DIR="$INSTALL_DIR/current" NODE_DIR="$INSTALL_DIR/node" Z2M_DIR="$INSTALL_DIR/zigbee2mqtt" # How many old builds to keep. Two is enough for one rollback and costs ~200 MB # on a card; more is hoarding. KEEP_RELEASES=2 # ── Output helpers ───────────────────────────────────────────────────────── say() { if [[ -t 1 ]]; then printf '\n\033[1m==> %s\033[0m\n' "$*"; else printf '\n==> %s\n' "$*"; fi; } step() { printf '@@STEP:%s@@\n' "$1"; say "$2"; } fail() { printf '@@ERROR:%s@@\n' "$1"; echo "ERROR: $1" >&2; exit 1; } # Something the user should know about, but not a reason to stop: the hub is # useful without Zigbee, so a coordinator that won't start is a warning. warn() { printf '@@WARN:%s@@\n' "$1"; say "WARNING: $1"; } # Why a unit didn't start, in the install log, where the person watching it can # see it. # # This exists because it was missing. A `systemctl restart … >/dev/null 2>&1 || # warn "it didn't restart"` threw away the one line that mattered — mosquitto # was refusing a duplicate config key and saying so clearly — and left "check # with systemctl status" as homework for someone who is watching a progress bar # on another machine. Whatever systemd knows, put it in the log. service_failure() { local unit="$1" say "--- why ${unit} failed ---" $SUDO systemctl status "$unit" --no-pager --lines=0 2>&1 | sed 's/^/ /' || true $SUDO journalctl -u "$unit" -n 20 --no-pager 2>&1 | sed 's/^/ /' || true say "--- end ---" } # shellcheck disable=SC2154 # `code` is assigned inside the trap body itself. trap 'code=$?; printf "@@ERROR:Command failed (exit %s) at line %s: %s@@\n" "$code" "$LINENO" "$BASH_COMMAND"; echo "ERROR (exit $code) at line $LINENO: $BASH_COMMAND" >&2' ERR # ── Privilege check ──────────────────────────────────────────────────────── SUDO="" if [[ $(id -u) -ne 0 ]]; then command -v sudo >/dev/null 2>&1 || fail "This installer needs root. Run it as root, or install sudo first." SUDO="sudo" # A non-interactive SSH session can't answer a sudo password prompt. if ! sudo -n true 2>/dev/null; then fail "This user needs passwordless sudo to install unattended. On Raspberry Pi OS the default user already has it; otherwise add a sudoers rule, or run the install as root." fi fi command -v systemctl >/dev/null 2>&1 \ || fail "This installer needs systemd, which every current Raspberry Pi OS, Debian and Ubuntu has. Install the hub by hand on a system without it — see deploy/ in the repository." # Run a command as the hub's account, for anything that touches the hub's own # data directory — making those directories, reading the pairing code, writing # the files that tell the hub what plumbing it has. Root runs only what needs # root. The account owns that directory, so every name in it is whatever the # account made it, and root following one follows whatever was planted there: a # link from a file to one only root may touch, or a directory pointed elsewhere # so the `chmod` after it changes the target's mode. Done as the account, a # planted link reaches only what that account could reach already — `as_hub` in # deploy/wifi-networks.sh and deploy/update-runner.sh, for the same reason. # setpriv first (a plain setresuid, no PAM session), then runuser, both # util-linux. (`chown -R` stays root's: without -H or -L it changes a link # itself and never descends through one.) as_service_user() { local uid gid uid="$(id -u "$SERVICE_USER" 2>/dev/null)" || return 1 gid="$(id -g "$SERVICE_USER" 2>/dev/null)" || return 1 if command -v setpriv >/dev/null 2>&1; then $SUDO setpriv --reuid="$uid" --regid="$gid" --clear-groups -- "$@" elif command -v runuser >/dev/null 2>&1; then $SUDO runuser -u "$SERVICE_USER" -- "$@" else return 1 fi } # A file in the hub's own directories, read as the hub's account: its contents # when it is a regular file, and a failure with nothing printed otherwise — # missing, unreadable, or something else at that name (a FIFO would hold the # installer for ever). As the account for the reason above, and for a second # one that is easy to miss: run by a login user with sudo — `curl … | bash`, or # `gethome-hubctl update` without sudo — the installer cannot see into # /var/lib/gethome at all once "Accounts and directories" has made it 0750, so a # check it made in its own name would find nothing there and say so. read_hub_file() { as_service_user test -f "$1" 2>/dev/null || return 1 as_service_user cat "$1" 2>/dev/null } # ── System ───────────────────────────────────────────────────────────────── step system "Checking this machine…" MACHINE=$(uname -m) BOARD="$(tr -d '\0' < /proc/device-tree/model 2>/dev/null || true)" [[ -n "$BOARD" ]] || BOARD="$(uname -s) $MACHINE" printf '@@BOARD:%s@@\n' "$BOARD" say "Board: ${BOARD} (${MACHINE})" RAM_MB=$(awk '/^MemTotal:/ {printf "%d", $2 / 1024}' /proc/meminfo 2>/dev/null || echo 0) say "Memory: ${RAM_MB} MB" # **64-bit only.** Two architectures are refused here, by name, because both # failures are otherwise discovered twenty minutes in: # # - ARMv6 (original Pi Zero / Zero W / Pi 1 / CM1) genuinely cannot run this: # Node.js has published no ARMv6 build since Node 12. # - ARMv7 means a *32-bit operating system*. The board is almost always # 64-bit-capable — a Zero 2 W or a Pi 3/4/5 with the 32-bit image written to # it — so this is a fixable mistake, not a dead end, and the message says # exactly how to fix it. It is refused rather than warned about because # 32-bit is untested, has no prebuilt SQLite binding, and was a real part of # why the first hubs never worked. case "$MACHINE" in aarch64|arm64) NODE_ARCH="linux-arm64" ;; x86_64|amd64) NODE_ARCH="linux-x64" ;; armv7l|armv8l) if grep -q 'CPU architecture: 8' /proc/cpuinfo 2>/dev/null; then fail "${BOARD} has a 64-bit processor, but a 32-bit operating system is installed on it — that is what \"armv7l\" above means. The GetHome Hub needs the 64-bit system. Rewrite the card with Raspberry Pi Imager (raspberrypi.com/software): choose Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit), then set the hub up again. Nothing else about this Pi needs to change." fi fail "${BOARD} has a 32-bit ARMv7 processor, which the GetHome Hub doesn't support. A Raspberry Pi Zero 2 W, 3, 4 or 5 with the 64-bit system works." ;; armv6l) fail "${BOARD} has an ARMv6 processor (an original Raspberry Pi Zero, Zero W, or Pi 1) and can't run the GetHome Hub: the software it needs has no build for it, so there is nothing to install. A Raspberry Pi Zero 2 W, or any Pi 3 or newer, works — write a card for one of those with Raspberry Pi Imager (raspberrypi.com/software)." ;; *) fail "Unsupported processor architecture: ${MACHINE}. The hub runs on 64-bit ARM (Raspberry Pi Zero 2 W, 3, 4, 5) and x86-64." ;; esac if [[ "$RAM_MB" -gt 0 && "$RAM_MB" -lt 400 ]]; then fail "This machine has ${RAM_MB} MB of memory, which is below what the hub needs. A Raspberry Pi Zero 2 W (512 MB) is the smallest board that works." fi # Which Raspberry Pis we actually test on. Everything 64-bit runs, and a board # outside this list is far more likely to be fine than not — a Pi 3 has twice # the memory of a Zero 2 W. So this is a note, not a gate: saying "supported" # about hardware nobody has tried would be the misleading half of the choice. # Deliberately silent for machines that aren't Raspberry Pis at all, where # running a home hub is an informed decision rather than a purchase. # ("Raspberry Pi 5" also covers the 500, and "Pi 4" the 400 — they are # substrings. The Compute Modules need their own patterns, because their model # strings read "Raspberry Pi Compute Module 4".) case "$BOARD" in *"Raspberry Pi 5"*|*"Raspberry Pi 4"*|*"Raspberry Pi Zero 2"*|\ *"Compute Module 4"*|*"Compute Module 5"*) ;; *"Raspberry Pi"*) warn "${BOARD} isn't one of the boards this hub is regularly tested on (Raspberry Pi 5, Pi 4, and Zero 2 W). It should work — anything 64-bit with 512 MB or more does — but if something behaves oddly, that is worth knowing." ;; esac # Everything sized from here, so a Pi 5 isn't held to a Pi Zero's budget. # # Measured, not guessed: hubd is ~119 MB resident with Matter off and ~178 MB # with it on. So on a 512 MB board the ceilings are `MemoryHigh` — which # *throttles* the cgroup and lets the garbage collector catch up — and not # `MemoryMax`, which kills. A hard cap set anywhere near the working set turns # a busy minute into a restart, and that is what a too-tight 260 MB was doing. # Zigbee2MQTT keeps a hard cap: it is the optional process, and it should die # on its own rather than take the hub with it. SMALL_BOARD="" TIGHT_BOARD="" HUB_HEAP_MB=512 Z2M_HEAP_MB=512 HUB_MEM_HIGH="" Z2M_MEM_HIGH="" Z2M_MEM_MAX="" HUB_V8_FLAGS="" HUB_MALLOC_ENV="" # Where the small tier splits in two. Below this line is a 512 MB board, above # it a 1 GB one, and no board lands near it: a Zero 2 W reports 415-490 MB of # MemTotal and a "1 GB" Pi reports 920-970 once the GPU has taken its share. # The gap is wide on purpose — this has to separate two families of hardware, # not measure either of them. TIGHT_BOARD_MAX_MB=768 # How many radios this board was measured for — measured, not chosen. The # owner's preference is a separate thing and lives in /radio-mode; # gethome-zigbee-detect is where the two meet. # # **Advice, not a ceiling.** This number is measured against a *full* home — # the OS, the hub with Matter loaded, and a Zigbee2MQTT holding a hundred # devices' state — and most homes are nowhere near it. An owner may set # `radio-mode` to `both` on a board that says `one`, and the hub then watches # its own memory and hands a radio back by itself if the board really does run # short (src/core/radio-pressure.ts). What this value decides is what is # *recommended*, and what every app warns from. # # **The test is memory and only memory**, which is what makes the tier below # *512 MB and 1 GB together*: a Zero 2 W, a Pi 3, and the 1 GB Pi 4 all land on # `one`, because a board sold as "1 GB" reports ~920-950 MB once the GPU has # taken its share. Read as a shopping rule that is "2 GB or more runs both" — # and never as "a Pi 4 runs both", which is false for every 1 GB Pi 4 there is. # The 1 GB half of this tier is still **unmeasured** — nobody has run one for a # day — which is why it keeps the recommendation while getting ceilings of its # own below. Moving the *budget* is the separate decision, and it needs # hardware: a board on `both` is one the pressure watch only reports on # (src/core/radio-pressure.ts gates acting on `budget === 'one'`), so promoting # an unmeasured tier would take away its safety net as well as its warning. RADIO_BUDGET=both if [[ "$RAM_MB" -gt 0 && "$RAM_MB" -le 1024 ]]; then SMALL_BOARD=1 # One radio, not none. Matter and Zigbee do not both fit — 70 (OS) + 178 # (hub with Matter) + 150 (Zigbee2MQTT) is more than a Zero 2 W has, while # 70 + 119 + 150 fits with room for zram. But this used to be written as # "small board, no Matter", which was wrong in the common case: Zigbee2MQTT # is only started when a coordinator is actually plugged in, so a Zero 2 W # without a stick was holding 150 MB for a process that never ran *and* # going without Matter. gethome-zigbee-detect now owns that call, because it # is the only thing that knows whether the stick is there — at boot, on # every plug and unplug, and at the end of this install. RADIO_BUDGET=one if [[ "$RAM_MB" -le "$TIGHT_BOARD_MAX_MB" ]]; then # A 512 MB board. Every number here was measured on a Zero 2 W and they # are deliberately tight: 200M is 25 MB above the highest resident set ever # recorded there (175 MB, both radios, one Matter plug, seven hours), which # is the margin that makes throttling the signal the radio watch acts on. TIGHT_BOARD=1 HUB_HEAP_MB=160 Z2M_HEAP_MB=200 HUB_MEM_HIGH="MemoryHigh=200M" Z2M_MEM_HIGH="MemoryHigh=170M" Z2M_MEM_MAX="MemoryMax=230M" # Measured on this hub: with Matter loaded these two take its resident set # from 176 MB to 139 MB, for about half a second of extra startup and no # change in request latency. They have to be argv — NODE_OPTIONS refuses # --optimize-for-size outright ("not allowed in NODE_OPTIONS"). # # --expose-gc is what lets a room drawing hand its memory back when it is # done (src/room-pictures/store.ts calls gc() when one is there, and only # then). A drawing moves ~40 MB through the hub in objects only a full # collection frees, this hub runs ~15 MB under its MemoryHigh, and on # 2026-10-23 one held it at the limit for four minutes after the night had # landed — long enough for the pressure watch to stand Matter down. HUB_V8_FLAGS="--optimize-for-size --max-semi-space-size=1 --expose-gc" # And glibc's half of the same thing. By default it raises its mmap # threshold to the size of the last large block it freed, so after the # first picture every later multi-megabyte buffer comes out of the heap # instead of mmap, and freeing one gives nothing back; and it gives every # thread an arena of its own. Replaying a drawing on a Zero 2 W # (scripts/replay-room-picture.mjs, which spends nothing): three minutes # after the night, ~64 MB of anonymous memory with the defaults and ~44 MB # with these two and the collection above; a second drawing added 8.9 MB # before and nothing after; the peak fell from +40 MB to +26 MB. HUB_MALLOC_ENV="Environment=MALLOC_MMAP_THRESHOLD_=131072 MALLOC_ARENA_MAX=2" else # A 1 GB board — a Pi 3, a Pi 3B+, a 1 GB Pi 4. It shares the tier above # for everything that is about *scarcity* (zram, the memory cgroup, no # building from source here, one radio recommended) and must not share the # ceilings, which are a 512 MB board's arithmetic. It had them, and that was # a real fault rather than an untidiness: `MemoryHigh=200M` on a board with # ~920 MB of MemTotal throttles the hub with hundreds of megabytes free, and # throttling is exactly what `radio-pressure.ts` acts on — so a 1 GB board # running both radios could have one taken back while its memory was fine. # # **These are reasoned, not measured**, and the reasoning is the same # arithmetic the 512 MB tier came from rather than a new claim: a full home # is ~70 (OS) + ~180 (hub with Matter) + ~150 (Zigbee2MQTT), so the ceilings # below sit at roughly 2.3x the hub's measured both-radio peak and 2.5x # Z2M's assumed full-home working set. They are also, unlike the tier above, # **not over-subscribed**: 400 + 400 + 70 is 870 of ~920, where the 512 MB # board deliberately promises 200 + 230 + 70 out of 415 and relies on zram # to make that true. A ceiling is a bound on a leak here, not a squeeze. HUB_HEAP_MB=320 Z2M_HEAP_MB=320 HUB_MEM_HIGH="MemoryHigh=400M" Z2M_MEM_HIGH="MemoryHigh=320M" Z2M_MEM_MAX="MemoryMax=400M" # `--optimize-for-size` stays: measured, it is most of that 176 -> 139 MB # for half a second of startup and no change in request latency, which is # worth taking on any board. `--max-semi-space-size=1` does not — it pins # the scavenger's young generation to buy memory with garbage-collection # throughput, and buying memory is the trade a board with 500 MB spare has # no reason to make. HUB_V8_FLAGS="--optimize-for-size" fi fi # Said out loud, and early. GetHome Studio draws the choice between one radio # and both on its install screen, which is well before there is a hub to ask — # and the question is one somebody should meet while they are still deciding # what to plug in, not after the install has already picked for them. printf '@@RADIO_BUDGET:%s@@\n' "$RADIO_BUDGET" # ── System packages ──────────────────────────────────────────────────────── # Only what is actually missing. Raspberry Pi OS Lite already ships # avahi-daemon, curl, ca-certificates and xz-utils, so on the machine this is # built for the whole step is "install mosquitto" — seconds, not the several # minutes an unconditional `apt-get update` plus five packages was taking with # all its output sent to /dev/null and nothing on screen moving. export DEBIAN_FRONTEND=noninteractive MISSING=() for pkg in ca-certificates curl xz-utils avahi-daemon mosquitto; do dpkg-query -W -f='${Status}' "$pkg" 2>/dev/null | grep -q '^install ok installed$' || MISSING+=("$pkg") done if [[ ${#MISSING[@]} -eq 0 ]]; then say "System packages: everything the hub needs is already installed." else say "Installing system packages: ${MISSING[*]}…" $SUDO apt-get update -qq || warn "Could not refresh the package lists; carrying on with what is already cached." $SUDO apt-get install -y -qq --no-install-recommends "${MISSING[@]}" \ || fail "Could not install: ${MISSING[*]}. Check the network and run the install again." fi # ── The memory limits need a controller the Raspberry Pi turns off ───────── # Every ceiling written below — `MemoryHigh` on the hub, `MemoryMax` on # Zigbee2MQTT — is enforced by the kernel's memory cgroup, and a Raspberry Pi # boots with `cgroup_disable=memory`. Observed on a Zero 2 W: the units carried # the right numbers, `systemctl show` read them straight back, and # `MemoryCurrent` was `[not set]` with no `memory.*` file anywhere in the unit's # own cgroup. The caps were decoration — not on that board particularly, but on # every Raspberry Pi this installer has ever run on. # # **That parameter is not in `cmdline.txt`.** The firmware prepends its own # arguments to the file's, and `cgroup_disable=memory` is one of them — so # there is usually nothing here to delete, and the deletion below is only for a # machine where somebody added one by hand. What does the work is the # **append**: the kernel takes the last setting it is given, and anything this # script adds lands after the firmware's. Verified on the Zero 2 W this was # found on — `/proc/cmdline` still shows `cgroup_disable=memory`, followed by # our two, and `/sys/fs/cgroup/cgroup.controllers` lists `memory`. # # That is also why the check is `memory_cgroup_live` and not "did we edit the # file": what matters is whether the controller is actually there, which is the # only thing a caller can act on and the only thing that makes a re-run a no-op. # # Three things make this safe to do to the file that decides whether the board # boots: the result must still carry `root=` before it is written, the original # is kept beside it, and it is rewritten as the **single line** the firmware # requires — only the first line is read, so a stray newline silently drops # every parameter after it. # # It costs a reboot, and this script deliberately does not perform one: an # installer that restarts the machine in the middle of the flow its user is # watching would be worse than a limit that starts working a little later. # Studio's SD path writes the same parameters onto the card before the first # boot, so a hub installed that way never meets this at all. # # `GETHOME_CMDLINE` and `GETHOME_CGROUP_CONTROLLERS` exist so the tests can # exercise this against files they own — the same reason the detector has # `GETHOME_ZIGBEE_SCAN_DIR`. Nothing sets them in production. memory_cgroup_live() { grep -qw memory "${GETHOME_CGROUP_CONTROLLERS:-/sys/fs/cgroup/cgroup.controllers}" 2>/dev/null } enable_memory_cgroup() { if memory_cgroup_live; then return 0 fi local file="" candidate current updated param local -a candidates if [[ -n "${GETHOME_CMDLINE:-}" ]]; then candidates=("$GETHOME_CMDLINE") else candidates=(/boot/firmware/cmdline.txt /boot/cmdline.txt) fi for candidate in "${candidates[@]}"; do if [[ -f "$candidate" ]]; then file="$candidate"; break; fi done if [[ -z "$file" ]]; then warn "The kernel's memory accounting is switched off on this machine, and there is no cmdline.txt here to switch it back on — that file is a Raspberry Pi thing. The hub installs and runs normally. What it goes without is the ceiling that keeps Zigbee2MQTT from taking memory the hub needs." return 0 fi current=$(tr -d '\r\n' < "$file") updated=$(printf '%s' "$current" | sed 's/cgroup_disable=memory//g' | tr -s '[:space:]' ' ') updated="${updated# }" updated="${updated% }" for param in cgroup_enable=memory cgroup_memory=1; do case " $updated " in *" $param "*) ;; *) updated="$updated $param" ;; esac done if [[ "$updated" == "$current" ]]; then return 0 fi # A command line without `root=` is a machine that does not come back. If the # rewrite lost it, this file is not the file we think it is, and the right # move is to leave it exactly as it was and say so. if [[ -z "$updated" || "$updated" != *"root="* ]]; then warn "Left ${file} alone: the rewritten kernel command line didn't look like one this Pi could boot from, and a wrong one is a Pi that doesn't come back. Nothing changed; this board's memory limits stay off." return 0 fi $SUDO cp "$file" "${file}.gethome-backup-cgroup" 2>/dev/null || true if ! printf '%s\n' "$updated" | $SUDO tee "${file}.gethome-new" >/dev/null \ || ! $SUDO mv "${file}.gethome-new" "$file"; then $SUDO rm -f "${file}.gethome-new" 2>/dev/null || true warn "Could not update ${file}, so this board's memory limits stay off. The hub itself is unaffected." return 0 fi warn "Raspberry Pi OS ships with the kernel's memory accounting switched off, so the limits that keep Zigbee2MQTT from crowding out the hub were not actually in force on this board. That is corrected in ${file} and takes effect the next time this Pi is restarted. There is nothing to do now, and nothing else about the boot changed." } # Does this machine already have compressed swap of its own? Configuration # counts, not just a running device — see the ordering note below, which is the # whole reason this question is asked this way. zram_provided_by_the_system() { local conf if [[ -e /etc/systemd/zram-generator.conf ]]; then return 0; fi for conf in /etc/systemd/zram-generator.conf.d/*.conf \ /usr/lib/systemd/zram-generator.conf.d/*.conf; do if [[ -e "$conf" ]]; then return 0; fi done # zram-tools, the other common packaging of the same idea. if systemctl cat zramswap.service >/dev/null 2>&1; then return 0; fi if swapon --show=NAME --noheadings 2>/dev/null | grep -q '^/dev/zram'; then return 0; fi return 1 } # ── Memory headroom ──────────────────────────────────────────────────────── # zram before a swapfile: it compresses pages in RAM, so it buys roughly twice # the usable memory at the cost of a little CPU, and — unlike a swapfile — the # device this script adds writes nothing to the SD card. The disk swap stays as # a backstop for the rare genuine spike; `swappiness=100` is right for zram # specifically, where swapping is cheap, and would be wrong if the disk were the # only swap. # # **Unless the machine already has some, in which case leave it alone.** # Raspberry Pi OS Trixie ships its own (`systemd-zram-setup@zram0`, from # systemd's zram generator, presented as `rpi-swap`) — and this script added a # second one anyway. The guard was "is a zram swap already on?", and the unit # below is deliberately early (`DefaultDependencies=no`, `Before=swap.target`) # so the hub never starts before its headroom exists. Being early is exactly # what defeated the guard: the distribution's device was not up yet, the check # saw nothing, and the script hot-added its own. Observed on a Zero 2 W — two # 415 MB devices and a `SwapTotal` of 830 MB on a board with 415 MB of RAM. # Compressed pages live in that same RAM, so twice the swap is twice the worst # case, which is the opposite of the headroom this exists for. The question has # to be "is one *configured* on this machine", which is answerable at any point # in the boot, and not "is one running", which is not. if [[ -n "$SMALL_BOARD" ]]; then enable_memory_cgroup # A desktop image is the largest single thing in the way on a board this # size. Measured on a Zero 2 W running the Desktop image with nothing plugged # into its HDMI: pcmanfm, wf-panel-pi, labwc, two xdg-desktop-portals, # wireplumber and the user session held about 75 MB between them — more than # the hub's whole Matter adapter. Switching somebody's desktop off is not this # installer's business. Saying what it costs, on the machine where it costs # the most, is. # # The measurement stays in this comment and out of the message. Studio shows # that message to someone who is not going to convert megabytes into anything # — what they can act on is "it takes memory the hub needs" plus the command. # And it must not promise a second radio: RADIO_BUDGET is computed from the # board's RAM above and a desktop makes no difference to it, so "turn it off # and get Matter too" would simply be untrue. It is not untrue that the # desktop is 75 MB of the margin an owner who turns both radios on is # spending — but that offer is made at the end of the install, in one place, # where it can be answered rather than being an aside in a warning about # something else. # # The first clause is the one that has to follow the tier: 75 MB is a good # part of a 512 MB board and about eight per cent of a 1 GB one, so telling a # Pi 3 owner their board is too small to run a desktop is the 512 MB # conclusion applied to twice the hardware. The advice is the same either way, # which is why only the claim changes. if [[ "$(systemctl get-default 2>/dev/null || true)" == "graphical.target" ]]; then if [[ -n "$TIGHT_BOARD" ]]; then DESKTOP_COST="On a board this small the desktop uses up a good part of the memory the hub needs, for a screen that isn't attached." else DESKTOP_COST="The desktop holds about 75 MB for a screen that isn't attached — not a lot on this board, but it is memory the hub could be using." fi warn "This Pi is running the desktop version of Raspberry Pi OS. ${DESKTOP_COST} The hub works either way, it just has less room. If nobody uses a screen on this Pi, run \`sudo systemctl set-default multi-user.target\` and restart it to give that memory back; Raspberry Pi OS Lite is the version that never takes it in the first place." fi fi if [[ -n "$SMALL_BOARD" ]] && zram_provided_by_the_system; then say "Compressed memory is already set up by the operating system; leaving that to it." # An earlier install of ours may be the reason there are two. if [[ -e /etc/systemd/system/gethome-zram.service ]]; then $SUDO systemctl disable gethome-zram.service >/dev/null 2>&1 || true $SUDO rm -f /etc/systemd/system/gethome-zram.service /usr/local/lib/gethome-zram.sh $SUDO systemctl daemon-reload >/dev/null 2>&1 || true warn "An earlier install of the hub had added a second compressed-swap device beside the one this system provides — twice the swap this board should have, on a machine where the compressed pages sit in the memory they are saving. It is switched off now; the spare device itself goes away at the next restart." fi elif [[ -n "$SMALL_BOARD" ]]; then say "Setting up zram (compressed memory) so a small board has room to breathe…" $SUDO tee /usr/local/lib/gethome-zram.sh >/dev/null <<'ZRAM' #!/bin/sh # Add one zstd-compressed swap device sized to total RAM. Real-world # compression on this kind of workload is about 3:1, so it buys most of a # second machine's worth of memory and writes nothing to the SD card. set -e [ -n "$GETHOME_ZRAM_SIZE" ] || exit 0 # Stand down if this machine has compressed swap of its own — the same check # install.sh makes, repeated here because this unit runs on every boot and the # operating system underneath it can gain one at any upgrade. Configuration, # not a running device: this unit runs before swap.target, so at this moment # the system's own zram is configured but not yet on, and asking whether one is # *running* is what produced two of them. if [ -e /etc/systemd/zram-generator.conf ] || \ ls /etc/systemd/zram-generator.conf.d/*.conf \ /usr/lib/systemd/zram-generator.conf.d/*.conf >/dev/null 2>&1; then exit 0 fi modprobe zram || exit 0 if swapon --show=NAME --noheadings 2>/dev/null | grep -q '^/dev/zram'; then exit 0 fi if [ -e /sys/class/zram-control/hot_add ]; then N=$(cat /sys/class/zram-control/hot_add) else N=0 fi echo zstd > "/sys/block/zram${N}/comp_algorithm" 2>/dev/null || true echo "$GETHOME_ZRAM_SIZE" > "/sys/block/zram${N}/disksize" mkswap -q "/dev/zram${N}" # A higher priority than the disk swap, so the kernel reaches for RAM first # and only falls through to the card under real pressure. swapon --priority 100 "/dev/zram${N}" ZRAM $SUDO chmod 0755 /usr/local/lib/gethome-zram.sh $SUDO tee /etc/systemd/system/gethome-zram.service >/dev/null </dev/null 2>&1 || true $SUDO systemctl enable --now gethome-zram.service >/dev/null 2>&1 \ || warn "Could not enable compressed swap. The hub still installs; a board with 512 MB has less headroom without it." fi # Whichever of the two set it up, the swap this board ends up with is # compressed and in RAM, so it wants the same tuning either way. if [[ -n "$SMALL_BOARD" ]]; then $SUDO tee /etc/sysctl.d/60-gethome.conf >/dev/null <<'SYSCTL' # Tuned for compressed swap in RAM, which is far cheaper to use than a disk — # the kernel's defaults assume swapping means writing to one. # # Two things this is *not* saying. It is not saying the card is untouched: # Raspberry Pi OS gives its zram a backing device and moves idle pages onto the # card from a daily timer, so a page that goes out here can end up being read # back 4 KB at a time off an SD card. And it is not saying the hub may be # swapped — gethome-hubd.service sets MemorySwapMax=0 and is exempt from all of # this, because a hub that has to be paged back in before it can answer is a # hub that reads as unreachable. What is left for zram to spend is Zigbee2MQTT, # the page cache, and whatever else the board is running, which is the right # order to spend it in. vm.swappiness=100 vm.vfs_cache_pressure=50 SYSCTL $SUDO sysctl -q -p /etc/sysctl.d/60-gethome.conf >/dev/null 2>&1 || true fi # ── Accounts and directories ─────────────────────────────────────────────── if ! id -u "$SERVICE_USER" >/dev/null 2>&1; then $SUDO useradd --system --home-dir /var/lib/gethome --shell /usr/sbin/nologin "$SERVICE_USER" fi # Serial access for a Zigbee coordinator, without running anything as root. $SUDO usermod -aG dialout "$SERVICE_USER" >/dev/null 2>&1 || true # INSTALL_DIR and CONF_DIR are root's own. The hub's tree under /var/lib/gethome # is the hub account's, so root makes only the top of it and hands it over, and # the account makes the rest: a name under it the account replaced with a link # is then one root never follows — as `mkdir -p` and `chmod` both do. `chown -R` # stays root's; without -H/-L it changes a link itself and never descends one. $SUDO mkdir -p "$INSTALL_DIR" "$CONF_DIR" /var/lib/gethome $SUDO chown "$SERVICE_USER:$SERVICE_USER" /var/lib/gethome as_service_user mkdir -p "$DATA_DIR" "$DATA_DIR/update" "$Z2M_DATA_DIR" $SUDO chown -R "$SERVICE_USER:$SERVICE_USER" /var/lib/gethome as_service_user chmod 0750 /var/lib/gethome "$DATA_DIR" # ── Downloads are checked against a digest ───────────────────────────────── # Both things this script fetches and then *executes* — the hub bundle and the # Node.js runtime under it — arrived on TLS alone. That is a real guarantee # about the pipe and no guarantee at all about what was published down it: an # asset replaced in the release, a half-written upload, a CDN serving a stale # object. So each one is now checked against a SHA-256 the publisher wrote # separately, and the two outcomes are deliberately not the same thing. # # **Not verified is not installed, and there is exactly one path through # here.** A mismatch, a release with no `.sha256` beside it, a machine that # cannot hash — all three stop the install. That is the one place in this file # that chooses stopping over carrying on, and it can afford to, because nothing # has been put in place yet: the release directory is staging, `current` still # points at the build that is running, and the hub on this machine is untouched. # Falling back to a source build would be answering "this download cannot be # trusted" by fetching from the same place with less checking. # # The obvious softer rule — warn when the digest is merely *missing*, since # that is not evidence of tampering — was deliberately not taken. It makes the # check trivial to walk past (delete the file and the install proceeds), and # the case it protects is a branch whose bundle predates this, which one push # rebuilds. Every failure below says which of the three it was, so nobody has # to guess; what none of them does is carry on. # # `sha256sum` is coreutils and `shasum` is perl's; Linux has the first and the # machines these functions are *tested* on have the second. # # **These sit here, above the Node block, because one caller is inside a branch # the other is not — and that cost a release.** They were written beside their # first use, inside the `else` that downloads Node, so on any machine that # already had Node 22 that branch never ran and the bundle check below called a # function that did not exist. `command not found` is status 127, which the # case there read as its catch-all "this machine cannot hash", so a Raspberry # Pi was told to install the coreutils it ships with. Every *update* of an # existing hub failed that way and every fresh install on a board without Node # 22 worked, which is the wrong way round for anything to be noticed in. # # `test/deploy-integrity.test.ts` pins that they stay at the top level, because # the suite `eval`s them out of this file before running them and therefore # cannot fail the way a real machine did. sha256_of() { local file="$1" if command -v sha256sum >/dev/null 2>&1; then sha256sum "$file" | awk '{print $1}' elif command -v shasum >/dev/null 2>&1; then shasum -a 256 "$file" | awk '{print $1}' else return 1 fi } # 0 matched · 1 MISMATCH · 2 no usable digest given · 3 nothing here can hash. # Three failure codes rather than one, because only the first means the file is # wrong and only the first may stop an install. verify_sha256() { local file="$1" expected="$2" actual="" expected="$(printf '%s' "$expected" | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]')" case "$expected" in *[!0-9a-f]* | "") return 2 ;; esac [[ ${#expected} -eq 64 ]] || return 2 actual="$(sha256_of "$file")" || return 3 actual="$(printf '%s' "$actual" | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]')" [[ "$actual" == "$expected" ]] } # One digest out of a `sha256sum`-format listing: lines of " ". # The name is matched whole rather than as a substring, so # `node-v22.22.2-linux-arm64.tar.xz` cannot be answered by the line for # `node-v22.22.2-linux-arm64.tar.xz.asc` — which would be a mismatch on every # install. The listing is the forty-odd lines nodejs.org publishes per release, # or the single line `bundle.yml` writes. digest_for() { local listing="$1" name="$2" awk -v want="$name" '$2 == want { print $1; exit }' "$listing" 2>/dev/null } # ── Node ─────────────────────────────────────────────────────────────────── step runtime "Making sure Node.js 22 is available…" node_major() { "$1" --version 2>/dev/null | sed -n 's/^v\([0-9]*\).*/\1/p'; } NODE_BIN="" if [[ -x "$NODE_DIR/bin/node" ]] && [[ "$(node_major "$NODE_DIR/bin/node")" -ge 22 ]] 2>/dev/null; then NODE_BIN="$NODE_DIR/bin/node" say "Using the Node.js already installed at ${NODE_DIR}." elif command -v node >/dev/null 2>&1 && [[ "$(node_major "$(command -v node)")" -ge 22 ]] 2>/dev/null; then NODE_BIN="$(command -v node)" say "Using the system Node.js ($("$NODE_BIN" --version))." else # Raspberry Pi OS Bookworm ships Node 18. Take the official build rather than # adding a package repository: one tarball, no apt keyring to go stale, and # the same version on every board. say "Downloading Node.js ${NODE_VERSION} (${NODE_ARCH})…" NODE_TGZ="/tmp/node-${NODE_VERSION}-${NODE_ARCH}.tar.xz" NODE_TARBALL="node-v${NODE_VERSION}-${NODE_ARCH}.tar.xz" curl -fsSL --retry 5 --retry-delay 5 --retry-connrefused \ "https://nodejs.org/dist/v${NODE_VERSION}/${NODE_TARBALL}" \ -o "$NODE_TGZ" \ || fail "Couldn't download Node.js from nodejs.org. Check the network and run the install again." # nodejs.org publishes SHASUMS256.txt beside every release, so the runtime # this hub is about to execute can be checked against something other than # the connection it arrived on. See the digest helpers above for why only a # mismatch is fatal. NODE_SHA_FILE="/tmp/node-${NODE_VERSION}-SHASUMS256.txt" NODE_EXPECTED="" if curl -fsSL --retry 3 --retry-delay 2 \ "https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt" -o "$NODE_SHA_FILE" 2>/dev/null; then # `|| true`, because this file runs under `set -e`: a listing that does not # name this tarball makes `digest_for` exit non-zero, and an unguarded # command substitution would end the install then and there — turning "no # checksum to compare against" into the one outcome this must never be. NODE_EXPECTED="$(digest_for "$NODE_SHA_FILE" "$NODE_TARBALL" || true)" fi rm -f "$NODE_SHA_FILE" # Same reason, and the more dangerous half: `verify_sha256` reports its # verdict *through* its exit status, so every verdict but "matched" is a # non-zero return. Called bare it would abort the script under `set -e` # before the case below could tell a mismatch from a missing digest. NODE_VERIFY_RC=0 verify_sha256 "$NODE_TGZ" "$NODE_EXPECTED" || NODE_VERIFY_RC=$? case "$NODE_VERIFY_RC" in 0) say "Node.js ${NODE_VERSION} matches the checksum nodejs.org published." ;; 1) rm -f "$NODE_TGZ" fail "The Node.js download does not match the checksum nodejs.org publishes for it. Nothing has been installed and your hub is untouched. This is usually a proxy or a captive portal rewriting the download; try again on a different network." ;; 2) rm -f "$NODE_TGZ" fail "Could not get nodejs.org's checksum for Node.js ${NODE_VERSION}, so the download could not be verified and was not installed. Your hub is untouched. Check the network — something between this machine and nodejs.org may be blocking or rewriting it — and run the install again." ;; 3) rm -f "$NODE_TGZ" fail "This machine has neither sha256sum nor shasum, so the Node.js download could not be verified and was not installed. Install coreutils and run the install again." ;; # Anything else is the check itself going wrong rather than a verdict # about the file, and it must not borrow one of the sentences above. # This used to be the catch-all itself, so a helper never defined at all # returned 127 and was reported as a machine with no sha256sum — on a # Raspberry Pi, which ships coreutils, telling its owner to install it. *) rm -f "$NODE_TGZ" fail "The Node.js download could not be checked: the verification step itself failed with status ${NODE_VERIFY_RC}. Nothing has been installed and your hub is untouched. Please report this." ;; esac $SUDO rm -rf "$NODE_DIR" $SUDO mkdir -p "$NODE_DIR" $SUDO tar -xJf "$NODE_TGZ" -C "$NODE_DIR" --strip-components=1 \ || fail "The Node.js download arrived damaged. Run the install again." rm -f "$NODE_TGZ" NODE_BIN="$NODE_DIR/bin/node" fi NPM_BIN="$(dirname "$NODE_BIN")/npm" [[ -x "$NPM_BIN" ]] || NPM_BIN="$(command -v npm || true)" # ── The hub itself ───────────────────────────────────────────────────────── step download "Downloading the hub…" # The Pi downloads the hub; it does not compile it. Building here means `npm # ci` fetching a thousand packages onto an SD card and then `tsc` compiling # them — twenty to forty minutes, several hundred megabytes of memory, and # every minute another chance for a dropped connection to lose the lot. CI # builds one tarball per architecture instead, native modules included. BUNDLE_TAG="bundle-$(printf '%s' "$BRANCH" | tr '/' '-')" BUNDLE_URL="https://github.com/${REPO_SLUG}/releases/download/${BUNDLE_TAG}/gethome-hub-${NODE_ARCH}.tar.gz" BUNDLE_TGZ="/tmp/gethome-hub-bundle.tar.gz" INSTALLED="" STAGING="" # What `current` points at right now, so a failed install can go back to it. PREVIOUS_RELEASE="" if [[ -L "$HUB_DIR" ]]; then PREVIOUS_RELEASE="$(readlink -f "$HUB_DIR" 2>/dev/null || true)" fi $SUDO mkdir -p "$RELEASES_DIR" if [[ -z "$FORCE_BUILD" ]]; then say "Fetching ${BUNDLE_URL}…" if curl -fsSL --retry 5 --retry-delay 5 --retry-connrefused "$BUNDLE_URL" -o "$BUNDLE_TGZ" && [[ -s "$BUNDLE_TGZ" ]]; then # The bundle is `dist/` plus a production `node_modules` — the code this # machine is about to run as a service. `bundle.yml` publishes a `.sha256` # beside it, computed in the same container that built the tarball, so a # tarball replaced or truncated after the build does not survive this. # `|| true` on both: this file runs under `set -euo pipefail`, so a release # with no `.sha256` beside it (every one published before this existed) # would otherwise end the install rather than fall through to the "cannot # check" branch below — and `verify_sha256` reports every verdict but # "matched" as a non-zero return, so calling it bare would abort before the # case could tell a mismatch from a missing file. BUNDLE_EXPECTED="$(curl -fsSL --retry 3 --retry-delay 2 "${BUNDLE_URL}.sha256" 2>/dev/null | awk '{print $1; exit}' || true)" BUNDLE_VERIFY_RC=0 verify_sha256 "$BUNDLE_TGZ" "$BUNDLE_EXPECTED" || BUNDLE_VERIFY_RC=$? # None of these falls through to the source build below. Answering "this # download cannot be trusted" by cloning from the same place with less # checking is not a fallback — and nothing has moved yet, so stopping costs # the update and leaves the hub exactly as it was. case "$BUNDLE_VERIFY_RC" in 0) say "The hub bundle matches its published checksum." ;; 1) rm -f "$BUNDLE_TGZ" fail "The hub download does not match the checksum published beside it, so it was not installed. Your hub is untouched and still running the build it was. Run the install again; if it keeps happening, check whether something on this network is rewriting downloads before opening an issue." ;; 2) rm -f "$BUNDLE_TGZ" fail "The '${BUNDLE_TAG}' release publishes no checksum for ${NODE_ARCH}, so the download could not be verified and was not installed. Your hub is untouched. Every bundle built by the 'Publish bundle' workflow carries one — push to branch ${BRANCH} to rebuild it, then run the install again." ;; 3) rm -f "$BUNDLE_TGZ" fail "This machine has neither sha256sum nor shasum, so the hub download could not be verified and was not installed. Install coreutils and run the install again." ;; # Anything else is the check itself going wrong rather than a verdict # about the file, and it must not borrow one of the sentences above. # This used to be the catch-all itself, so a helper never defined at all # returned 127 and was reported as a machine with no sha256sum — on a # Raspberry Pi, which ships coreutils, telling its owner to install it. *) rm -f "$BUNDLE_TGZ" fail "The hub download could not be checked: the verification step itself failed with status ${BUNDLE_VERIFY_RC}. Nothing has been installed and your hub is untouched. Please report this." ;; esac STAGING="$RELEASES_DIR/.incoming.$$" $SUDO rm -rf "$STAGING" $SUDO mkdir -p "$STAGING" if $SUDO tar -xzf "$BUNDLE_TGZ" -C "$STAGING"; then INSTALLED=1 else say "The download arrived damaged; falling back." $SUDO rm -rf "$STAGING" STAGING="" fi rm -f "$BUNDLE_TGZ" else rm -f "$BUNDLE_TGZ" say "No prebuilt hub for ${NODE_ARCH} on branch ${BRANCH}." fi fi if [[ -z "$INSTALLED" ]]; then # Building needs roughly a gigabyte of memory for `tsc` alone. On a board that # doesn't have it, starting the build means forty minutes of thrashing an SD # card and then an OOM kill — so say what is wrong now instead. if [[ -n "$SMALL_BOARD" && -z "$FORCE_BUILD" ]]; then fail "There is no prebuilt hub for this machine (${NODE_ARCH}) on branch ${BRANCH}, and this board has ${RAM_MB} MB of memory — not enough to build one here. The build that publishes it is the 'Publish bundle' workflow, and it puts the result in the '${BUNDLE_TAG}' release. If you have just pushed, it may still be running: check https://github.com/${REPO_SLUG}/actions and try again when it is green. To install what is on main instead, re-run with --branch main." fi say "Building the hub from source (this takes a while)…" command -v git >/dev/null 2>&1 || $SUDO apt-get install -y -qq git >/dev/null 2>&1 STAGING="$RELEASES_DIR/.incoming.$$" $SUDO rm -rf "$STAGING" $SUDO git clone --depth 1 --branch "$BRANCH" "$REPO_URL" "$STAGING" \ || fail "Could not clone ${REPO_URL} — check the network and try again." BUILD_LOG=$(mktemp) if ! ( cd "$STAGING" && $SUDO env PATH="$(dirname "$NODE_BIN"):$PATH" "$NPM_BIN" ci --no-audit --no-fund --maxsockets 5 --fetch-retries 5 \ && $SUDO env PATH="$(dirname "$NODE_BIN"):$PATH" "$NPM_BIN" run build \ && $SUDO env PATH="$(dirname "$NODE_BIN"):$PATH" "$NPM_BIN" prune --omit=dev ) 2>&1 | tee "$BUILD_LOG"; then REASON="The hub could not be built here. See the output above." if grep -qE 'ECONNRESET|ETIMEDOUT|EAI_AGAIN|npm error network' "$BUILD_LOG"; then REASON="The download of the hub's dependencies was cut off partway. This is a slow or flaky connection rather than a problem with the Pi — running the install again picks up where it left off, and a network cable instead of Wi-Fi makes it much more likely to finish first time." elif grep -qE 'no space left on device|ENOSPC' "$BUILD_LOG"; then REASON="The Pi ran out of disk space while building the hub. Free some space (or use a larger card) and run the install again." elif grep -qiE 'killed|out of memory|Cannot allocate memory' "$BUILD_LOG"; then REASON="The Pi ran out of memory while building the hub. This board is too small to build on; install from a branch that has a published build instead." fi rm -f "$BUILD_LOG" $SUDO rm -rf "$STAGING" fail "$REASON" fi rm -f "$BUILD_LOG" fi [[ -n "$STAGING" && -f "$STAGING/dist/index.js" ]] \ || fail "The hub install is incomplete — dist/index.js is missing. Run the install again." # ── Name the build, then make it current ─────────────────────────────────── # CI stamps VERSION into the bundle; a source build has no stamp, so it gets a # timestamp. Either way "which build is this Pi running" has an answer that # survives to the API and the app. BUILD_ID="$($SUDO cat "$STAGING/VERSION" 2>/dev/null | head -n1 | tr -cd '[:alnum:]._-' || true)" [[ -n "$BUILD_ID" ]] || BUILD_ID="src-$(date -u +%Y%m%d%H%M%S)" RELEASE_DIR="$RELEASES_DIR/$BUILD_ID" # Re-installing the same build id must not destroy the running one before the # replacement is in place: move the old directory aside, put the new one in, # and only then delete. `rm -rf` followed by a `mv` that fails would leave the # hub with no install at all, on a machine nobody is sitting in front of. if [[ -e "$RELEASE_DIR" ]]; then $SUDO rm -rf "${RELEASE_DIR}.replaced" $SUDO mv "$RELEASE_DIR" "${RELEASE_DIR}.replaced" fi if ! $SUDO mv "$STAGING" "$RELEASE_DIR"; then [[ -e "${RELEASE_DIR}.replaced" ]] && $SUDO mv "${RELEASE_DIR}.replaced" "$RELEASE_DIR" $SUDO rm -rf "$STAGING" fail "Could not put the new build in place at ${RELEASE_DIR}. The hub is unchanged." fi $SUDO rm -rf "${RELEASE_DIR}.replaced" $SUDO chown -R root:root "$RELEASE_DIR" # `ln -sfn` through a temporary name and `mv -T`: a plain `ln -sf` onto an # existing symlink-to-a-directory creates a link *inside* it instead of # replacing it. This way the switch is one atomic rename. $SUDO ln -sfn "$RELEASE_DIR" "${HUB_DIR}.new" $SUDO mv -T "${HUB_DIR}.new" "$HUB_DIR" say "Installed build ${BUILD_ID}." # Old builds, minus the one we came from (kept for rollback). mapfile -t OLD_RELEASES < <(ls -1dt "$RELEASES_DIR"/*/ 2>/dev/null | sed 's:/$::' || true) if [[ ${#OLD_RELEASES[@]} -gt $KEEP_RELEASES ]]; then for stale in "${OLD_RELEASES[@]:$KEEP_RELEASES}"; do [[ "$stale" == "$RELEASE_DIR" || "$stale" == "$PREVIOUS_RELEASE" ]] && continue $SUDO rm -rf "$stale" done fi # ── Mosquitto ────────────────────────────────────────────────────────────── # The broker is the meeting point for hubd, Zigbee2MQTT, and any MQTT # integration the user builds. It listens on the LAN, not just loopback: DIY # boards and wired controllers live on other machines, and the firewall # boundary for a home hub is the router. # # ── It asks for a password, and there are two accounts ───────────────────── # It used to be `allow_anonymous true`, and that was a hole the size of the # whole product: everything else a member may do is behind a token and a role, # while anybody on the home Wi-Fi could open a broker connection and publish # `zigbee2mqtt//set` to work every light and lock in the house, or # `bridge/request/permit_join` to open the Zigbee network. The REST API's # access table is not worth much with that sitting next to it. # # Two accounts, because "who may read the home" and "who may drive the radio" # are different questions: # # gethome-hub full read/write. hubd and Zigbee2MQTT sign in as this, and it # is what an owner is shown only when they ask for it. # gethome the one an owner is actually handed. It publishes under # `gethome/#` — the public integrator convention, see # docs/mqtt-integrations.md — and *reads* Zigbee device state, # so a board somebody builds can react to a motion sensor. It # cannot write to `zigbee2mqtt/#` at all, so a devboard that is # lost, resold or compromised cannot switch the house off or # open the network for pairing. # # Both are minted here, once, and reused on every later run: rotating them on # each update would silently break every integration the owner had wired in. # `GET /settings/mqtt` is how they reach an app. MQTT_HUB_USER="gethome-hub" MQTT_APP_USER="gethome" MQTT_ENV="$CONF_DIR/mqtt.env" MQTT_PASSWD_FILE="/etc/mosquitto/gethome.passwd" MQTT_ACL_FILE="/etc/mosquitto/gethome.acl" # Set once the broker really is asking for a password, which is what decides # whether the units get credentials and what the closing summary says. MQTT_SECURED="" # 16 bytes of urandom as hex. Hex rather than base64 on purpose: this value is # also handed to people to paste into ESP32 sketches and Home Assistant YAML, # and it travels through a `mqtt://user:pass@host` URL in `mqtt.env`, where a # `/` or a `+` would have to be percent-encoded by every reader. # # `od -N16` reads exactly sixteen bytes and exits; the obvious # `tr -dc … /dev/null || true) printf '%s\n' "$existing" | awk -F= -v key="$1" '$1 == key { sub(/^[^=]*=/, ""); print; exit }' } MQTT_HUB_PASS="$(mqtt_env_value MQTT_PASSWORD)" MQTT_APP_PASS="$(mqtt_env_value MQTT_INTEGRATION_PASSWORD)" # A hub that already exists and has no credentials is one whose broker has been # open until now — so somebody may have wired a devboard straight into it, and # that board is about to stop being able to publish. That is worth saying out # loud once, at the end, where the user is looking; it is not worth leaving the # hole open for. MQTT_WAS_OPEN="" [[ -z "$MQTT_HUB_PASS" && -f "$CONF_DIR/hub.env" ]] && MQTT_WAS_OPEN=1 [[ -n "$MQTT_HUB_PASS" ]] || MQTT_HUB_PASS="$(gen_secret)" [[ -n "$MQTT_APP_PASS" ]] || MQTT_APP_PASS="$(gen_secret)" $SUDO mkdir -p /etc/mosquitto/conf.d # ── Never lock the hub out of its own broker ─────────────────────────────── # `mosquitto_passwd` ships with the broker, so this should always be present. # If it somehow isn't, writing `allow_anonymous false` beside a password file # that does not exist would take Zigbee and every MQTT device down for good, on # a hub that installed perfectly — the installed-but-unusable trap. Stay open, # and say so loudly enough that it gets fixed. if command -v mosquitto_passwd >/dev/null 2>&1; then if $SUDO mosquitto_passwd -c -b "$MQTT_PASSWD_FILE" "$MQTT_HUB_USER" "$MQTT_HUB_PASS" >/dev/null 2>&1 \ && $SUDO mosquitto_passwd -b "$MQTT_PASSWD_FILE" "$MQTT_APP_USER" "$MQTT_APP_PASS" >/dev/null 2>&1; then MQTT_SECURED=1 else warn "Could not write the MQTT password file, so the broker is staying open to the local network." fi else warn "mosquitto_passwd is missing, so the MQTT broker is staying open to the local network." fi if [[ -n "$MQTT_SECURED" ]]; then # ── What each account may touch ────────────────────────────────────────── # Only `read`, `write` and `readwrite` are used. mosquitto also understands # `deny`, which would express "everything under zigbee2mqtt/ except # bridge/info" in one line — and a config option an older broker does not # parse is a fatal error, which here means a hub with no Zigbee and no MQTT # at all. Listing what is allowed cannot fail that way. # # `zigbee2mqtt/+` is one level, so it is every device's state topic and none # of `bridge/#`. The three bridge topics that are named are the ones a DIY # integration actually wants; `bridge/info` is deliberately not among them, # because it carries Zigbee2MQTT's own configuration and we are not going to # depend on upstream redacting the network key from it. $SUDO tee "$MQTT_ACL_FILE" >/dev/null </dev/null 2>&1 \ && $SUDO chown root:mosquitto "$MQTT_PASSWD_FILE" "$MQTT_ACL_FILE" 2>/dev/null \ && $SUDO chmod 0640 "$MQTT_PASSWD_FILE" "$MQTT_ACL_FILE" 2>/dev/null; }; then MQTT_SECURED="" $SUDO rm -f "$MQTT_PASSWD_FILE" "$MQTT_ACL_FILE" 2>/dev/null || true warn "The MQTT broker's own account can't read the password file this machine would need, so the broker is staying open to the local network." fi fi # ── Add nothing the distribution's own config already sets ───────────────── # This file is included *after* /etc/mosquitto/mosquitto.conf, which on Debian # and Raspberry Pi OS already contains `persistence` and # `persistence_location`. Repeating a string option there is not an override — # mosquitto's parser treats it as a fatal error and refuses to start: # # Error: Duplicate persistence_location value in configuration. # # which is exactly how the broker ended up down, port 1883 closed, and Zigbee # unable to work at all on a hub that otherwise installed perfectly. Keep this # to the few lines we genuinely need — `password_file` and `acl_file` are not # among what Debian sets, which is the only reason they can be here. if [[ -n "$MQTT_SECURED" ]]; then $SUDO tee /etc/mosquitto/conf.d/gethome.conf >/dev/null </dev/null <<'MOSQ_OPEN' # GetHome Hub — fallback. This broker takes anonymous connections because the # installer could not set a password up (the warning above says why), which # means anyone on this network can read the home and control every Zigbee # device on it. Re-run the installer to close it. listener 1883 allow_anonymous true MOSQ_OPEN fi # ── The credentials, where systemd can hand them to both services ────────── # Deliberately *not* hub.env: that file is written only when it is absent, so # an upgraded hub would never see a new variable in it — the same trap that # makes a `GETHOME_UPDATE=1` line there the wrong answer. This one is rewritten # on every run and pulled in by both units. # # It carries `MQTT_URL` with the credentials in it as well as the two fields # beside it, and that redundancy is the rollback story. `install.sh` puts the # previous build back when a new one fails its health check, and that build may # predate `MQTT_USERNAME` — but every build the hub has ever had reads # `MQTT_URL`, and this file is listed *after* hub.env so its value is the one # that survives. The current build is right either way: `loadConfig` lifts the # credentials out of whichever URL it is given, and an explicit `MQTT_USERNAME` # outranks them. # # 0600 root: systemd reads EnvironmentFile as PID 1, before it drops to the # service account, so nothing here needs to be readable by the hub itself. if [[ -n "$MQTT_SECURED" ]]; then $SUDO tee "$MQTT_ENV" >/dev/null </dev/null || true $SUDO chmod 0600 "$MQTT_ENV" 2>/dev/null || true else # No credentials, so no file: a stale one would hand both services a password # the broker is no longer checking, and hubd would fail to connect to a # broker that would have taken it anonymously. $SUDO rm -f "$MQTT_ENV" 2>/dev/null || true fi $SUDO systemctl enable mosquitto >/dev/null 2>&1 || true if ! $SUDO systemctl restart mosquitto >/dev/null 2>&1; then warn "The MQTT broker didn't start. Zigbee and MQTT devices need it — the reason is below." service_failure mosquitto fi # ── The log has to survive the reboot that hid the problem ───────────────── # systemd's `Storage=auto` means "persist if /var/log/journal exists", and on # the Pi this was found on that directory existed and was **empty** — journald # had never been told to adopt it, so every log the machine had was in `/run`, # thrown away on every boot. The cost lands exactly where it hurts: a hub that # went unreachable on Tuesday and recovered by itself has no record of Tuesday # left by Wednesday, and what the machine was doing at the time is the only # question worth asking. `journalctl --list-boots` answering with one boot is # what that looks like from the outside. # # `Storage=persistent` states it rather than inferring it from a directory, and # the caps are for the SD card: journald sizes itself at 10% of the filesystem, # which on a 64 GB card is six gigabytes of writes nobody asked for. 64 MB is # weeks of a hub that is behaving itself, and the boots either side of one that # is not. $SUDO mkdir -p /etc/systemd/journald.conf.d if $SUDO tee /etc/systemd/journald.conf.d/50-gethome.conf >/dev/null <<'JOURNALD' # Written by GetHome. A hub is a machine nobody is sitting in front of, so what # it logged before the last reboot is usually the only evidence there is. [Journal] Storage=persistent # The bound is the SD card's, not the filesystem's: journald's own default # would take 10% of the card. SystemMaxUse=64M SystemMaxFileSize=8M RuntimeMaxUse=16M JOURNALD then $SUDO mkdir -p /var/log/journal $SUDO systemd-tmpfiles --create --prefix /var/log/journal >/dev/null 2>&1 || true $SUDO systemctl restart systemd-journald >/dev/null 2>&1 || true $SUDO journalctl --flush >/dev/null 2>&1 || true else warn "The system log could not be made persistent, so a reboot will keep losing what the hub logged before it." fi # ── Wi-Fi must not doze ──────────────────────────────────────────────────── # A hub is a machine nobody talks to for hours and then everybody talks to at # once — a phone opens the app, Studio browses for it, somebody SSHs in. That # is the worst traffic pattern there is for 802.11 power save, and the Pi's # brcmfmac is asked to sleep by default (`brcmf_cfg80211_set_power_mgmt: # power save enabled`, in every Pi's kernel log). # # **This was first written as the fix for a hub that nothing could reach for # ten minutes at a time, and it was not that fix.** Those outages went on with # power save off; they were the router sitting on the broadcasts it owes the # hub, which is what `keep_wifi_reachable` below is about. Power save stays off # for a reason of its own: a dozing radio listens for broadcasts only when the # access point's DTIM signalling says there are some, and that signalling is # what the routers with that fault get wrong — openwrt/mt76#598 is power-saving # clients that stop hearing broadcasts altogether until they next transmit. # An awake radio at least hears them when the router finally sends them. # # The saving is on the order of 20 mA, on a mains-powered board that is the # home's front door. Not a trade worth making — so it goes off now, and off # again on every association, because that is where it comes back. # # A wired hub needs none of this: the interface is whichever one carries the # default route (which provably exists — the bundle was just downloaded over # it), and a machine that reaches the LAN over Ethernet gets no unit, no # dispatcher, and nothing said about it. `GETHOME_NET_DIR` and the two path # overrides are there for the same reason `GETHOME_CMDLINE` is: so a test can # run this against files it owns rather than against the machine it is on. find_iw() { local found found="$(command -v iw 2>/dev/null || true)" if [[ -z "$found" && -x /usr/sbin/iw ]]; then found=/usr/sbin/iw; fi printf '%s' "$found" } # **Two different programs are called `arping`, and root gets the wrong one by # default.** `iputils-arping` installs `/usr/bin/arping` and takes `-I` for the # interface; Thomas Habets' `arping` package installs `/usr/sbin/arping` and # takes `-i`. Root's PATH on Debian puts `/usr/sbin` *first*, so a hub with # both would run the one whose flags we are not using — and it would fail # silently, taking with it the one announcement that was measured to keep the # router from losing the hub. Resolved by path here, and the caller sends one # real announcement before trusting it. find_arping() { local cand for cand in /usr/bin/arping "$(command -v arping 2>/dev/null || true)"; do if [[ -n "$cand" && -x "$cand" ]]; then printf '%s' "$cand"; return 0; fi done } # The interface the LAN is reached over, when that is a wireless one. Empty for # a wired hub, and empty when there is no default route to judge by. lan_wifi_iface() { local net_dir="${GETHOME_NET_DIR:-/sys/class/net}" iface iface="$(ip -o route show default 2>/dev/null \ | awk '{ for (i = 1; i < NF; i++) if ($i == "dev") { print $(i + 1); exit } }' || true)" [[ -n "$iface" ]] || return 0 # Two markers, because only one of them is guaranteed. `wireless/` is the old # wireless-extensions directory, and a driver built without them has none; # `phy80211` is cfg80211's own link to the radio and is there on everything # this hub runs on. Asking for the first alone is how the whole of the # section below turns into a no-op that says nothing — "no wireless # interface" is the case that is meant to be silent, so a radio we failed to # recognise would leave power saving on and never mention it. [[ -d "${net_dir}/${iface}/wireless" || -e "${net_dir}/${iface}/phy80211" ]] || return 0 printf '%s' "$iface" } # What that interface is associated on, in MHz. Empty when it is not, or when # the driver will not say — the caller must treat that as "no information", # never as a frequency. wifi_frequency_mhz() { local iface iw_bin iface="$(lan_wifi_iface)" [[ -n "$iface" ]] || return 0 iw_bin="$(find_iw)" [[ -n "$iw_bin" ]] || return 0 "$iw_bin" dev "$iface" link 2>/dev/null | awk '/freq:/ { printf "%d", $2; exit }' } keep_wifi_awake() { local net_dir="${GETHOME_NET_DIR:-/sys/class/net}" local dispatcher="${GETHOME_NM_DISPATCHER:-/etc/NetworkManager/dispatcher.d/50-gethome-wifi-awake}" local unit="${GETHOME_WIFI_UNIT:-/etc/systemd/system/gethome-wifi-awake.service}" local iface iw_bin persisted="" # Wired, or no default route to judge by: nothing to do and nothing to say. iface="$(lan_wifi_iface)" [[ -n "$iface" ]] || return 0 iw_bin="$(find_iw)" if [[ -z "$iw_bin" ]]; then # With the lists refreshed first. The packages step above is the only one # that runs `apt-get update`, and it only reaches it when something it # needs is missing — so on a hub where everything else was already there, # an install here would be resolving against whatever the card happened to # have cached, which on an image that has sat in a drawer is nothing. That # failure is silent by construction: it ends in the warning below, on a # hub whose radio then goes on sleeping. $SUDO apt-get update -qq >/dev/null 2>&1 || true $SUDO apt-get install -y -qq --no-install-recommends iw >/dev/null 2>&1 || true iw_bin="$(find_iw)" fi if [[ -z "$iw_bin" ]]; then warn "This hub reaches the network over Wi-Fi (${iface}) and 'iw' could not be installed, so power saving is still on. The hub may stop answering for minutes at a time while the radio sleeps." return 0 fi # The link that is up right now, so this install does not have to wait for a # reconnect to take effect. $SUDO "$iw_bin" dev "$iface" set power_save off >/dev/null 2>&1 || true if command -v nmcli >/dev/null 2>&1; then # NetworkManager turns power save back on as it associates, so a value # written into one profile is a value the next profile has not got — and a # home that re-enters its Wi-Fi password next month gets a fresh profile # with the fault back in it. The dispatcher covers every wireless # connection this machine ever grows, which is the one thing enumerating # today's profiles cannot do. NM ignores a dispatcher script that anyone # but root can write, so the ownership and the mode are part of the fix. $SUDO mkdir -p "$(dirname "$dispatcher")" if $SUDO tee "$dispatcher" >/dev/null </dev/null || true if $SUDO chmod 0755 "$dispatcher"; then persisted="NetworkManager"; fi fi else # A wpa_supplicant/dhcpcd machine has no dispatcher, so the unit is bound # to the device and runs whenever it appears. if $SUDO tee "$unit" >/dev/null </dev/null 2>&1 || true $SUDO systemctl enable gethome-wifi-awake >/dev/null 2>&1 || true # Restarted rather than `--now`, for the reason `keep_wifi_reachable` # gives: this is a `RemainAfterExit` oneshot, so an update that changed # its ExecStart would otherwise not run until the board rebooted. if $SUDO systemctl restart gethome-wifi-awake >/dev/null 2>&1; then persisted="systemd" fi fi fi # Ask the radio rather than trusting the write: a driver with no support for # the call answers success and changes nothing. if ! $SUDO "$iw_bin" dev "$iface" get power_save 2>/dev/null | grep -qi 'power save: off'; then warn "Wi-Fi power saving could not be turned off on ${iface}. The hub works, but it may stop answering for minutes at a time while the radio sleeps — the apps and SSH both go quiet while the hub itself keeps running." elif [[ -z "$persisted" ]]; then warn "Wi-Fi power saving is off on ${iface} now, but it could not be made to stay off, so it comes back on the next reconnect." else say "Wi-Fi power saving is off on ${iface}, and stays off across reconnects (${persisted})." fi } # ── The hub has to stay findable without a broadcast ever reaching it ────── # **Some routers sit on the broadcasts they owe the hub's radio, and a hub that # can only be found by broadcast goes missing while it runs perfectly.** # Measured on the hub this came from, behind a TP-Link Archer C6 (MediaTek # radios): numbered UDP broadcasts from a Mac on 5 GHz reached the hub up to 43 # seconds late, released in bursts, and at worst three in five never arrived — # while unicast from the same Mac, in the same minute, arrived 45 of 45 inside # 30 ms. The router is the one holding them. The hub's radio is in constant- # awake mode, its own broadcasts reach the 5 GHz side at once, and turning the # Wi-Fi firmware's ARP offload off (promiscuous mode) changed nothing. It is a # known fault of these chips' group-addressed queue (openwrt/mt76#598), it comes # and goes, and nothing on the hub can see it happening. # # **Two different things only ever reach the hub through that queue, and each # was its own outage.** The first was the router losing its way to a hub that # had been quiet for minutes, which a broadcast from the hub every 20 seconds # cured: four hours of probes idled 55 seconds apart, 503 of 504 replies, # against multi-minute blackouts before it. The second is the one that # measurement could not see, because a 55-second gap never lets a cache # expire: **a phone's ARP request for the hub.** macOS keeps an entry for 20 # minutes (`net.link.ether.inet.max_age`), iOS is the same kernel, and then # it asks again by broadcast. While the queue is stuck nothing answers and the # app gets `Host is down`, from a phone whose Wi-Fi is plainly fine, about a hub # that is up and serving every client whose cache is still warm. # # **A gratuitous ARP does not refresh that cache, and that was measured.** The # expiry of the Mac's entry for the hub did not move for one, request or # reply; it went back to 1200 seconds the moment the hub sent an ARP request # *addressed to the Mac* — which is what the kernel sends when it re-checks a # stale neighbour, by unicast, so the stuck queue never sees it. `ip neigh # replace lladdr nud probe` asks for exactly that, at the link # address the kernel already holds: the entry goes to PROBE and the kernel # sends its unicast question at once (measured on the hub: STALE to REACHABLE # inside a second). `ip neigh change … use` would ask the same thing more # politely, but only iproute2 5.17 and later know it — not Bullseye's 5.10 and # not Ubuntu 22.04's 5.15 — while `nud probe` is older than both. So every # round the keep-alive has the kernel re-check each neighbour whose entry has # gone stale, and it remembers the ones the kernel has given up on for a day, # asking about them by unicast at the address they had every two minutes: a # phone that comes home rejoins with an empty cache, and this is what makes the # hub known to it again before anybody opens the app. **Nothing is ever # broadcast at a neighbour** — that is the path that is broken, and it would # wake every sleeping device in the house besides. # # **A Matter accessory is the case a day does not cover.** Reaching one starts # with a Neighbour Solicitation, which is multicast, and on the hub this came # from the hub's multicast reached its plug 7 times in 30 while unicast went # 30 in 30. A plug switched off for days was forgotten here and by the kernel # alike, so once it was back on, every retry the hub made — at the right # address, every two minutes — died in neighbour discovery until a multicast # got through, eight and a half minutes later. A reboot empties both memories # too, for every accessory at once. The hub knows better than either: each # accessory reports its own link-local address and link address, and # matter.js keeps them for as long as the accessory is commissioned. So the # hub writes them to `/matter-neighbours` # (`src/adapters/matter/neighbours.ts`) and the loop asks after each the # kernel has no link address for, by unicast, every two minutes, for as long # as the file lists it. The file is written by the hub's own user and read # here as root, so the loop takes a line only if it is exactly a link-local # address and a MAC, and reads no more than 16 KiB of it. # # The gratuitous ARP stays: it is what keeps the router from losing the hub in # the first place. The ping at the gateway that sat beside it is gone. It was # the first attempt at that outage, shipped on a theory the next commit # disproved, and kept afterwards "because it costs nothing" — but the gateway # is a neighbour like any other now and is re-checked with the rest. A wired # hub gets none of this, for the reason it gets no dispatcher. # # **And every round ends by asking whether anything answered at all.** A hub # whose Wi-Fi stays connected while nothing gets through — seen once, for fifty # minutes, with NetworkManager and the kernel saying nothing — is one no amount # of asking can help, because none of the questions is answered. So the round # calls `deploy/wifi-watchdog.sh` (installed as `/usr/local/lib/gethome-wifi- # watchdog.sh`), which after five minutes with no answer from anything while # NetworkManager says the hub is connected reloads the radio's driver, and five # minutes after that restarts the machine. It is called with no interface on a # round with no default route, because that is what a reload that did not help # looks like. That file says why, and what keeps it from acting on a hub that # is fine. keep_wifi_reachable() { local iface self arping_bin gateway gateway_mac unit="${GETHOME_KEEPALIVE_UNIT:-/etc/systemd/system/gethome-wifi-keepalive.service}" local script="${GETHOME_KEEPALIVE_SCRIPT:-/usr/local/lib/gethome-wifi-keepalive.sh}" local watchdog="${GETHOME_WIFI_WATCHDOG_BIN:-/usr/local/lib/gethome-wifi-watchdog.sh}" iface="$(lan_wifi_iface)" [[ -n "$iface" ]] || return 0 # `arping` sends the broadcast. It is only wanted on a wireless hub, so it is # installed here rather than with the base packages — and with the lists # refreshed first, for the reason `iw` is. arping_bin="$(find_arping)" if [[ -z "$arping_bin" ]]; then $SUDO apt-get update -qq >/dev/null 2>&1 || true $SUDO apt-get install -y -qq --no-install-recommends iputils-arping >/dev/null 2>&1 || true arping_bin="$(find_arping)" fi # Ask, never assume — `keep_wifi_awake`'s rule, and here it covers more than # a missing binary: an announcement that cannot be sent leaves the router # free to lose a quiet hub, which is the first of the two outages above. One # real broadcast during the install is what tells the two apart. self="$(ip -4 -o addr show "$iface" 2>/dev/null | awk '{ split($4, a, "/"); print a[1]; exit }')" if [[ -z "$arping_bin" ]] || ! $SUDO "$arping_bin" -U -c 1 -I "$iface" "${self:-0.0.0.0}" >/dev/null 2>&1; then warn "This hub reaches the network over Wi-Fi (${iface}) and could not announce itself to the router. It works, but it may become unreachable for minutes at a time after a quiet spell, while running perfectly." arping_bin="" fi # Ask, never assume, for the other half too: one real re-check, of the # gateway, which is the one neighbour certain to be there (the bundle was # just downloaded through it). A kernel or an `ip` that refuses it would fail # every call the loop makes, and the loop says nothing — leaving each phone's # record of this hub to expire, which is the fault itself behind a clean # install log. No entry to try it on is not a refusal, so it says nothing. gateway="$(ip route show default 2>/dev/null | awk '/^default/ { print $3; exit }')" gateway_mac="$(ip -4 neigh show "${gateway:-0.0.0.0}" dev "$iface" 2>/dev/null | awk '$2 == "lladdr" { print $3; exit }')" if [[ -n "$gateway_mac" ]] && ! $SUDO ip neigh replace "$gateway" lladdr "$gateway_mac" nud probe dev "$iface" >/dev/null 2>&1; then warn "This hub could not ask the kernel to re-check a neighbour, so a phone that has not talked to the hub for 20 minutes may not find it for a while, on a router that is slow to pass broadcasts on." fi # The watchdog every round ends with, from the build being installed. A hub # it cannot be installed on still gets the rest of the round, and is told # what it goes without. if ! { $SUDO mkdir -p "$(dirname "$watchdog")" \ && $SUDO install -m 0755 "$HUB_DIR/deploy/wifi-watchdog.sh" "$watchdog"; } >/dev/null 2>&1; then warn "Could not install the Wi-Fi watchdog. The hub works, but if its Wi-Fi ever stops passing traffic while it stays connected, it stays off the network until it is switched off and on again." watchdog="" fi # The body is quoted, so it is written exactly as it reads. Three values are # baked in at install time: the `arping` resolved above, by path — see # `find_arping` for why it is never looked up at run time — where the hub # keeps its list of Matter accessories (`src/adapters/matter/ # neighbours.ts`, `MATTER_NEIGHBOURS_FILE`; the suite holds the two names # together), and the watchdog just installed. **No line in it may begin # with `}`**: the suites lift this function out of the file with # `sed '/^keep_wifi_reachable() {/,/^}/p'`, which would end it there — which # is why the loop below has no functions of its own. $SUDO mkdir -p "$(dirname "$script")" if ! { printf '#!/bin/sh\n' printf '# Installed by GetHome. deploy/install.sh says why in full.\n' printf 'arping_bin="%s"\n' "${arping_bin:-/nonexistent}" printf 'matter_neighbours="%s"\n' "${DATA_DIR}/matter-neighbours" printf 'wifi_watchdog="%s"\n' "${watchdog:-/nonexistent}" cat <<'KEEPALIVE' # # The short version: a router can sit on the broadcasts it owes this hub's # radio for seconds or minutes at a time while passing unicast perfectly, so # nothing here depends on a broadcast arriving. # # Every round: # - a gratuitous ARP, so the router does not lose its way to a hub that has # been quiet; # - the kernel re-checks every neighbour whose entry has gone stale, which it # does by asking that one machine, by unicast. That is what refreshes the # neighbour's own record of this hub: macOS and iOS take nothing from a # gratuitous ARP, and once their record expires they can only ask by # broadcast, which is the question that goes missing; # - and last, whether anything answered at all. After five minutes in which # nothing has while NetworkManager says this hub is connected, the # watchdog reloads the radio's driver, then restarts the machine; its own # file says why, and what keeps it from acting on a hub that is fine. # Neighbours the kernel has given up on are remembered for a day and asked # about the same way every two minutes, at the address they had, so a phone # that comes home is known again before anybody opens the app. Nothing is ever # broadcast at a neighbour. # # **Both families.** Matter is IPv6, and its neighbour discovery is multicast # through the same stuck queue: a Wi-Fi accessory that has lost its record of # this hub asks for it the way a phone does, and a hub that has lost its record # of the accessory asks back the same way. A stale IPv6 entry re-checked by # unicast carries this hub's link address to the accessory as well. # # **And every Matter accessory the hub owns, however long it has been gone.** # A day in /run covers a phone; it does not cover a plug switched off for a # week, or any accessory after this board reboots, and either was left to # multicast — measured reaching a plug 7 times in 30, which kept one that had # been off for days unreachable for eight and a half minutes after it was # back. So the hub writes down where each accessory it owns can be reached — # the link-local address and link address it reports about itself — and every # two minutes this asks for each the kernel has no link address for, by # unicast. The file is the hub's and this runs as root, so a line counts only # if it is exactly a link-local address and a MAC. # # Everything is re-read each round rather than captured, so a lease or an # interface that moves does not leave this announcing an address it no longer # has. # $state holds one "address link-address last-reached" per neighbour. state="${GETHOME_NEIGH_STATE:-/run/gethome-wifi-neighbours}" # $matter holds one "link-local-address link-address" per accessory. matter="${GETHOME_MATTER_NEIGHBOURS:-$matter_neighbours}" watchdog="${GETHOME_WIFI_WATCHDOG:-$wifi_watchdog}" round=0 while :; do iface=$(ip route show default 2>/dev/null | awk '/^default/ { for (i = 1; i < NF; i++) if ($i == "dev") { print $(i + 1); exit } }') if [ -n "$iface" ]; then self=$(ip -4 -o addr show "$iface" 2>/dev/null | awk '{ split($4, a, "/"); print a[1]; exit }') [ -n "$self" ] && [ -x "$arping_bin" ] && "$arping_bin" -U -c 1 -I "$iface" "$self" >/dev/null 2>&1 now=$(date +%s) fresh="$state.new" if : > "$fresh" 2>/dev/null; then ip neigh show dev "$iface" 2>/dev/null | while read -r addr ll mac rest; do [ "$ll" = lladdr ] || continue # Reached means confirmed. Anything else keeps the time it last was, # or a neighbour that never answers again would be remembered for ever. case " $rest " in *" REACHABLE "*) seen=$now ;; *) seen=$(awk -v a="$addr" '$1 == a { print $3; exit }' "$state" 2>/dev/null) case "$seen" in '' | *[!0-9]*) seen=$now ;; esac ;; esac echo "$addr $mac $seen" >> "$fresh" case " $rest " in # An IPv6 router keeps its flag: `replace` would clear it otherwise. *" router "*"STALE "*) ip neigh replace "$addr" lladdr "$mac" router nud probe dev "$iface" 2>/dev/null ;; *" STALE "*) ip neigh replace "$addr" lladdr "$mac" nud probe dev "$iface" 2>/dev/null ;; esac done if [ -r "$state" ]; then while read -r addr mac seen; do case "$seen" in '' | *[!0-9]*) continue ;; esac awk -v a="$addr" '$1 == a { found = 1 } END { exit !found }' "$fresh" && continue [ $((now - seen)) -le 86400 ] || continue echo "$addr $mac $seen" >> "$fresh" [ $((round % 6)) -eq 0 ] || continue # Never over a resolution the kernel is already making. ip neigh show "$addr" dev "$iface" 2>/dev/null | grep -q INCOMPLETE && continue ip neigh replace "$addr" lladdr "$mac" nud probe dev "$iface" 2>/dev/null done < "$state" fi mv -f "$fresh" "$state" fi # The hub's Matter accessories, on the same two-minute beat: every one the # kernel holds no link address for, which includes one the loop above has # just seeded. **Over a resolution in flight too**, unlike that loop: this # link address is the accessory's own word rather than a memory gone # stale, and one the hub is busy trying to reach is resolving nearly all # the time — its traffic starts a new multicast round the moment the last # fails — so waiting for a quiet moment would be waiting for ever. Seeding # sends what the kernel had queued at once. Bounded, because the file is # somebody else's to write. if [ $((round % 6)) -eq 0 ] && [ -f "$matter" ]; then head -c 16384 "$matter" 2>/dev/null | while read -r addr mac rest; do case "$addr" in fe80:*) ;; *) continue ;; esac case "$addr" in *[!0-9a-f:]*) continue ;; esac [ "${#addr}" -le 39 ] || continue case "$mac" in [0-9a-f][0-9a-f]:[0-9a-f][0-9a-f]:[0-9a-f][0-9a-f]:[0-9a-f][0-9a-f]:[0-9a-f][0-9a-f]:[0-9a-f][0-9a-f]) ;; *) continue ;; esac ip neigh show "$addr" dev "$iface" 2>/dev/null | grep -q lladdr && continue ip neigh replace "$addr" lladdr "$mac" nud probe dev "$iface" 2>/dev/null done fi # Last, after every question this round has asked: did anything answer? [ -x "$watchdog" ] && "$watchdog" "$iface" else # No default route, which is also what a reload looks like when the # network it joins afresh still passes nothing: the watchdog has to see # that round too, to take its last step. [ -x "$watchdog" ] && "$watchdog" fi # One round and out, for the suite that runs this file. [ -z "${GETHOME_KEEPALIVE_ONCE:-}" ] || exit 0 round=$((round + 1)) sleep 20 done KEEPALIVE } | $SUDO tee "$script" >/dev/null; then warn "Could not install the Wi-Fi keep-alive. The hub works, but it may become unreachable for minutes at a time after a quiet spell, while running perfectly." return 0 fi $SUDO chmod 0755 "$script" if $SUDO tee "$unit" >/dev/null </dev/null 2>&1 || true $SUDO systemctl enable gethome-wifi-keepalive >/dev/null 2>&1 || true # `restart`, not `enable --now`. Every update re-runs this installer and # rewrites the script above, and `--now` on a unit that is already running # does nothing at all — so the fix would sit on disk until the next reboot # while the old one kept running. `restart` starts a stopped unit too. if $SUDO systemctl restart gethome-wifi-keepalive >/dev/null 2>&1; then say "The hub will keep itself known on the network — to the router every 20 seconds, and to every phone and computer that talks to it — so it stays reachable after a quiet spell." [[ -z "$watchdog" ]] \ || say "If its Wi-Fi ever stays connected while nothing gets through, it restarts the radio after five minutes, and the whole hub if that is not enough." return 0 fi fi warn "Could not start the Wi-Fi keep-alive. The hub works, but it may become unreachable for minutes at a time after a quiet spell, while running perfectly." } keep_wifi_awake keep_wifi_reachable # ── Bluetooth, so a factory-new Matter accessory can be found at all ─────── # **An accessory that has never been on a network cannot be found on one.** A # Wi-Fi Matter plug out of its box — or one somebody has just held the button # on to reset — advertises over Bluetooth LE and nowhere else, and the # conversation that follows is what gives it the Wi-Fi it lives on afterwards. # Without this the hub can only take in accessories already on the LAN, which # is a minority of what people buy, and was for a long time the whole of what # it could do: the app searched the network for a device that was never going # to be there and said "Pairing with your hub" until somebody gave up. # # The radio is usually present and usually off. Raspberry Pi OS ships a # headless image with Bluetooth **soft-blocked** in rfkill, which is invisible # from anywhere the product can see: `hciconfig` lists the adapter perfectly # happily and bringing it up fails with an errno nothing logs. So this # unblocks it, makes that stick across reboots, and starts bluetoothd. matter_bluetooth() { local rfkill_dir="${GETHOME_RFKILL_DIR:-/sys/class/rfkill}" local entry name unblocked="" # No adapter at all is an ordinary machine, not a fault: a Pi 4 with the # radio disabled in config.txt, a virtual machine, an x86 box. The hub says # so on GET /hub and the app explains it; there is nothing to warn about # here. [[ -d "$rfkill_dir" ]] || return 0 for entry in "$rfkill_dir"/*; do [[ -r "$entry/name" ]] || continue name="$(cat "$entry/name" 2>/dev/null || true)" case "$name" in hci*) ;; *) continue ;; esac # Writing the sysfs node rather than shelling out to `rfkill`: that binary # is not on a minimal image, and this is one byte. if [[ "$(cat "$entry/soft" 2>/dev/null || echo 0)" == "1" ]]; then printf '0' | $SUDO tee "$entry/soft" >/dev/null 2>&1 || true fi [[ "$(cat "$entry/soft" 2>/dev/null || echo 1)" == "0" ]] && unblocked=1 if [[ "$(cat "$entry/hard" 2>/dev/null || echo 0)" == "1" ]]; then warn "This board's Bluetooth is blocked by a hardware switch, so the hub cannot pair a brand-new Matter accessory. Accessories already on your network still pair normally." return 0 fi done [[ -n "$unblocked" ]] || return 0 # `rfkill unblock` does not survive a reboot on its own. systemd-rfkill # restores the state it saw at shutdown, so unblocking now and letting it # save is the persistence — but only where it is enabled, so ask for it. $SUDO systemctl enable systemd-rfkill >/dev/null 2>&1 || true $SUDO systemctl enable bluetooth >/dev/null 2>&1 || true if $SUDO systemctl start bluetooth >/dev/null 2>&1; then say "Bluetooth is on, so the hub can pair a Matter accessory straight out of its box." else warn "Bluetooth would not start, so the hub can only pair Matter accessories that are already on your network. 'systemctl status bluetooth' says why." fi } # ── The Wi-Fi the hub passes on ──────────────────────────────────────────── # The other half of the above: taking an accessory on over Bluetooth means # handing it a network, and the hub cannot read the root-owned profile the # password lives in. deploy/wifi-credentials.sh says why this is a file the hub # is *given*. The dispatcher is what keeps it true — a home that retypes its # Wi-Fi password next month gets a fresh profile, and enumerating today's # profiles is exactly what cannot cover that. share_wifi_for_matter() { local helper="${GETHOME_WIFI_CREDS_BIN:-/usr/local/lib/gethome-wifi-credentials.sh}" local dispatcher="${GETHOME_WIFI_CREDS_DISPATCHER:-/etc/NetworkManager/dispatcher.d/52-gethome-wifi-credentials}" $SUDO install -m 0755 "$HUB_DIR/deploy/wifi-credentials.sh" "$helper" 2>/dev/null || { warn "Could not install the Wi-Fi helper, so the hub will ask for your Wi-Fi password when you pair a Matter accessory." return 0 } if command -v nmcli >/dev/null 2>&1; then $SUDO mkdir -p "$(dirname "$dispatcher")" 2>/dev/null || true # NM ignores a dispatcher script anybody but root can write, so the # ownership and the mode are part of the fix, exactly as for the power-save # one above. if $SUDO tee "$dispatcher" >/dev/null </dev/null || true $SUDO chmod 0755 "$dispatcher" 2>/dev/null || true fi fi # And once now, so pairing works on a hub nobody reconnects. $SUDO env GETHOME_GROUP="$SERVICE_USER" "$helper" --conf "$CONF_DIR" || true } # ── The hub's own Wi-Fi profile, kept where a power cut cannot empty it ──── # **A hub that loses its Wi-Fi profile is a hub nobody can reach to fix it.** # On 2026-10-12 one was unplugged seconds after it was switched on, while # NetworkManager was saving its profiles, and both were left at 0 bytes: every # boot after that came up healthy and off the network, with no Wi-Fi profile at # all, until the card was taken to another computer. Raspberry Pi OS Trixie's # NetworkManager keeps the profile Imager set up as netplan YAML and writes it # back in place, with no temporary file and no fsync — deploy/wifi-profile.sh # says what that costs. # So the hub keeps its own copy of the profile it last connected with, taken by # a dispatcher whenever a connection comes up (atomically, fsynced, root-only, # and only when it changed), and a oneshot puts it back at boot when # NetworkManager no longer holds that profile and the hub is not on the network # another way — whether or not it holds others, since the hub can be told about # more than one network (manage_wifi_networks, below). It never edits a profile # that exists, so whatever the owner has changed stands, and becomes the copy # the next time it connects. # # Installed wherever NetworkManager is, a wired hub included: the dispatcher # keeps nothing until a Wi-Fi connection comes up, the oneshot does not run # without a copy (`ConditionPathExists`), and a hub moved to Wi-Fi later is # covered from its first connection rather than from its next update. keep_wifi_profile() { local helper="${GETHOME_WIFI_PROFILE_BIN:-/usr/local/lib/gethome-wifi-profile.sh}" local dispatcher="${GETHOME_WIFI_PROFILE_DISPATCHER:-/etc/NetworkManager/dispatcher.d/53-gethome-wifi-profile}" local unit="${GETHOME_WIFI_RESTORE_UNIT:-/etc/systemd/system/gethome-wifi-restore.service}" # A machine without NetworkManager keeps its Wi-Fi elsewhere, written by # something else: nothing to do and nothing to say. command -v nmcli >/dev/null 2>&1 || return 0 if ! $SUDO install -m 0755 "$HUB_DIR/deploy/wifi-profile.sh" "$helper" 2>/dev/null; then warn "Could not install the Wi-Fi profile helper, so a power cut at the wrong moment could still leave this hub off the network until its SD card is repaired on another computer." return 0 fi $SUDO mkdir -p "$(dirname "$dispatcher")" 2>/dev/null || true # NM ignores a dispatcher script anybody but root can write, so the # ownership and the mode are part of the fix, as for the two above. if $SUDO tee "$dispatcher" >/dev/null </dev/null || true $SUDO chmod 0755 "$dispatcher" 2>/dev/null || true fi # After NetworkManager, and not `Wants=` it: a machine where somebody has # turned NetworkManager off has its reasons, and this must not start it. # Not ordered before anything either — the hub does not wait for a network, # and the restored profile comes up on NetworkManager's own autoconnect. if $SUDO tee "$unit" >/dev/null </dev/null 2>&1 || true # Enabled and not started: it is for the next boot, and there is nothing # to put back on a machine that is running this installer over a network. $SUDO systemctl enable gethome-wifi-restore >/dev/null 2>&1 || true fi # And once now, so a hub nobody reconnects is covered from tonight. $SUDO "$helper" backup --conf "$CONF_DIR" || true } # ── IPv6, which is the network Matter actually runs on ───────────────────── # **Matter is IPv6, and on one Wi-Fi the link-local address is all it needs** — # no IPv6 from the internet provider, no DHCPv6. What more it needs is for one # kind of accessory: a **Thread** one lives behind a border router (an Apple TV # or HomePod, a Google Nest hub, …), and the border router tells the LAN how to # reach its Thread network with a Route Information Option in its router # advertisements. The kernel ignores those unless it is told to take prefixes # up to /64 — `accept_ra_rt_info_max_plen`, which is 0 by default everywhere # (matter.js's and OpenThread's own troubleshooting pages both lead with it) — # so without this a Thread accessory shared into GetHome from Apple Home or # Google Home pairs through the phone and is then never heard from again. # # **Routes and nothing else**: no address, no listener, no forwarding, so the # rule that the API answers on IPv4 only (`BIND_ADDRESS`, `mdns/advertiser.ts`) # is untouched. `default` covers an interface that appears after boot applied # this, and each physical interface is named as well, because systemd re-applies # a per-interface key when that interface appears and `default` alone is too # late for one that already existed. A NetworkManager profile with # `ipv6.method=auto` handles advertisements itself and learns these routes on # its own; Raspberry Pi OS's Imager writes `ignore`, which leaves them to the # kernel — the case this is for. matter_ipv6() { local conf="${GETHOME_SYSCTL_MATTER:-/etc/sysctl.d/61-gethome-matter.conf}" local proc="${GETHOME_PROC_IPV6:-/proc/sys/net/ipv6/conf}" local net_dir="${GETHOME_NET_DIR:-/sys/class/net}" local helper="${GETHOME_MATTER_IPV6_BIN:-/usr/local/lib/gethome-matter-ipv6.sh}" local dispatcher="${GETHOME_MATTER_IPV6_DISPATCHER:-/etc/NetworkManager/dispatcher.d/51-gethome-matter-ipv6}" local body entry iface lan # No IPv6 at all is the one thing Matter cannot work around. if [[ ! -d "$proc" ]]; then warn "IPv6 is switched off on this machine, and Matter runs on IPv6, so the hub cannot pair or control Matter accessories. Zigbee is unaffected." return 0 fi if [[ ! -e "$proc/default/accept_ra_rt_info_max_plen" ]]; then warn "This kernel cannot learn routes from IPv6 router advertisements, so a Matter accessory on Thread behind a border router, such as an Apple TV or HomePod, will not be reachable from the hub. Wi-Fi Matter accessories are unaffected." return 0 fi body="net.ipv6.conf.default.accept_ra_rt_info_max_plen = 64" for entry in "$net_dir"/*; do iface="${entry##*/}" [[ -e "$net_dir/$iface/device" && -e "$proc/$iface/accept_ra_rt_info_max_plen" ]] || continue body+=$'\n'"net.ipv6.conf.${iface}.accept_ra_rt_info_max_plen = 64" done if printf '# Installed by GetHome: routes to Thread networks. deploy/install.sh (matter_ipv6) says why.\n%s\n' "$body" \ | $SUDO tee "$conf" >/dev/null 2>&1; then # And now, rather than at the next boot. for entry in "$proc"/*/accept_ra_rt_info_max_plen; do printf '64' | $SUDO tee "$entry" >/dev/null 2>&1 || true done say "The hub will learn routes to Thread networks from your border routers, so Matter accessories on Thread can be reached." fi # Forwarding quietly undoes it: with it on the kernel ignores advertisements # unless `accept_ra` is 2, and stops probing whether a border router that has # gone away is still there — matter.js documents outages of half an hour. if [[ "$(cat "$proc/all/forwarding" 2>/dev/null || echo 0)" == "1" ]]; then warn "IPv6 forwarding is on here, which stops this machine learning routes to Thread accessories and noticing when a border router goes away, so Matter over Thread may be unreliable until it is off (net.ipv6.conf.all.forwarding=0)." fi # **NetworkManager switches IPv6 off by itself, and leaves it off.** A # connection that says `ipv6.method=ignore`, which is what Raspberry Pi # Imager's Wi-Fi profile says, can come back up with IPv6 disabled on its # interface after the network has gone away and returned, and stays that way # until NetworkManager restarts; deploy/matter-ipv6.sh says exactly when. So a # dispatcher puts the kernel's IPv6 back every time a connection comes up. # Installed wherever NetworkManager is, a wired hub included, because it acts # only on a connection that leaves IPv6 to the kernel. NetworkManager ignores # a dispatcher script anybody but root can write, so the ownership and the # mode are part of it, as for the Wi-Fi ones. if $SUDO install -m 0755 "$HUB_DIR/deploy/matter-ipv6.sh" "$helper" 2>/dev/null \ && command -v nmcli >/dev/null 2>&1; then $SUDO mkdir -p "$(dirname "$dispatcher")" 2>/dev/null || true if $SUDO tee "$dispatcher" >/dev/null </dev/null || true $SUDO chmod 0755 "$dispatcher" 2>/dev/null || true fi fi # And a LAN interface with IPv6 disabled has no link-local address, which is # what Matter is built on: an accessory that also answers on IPv4 is still # reached that way, but one that is only on IPv6, which every Thread accessory # is, is not. Turned back on now when it is NetworkManager's doing, so a hub # this already happened to is not left waiting for its next reconnect; said # when it is not ours to change. lan="$(ip -o route show default 2>/dev/null \ | awk '{ for (i = 1; i < NF; i++) if ($i == "dev") { print $(i + 1); exit } }' || true)" if [[ -n "$lan" && "$(cat "$proc/$lan/disable_ipv6" 2>/dev/null || echo 0)" == "1" ]]; then if [[ -x "$helper" ]]; then $SUDO "$helper" "$lan" --quiet >/dev/null 2>&1 || true; fi if [[ "$(cat "$proc/$lan/disable_ipv6" 2>/dev/null || echo 0)" == "1" ]]; then warn "IPv6 is disabled on ${lan}, so the hub has no IPv6 link-local address there and cannot reach a Matter accessory that is only on IPv6, which every Thread accessory is, until it is turned back on." else say "IPv6 was off on ${lan}, which NetworkManager leaves that way after some reconnects, and is back on, so Matter accessories can be reached over IPv6 again." fi fi } matter_bluetooth share_wifi_for_matter keep_wifi_profile matter_ipv6 # ── mDNS ─────────────────────────────────────────────────────────────────── # avahi answers for this machine's own name; the hub hands it the # `_gethome._tcp` service rather than running a second responder of its own. # Two responders on one host is a name conflict, and the loser renames itself — # which is why a Pi would answer to raspberrypi.local right after an install # and stop answering after a power cut. # # avahi reads exactly one config file — there is no conf.d — so these are # edited in place, idempotently, with the original kept alongside. AVAHI_CONF=/etc/avahi/avahi-daemon.conf if [[ -f "$AVAHI_CONF" ]]; then [[ -f "${AVAHI_CONF}.pre-gethome" ]] || $SUDO cp "$AVAHI_CONF" "${AVAHI_CONF}.pre-gethome" # Set `key=value` inside `[section]`: replace the line if it is there in any # form (including commented out, which is how Debian ships most of them), # otherwise append it to the section. avahi_set() { $SUDO awk -v section="[$1]" -v key="$2" -v value="$3" ' BEGIN { in_section = 0; done = 0 } /^\[/ { if (in_section && !done) { print key "=" value; done = 1 } in_section = ($0 == section) } { if (in_section && $0 ~ "^[#;[:space:]]*" key "[[:space:]]*=") { if (!done) { print key "=" value; done = 1 } next } print } END { if (in_section && !done) print key "=" value } ' "$AVAHI_CONF" > /tmp/avahi-daemon.conf.gethome && $SUDO cp /tmp/avahi-daemon.conf.gethome "$AVAHI_CONF" rm -f /tmp/avahi-daemon.conf.gethome } # `raspberrypi.local` has to resolve to an address a phone can actually # reach. If Docker is ever installed here for something else, avahi would # otherwise also publish docker0's 172.17.0.1 and clients take whichever # answer arrives first. avahi_set server deny-interfaces docker0 # The same rule one step further, applied to an address family instead of an # interface. The hub's API binds 0.0.0.0, so the board's IPv6 link-local # answers nothing on port 8420 — and it is the answer a client usually gets # *first*, which is why both apps had to learn to ask for IPv4 before they # could reach a hub sitting next to them. avahi answers an IPv4 lookup with # AAAA records by default; this stops it, and the service file the hub writes # announces over IPv4 only. # # That is as far as it goes, which was measured rather than assumed: a client # asking over the IPv6 transport still gets the board's link-local AAAA, # because that is `use-ipv6`'s business. Turning *that* off is a protocol # family switched off system-wide on somebody's own machine and is # deliberately not done here. Matter is untouched either way: matter.js runs # its own responder, and the IPv6 it needs is its own. avahi_set publish publish-aaaa-on-ipv4 no # GetHome Studio finds Raspberry Pis by browsing _workstation._tcp: Debian # publishes no _ssh._tcp record, so on a stock Pi this is the announcement # that makes the machine findable at all. avahi_set publish publish-workstation yes fi # The hub publishes `_gethome._tcp` by dropping a service file here rather than # running a second mDNS responder of its own. avahi watches the directory, so # there is nothing to reload. $SUDO mkdir -p /etc/avahi/services $SUDO chgrp "$SERVICE_USER" /etc/avahi/services 2>/dev/null || true $SUDO chmod 0775 /etc/avahi/services $SUDO systemctl enable avahi-daemon >/dev/null 2>&1 || true $SUDO systemctl restart avahi-daemon >/dev/null 2>&1 || true # ── Zigbee ───────────────────────────────────────────────────────────────── # Zigbee is optional: Matter and Wi-Fi devices work without it. So nothing here # is ever fatal unless the user named an adapter explicitly and got it wrong. step zigbee "Setting up Zigbee…" if [[ ! -x "$Z2M_DIR/node_modules/.bin/zigbee2mqtt" ]]; then say "Installing Zigbee2MQTT…" $SUDO mkdir -p "$Z2M_DIR" # From npm, where it ships already built. The alternative — cloning the # repository and compiling its TypeScript — is the same twenty-minute, # several-hundred-megabyte problem we just took out of the hub's own install. ( cd "$Z2M_DIR" && $SUDO env PATH="$(dirname "$NODE_BIN"):$PATH" "$NPM_BIN" install --omit=dev --no-audit --no-fund --silent \ --prefix "$Z2M_DIR" "zigbee2mqtt@${Z2M_VERSION}" ) >/dev/null 2>&1 \ || warn "Zigbee2MQTT didn't install. Everything else works — Matter and Wi-Fi devices are unaffected. Run the install again to retry." fi $SUDO chown -R "$SERVICE_USER:$SERVICE_USER" "$Z2M_DATA_DIR" # ── Zigbee2MQTT must not wait for a browser ──────────────────────────────── # Zigbee2MQTT 2.x runs an *onboarding* wizard on a web page and does not bring # the Zigbee stack up at all until somebody finishes it. On a hub that is # nobody's business to configure by hand — the serial port and the broker are # both supplied as environment overrides — that is a service which starts, # stays "active (running)", never touches the coordinator, and reports nothing # wrong. Observed exactly that: a correctly identified SONOFF dongle, the right # path in the config, `zigbee.connected: false` forever, and one line in the # journal offering a setup page on port 8080. # # `ZIGBEE2MQTT_CONFIG_ONBOARDING=false` is set on the unit as well, but it # cannot be the whole answer: upstream ignores that variable when there is no # configuration.yaml yet, which is precisely the fresh-install case. So the # file gets the setting too. # # **This is the one thing written into configuration.yaml, and it is surgical # on purpose.** That file holds the network key and the paired-device list; # rewriting it would lose somebody's whole Zigbee network. Creating it when it # is absent, or replacing one `onboarding:` line when it is present, does # neither. # ── Zigbee and Wi-Fi are the same band, and the default puts them on top ─── # 802.15.4 channels 11–26 sit 5 MHz apart from 2405 MHz and are 2 MHz wide; a # 20 MHz Wi-Fi channel covers its centre ±11 MHz. So several Zigbee channels # fall *inside* every Wi-Fi channel, and Zigbee2MQTT's default — 11, at # 2405 MHz — is inside Wi-Fi channel 1, which is the commonest Wi-Fi channel # there is. On this hardware the two radios are centimetres apart: the # coordinator hangs off the Pi's USB socket and the Wi-Fi antenna is printed on # the board beside it. # # What that costs is **retries and throughput, in proportion to how busy the # Zigbee side is**, and it is worth being exact about the size of it: a Zigbee # frame is tens of bytes at 250 kbit/s, so a quiet home is a fraction of a # percent of the air and costs almost nothing. It is a standing handicap on the # Wi-Fi rather than an outage — the thing to reach for when a hub is slow or # lossy, not when it disappears completely, which is a link that is down or a # path that is broken and wants looking for elsewhere. The reason to avoid it # anyway is that it is free to avoid at install time and expensive afterwards. # # So the channel is picked at the only moment it can be picked: when this hub # has never formed a network. Changing it afterwards is not an upgrade — it is # a home whose sleepy devices all have to be paired again — so a hub that # already has a network keeps the channel it formed on, whatever the Wi-Fi # under it has done since. # The other half of that decision, for a hub that already has a network. The # channel is not ours to move there — but it is ours to *name*, because nothing # else in the system ever will: Zigbee is connected, the devices report, and # what suffers is the other radio. Said as a standing handicap, never as a # diagnosis — see the sizing above. # # Both files are read as the hub's account, for the reasons the config section # below gives. zigbee_network_channel() { local channel="" channel="$(read_hub_file "$Z2M_DATA_DIR/coordinator_backup.json" \ | grep -o '"logical_channel"[[:space:]]*:[[:space:]]*[0-9]*' \ | head -n1 | grep -o '[0-9]*$' || true)" if [[ -z "$channel" ]]; then channel="$(read_hub_file "$Z2M_CONFIG" \ | sed -n 's/^[[:space:]]*channel:[[:space:]]*\([0-9][0-9]*\).*/\1/p' \ | head -n1 || true)" fi printf '%s' "$channel" } # **Said once, not on every update.** This runs from `install.sh`, and # `gethome-hubctl update` *is* `install.sh` — so a warning here is a warning the # owner meets every single time they update, for ever. It travels, too: # `update-runner.sh` collects `@@WARN@@` into `status.json`, the hub serves it, # and the iOS app draws it on the update checklist. Ninety words about radio # physics, on every update, about a hub that is working — and about the one # thing the owner cannot act on without re-pairing their battery devices. # # That is the shape of the noise `zigbee.problem` already refuses ("a wrong # diagnosis is worse than none, because the caller already has # `connected: false`") and the activity log's rule about a feed read a week # later. The message itself is true and worth hearing; hearing it eleven times # is what makes it worthless. # # So it is remembered, keyed on the **pair** — which Zigbee channel against # which Wi-Fi frequency. If either moves the situation is genuinely different # and it is said again, because it may have become worse or gone away. This is # `zigbee.env`'s idiom: a small file that is the memory of something that has # already been decided. zigbee_notice_file() { printf '%s' "${GETHOME_ZIGBEE_NOTICE:-$CONF_DIR/zigbee-channel-notice}"; } warn_if_zigbee_jams_wifi() { local wifi_mhz zigbee_channel zigbee_mhz gap clear notice pair told notice="$(zigbee_notice_file)" wifi_mhz="$(wifi_frequency_mhz)" zigbee_channel="$(zigbee_network_channel)" # No Wi-Fi to collide with, or no network yet: nothing to say either way, and # nothing learned — so the memory is left exactly as it is. [[ -n "$wifi_mhz" && -n "$zigbee_channel" ]] || return 0 (( zigbee_channel >= 11 && zigbee_channel <= 26 )) || return 0 zigbee_mhz=$((2405 + 5 * (zigbee_channel - 11))) if (( zigbee_mhz > wifi_mhz )); then gap=$((zigbee_mhz - wifi_mhz)); else gap=$((wifi_mhz - zigbee_mhz)); fi # A 20 MHz Wi-Fi channel is its centre ±11 MHz. Inside that, the coordinator # is transmitting into this hub's own uplink from a few centimetres away. if (( gap > 11 )); then # Positively clear of each other. Forget having said anything, so a # collision that appears later — a router moved to another channel, a # network re-formed — is announced afresh rather than swallowed by a # memory of the last one. $SUDO rm -f "$notice" 2>/dev/null || true return 0 fi pair="${zigbee_channel}:${wifi_mhz}" told="$($SUDO cat "$notice" 2>/dev/null || true)" # Already said, about exactly this pair. The situation has not changed and # neither has the advice, so there is nothing here the owner has not read. [[ "$told" == "$pair" ]] && return 0 $SUDO mkdir -p "$(dirname "$notice")" 2>/dev/null || true printf '%s\n' "$pair" | $SUDO tee "$notice" >/dev/null 2>&1 || true clear="$(zigbee_channel_clear_of_wifi "$wifi_mhz")" warn "This hub's Wi-Fi (${wifi_mhz} MHz) and its Zigbee network (channel ${zigbee_channel}, ${zigbee_mhz} MHz) are on the same frequency, and the two radios are a few centimetres apart. They share the air rather than take turns, so the Wi-Fi carries more retries and less throughput than it should — how much depends on how busy the Zigbee network is, and a quiet one costs little. Channel ${clear} is clear of this hub's Wi-Fi. It is not changed for you, and is worth changing only if something is actually wrong: the network re-forms, so mains-powered devices usually follow and battery ones usually have to be paired again." } zigbee_channel_clear_of_wifi() { local wifi_mhz="$1" best=25 best_gap=-1 channel gap mhz # Nothing to measure — a wired hub, or a radio that would not say. 25 is # still the better guess than 11: it is clear of Wi-Fi 1 and 6, which is most # homes, and 11 sits inside the first of them. # # **A hub on 5 GHz is that same case, not a 2.4 GHz channel a long way off.** # Measured from 5180 MHz, "furthest away" is channel 11 — inside Wi-Fi 1, the # channel the home's own 2.4 GHz radio is most often on — so a dual-band # board would have formed its network in the worst place there is. Its uplink # is clear of Zigbee either way; the rest of the house's 2.4 GHz is not. if [[ -z "$wifi_mhz" ]] || (( wifi_mhz < 2400 || wifi_mhz > 2500 )); then printf '25' return 0 fi # 26 is left out on purpose: several regions cap its transmit power and some # devices will not join on it at all. for channel in $(seq 11 25); do mhz=$((2405 + 5 * (channel - 11))) if (( mhz > wifi_mhz )); then gap=$((mhz - wifi_mhz)); else gap=$((wifi_mhz - mhz)); fi if (( gap > best_gap )); then best_gap=$gap; best=$channel; fi done printf '%s' "$best" } # ── configuration.yaml is touched only as the hub's account ──────────────── # **Doing it as root was two bugs, and the second could cost a network.** The # directory is the hub account's, so every name in it is whatever the account # made it, and root writing `configuration.yaml` followed a link planted there: # `tee` wrote where it pointed and the `chown` after it handed the target to the # account — a file of its choosing anywhere on the machine, made its own. # # And the checks that decide *whether* to write ran as whoever ran the # installer, which for `curl … | bash` and for `gethome-hubctl update` without # sudo is the login user. By this point "Accounts and directories" has made # /var/lib/gethome 0750 — systemd's `StateDirectory=` puts it back to 0755 only # when the hub restarts, further down — so that user saw no configuration.yaml # and no coordinator backup, took the hub for one that had never formed a # network, and wrote a fresh three-line file over a working one — its network # key, its PAN IDs and its channel, gone. Measured on a Zero 2 W: with # /var/lib/gethome at 0750, `pi` sees neither file. # # As the account, the checks see what is there and a planted link reaches only # what the account could reach already. Creating is create-only (`set -C`), so # no check that is wrong can ever replace a file that exists. And an edit is the # whole file written beside the old one with the old one's mode (`cp -p`), # flushed, and renamed over it — read in full first, so a read that fails part # way is never what gets written back — so a power cut leaves the old file or # the new one, never half of the file the key is in. Z2M_CONFIG="$Z2M_DATA_DIR/configuration.yaml" Z2M_ONBOARDING_CHANGED="" z2m_onboarding_off() { local current updated channel="" if ! as_service_user test -e "$Z2M_CONFIG" 2>/dev/null; then # A backup means a network exists even with the config gone, and its channel # is not ours to move. if as_service_user test -f "$Z2M_DATA_DIR/coordinator_backup.json" 2>/dev/null; then updated=$'onboarding: false\n' else channel="$(zigbee_channel_clear_of_wifi "$(wifi_frequency_mhz)")" updated=$'onboarding: false\nadvanced:\n channel: '"${channel}"$'\n' fi printf '%s' "$updated" \ | as_service_user sh -c 'set -C; cat > "$1"' sh "$Z2M_CONFIG" 2>/dev/null || return 0 [[ -z "$channel" ]] || say "Zigbee will form its network on channel ${channel}, clear of this hub's Wi-Fi." Z2M_ONBOARDING_CHANGED=1 return 0 fi current="$(read_hub_file "$Z2M_CONFIG")" || return 0 if grep -qE '^onboarding:[[:space:]]*true' <<<"$current"; then updated="$(sed 's/^onboarding:[[:space:]]*true.*/onboarding: false/' <<<"$current")" elif ! grep -qE '^onboarding:' <<<"$current"; then updated="$current" [[ -z "$updated" ]] || updated+=$'\n' updated+='onboarding: false' else return 0 fi replace_z2m_config "$updated" && Z2M_ONBOARDING_CHANGED=1 return 0 } replace_z2m_config() { local tmp="${Z2M_CONFIG}.gethome-$$" if as_service_user cp -p "$Z2M_CONFIG" "$tmp" 2>/dev/null \ && printf '%s\n' "$1" | as_service_user tee "$tmp" >/dev/null 2>&1 \ && { as_service_user sync "$tmp" 2>/dev/null || sync; } \ && as_service_user mv -f "$tmp" "$Z2M_CONFIG" 2>/dev/null; then return 0 fi as_service_user rm -f "$tmp" 2>/dev/null || true return 1 } z2m_onboarding_off # A running Z2M read the old file at startup, and the detector below only # restarts it when the *device path* changed — so without this an existing hub # would keep waiting for its browser until the next reboot. if [[ -n "$Z2M_ONBOARDING_CHANGED" ]] && command -v systemctl >/dev/null 2>&1 \ && $SUDO systemctl is-active --quiet gethome-zigbee2mqtt.service 2>/dev/null; then say "Zigbee2MQTT was waiting on its setup page; turning that off and restarting it." $SUDO systemctl restart gethome-zigbee2mqtt.service >/dev/null 2>&1 || true fi # The detector is the authority on what counts as a coordinator, and it is what # starts and stops Zigbee2MQTT — at boot and whenever something is plugged in # or unplugged. Installing it unconditionally is what makes buying a stick next # month just work, with no second visit to the installer. $SUDO install -m 0755 "$HUB_DIR/deploy/zigbee-detect.sh" /usr/local/lib/gethome-zigbee-detect.sh 2>/dev/null \ || warn "Could not install the Zigbee detector; plugging a coordinator in later won't configure itself." $SUDO tee /etc/systemd/system/gethome-zigbee-detect.service >/dev/null </dev/null <<'RULE' SUBSYSTEM=="tty", ACTION=="add", ENV{ID_BUS}=="usb", TAG+="systemd", ENV{SYSTEMD_WANTS}="gethome-zigbee-detect.service" SUBSYSTEM=="tty", ACTION=="remove", ENV{ID_BUS}=="usb", TAG+="systemd", ENV{SYSTEMD_WANTS}="gethome-zigbee-detect.service" RULE $SUDO udevadm control --reload-rules >/dev/null 2>&1 || true if [[ -n "$ZIGBEE_ADAPTER" ]]; then # Explicitly named by the user (or by GetHome Studio, which detected it) — # a wrong path here is worth stopping for. [[ -e "$ZIGBEE_ADAPTER" ]] || fail "Zigbee adapter $ZIGBEE_ADAPTER not found on this machine (check: ls /dev/serial/by-id/)." # Pinned, so the detector stops guessing on this machine and keeps using it. # This is how a generic CP210x bridge — which the detector will never adopt # on its own — gets used once a human has said it is a Zigbee stick. printf 'GETHOME_ZIGBEE_PINNED=%s\n' "$ZIGBEE_ADAPTER" | $SUDO tee "$CONF_DIR/zigbee.env" >/dev/null printf '@@ZIGBEE_FOUND:%s@@\n' "$ZIGBEE_ADAPTER" fi # ── Configuration and services ───────────────────────────────────────────── step start "Starting the hub…" if [[ ! -f "$CONF_DIR/hub.env" ]]; then $SUDO tee "$CONF_DIR/hub.env" >/dev/null </radio-mode and is applied # by gethome-zigbee-detect, which is the only thing that knows whether a # coordinator is actually plugged in. GETHOME_RADIO=${RADIO_BUDGET} # Matter. Managed by gethome-zigbee-detect on a one-radio board — editing it by # hand there will be overwritten the next time something is plugged in. Switch # radios from the GetHome app instead. ADAPTER_MATTER=1 ENV fi # **A budget is a measurement of the machine, and the machine can change under # it.** `hub.env` is written only when it is absent, which is right for # everything else in it — those are settings, and an upgrade must not stamp on # them. `GETHOME_RADIO` and the heap are not settings: they are what this # script measured from the RAM it found, and the commonest way somebody grows # a GetHome home is to move the SD card into a bigger Pi. That carries # `/etc/gethome/hub.env` with it, so a card that started life in a Zero 2 W # went on telling a Pi 5 it had memory for one radio — for ever, because # re-running this installer does not rewrite an existing file either. The # upgrade path this project recommends in its own README ended on a board that # still recommended one radio, still drew the picker, and still let the hub # stand a radio down with gigabytes free. # # **It only ever widens.** A stored `one` on a board that now measures `both` # is a stale measurement and is corrected; a stored `both` is left alone # whatever this board measures, because that is the documented hand-edit (see # `deploy/CLAUDE.md`) and the owner's own override — and `radio-pressure.ts` # is already watching a board running two radios it was not measured for. So # this can remove a restriction and can never add one. if [[ -f "$CONF_DIR/hub.env" ]]; then STORED_RADIO=$(sed -n 's/^GETHOME_RADIO=//p' "$CONF_DIR/hub.env" | tail -n1) if [[ "$STORED_RADIO" == "one" && "$RADIO_BUDGET" == "both" ]]; then # A temporary file rather than `sed -i`, which takes the next argument as a # backup suffix on BSD and is the portability trap this repo has already # paid for once. HUB_ENV_NEW=$(mktemp) sed 's/^GETHOME_RADIO=one$/GETHOME_RADIO=both/' "$CONF_DIR/hub.env" > "$HUB_ENV_NEW" \ && $SUDO cp "$HUB_ENV_NEW" "$CONF_DIR/hub.env" rm -f "$HUB_ENV_NEW" # The heap travels with it for the same reason: 160 MB was this board's # predecessor's number, and nothing else would ever revisit it. if grep -q '^NODE_OPTIONS=--max-old-space-size=' "$CONF_DIR/hub.env"; then HUB_ENV_NEW=$(mktemp) sed "s/^NODE_OPTIONS=--max-old-space-size=.*/NODE_OPTIONS=--max-old-space-size=${HUB_HEAP_MB}/" \ "$CONF_DIR/hub.env" > "$HUB_ENV_NEW" \ && $SUDO cp "$HUB_ENV_NEW" "$CONF_DIR/hub.env" rm -f "$HUB_ENV_NEW" fi say "This Pi has more memory than the one this hub was first set up on, so it is no longer held to one radio at a time: ${RAM_MB} MB runs Zigbee and Matter together. Nothing else about the hub changed." fi fi $SUDO tee /etc/systemd/system/gethome-hubd.service >/dev/null </dev/null </dev/null || true # Switching radios from the app, without giving the hub root. The hub writes # one word to a file in its own data directory — which it already owns — and # this wakes the detector, which is where the decision lives anyway. No sudo # rule, no systemctl from the service user, nothing new to lock down. $SUDO tee /etc/systemd/system/gethome-radio.path >/dev/null </dev/null \ || warn "Could not install the update runner; this hub won't be able to update itself from an app." $SUDO tee /etc/systemd/system/gethome-update.path >/dev/null </dev/null </update. The runner is root and does its file I/O # in that directory as this account, so a link the account planted there is one # root never follows — see as_hub in update-runner.sh. Environment=GETHOME_USER=${SERVICE_USER} Environment=GETHOME_GROUP=${SERVICE_USER} ExecStart=/usr/local/lib/gethome-update.sh # Not a number, and not the 90-second default a Type=oneshot otherwise gets. # A real run is apt, a bundle over a domestic line, migrations onto an SD card, # up to four minutes of health check and up to another minute waiting on Zigbee # — and a source build, which a board over 1 GB is still allowed to do, is # twenty minutes on its own. What makes a timeout here dangerous rather than # merely annoying is *where* it would land: most likely after the symlink has # been flipped to the new build and before the health check that would have # rolled it back, killing the only thing that could undo it. TimeoutStartSec=infinity UNIT # What the hub reads to know this machine can apply an update at all. A file in # the hub's own directory rather than a systemd path it would have to know # about: the hub stays portable, and this is written in the same breath as the # units, so it cannot promise plumbing that was never installed. $SUDO chown -R "$SERVICE_USER:$SERVICE_USER" "${DATA_DIR}/update" 2>/dev/null || true as_service_user touch "${DATA_DIR}/update/enabled" 2>/dev/null || true # ── The Wi-Fi networks the hub knows, changed from an app ────────────────── # So a hub set up on one network can be told about another before it is carried # there. Same shape as the update: the hub writes a request into its own data # directory, the path unit notices, and the root script applies it with nmcli. # deploy/wifi-networks.sh says what it refuses and why. # # NetworkManager or nothing: it is what every current Raspberry Pi OS manages # Wi-Fi with, and a machine without it (Bullseye's wpa_supplicant, Ubuntu's # netplan, a wired box) gets no units and a one-word reason the hub passes on, # so an app says why rather than offering a form that can only fail. The # reason file and the capability are written in the same breath as the units, # for the reason `update/enabled` is: `hub.env` never reaches an upgraded hub. manage_wifi_networks() { local helper="${GETHOME_WIFI_NETWORKS_BIN:-/usr/local/lib/gethome-wifi-networks.sh}" local dispatcher="${GETHOME_WIFI_NETWORKS_DISPATCHER:-/etc/NetworkManager/dispatcher.d/54-gethome-wifi-networks}" local wifi_dir="${DATA_DIR}/wifi" # 54, because the profile copy (keep_wifi_profile) has 53. This dispatcher # was 53 on its branch before that landed, so a hub that tried the branch has # it under the old name too, and would run it twice on every association. $SUDO rm -f "$(dirname "$dispatcher")/53-gethome-wifi-networks" 2>/dev/null || true # Everything inside the directory as the hub's account (`as_service_user`). as_service_user mkdir -p "$wifi_dir" 2>/dev/null || true as_service_user rm -f "$wifi_dir/enabled" "$wifi_dir/unsupported" 2>/dev/null || true # Installed is not running: nmcli can be on a machine whose Wi-Fi something # else manages (dhcpcd, on an older Raspberry Pi OS), and there every change # would fail with "NetworkManager is not running" behind a form the app had # offered. `general status` answers only when the daemon does. if ! command -v nmcli >/dev/null 2>&1 || ! $SUDO nmcli -t general status >/dev/null 2>&1; then printf 'no-networkmanager\n' | as_service_user tee "$wifi_dir/unsupported" >/dev/null 2>&1 || true return 0 fi if ! $SUDO install -m 0755 "$HUB_DIR/deploy/wifi-networks.sh" "$helper" 2>/dev/null; then warn "Could not install the Wi-Fi helper, so this hub's Wi-Fi networks can't be changed from an app." return 0 fi $SUDO tee /etc/systemd/system/gethome-wifi.path >/dev/null </dev/null </dev/null || true if $SUDO tee "$dispatcher" >/dev/null </dev/null || true $SUDO chmod 0755 "$dispatcher" 2>/dev/null || true fi # A hub installed by an earlier build may hold files root made here; `chown -R` # hands them back without following anything (see `as_service_user`). $SUDO chown -R "$SERVICE_USER:$SERVICE_USER" "$wifi_dir" 2>/dev/null || true as_service_user touch "$wifi_dir/enabled" 2>/dev/null || true as_service_user chmod 0750 "$wifi_dir" 2>/dev/null || true # Once now, so the list is there before anybody reconnects. $SUDO env GETHOME_CONF="$CONF_DIR" GETHOME_USER="$SERVICE_USER" GETHOME_GROUP="$SERVICE_USER" "$helper" --list --quiet || true WIFI_NETWORKS_UNITS=1 } WIFI_NETWORKS_UNITS="" manage_wifi_networks $SUDO systemctl daemon-reload $SUDO systemctl enable gethome-hubd.service >/dev/null 2>&1 $SUDO systemctl enable gethome-zigbee-detect.service >/dev/null 2>&1 || true $SUDO systemctl enable --now gethome-radio.path >/dev/null 2>&1 || true $SUDO systemctl enable --now gethome-update.path >/dev/null 2>&1 || true if [[ -n "$WIFI_NETWORKS_UNITS" ]]; then $SUDO systemctl enable --now gethome-wifi.path >/dev/null 2>&1 || true fi # Zigbee2MQTT, when it is already running, is holding a broker connection that # was opened before any of this and may have been anonymous. Its unit has just # gained the credentials, so it needs restarting to pick them up — but only if # it is actually up: starting it here would hold ~150 MB open for a coordinator # that may not exist, which is exactly why `gethome-zigbee-detect` owns its # lifecycle and this unit is never enabled. if systemctl is-active --quiet gethome-zigbee2mqtt.service 2>/dev/null; then $SUDO systemctl restart gethome-zigbee2mqtt.service >/dev/null 2>&1 \ || warn "Zigbee2MQTT didn't restart after the broker credentials changed; Zigbee may be down." fi $SUDO systemctl restart gethome-hubd.service \ || fail "The hub is installed but wouldn't start. See: journalctl -u gethome-hubd -n 50" # ── Autostart ────────────────────────────────────────────────────────────── step autostart "Setting the hub to start automatically on power-up…" AUTOSTART_OK=1 for unit in gethome-hubd.service mosquitto.service avahi-daemon.service; do if ! systemctl is-enabled "$unit" >/dev/null 2>&1; then AUTOSTART_OK="" warn "${unit} is not set to start at boot. Enable it with: sudo systemctl enable ${unit}" fi done [[ -n "$AUTOSTART_OK" ]] && say "The hub, the MQTT broker and mDNS all start with the Pi." # ── Health ───────────────────────────────────────────────────────────────── step health "Waiting for the hub to answer on port 8420…" # Generous, because the first start also runs the database migrations onto an # SD card. Costs nothing when it is healthy: the loop breaks on the first # success. HEALTHY="" DIED="" for attempt in $(seq 1 120); do if curl -fsS http://localhost:8420/api/v1/hub >/dev/null 2>&1; then HEALTHY=1; break; fi if ! systemctl is-active --quiet gethome-hubd.service; then sleep 2 if ! systemctl is-active --quiet gethome-hubd.service; then DIED=1; break; fi fi # Nothing else prints during this wait, and GetHome Studio shows the log as # it grows — so mark the time rather than let it look stalled. if [[ $((attempt % 15)) -eq 0 ]]; then say "Still waiting for the hub… ($((attempt * 2))s)"; fi sleep 2 done # ── If the new build doesn't answer, go back to the one that did ─────────── # This is the whole point of installing beside the running version rather than # over it. An update that breaks the hub on a machine nobody is sitting in # front of has to undo itself; leaving a Pi with a hub that won't start, # reachable only by SSH, is the failure that costs a person their evening. if [[ -z "$HEALTHY" ]]; then service_failure gethome-hubd if [[ -n "$PREVIOUS_RELEASE" && -d "$PREVIOUS_RELEASE" && "$PREVIOUS_RELEASE" != "$RELEASE_DIR" ]]; then printf '@@ROLLBACK:%s@@\n' "$(basename "$PREVIOUS_RELEASE")" say "Rolling back to the build that was running before…" $SUDO ln -sfn "$PREVIOUS_RELEASE" "${HUB_DIR}.new" $SUDO mv -T "${HUB_DIR}.new" "$HUB_DIR" $SUDO systemctl restart gethome-hubd.service || true for _ in $(seq 1 30); do curl -fsS http://localhost:8420/api/v1/hub >/dev/null 2>&1 && { HEALTHY=1; break; } sleep 2 done if [[ -n "$HEALTHY" ]]; then fail "Build ${BUILD_ID} wouldn't start, so the hub was put back on the previous build and is running again. Nothing was lost. The log above says why the new one failed." fi fi if [[ -n "$DIED" ]]; then fail "The hub started and then stopped. The log above says why; there is more in: journalctl -u gethome-hubd -n 50" fi fail "The hub is running but didn't answer on port 8420 within four minutes. The log above may say why; there is more in: journalctl -u gethome-hubd -n 50" fi INFO=$(curl -fsS http://localhost:8420/api/v1/hub) if echo "$INFO" | grep -q '"claimed":false'; then # Read as the hub's account, not by root through a path: pairing-code is a # name in the hub's own directory, so a link the account planted there (this # output lands in the hub-readable update log) is followed as that account # rather than turned into a read of any root-only file. CODE=$(as_service_user cat "$DATA_DIR/pairing-code" 2>/dev/null | tr -d '[:space:]' || true) if [[ -n "$CODE" ]]; then printf '@@PAIRING:%s@@\n' "$CODE" say "Pairing code: ${CODE}" echo "GetHome Studio claims the hub for you; this code is for other devices." fi fi # Now that the hub is up and the code is out, see whether there is a Zigbee # coordinator to bring up. It runs *here* because it is a confirmation rather # than a dependency: a working hub should not be held back from its owner by a # question about an accessory it doesn't need. # Two different facts, and conflating them is what let a dead radio be # announced as a working one: ZIGBEE_CONFIGURED means the detector found a # coordinator and gave the board to it, ZIGBEE_READY means Zigbee2MQTT is # actually talking to it. The first decides what to say about the *board*, the # second decides what to claim the hub can talk to. ZIGBEE_CONFIGURED="" ZIGBEE_READY="" if [[ -x /usr/local/lib/gethome-zigbee-detect.sh ]]; then if $SUDO env GETHOME_CONF="$CONF_DIR" /usr/local/lib/gethome-zigbee-detect.sh; then ZIGBEE_CONFIGURED=1 ZIGBEE_READY=1 fi fi # A third state, and neither of the two above. The detector exits non-zero when # Zigbee is not the radio here — which includes a board whose owner has *chosen* # Matter with a coordinator sitting in its socket. Without asking separately, # the install's closing line said "with no Zigbee coordinator plugged in", # four lines under the detector's own "A Zigbee coordinator is plugged in", on # one screen, about hardware the owner could see. Same read as the hub's, from # the same file: the recorded by-id name, and whether it is still there. ZIGBEE_STANDING_BY="" if [[ -z "$ZIGBEE_CONFIGURED" ]]; then zigbee_recorded=$(sed -n 's/^ZIGBEE_ADAPTER=//p' "$CONF_DIR/zigbee.env" 2>/dev/null | tail -n1) [[ -n "$zigbee_recorded" && -e "$zigbee_recorded" ]] && ZIGBEE_STANDING_BY=1 fi # A started service is not a working radio. The detector's success means "a # device node is there and I started the unit"; whether Zigbee2MQTT actually # reached the stick is a different question, and the hub already answers it — # `zigbee.connected` is Z2M's own bridge reporting itself online. # # Asking is what turns a silent failure into a sentence. A missing serial-port # override, a coordinator on the GPIO header with the UART still off, a stick # that needs its firmware flashed: all of them leave the unit running, the # install "successful", and the owner with a hub that pairs nothing. Z2M takes # a while to come up on this class of board, so give it a real minute before # concluding anything. if [[ -n "$ZIGBEE_READY" ]]; then say "Checking that Zigbee2MQTT reached the coordinator…" # Wait for the *hub* first, and don't count that time against Zigbee. # # The answer comes from the hub's API, and the detector a few lines up may # have just restarted the hub — that is what happens on a fresh install where # a coordinator takes the board from Matter, and on a Zero 2 W coming back is # over a minute. Polling straight away would spend the whole window on a # closed port and then blame the radio for a restart this script performed. HUB_NOW="" for _ in $(seq 1 40); do HUB_NOW=$(curl -fsS --max-time 5 http://localhost:8420/api/v1/hub 2>/dev/null || true) [[ -n "$HUB_NOW" ]] && break sleep 3 done ZIGBEE_LIVE="" if [[ -z "$HUB_NOW" ]]; then # Nothing to say about the radio: the thing that would answer the question # is itself not answering, and the health step above already covers a hub # that won't start. Saying "Zigbee isn't working" here would be a guess. warn "The hub isn't answering, so whether Zigbee reached its coordinator couldn't be checked. See: journalctl -u gethome-hubd -n 50" ZIGBEE_READY="" else # Now a full window of a *live* hub, however long the restart took. Z2M is # a second Node process starting on an SD card; a minute and a half is # patient without being an install that looks hung. for _ in $(seq 1 30); do case "$HUB_NOW" in *'"connected":true'*) ZIGBEE_LIVE=1; break ;; esac sleep 3 HUB_NOW=$(curl -fsS --max-time 5 http://localhost:8420/api/v1/hub 2>/dev/null || printf '%s' "$HUB_NOW") done if [[ -z "$ZIGBEE_LIVE" ]]; then # A warning, never a failure: the hub itself is fine, and the coordinator # stays configured, so this is something to fix rather than something that # undoes the install. # # And a *named* warning where we can manage it. "Check the journal" is # homework for somebody watching this from another machine, and the one # cause that is near-universal deserves better: a SONOFF ZBDongle-E ships # from the factory running EmberZNet 6.10 (EZSP v8), while Zigbee2MQTT's # ember driver needs EZSP 13 or newer — NCP firmware 7.4.x. So the very # first thing a new owner of the coordinator this project recommends sees # is a radio that answers and then refuses, once, until it is flashed. # # The message says what to do rather than quoting those numbers, and that # is deliberate: they are *protocol* versions, while the flasher shows # *firmware* versions and offers "6.10.3 → 8.0.2" for this very stick. # "Needs 13 or newer" beside an 8.0.2 makes the fix look wrong. The hub's # own `zigbee.problem` keeps the raw line for anyone who wants it. Z2M_TAIL=$($SUDO journalctl -u gethome-zigbee2mqtt -n 80 --no-pager 2>/dev/null || true) case "$Z2M_TAIL" in *"EZSP protocol version"*"is not supported by Host"*) warn "The Zigbee coordinator answered, but its firmware is too old for Zigbee2MQTT. SONOFF ZBDongle-E sticks ship this way, and updating one is a one-time job that needs no cable and no tools: unplug it, put it in a Mac or PC, open https://dongle.sonoff.tech/sonoff-dongle-flasher/ in Chrome or Edge (Safari cannot talk to USB devices), and flash the coordinator firmware it offers. Put it back and this hub picks it up on its own. Everything else here is unaffected." ;; *"No valid USB adapter found"*) warn "Zigbee2MQTT could not identify the coordinator on ${ZIGBEE_ADAPTER:-the configured port}. If this is a generic USB-serial stick, Zigbee2MQTT needs to be told what it is. See: journalctl -u gethome-zigbee2mqtt -n 50" ;; *) warn "Zigbee2MQTT started but hasn't reached the coordinator. The hub works; Zigbee devices won't pair until it does. Check: journalctl -u gethome-zigbee2mqtt -n 50" ;; esac ZIGBEE_READY="" fi fi fi # A Zigbee network that works perfectly can still be sitting on top of this # hub's own Wi-Fi, and nothing above would notice: the coordinator is reached, # the devices report, and the only casualty is the other radio. if [[ -n "$ZIGBEE_READY" ]]; then warn_if_zigbee_jams_wifi fi # What this hub can actually talk to, said in as many words. The radio decision # was made by the detector a few lines up, so read back what it settled on # rather than repeating what we guessed before the hardware was known. MATTER_ON=$(sed -n 's/^ADAPTER_MATTER=//p' "$CONF_DIR/hub.env" 2>/dev/null | tail -n1) CAPS="" [[ -n "$ZIGBEE_READY" ]] && CAPS="Zigbee" if [[ "$MATTER_ON" == "1" ]]; then [[ -n "$CAPS" ]] && CAPS="$CAPS, Matter" || CAPS="Matter" fi [[ -n "$CAPS" ]] && CAPS="$CAPS, Wi-Fi and MQTT" || CAPS="Wi-Fi and MQTT" # Additive marker: GetHome Studio shows this on the hub page. Unknown markers # are ignored by older builds, so adding one is safe. printf '@@CAPABILITIES:%s@@\n' "$CAPS" say "This hub can talk to: ${CAPS}." # Read as the hub's account, like everything else in its directory — which is # also what lets an install run by the login user read it at all ( is # 0750), rather than settle on `auto` and tell somebody who chose both radios # that their coordinator has the board. RADIO_MODE="$(read_hub_file "$DATA_DIR/radio-mode" | tr -d '[:space:]' || true)" [[ -n "$RADIO_MODE" ]] || RADIO_MODE=auto if [[ "$RADIO_BUDGET" == "one" && "$RADIO_MODE" == "both" ]]; then # The owner has already overridden the measurement, on this board, before # this run. Falling through to the branches below would tell them their # coordinator has the board and Matter is off — which is what the detector # was *told not to do* twenty lines earlier, and reads as the install having # quietly reverted a setting they made on purpose. say "This board was measured for one radio at a time and you have asked it to run both, which it is doing. The hub watches its own memory from here: if this board really does run short — a bigger Zigbee network is what usually does it — the hub hands a radio back by itself rather than letting the system pick, and says so in the GetHome app. You can go back to one radio there at any time." elif [[ "$RADIO_BUDGET" == "one" ]]; then # One radio at a time, so say which one has it and how to change that — and # keep `ZIGBEE_CONFIGURED` (the board went to the coordinator) apart from # `ZIGBEE_READY` (Zigbee2MQTT actually reached it), because on a small board # the gap between them is a hub running *neither* radio. # # This is the last line before the install ends, and it used to be the # reassuring one in that case: "the coordinator you plugged in has it, so # Matter is off" is true, but printed under a firmware warning and beside # `@@CAPABILITIES:Wi-Fi and MQTT@@` it reads as "all set" on a hub that can # talk to no radio at all. Naming it is the whole point of the check that # produced the warning in the first place. if [[ -n "$ZIGBEE_READY" ]]; then say "This board has memory for one radio at a time, and the Zigbee coordinator you plugged in has it, so Matter is off. You can switch to Matter in the GetHome app — the coordinator stays configured, and Zigbee devices come back when you switch back." elif [[ -n "$ZIGBEE_CONFIGURED" ]]; then say "This board has memory for one radio at a time and the coordinator has it, so Matter is off — and until the coordinator is talking, this hub is running neither radio. Sort out the warning above and Zigbee starts on its own. If you would rather use Matter meanwhile, switch this board in the GetHome app; the coordinator stays configured and Zigbee devices come back when you switch back." elif [[ "$MATTER_ON" == "1" && -n "$ZIGBEE_STANDING_BY" ]]; then # The coordinator is here and standing down, which is a *choice* somebody # made in the app. Said with the other sentence — "with no Zigbee # coordinator plugged in" — this line contradicted the detector's own # output four lines above it, on the same screen, about hardware the owner # could see. It is the installer's half of the same bug the app had, where # a hub set to Matter reported "Zigbee · no stick". say "This board has memory for one radio at a time, and you have set it to Matter — so the Zigbee coordinator that is plugged in is standing by rather than missing. Switch back in the GetHome app whenever you like; it stays configured, and your Zigbee devices come back with it." elif [[ "$MATTER_ON" == "1" ]]; then say "This board has memory for one radio at a time, and with no Zigbee coordinator plugged in that radio is Matter. Plug a stick in whenever you like (SONOFF ZBDongle-E/P, ConBee, SkyConnect) and Zigbee takes over by itself, with no reboot." else # The third case, and it only exists because the detector deliberately # doesn't follow a coordinator *out*: a stick was set up on this machine # once and isn't here now, so the board is still held for it and Matter is # off. Saying "that radio is Matter" here — which this branch used to — is # simply false, and it is the kind of false that sends somebody looking for # a Matter device that will never appear. warn "This board has memory for one radio at a time, and it is still held for the Zigbee coordinator that was set up here — which isn't plugged in now, so neither radio is running. Plug the coordinator back in and Zigbee starts by itself, or switch this board to Matter in the GetHome app." fi elif [[ -z "$ZIGBEE_CONFIGURED" ]]; then say "No Zigbee coordinator is plugged in, so this hub starts with Matter, Wi-Fi and MQTT devices. Plug one in whenever you like — Zigbee starts by itself, with no reboot." fi # The offer, and its price, said once on the board where it is a real decision. # # Deliberately **after** the sentence naming which radio ended up with the # board, because it only makes sense as an answer to that — and deliberately # not said on a hub already running both, where the branch above has covered # it. `say` rather than `warn`: nothing is wrong, and an amber line here would # read as the install having gone badly on every 512 MB board there is. if [[ "$RADIO_BUDGET" == "one" && "$RADIO_MODE" != "both" ]]; then say "If you would rather have both radios at once, you can turn that on in the GetHome app, and on a small home this board handles it comfortably — measured, not assumed." # **The sentence that has to be read before the network exists.** The failure # this is aimed at is not a hub falling over: it is somebody turning both # radios on with four devices, being perfectly happy, spending a year buying # more, and meeting the trade long after the point where a different board # was still an option. So it names what *changes* the answer, and names the # board that never has the question — which is the only part somebody # standing at the start of a setup can act on. say "Worth knowing before you build the network, though: what uses up the margin is Zigbee growing. Zigbee2MQTT holds state for every device you pair, so the board that copes with a handful may not cope with another twenty — this is a setting to come back to rather than one to set and forget. If it does run short the hub notices before anything breaks, hands one radio back by itself and says so in the app; nothing is unpaired. And if you already know you want a large Zigbee network alongside Matter, a board with 2 GB of memory or more never has to choose — that is a Pi 5, or a Pi 4 in its 2 GB or larger version, and not the 1 GB Pi 4, which is measured exactly like this one." # Two things the watch depends on, and both are worth naming *here* rather # than where they were set up: they were noise on a hub running one radio and # they are the difference between "hands a radio back" and "something dies" # on a hub running two. if ! memory_cgroup_live; then say "One caveat if you do: the kernel's memory accounting is not in force on this board yet, so the hub cannot see the board running short and cannot hand a radio back. Restart this Pi first — the installer has already switched it on for the next boot." fi # `/proc/swaps` rather than `swapon`, which lives in /sbin and is not on a # non-root PATH on Raspberry Pi OS — so the command fails, the output is # empty, and the check reports "no swap" on a board that has zram running. # A false warning about the one thing that makes this offer thinner is worse # than no warning: it argues against a choice the numbers actually support. if [[ "$(grep -c '^/' /proc/swaps 2>/dev/null || echo 0)" == "0" ]]; then say "One caveat if you do: this board has no swap of any kind, so there is no compressed memory to fall back on and the margin for running both radios is a good deal thinner than the numbers above assume." fi fi # ── The broker asks for a password now ───────────────────────────────────── # Only on a hub that already existed and had an open broker: a fresh install # has nothing wired into it yet, and telling somebody their integrations broke # before they have written one is noise on the last screen of a setup. # # It is a warning rather than a failure because the hub itself is fine — this # is about the boards *around* it, and the fix is two fields in whatever wrote # them, with the credentials one tap away in the app. if [[ -n "$MQTT_WAS_OPEN" && -n "$MQTT_SECURED" ]]; then warn "The MQTT broker now asks for a username and password, so anything you wired into it yourself has stopped being able to publish. Open your hub in the GetHome app to copy the credentials — use the account named for your own devices — and put them into your board or integration. Zigbee, Matter and the apps are unaffected." fi if [[ -z "$MQTT_SECURED" ]]; then warn "This hub's MQTT broker takes connections with no password, so anyone on this network can read the home and control its Zigbee devices. Re-run the installer to close it." fi printf '@@DONE@@\n' # Re-read rather than reprinting the copy taken at the health check. That one # predates the detector, so on a board that just handed its radio to Zigbee it # ended the install claiming `"matter":true` directly under a line saying # Matter is off — and `"claimed":false` on a hub the owner had since claimed. say "GetHome Hub is running: $(curl -fsS --max-time 5 http://localhost:8420/api/v1/hub 2>/dev/null || printf '%s' "$INFO")"