hald — the hardware daemon

hald is the one process that owns the Gardyn’s pins and buses (ADR-0004). It publishes the HAL contract over MQTT, serves stills and a state snapshot over HTTP, announces itself over mDNS, and advertises itself to Home Assistant by MQTT discovery so HA works with no core at all. Every pump command, from any surface, passes through PumpGuard (ADR-0009); every dosing command through DoseGuard.

Source: hal/ — hal-core (contract, traits, guards), hal-drivers (real drivers behind the hardware cargo feature), hal-sim (fakes), hald (the daemon).

Running

hald [--config /etc/seedypod/hal.toml] [--sim] [--stdout] [--mqtt-url mqtt://host:1883]
hald --check                   # validate the config, print the planned capability set, exit 1 on errors
hald --print-default-config    # the commented hal.toml the installer writes
hald --sim --stdout --ticks 3  # smoke test: simulated hardware, publishes as JSON lines

Builds: cargo build -p hald is hardware-free (simulator only; what CI runs). cargo build -p hald --features hardware links rppal and is what the release binaries contain. A hardware build off a Pi starts, logs every device as unavailable, and keeps serving MQTT/HTTP — it never panics on missing GPIO.

Configuration (hal.toml)

Pins, addresses and limits live only here; drivers receive them as arguments (AGENTS.md invariant). Unknown keys are rejected. hald --print-default-config prints every key with its default; the important ones:

Device list

With no [[sensor]] / [[actuator]] tables the stock Gardyn set is built from [pins] and [i2c]: pct2075, ina219, dht20 (optional), am2320 (optional), dyp_a01, over_temp_alert (optional); actuators light (pwm_light) and pump (pwm_pump). Optional devices that fail to probe are skipped; required ones are kept and re-probed on every failed read.

Explicit tables replace that list entirely, including the water ranger the dry-run interlock needs — list every part you keep. To add a probe (pH, EC, water temperature), prefer the app’s Sensors screen, which appends instead (see Sensors added from the app below):

[[sensor]]
kind = "ezo_ph"        # pct2075 | ina219 | dht20 | am2320 | dyp_a01 | over_temp_alert | ezo_ph | ezo_ec | ezo_rtd
addr = 0x63            # i2c kinds
optional = true
[[sensor]]
kind = "dyp_a01"
trigger = 26
echo = 19
[[actuator]]
id = "dose_1"          # light | pump | dose_1 | dose_2 | dose_3
kind = "dosing"        # pwm_light | pwm_pump | dosing
pin = 5

hald --check rejects unknown kinds and ids, missing addr/pin/trigger/echo, I²C addresses outside 0x08–0x77 or used twice, duplicate ids, and out-of-range limits, and prints the capability set the config yields. --sim honours the same tables, so a config can be exercised on a laptop first.

MQTT

Prefix seedypod/<unit-id>/; the topic table in ADR-0007 is authoritative. QoS 1 throughout. Client id hald-<unit-id>.

Semantics worth knowing:

• Pump: {"on":true} runs at the last/ max duty for pump_max_run_s; level is clamped to pump_max_duty; durationS is clamped to pump_max_run_s. A start is refused when the median water distance ≥ water_low_cm (or the ranger is unavailable), when the PCB is ≥ over_temp_c, when the board’s GPIO25 alert line is asserted, or while a fault is latched. A running pump that trips latches fault (dry-run, over-temp) until alert/pump_fault/ack. {"on":false} always works.
• Light: level 0–100, no interlock; {"on":true} without a level restores the last on-level. The level is persisted and restored on boot.
• Dosing (dose_1..3): durationS is seconds of pumping, converted to ml through ml_per_s, clamped to max_single_ml; omitted → default_dose_ml. Refused when disabled, when the dose would cross max_daily_ml (UTC day), while a dose runs, or after max_doses_per_day until alert/dose_fault/ack. The ledger survives restarts.
• Calibration (ph, ec, water_temp on EZO circuits): put the probe in the reference solution and wait for the reading to settle, then send {"point": …, "value": …}. value uses the reported unit (pH, mS/cm, °C; EC goes to the circuit in µS/cm). pH: mid first (it clears the others), then optionally low and high. EC: dry in air, then single, or low and high. RTD: single. clear wipes stored points. Implausible values (pH outside 0–14, EC ≤ 0 or > 500 mS/cm) and points the circuit doesn’t have are refused before anything reaches the bus; the result says why. Core exposes it as POST /api/sensors/{id}/calibrate.
• Button (GPIO13): single toggles the light, double starts/stops a button.pump_run_s bounded pump run, long acknowledges the pump fault and any dosing lockout. Keep holding to button.setup_hold_ms (10 s) and a setup press follows: hald does nothing else with it, and core opens its Wi-Fi setup hotspot (Installation → Change Wi-Fi). All four are published on event/button and on the Home Assistant button event entity.
• Reconnect: on broker loss hald backs off 1 → 30 s and keeps running; after reconnecting it republishes every retained topic and discovery.

Home Assistant entities

Published retained under <prefix>/<component>/<unit>_<object>/config at boot and on every reconnect. Every entity shares device = {identifiers: [<unit>], name: "Gardyn <unit>", manufacturer: "seedypod", model, sw_version} and availability_topic = seedypod/<unit>/availability.

All sensors carry state_class: measurement and value_template: {{ value_json.value }}; the full JSON is attached as attributes.

Sensors added from the app

devices/set (and the app’s Sensors screen) adds and removes probes at runtime (ADR-0018). Addable kinds are SensorKind implementations, published with their calibration steps in the retained devices inventory: ezo_ph (0x63), ezo_ec (0x64) and ezo_rtd (0x66). An add goes live immediately: the driver is probed, joins the registry and caps, and HA discovery is republished. It is persisted in <state_dir>/sensors.json and appended to the configured list at every boot. Refusals: kind not addable, address outside 0x08–0x77 or in use, quantity already installed, probe not answering. Built-in (hal.toml) sensors can’t be removed this way. The inventory also lists any configured sensor that failed to probe at boot, as absent with the error.

HTTP

Captures shell out to fswebcam -S <skip_frames> --no-banner and reject anything that is not a plausible JPEG (upstream #143, #144).

Camera names

USB cameras come up as /dev/videoN in whatever order they enumerate, so upper and lower can swap after a reboot. Each UVC camera also exposes a metadata node next to its capture node (video0 + video1), which only breaks things if it gets the name. hald therefore prefers stable names pinned to the USB port by a udev rule that matches the capture node only (ATTR{index}=="0"), and falls back to /dev/videoN until the rule exists:

hald --list-cameras            # capture nodes, their ports, and the default assignment
hald --camera-rules            # rules for that assignment: first port → upper, second → lower
sudo hald --camera-rules upper=1-1.3:1.0 lower=1-1.2:1.0 \
  | sudo tee /etc/udev/rules.d/70-seedypod-cameras.rules
sudo udevadm control --reload && sudo udevadm trigger --subsystem-match=video4linux
ls -l /dev/seedypod/           # camera-upper, camera-lower

scripts/install-hal writes the rules on first install if it finds cameras, and prints which port became which name. If the photos come out swapped, rerun the third command with the ports exchanged. Which physical port feeds which camera on a Gardyn is still unverified (see the hardware map).

State file

<state_dir>/sensors.json holds the sensors added from the app (above). <state_dir>/state.json (atomic write): lightLevel, lightSince, lightHoursTotal (cumulative, for LED ageing), lastPumpRun, doses\{id: ledger\}. On boot the light is restored to lightLevel without a glitch; on SIGTERM the pump and dosers are turned off, the light is left as-is, the state is saved and availability goes offline.

mDNS

_seedypod-hal._tcp instance <unit-id> on the HTTP port with TXT id=<unit-id>, model=<model>, v=<hal version>. Core discovers units from this rather than from configuration.

Install

curl -fsSL https://raw.githubusercontent.com/seedypod/core/main/scripts/install-hal | bash

scripts/install-hal detects the CPU (aarch64 → Zero 2 W / Pi 4 / Pi 5; armv6l/armv7l → Zero W), downloads hald-<target> from the latest GitHub Release, installs it to /usr/local/bin/hald, writes /etc/seedypod/hal.toml if absent (the commented defaults), creates the seedypod system user in gpio, i2c, video, enables I²C (raspi-config nonint do_i2c 0) and the PWM overlay (dtoverlay=pwm,pin=18,func=2, reboot required once), installs fswebcam, pins camera names to USB ports (/etc/udev/rules.d/70-seedypod-cameras.rules, see Camera names), installs Mosquitto with a listener on 127.0.0.1:1883 and no password (/etc/mosquitto/conf.d/seedypod.conf, written once), and installs/enables hald.service (Restart=always, After=network-online.target mosquitto.service, hardened). --binary ./hald installs a local build; --version vX.Y.Z pins a release; --no-enable skips starting it. --mqtt-lan adds a password-protected listener on port 1884 for Home Assistant on another machine and prints the homeassistant password once; --no-broker skips Mosquitto, for use with another broker such as Home Assistant’s add-on (Installation → Home Assistant).

It also cuts SD card writes (ADR-0021). Each change is checked once applied and undone if the check fails; a rerun reapplies them:

--no-wear leaves all three alone.

For core’s backups, the user core runs as (the one who ran the installer, or the owner of /opt/seedypod; SEEDYPOD_CORE_USER overrides) joins the seedypod group, which can read /etc/seedypod, /var/lib/seedypod and the Mosquitto password file (mosquitto:seedypod, mode 0640). A running core is restarted so it picks up the group.

Operations: journalctl -u hald -f, hald --config /etc/seedypod/hal.toml --check, mosquitto_sub -v -t 'seedypod/#'. See Debugging.

Verification status

Everything here is tested on the simulator and against a local Mosquitto; the real drivers compile for both targets but their register sequences, timings and the PWM/overlay details are unverified on a unit until the Phase 1 checklist in the hardware map is done.

Sources: ADR 0007: HAL contract v1 (topic table is authoritative) · ADR 0009: Pump safety guard and latched faults · Gardyn hardware map · Home Assistant MQTT integration (discovery payload keys) 

Imported from docs/hardware/hal.md in seedypod/core. Edit it there, not here.