Troubleshooting

USB port doesn't appear or connect

Try a known USB data cable, close serial monitors and confirm you're choosing the right port. Follow the board's ROM BOOT/reset procedure to enter its download mode. Chip detection doesn't identify the correct hardware profile. Recheck hardware selection before installing anything.

Bluetooth discovery or pairing fails

Normal firmware stops BLE while Wi-Fi is active. Switch radios using the board's button gesture. Disconnect another phone/watch that already owns the connection. For new pairing, confirm the OS request and release, then click the headset within 30 seconds. Repeatedly holding the startup button doesn't confirm pairing.

After an explicit storage reset, forget the old OS bond and pair again. Current firmware has no fixed PIN. See pairing and BLE security.

Wi-Fi network or page isn't available

Set an AP password over bonded BLE first. Use Settings → Wi-Fi, or Set up recovery Wi-Fi in recovery. Join the device's own reported network, then open http://192.168.4.1/ directly. A phone reporting “no internet” on that AP is expected. The default timeout closes normal Wi-Fi five minutes after the last client leaves; HTTP polling alone doesn't keep it open. See Wi-Fi controls.

LEDs are dark, backwards or show the wrong colours

Check power, wiring, global power, brightness, configured counts and RGB/GRB order. On v1, saved reverse settings can override build defaults. V2 has a fixed map and stays dark without a qualified current allowance. Recovery may show no LED output. Don't raise current limits to troubleshoot an unknown power path.

Use LED diagnostics to identify ears, primaries and traversal. The configured count must cover the whole connected strip to clear old tail pixels. See wiring, layout and output limits.

Motion looks wrong or has no directional response

Check sensor availability, capture mounting calibration while still, and verify physical left/right identity. Recalibrate after moving the board. A missing sensor can leave lighting usable with idle motion effects; a rendered phone preview doesn't establish that the headset sensor is working.

Settings didn't survive reboot, or an update failed

Read the app's applied/save result before powering off. A save failure can leave the new value active only in RAM. Check Settings → Firmware diagnostics for active warnings and explicitly refresh recent logs; logs are RAM-only and disappear on reboot. Export only what you intend to share.

Use updates and recovery for a failed transfer and settings storage for repair behaviour. Automatic repair preserves unknown newer schemas and never mass-erases NVS.