Device Configuration

The ESP32-S3 firmware uses two kinds of settings.

Setting	Storage	How to change
Role / Index / Rate / Gateway / LAN	DIP switches (live)	DIP Switch Configuration
MQTT / WiFi(OTA) / OTA URL / mode	NVS (survives reboot)	SETUP portal, UART menu, UART commands — below

NVS values can be changed two different ways. They all read and write the same store, so the values you see in one are the same in any other.

---

1. SETUP Portal (Wi-Fi AP + Web Form)

The most visual option. Use a phone or laptop browser to fill the form.

Entry

• Hold IO35 while powering the board on (≥ 200 ms)

📷 [image placeholder] Photo of the board with a red arrow pointing at the IO35 button. Filename: assets/board_io35_button.png

The OLED then shows SSID / password / URL:

SETUP
WiFi: UWB-Anchor-XXXX
PW:   00000000
URL:  http://192.168.4.1

XXXX is the last two MAC bytes — different per device.

Configuration

1. From your phone, join Wi-Fi UWB-Anchor-XXXX with password 00000000
2. Browse to http://192.168.4.1
3. Fill the form and press Save & Reboot

A Current settings panel at the top shows what is currently saved; the inputs below are for new values.

📷 [image placeholder] Full screenshot of the SETUP page on a phone browser, showing the Current settings panel and the input fields. Filename: assets/setup_portal_phone.png

Fields

Group	Field	Notes
MQTT	Host	Broker address
	Port	Defaults to 1883
	User / Password	Leave empty for anonymous brokers
	Topic prefix	Final topic is <prefix>/<role><idx>
Firmware Update	WiFi SSID / Password	Used briefly while OTA temporarily switches to STA
	OTA URL	Direct URL to firmware.bin
	Update mode	Manual or Auto (see OTA section)
	Force update	Skip the version check; re-download regardless

Buttons

• Save & Reboot — write to NVS, reboot
• Save & Update Now — save then immediately run OTA. The AP comes down, the device joins the configured Wi-Fi, downloads firmware.bin, then auto-reboots into the new image.

Wi-Fi credentials are required even when LAN (Ethernet) is also configured. OTA fetches over HTTPS from GitHub Releases, and the ENC28J60 LAN stack does not support TLS — so the download has to go over Wi-Fi.

---

2. UART Interactive Menu

Pick options on a numbered screen from the USB serial terminal. Clean text UI, no GUI needed.

Entry

Press Enter twice on a blank line.

[Enter][Enter]

=== entering SETUP menu ===
Tips:
  - Pick an option by typing its number then Enter.
  - Inside a value prompt, just press Enter to keep
    current; type '-' to clear; Ctrl+C to cancel.
  - Changes are pending until you choose Save (5).

=== SETUP MENU ===           [Pending: 0]
1) MQTT
2) WiFi (for OTA)
3) OTA
4) Show all
5) Save & exit
6) Cancel & exit
0) Run OTA now (uses live cfg)
(Ctrl+C = cancel & exit menu)
> _

How it behaves

• While the menu is up, range JSON, DIP dump, and STM32 chatter are silenced so the UI stays readable. MQTT publishing keeps running.
• Edits go into a pending copy. NVS only updates when you pick Save (5).
• Cancel (6) or Ctrl+C from the main menu discards everything.

Value-prompt rules

When you pick a field:

Editing: mqtt.user
Current value: admin
How to respond:
  - type new value then press Enter
  - press Enter alone to keep current
  - type '-' then Enter to clear (empty)
  - press Ctrl+C to cancel without changing
> _

Input	Result
value Enter	save new value into pending
Enter alone	keep current (no change)
- Enter	clear to empty
Ctrl+C	discard, return to submenu
Invalid value (port out of range, bad mode token)	error, re-prompt

Ctrl+C in the menu

Position	Ctrl+C does
Inside a value prompt	discard input, return to submenu
Submenu (MQTT/WiFi/OTA)	go back to main
Main menu	exit menu (same as Cancel)

pio device monitor uses Ctrl+C as its own quit key by default. To forward Ctrl+C to the device, launch the monitor with a different exit char:

pio device monitor -b 115200 --exit-char 29

That makes Ctrl+] the monitor quit key and forwards Ctrl+C to the firmware. PuTTY / Tera Term forward Ctrl+C by default, so they need no special flag.

---

3. OTA Firmware Update

The device temporarily switches to Wi-Fi STA, downloads firmware.bin over HTTPS, then auto-reboots. The OTA URL and Wi-Fi credentials must be saved.

Update mode

Mode	Behaviour
manual	No OTA on boot. Trigger via SETUP Save & Update Now, or UART menu option 0) Run OTA now
auto	On every boot, fetch a small firmware.version sidecar and compare it to the firmware's FW_VERSION. Download only if they differ.

Start with manual while validating a release. Switch to auto once you trust the upgrade path.

Serial log shapes

Success:

[ota] wifi connecting to home-wifi
[ota] wifi up, ip=192.168.0.123
[ota] remote="1.0.3" local="1.0.2"
[ota] downloading <URL>
ota: download
... progress ...
[auto-reboot into new firmware]

Same version (auto mode with no new release):

[ota] remote="1.0.2" local="1.0.2"
[ota] result: up-to-date

Troubleshooting

Symptom	Likely cause
wifi fail	SSID/PW typo, weak AP, 5 GHz-only AP (ESP32 is 2.4 GHz only)
version fetch http=4xx	OTA URL wrong, or the release lacks firmware.version
fail: -2 etc	Out of memory, or .bin is corrupted/wrong target
Re-downloads on every boot	FW_VERSION doesn't match the sidecar — check that the build embedded the right version

---

4. IO35 Button Reference

Action	When	Result
Hold during power-on (≥ 200 ms)	At boot	Enter SETUP portal (skips normal boot)
Hold for ≥ 5 s, then release	During normal run	Soft reboot
Press for < 5 s	During normal run	Ignored

After install, when the OLED is no longer visible (ceiling-mounted etc.), the button is your safety net. If the Wi-Fi scan shows UWB-Anchor-XXXX, SETUP mode entered successfully.

---

Priorities and Conflicts

• DIP-switch settings and NVS settings are independent — they don't override each other.
• If the same NVS field is changed by two different methods, the most recent write wins.
• When OTA runs from inside the SETUP portal (menu option 0 or the "Save & Update Now" button), the Wi-Fi radio switches from AP to STA before the download. The AP disappears at that moment.