Client Firmware

This guide covers flashing the snapclient firmware to a XIAO ESP32-S3 Plus endpoint and provisioning it onto your Wi-Fi HaLow network.

Flash via Web

Requirements

• Chrome or Edge on desktop.
• USB-C cable.
• An assembled endpoint. Temporarily remove the Audio DAC header for flashing if needed.

Steps

1. Open the LongWave Audio flasher.
2. Connect the XIAO ESP32-S3 Plus via USB-C.
3. Put the board into download mode: hold BOOT, tap RESET, then release BOOT.
4. Select your board variant and regulatory region.
5. Click Install Firmware, select the serial port, and wait for flashing to finish.
6. Press RESET without holding BOOT to boot the new firmware.

Provisioning with ESP SoftAP

A freshly flashed endpoint starts a 2.4 GHz Wi-Fi access point and waits for Wi-Fi HaLow credentials. Provisioning is done from a phone using Espressif's SoftAP Provisioning app, not the BLE or QR-code variant.

Attach the 2.4 GHz antenna to the XIAO before provisioning. Without it, the temporary SoftAP signal can be very weak.

1. Power the endpoint over USB-C. The status LED slow-blinks purple while waiting for credentials.
2. On your phone, join the endpoint's 2.4 GHz Wi-Fi network. The SSID begins with PROV_ and has no password.
3. Open the ESP SoftAP Provisioning app and tap Provision New Device.
4. Do not scan a QR code. Choose manual provisioning over the existing Wi-Fi connection.
5. Enter proof of possession longwave.
6. Select your Wi-Fi HaLow SSID or enter it manually, then provide the HaLow password.
7. Confirm. The endpoint stores credentials, drops its SoftAP, and joins the HaLow network.

The app will report "failed to associate" at the end of provisioning. This is expected behaviour.

Re-provisioning

Stored credentials persist across reboots. To clear them, hold RESET for 5 seconds until the status LED flashes red. The endpoint will reboot into SoftAP mode.

Build from Source

This path is for development. End users should use the web flasher.

Prerequisites

• ESP-IDF v5.4.2.
• USB-C cable.
• An assembled endpoint.

Set Up ESP-IDF

git clone -b v5.4.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32s3
source export.sh

Clone the Firmware Fork

git clone --recursive https://github.com/abaumann9/snapclient_halow
cd snapclient_halow

Configure

SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.esp32s3;sdkconfig.defaults.xaio-audio-hat;sdkconfig.defaults.<halow-board>" idf.py set-target esp32s3
idf.py menuconfig

• Wio-WM6180: seeed_halow_xiao_FGH100M_H.
• OSHWLab mm8108: halow_xiao_mm8108.

Set the country code in menuconfig:

CONFIG_HALOW_COUNTRY_CODE=?

HaLow SSID and password are normally set at runtime through SoftAP provisioning. For bench testing, they can be compiled in:

CONFIG_HALOW_SSID="network-ssid"
CONFIG_HALOW_PASSWORD="network-password"

If mDNS is not configured on the Snapserver, disable mDNS and set the server explicitly:

CONFIG_SNAPSERVER_HOST="server-ip"
CONFIG_SNAPSERVER_PORT=1704

Build, Flash, and Monitor

idf.py build
idf.py -p /dev/ttyACM0 flash
idf.py -p /dev/ttyACM0 monitor

Status LED

Troubleshooting

SoftAP network does not appear

• Verify the status LED is slow-blinking purple. If it is blue, credentials are already stored.
• The SoftAP is 2.4 GHz only. Make sure phone Wi-Fi is enabled.
• Clear stored credentials if the device was previously provisioned.

Provisioning rejects the proof of possession

• The default value is exactly longwave, lowercase, no quotes.
• If custom firmware changed the PoP, use that value instead.

HaLow module not detected

• Check SPI connections between ESP32-S3 and the HaLow module.
• Verify the module is seated or soldered correctly.
• Check that the correct SPI pins are configured in sdkconfig.

Cannot connect to Snapserver

• Verify Snapserver is running and listening on port 1704.
• Confirm the HaLow network is up and the endpoint has an IP address.
• Check firewall rules on the server.

No audio output

• Verify I2S pin assignments match the DAC hat wiring.
• Check DAC hat power and connections.
• Confirm the DAC receives I2S clock signals.