Docs menu

How it works

slownet

How a Slowboard gets on Wi-Fi: a hotspot and a setup page on your phone, brought up only while the board has no network.

Status. slownet is designed but not built yet; this page describes the design.

slownet handles Wi-Fi setup. It is the only Slowboard program that runs as root, and it runs only while it is needed: slowd starts it when the board can’t get on a network, and it exits once the board is online.

slownet scans, diagnoses, runs the hotspot and applies the network password; slowd decides when setup is needed and draws every screen. slownet never draws anything, never handles rfkill and does nothing once the board is online.

When setup starts

slowd connects to /run/slownet.sock only when the screen’s profile has wifi_setup = true and one of these holds:

  • No usable IPv4 address on wlan0 for 4 checks (one every 20 s) after a 120 s boot grace period. slowd first asks slownet to diagnose:
    • a saved network is visible but authentication failed (wrong key or a failed 4-way handshake): start the hotspot now;
    • no saved network is visible (the router is probably still booting): wait with backoff (5, 10, 20 min) before starting the hotspot;
    • nothing is configured: start the hotspot after 20 s.
  • The hub asks for it, through the wifi_setup generation in the state document (slowhub want wifi_setup).

It never starts because of “no internet”. With a local hub, losing the internet only shows in status; the internet probe lives in slowhub. A router that is unplugged from the internet but still up keeps the board on the LAN with no hotspot cycling.

If wlan0 doesn’t exist at all, slowd shows “no Wi-Fi device (rfkill?)” and doesn’t start slownet.

What happens during setup

no IPv4 on wlan0 for 4 x 20 s . . no saved SSID idle scanning visible: wait after a 120 s boot grace 5, 10, 20 min or the hub wants wifi setup hotspot 10.0.0.1 capti e portal :80 panel: join QR + setup QR SSID + password ok joining ' failed: restore the old netplan, back to the hotspot, error ok associated + address internet is not required shown nobody joins for 300 s: retry saved networks slowd holds the panel during setup and draws draws nothing and exits 60 s after ok backoff 5, 10, 20, 40 every screen; slownet min epaper-setup-<mac4>

slownet’s states, from a cold board to a joined network. “ok” means associated with an address, not internet access.

  1. slownet scans first (the radio can’t scan in AP mode), then brings up the hotspot: SSID epaper-setup-<mac4>, WPA2-PSK, channel 6, with a word-style password that stays the same for the life of the process.
  2. slowd shows the hotspot screen with two QR codes: one to join the network (WIFI:T:WPA;S:…;P:…;;) and one for the setup page.
  3. The phone joins. The DHCP server announces a captive portal (CaptivePortal=http://10.0.0.1/), DNS on 10.0.0.1:53 answers every name with the board, and the portal on port 80 redirects any other host to the setup page, so phones show their captive sheet.
  4. The user picks a network and enters its password (SSID up to 32 bytes; password 8–63 characters, or empty).
  5. slownet writes the network to /etc/netplan/90-epaper-wifi.yaml (mode 0600, atomic, merged with the saved networks), tears the hotspot down and joins. Success means associated plus an address, not internet access.
  6. slowd shows the “connected” screen, with a QR code for the hub’s web page (http://<ip>:<hub_web_port>/).

If the join fails, slownet restores the previous netplan file and returns to the hotspot with the error shown.

How the board recovers on its own

If nobody connects to the hotspot for 300 s (no stations and no hits on the portal), slownet tries the saved networks again. Failed rejoins back off the hotspot and rejoin cycle: 5, 10, 20, then 40 minutes. This self-heal matters because each hotspot and rejoin cycle costs the panel two full refreshes.

What slowd does while setup is active

slowd holds the panel: decks, arming and scheduled refreshes pause, and slowd follows slownet’s reported state rather than its own address check (in AP mode wlan0 holds 10.0.0.1).

  • Holding the spare key means “retry saved networks now”.
  • The hold is released when slownet reports ok and the hub bumps wifi_dismiss (it does so when the hub’s web page is opened from outside 10.0.0.0/24), or after a 600 s timeout.
  • On release, slowd forgets the strips and runs a full update.

slowd closes its /v1/watch long-poll once the state is ok, and slownet exits 60 s after ok with no clients.

How the hotspot is built

The NetplanNetworkd backend targets netplan with systemd-networkd and wpa_supplicant (Armbian trixie).

  • Hotspot up: stop netplan-wpa-wlan0; write the runtime file /run/systemd/network/05-epaper-ap-wlan0.network with Address=10.0.0.1/24, DHCPServer=yes, ConfigureWithoutCarrier=yes, EmitDNS, DNS=10.0.0.1 and [DHCPServer] CaptivePortal=http://10.0.0.1/; networkctl reload; start hostapd with its config at mode 0600.
  • Hotspot down: delete the runtime .network, networkctl reload, systemctl restart netplan-wpa-wlan0, networkctl reconfigure wlan0. No netplan apply, because the netplan-generated files didn’t change.

IPC between slowd and slownet

HTTP/1.1 on /run/slownet.sock. slowd is the only client.

  • GET /v1/status returns {state, configured, ssid?, ip?, saved:[…]}.
  • POST /v1/diagnose returns {configured, saved_visible, auth_failed}, worked out from wpa_cli status and scan_results.
  • POST /v1/hotspot {reason} scans, then brings the hotspot up.
  • POST /v1/rejoin retries the saved networks.
  • POST /v1/stop tears the hotspot down and rejoins.
  • GET /v1/watch is a long-poll of state changes.

What root is allowed to do

slownet runs as uid 0 because restarting units and reloading networkd go to PID 1 over D-Bus. Root is bounded by the unit:

slownet.socket: ListenStream=/run/slownet.sock, SocketUser=root, SocketGroup=slowd, SocketMode=0660. Only slowd can connect.

slownet.service:

  • CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE, NoNewPrivileges=yes
  • ProtectSystem=strict, with write access only to /etc/netplan, /run/systemd/network, /run/slownet, /run/netplan, /run/systemd/system and /run/udev/rules.d
  • ProtectHome, PrivateTmp, RuntimeDirectory=slownet
  • RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK AF_PACKET
  • MemoryMax=24M

Outside of setup, no Slowboard program runs as root.

Board quirk: rfkill on the Lyra

On the Luckfox Lyra Zero W, the AIC8800DC Wi-Fi chip’s power pin is wired as the Bluetooth rfkill GPIO, which boots blocked, so there is no wlan0 until it is unblocked. This belongs to the board profile, not to slownet: the Lyra ships a oneshot unit, aic8800-power.service (ExecStart=/usr/sbin/rfkill unblock bluetooth, Before=network-pre.target). The chip is 2.4 GHz only.

Updates, now and then

A short note when there is a new board, a new slowapp, or kit news. Rarely more than one a month.