WiFi Access Point

WiFi access point (Pi)

A Backyard Hero Pi can act as its own WiFi network so the operator and any other phones / tablets at the launch site can talk to the controller with no surrounding infrastructure — no router, no upstream WiFi, nothing to provision in the field. This page covers how that AP is set up, how to change its credentials, and how to disable it.

This is Pi-specific. macOS / Windows hosts don't need any of this — the Pi installer is the only thing that wires hostapd + dnsmasq + NAT.

---

Topology

                ┌─────────────────────────────────────────────────┐
                │              Raspberry Pi                       │
                │                                                 │
  Internet ━━━► │ eth0 (DHCP from venue WiFi / wired uplink)      │
                │   │                                             │
                │   │ MASQUERADE NAT                              │
                │   ▼                                             │
   Phone ━━━━► │ wlan0  192.168.42.1  (AP, hostapd + dnsmasq)     │
   Phone ━━━━► │                                                  │
   Laptop ━━━► │ Docker:                                          │
                │   firework-system  →  port 80 + 1776 + 8090     │
                │                                                 │
                │ mDNS:  backyardhero.local → 192.168.42.1        │
                │        byh.local          → 192.168.42.1        │
                │        backyardhero       → 192.168.42.1        │
                └─────────────────────────────────────────────────┘

Two things happen at once:

1. wlan0 becomes an AP. hostapd broadcasts a WPA2-PSK SSID; dnsmasq hands out DHCP leases on 192.168.42.50–.150 and answers DNS for the friendly hostnames listed above.
2. eth0 (or any other non-wlan0 interface) is treated as the uplink. iptables -t nat -A POSTROUTING -s 192.168.42.0/24 ! -o wlan0 -j MASQUERADE makes clients on the AP appear to come from the Pi's external IP, so they can reach the internet through the Pi if there's an uplink connected.

If the Pi has no uplink, the AP still works — clients just can't reach the public internet, only the Backyard Hero UI. Pull the ethernet cable mid-show and nothing on the local AP changes.

---

Default credentials

SSID	BackyardHero-<5char> where the suffix is the first 5 chars of /etc/machine-id, stable per Pi
Password	backyardhero (WPA2-PSK)
Channel	6 (2.4 GHz)
Country	US
Gateway IP	192.168.42.1
DHCP pool	192.168.42.50 – 192.168.42.150

The default password is intentionally weak so first-boot setup works without coordinated paperwork. Change it before you take the Pi anywhere it might be reachable by other people. Two ways:

• From the UI: Settings → Network → WiFi access point (see below).
• At install time: sudo install.sh --ssid PyroPi --password 'longerthan8chars'.

---

Friendly hostnames

dnsmasq resolves a few names to the AP gateway IP. Any of these work for AP clients:

Hostname	What you get
backyardhero	The bare friendly name. Many browsers append .com if you forget — http://backyardhero/ is the safest form.
backyardhero.local	mDNS-style hostname. Works on iOS / macOS / Windows / Android.
byh.local	Short alias.
pyro.local	Short alias.
192.168.42.1	The raw gateway IP. Always works.

Port 80 on the Pi forwards to the container's port 1776 (the Next.js app), so http://backyardhero/ and http://backyardhero:1776/ both reach the same UI. The historical :1776 form keeps working for muscle memory.

backyardhero.local doesn't resolve! Browsers on Android sometimes refuse to resolve .local via DHCP-pushed DNS and only consult mDNS. The bare form (http://backyardhero/, no .local) bypasses that and is preferred for phones. iOS and macOS handle both.

---

Changing SSID / password from the UI

Open Settings → Network → WiFi access point.

1. Edit the SSID and/or password fields. Validation rules:
   • SSID: 1–32 printable ASCII characters.
   • Password: 8–63 printable ASCII characters (WPA2-PSK constraint).
   • Channel: 1–14 (the regulatory domain limits what's actually legal where you are).
   • Country: 2-letter ISO code (e.g. US, GB, DE).
2. Click Save.
3. The UI shows a "Connection will drop in ~3 s — reconnect to <new SSID> with password <new password>" dialog before hostapd actually resets.

The 3-second deferred restart is deliberate: it lets the API response reach your phone before the radio actually flips, so you can see the reconnect instructions even though your current WiFi connection is about to die.

What happens under the hood

The UI never touches /etc/hostapd/hostapd.conf directly. The flow is:

Browser  ─────► POST /api/system/ap  (Next.js, in container)
                  │
                  │  Writes payload to /data/byh_ap_request.json
                  ▼
              systemd path watcher  (byh-ap-apply.path)
                  │
                  ▼
              byh-ap-apply.py  (root, on the host)
                  │  - validates the request
                  │  - rewrites /etc/hostapd/hostapd.conf
                  │  - updates /data/byh_ap_current.json
                  │  - schedules a deferred hostapd restart (~3s)
                  │  - writes /data/byh_ap_status.json with ok/error
                  ▼
              Next.js polls /data/byh_ap_status.json
                  │
              UI shows "reconnect to <new SSID>"
                  ▼
              hostapd restarts ➡ AP relaunches with new config

If the new config is rejected (bad channel for the country, etc.), byh-ap-apply.py restores the previous hostapd.conf and reports the error back through byh_ap_status.json. The UI shows the error and the AP keeps running on the old credentials.

From the CLI on the Pi

You can also do this directly:

sudo /opt/backyardhero/host/run/pi/install.sh \
  --ssid PyroPi-East --password 'longerthan8chars' -y

Re-running the installer rewrites hostapd.conf and reloads hostapd. Idempotent.

---

Internet for AP clients (NAT)

When --no-nat is not passed, the installer:

1. Drops /etc/sysctl.d/99-byh-ap-nat.conf with net.ipv4.ip_forward=1.
2. Installs /usr/local/sbin/byh-ap-nat.sh which calls iptables -t nat -A POSTROUTING -s 192.168.42.0/24 ! -o wlan0 -j MASQUERADE.
3. Installs byh-ap-nat.service that runs the script on every boot (rules don't persist across reboots by default on Pi OS).

The ! -o wlan0 predicate matches whatever the uplink is — eth0, a USB-tethered phone, a second wireless interface, anything that isn't wlan0. So plugging in / unplugging the ethernet cable just works.

You can skip the NAT step by passing --no-nat. Useful if the Pi is on a venue network that you specifically don't want to forward AP-client traffic onto.

Verifying NAT

sudo iptables -t nat -L POSTROUTING -n -v
# Chain POSTROUTING (policy ACCEPT 0 packets, 0 bytes)
#  pkts bytes target     prot opt in     out     source              destination
#  1234 56789 MASQUERADE all  --  *      !wlan0  192.168.42.0/24     0.0.0.0/0

cat /proc/sys/net/ipv4/ip_forward
# 1

From an AP client, ping out:

ping -c 3 8.8.8.8

If that works but DNS doesn't, your uplink doesn't have working DNS. The Pi's dnsmasq forwards upstream DNS queries by default; if you're on a network that filters DNS, you may need to configure an upstream resolver explicitly in /etc/dnsmasq.d/backyardhero.conf and reload.

---

Disabling the AP

Three options:

1. Skip at install time:

sudo /opt/backyardhero/host/run/pi/install.sh --no-ap

This installs everything else but leaves wlan0 alone. Use this if the Pi is going to live on the venue's existing WiFi instead.

2. Disable after install:

sudo systemctl disable --now hostapd dnsmasq byh-ap-iface byh-ap-nat
sudo systemctl daemon-reload

The byh-host stack (the actual app) keeps running. You'll need an alternative way to reach the UI — typically the Pi's IP on the venue WiFi or wired ethernet.

3. Full uninstall of AP machinery:

sudo /opt/backyardhero/host/run/pi/install.sh --uninstall
sudo /opt/backyardhero/host/run/pi/install.sh -y --no-ap

This first removes everything, then reinstalls without the AP.

---

Diagnostic commands

# Is hostapd happy?
systemctl status hostapd
journalctl -u hostapd -n 50

# Is the radio actually broadcasting? (you should see your SSID)
sudo iw dev wlan0 info
sudo iw wlan0 scan | grep -E 'SSID|signal' | head -20

# Are clients connected?
sudo iw dev wlan0 station dump

# Is dnsmasq leasing addresses?
sudo journalctl -u dnsmasq -n 50
cat /var/lib/misc/dnsmasq.leases   # one line per active client

# Did the UI-driven AP-apply pipeline run?
journalctl -u byh-ap-apply -n 50
cat /opt/backyardhero/host/data/byh_ap_status.json
cat /opt/backyardhero/host/data/byh_ap_current.json

The two *.json files in host/data/ are the source-of-truth handoff between the UI and the host. If the UI ever says "no access point is configured on this host" but the AP is clearly running, that file is the one to inspect — usually it just needs to be regenerated by re-running the installer (which writes byh_ap_current.json as part of install_ap_apply_service).

---

Common problems

"No access point is configured on this host" but my phone sees the SSID

/opt/backyardhero/host/data/byh_ap_current.json is missing or malformed. The installer drops a seed copy during install_ap_apply_service. Re-run:

sudo /opt/backyardhero/host/run/pi/install.sh -y

…or seed the file manually from hostapd.conf if you don't want a full re-run. The UI's API route (/api/system/ap → GET) only reads from this file; it never inspects the live AP state directly.

Phones can connect but can't reach the internet

Check, in order:

1. cat /proc/sys/net/ipv4/ip_forward — must be 1.
2. sudo iptables -t nat -L POSTROUTING -n -v — must show the MASQUERADE rule.
3. From the Pi: ping 8.8.8.8 — must work. If not, the Pi's own uplink is broken.
4. On the client: nslookup backyard-hero.com — if this fails but nslookup 8.8.8.8 8.8.8.8 works, your dnsmasq isn't forwarding DNS. Reinstall or check /etc/dnsmasq.d/backyardhero.conf.

"I changed the SSID from the UI and the AP came back on the OLD one"

byh-ap-apply.py rolls back if hostapd refuses to start with the new config. Check journalctl -u byh-ap-apply and journalctl -u hostapd — common cause is a channel that's not legal in the configured country. The UI's Settings → Network should also show the error in the status badge.

NetworkManager keeps reclaiming wlan0

The installer drops a NetworkManager unmanaged-devices config but on some distros NetworkManager runs in a config-watching mode that needs an explicit reload:

sudo systemctl restart NetworkManager

If that's still not enough, double-check /etc/NetworkManager/conf.d/99-byh-unmanaged.conf is present and [keyfile] unmanaged-devices=interface-name:wlan0.

Channel mismatch errors in hostapd

Country US legally allows channels 1–11 on 2.4 GHz. Country JP allows 1–14. Country EU-aligned codes allow 1–13. The default channel is 6, which is legal everywhere. If you set country GB with channel 13, hostapd will refuse to start.

---

See also

• Pi install script — how the AP gets set up in the first place.
• Updating the Pi — pulling new versions onto the controller.
• Connecting the dongle — the friendly URLs (above) only resolve to the Pi gateway, not the dongle.
• UI Settings page — the in-app AP configuration form.