WiFi & network setup

Every network setting lives in one small file at the root of the device’s storage: config.json. This page is the reference for what’s in it, how the device behaves with (and without) it, and the different ways to edit it.

The file

A device that boots without a config.json creates one with defaults, so there is always a file to edit. A complete example:

{
  "wifi": { "ssid": "", "password": "", "hostname": "rfx", "ap": false },
  "show": "show.json",
  // Performance knobs — also live-tunable from the web UI (no reboot):
  "web": { "liveUpdate": true, "snapshotHz": 10, "screenPreview": false, "livePreview": false, "screenHz": 2, "inputHz": 10 }
}

// comments are allowed — the device reads JSONC.

wifi — connectivity

Field	Default	What it does
ssid	""	The WiFi network to join. Empty = don’t try; go straight to setup-network mode.
password	""	That network’s password.
hostname	"rfx"	The device’s name on the network — see below. Lowercased automatically; empty falls back to rfx.
ap	false	true = always start as an access point, even if ssid is set.

Note

ESP32-class boards connect to 2.4 GHz networks only — a 5 GHz-only SSID will never connect and the device will fall back to its setup network.

What the hostname gives you

• http://<hostname>.local/ — the dashboard address, via mDNS/Bonjour, so you never need to know the IP. Works on most home networks; if .local doesn’t resolve on yours, use the IP address instead.
• <hostname>-setup — the name of the device’s fallback WiFi network.

Give each prop its own hostname (gauntlet, helmet, …) so multiple devices can share a network without colliding.

Connection flow and AP fallback

On every boot the device:

1. Starts the show, web server, and USB drive immediately — WiFi connects in the background and never delays the show.
2. If ssid is set (and ap is false), tries to join that network.
3. Success → reachable at http://<hostname>.local/ and its IP.
4. No ssid, wrong password, network out of range, or 15 seconds pass → falls back to access-point mode: it creates an open WiFi network named <hostname>-setup. Join it and open http://192.168.4.1/ to reach the dashboard and fix the settings.

A broken config.json (invalid JSON) is treated like an empty one: the device logs the parse error and boots with defaults — which, with no SSID, means the setup network. So a bad edit can never lock you out of the dashboard.

Caution

The <hostname>-setup network has no password, and firmware updates on the LAN are unsigned in this build. Fine for the workbench and networks you trust — don’t leave a device in AP mode at a crowded con longer than you need to.

Finding the device: netinfo.json

Whenever the network comes up, the device writes netinfo.json to the root of its data drive: hostname, mode (STA on your network / AP fallback), SSID, IP address, MAC address, and the http://<hostname>.local/ URL. If you ever lose track of a device, plug it into a computer and read that file off the drive.

show — the active show file

"show": "show.json" names the show file the engine loads. Point it at a different file to keep several shows on one device and switch between them. Also editable as Active show file on the dashboard’s Config tab. See Show format.

web — dashboard tuning (brief)

Performance knobs for the web dashboard. Defaults are right for almost everyone:

Field	Default	What it does
liveUpdate	true	Publish live telemetry to the dashboard at all. Turn off to shave every last drop of overhead during a performance.
snapshotHz	10	How often (per second) the Live tab refreshes.
screenPreview	false	Stream the device’s LCD framebuffer to the browser (expensive).
livePreview	false	Show the live stage preview in the dashboard.
screenHz	2	Preview frame rate when enabled.
inputHz	10	How often the browser batches control input to the device.

Unlike the wifi block, these apply live — change them from the dashboard and they take effect immediately, no reboot.

How to edit config.json

Pick whichever is handiest:

1. Web dashboard → Config tab (recommended). A simple form for the WiFi fields and active show, plus a raw config.json editor for everything else. Save & reload writes the file and reboots the device to apply it.
2. The device’s USB data drive — on boards with on-chip storage, plug into a computer and edit config.json right on the drive, like a thumb drive. Applies on the next reboot.
3. The SD card — on SD-backed boards, pop the card into a computer and edit it there.
4. Web dashboard → Files tab — upload a config.json you prepared elsewhere; the device reboots to apply it.

Which storage your board has is on its page under Boards.

Tip

WiFi and hostname changes only apply at boot — that’s why the dashboard reboots the device when you save. If you edited the file on the drive or SD card instead, power-cycle (or tap RESET) to apply.