Troubleshooting

Troubleshooting

Common problems and how to isolate them. For live diagnostics use the CLI Commands (especially #L09, #L11, #L13, #L20/#L21) and the config tool's monitor.

---

The config tool won't connect

• Use Chrome or Edge on desktop. Firefox and Safari don't support the Web Serial API.
• Only one program can hold the serial port. Close the Arduino IDE Serial Monitor, other terminals, or another browser tab that's connected.
• Re‑plug the USB cable and click Connect again, then pick the port. A charge‑only cable won't enumerate a data port — use a data cable.
• After a manual reboot the native‑USB port re‑enumerates — just click Connect again. (After a flash the tool reconnects on its own; if that ever times out it tells you to click Connect.)

No SBUS / "SBUS not OK" in the monitor

• Confirm the receiver's SBUS line is on GPIO5, with common ground and correct receiver power.
• Run #L09 — if frames isn't climbing and fps is 0, no frames are arriving (wiring, wrong pin, or receiver not outputting SBUS).
• Make sure the radio is bound and actually transmitting, and that the model outputs SBUS (not just PWM/PPM).
• failsafe: YES or lost: YES means frames are arriving but the link is unhealthy — check RF/binding.
• Use #L13 to see the raw frame; header byte should be 0F. A 25‑byte frame = SBUS‑16, 36‑byte = SBUS‑24.

Buttons don't fire (or fire twice)

• Calibrate (Config → 🎯) — the default matrix bands are X18 measurements; your radio's values may differ. Watch the matrix value in the monitor as you press each button and confirm it lands in a band.
• Phantom double‑presses on a noisy analog matrix: raise matrix debounce frames (Config → Channels) from 1 to 2–4. (1 is best for a clean digital SBUS source.)
• A very fast tap that presses+releases inside a single ~9–14 ms SBUS frame can't be seen — that's a hard SBUS limit, not a bug.
• Remember mappings are per mode — check you're editing the mode the mode‑switch is actually in (shown live in the monitor).

Mode never changes / wrong mode

• The mode switch defaults to SE (CH12), 3‑position. Verify that switch is on CH12 (or rebind it), and watch modeVal in the monitor: <582 = Mode 1, 582–1401 = Mode 2, >1401 = Mode 3.

Save seems to fail / "no ACK received"

• A SET_CONFIG waits for the board's ACK. If you see a no‑ACK warning, click Refresh to verify what actually persisted, then re‑Save.
• Over Via WCB, large configs are fragmented and saving is slower (several seconds) — give it time before assuming failure.
• If saving over WCB is flaky, save over direct USB instead.

HCR is silent

1. Run #L20 (S3) or #L21 (S4) — sends a test phrase straight to the port, bypassing config.
   • HCR responds → the wiring is fine; the issue is config/mapping. Check Config → HCR destination (transport + port/WCB ID) is saved, and that your button is actually mapped to an HCR action.
   • No response → wiring: confirm NaviCore TX → HCR RX (GPIO15 for S3, GPIO17 for S4), common ground, correct voltage, and the right baud (HCR = 9600) in Config → Aux Serial.

• For HCR over WCB: it's unicast only — the destination must be a WCB ID 1–20 plus a port 1–5 (broadcast isn't supported).

MP3 Trigger doesn't play

• Local (S3/S4): set that port to 38400 baud (MP3 Trigger v2). Confirm TX→RX wiring and ground.
• Over WCB: the destination WCB must have its MP3 driver set up (?MP3,S<port> on that WCB), and you target that WCB's ID.
• PLAY track range is 1–255; VOL is 0 (loudest) … 64 (silent).

Remote Maestro / servo doesn't move

• The Maestro slot (1–8) must be set to Remote in Config → Maestro, and the device number must match the unit's number in Maestro Control Center.
• The receiving WCB must have Kyber forwarding enabled (?KYBER,REMOTE) and a Maestro port configured so it forwards the broadcast bytes to that port. Check with ?KYBER,LIST (must not say "Not used") and ?MAESTRO.
• For a local Maestro: it's on Serial2 (GPIO6), and its baud must match Config → Aux Serial → Maestro (default 115200) — or set the Maestro to Detect Baud Rate.
• Each Maestro on a shared bus needs a unique Pololu device number, or they'll collide.

WCB peers show offline

• Run #L11 (or the tool's WCB Status panel). If peers are dn, check that MAC octets, password, and quantity match the rest of your system (?WCBM / ?WCBP / ?WCBQ on a known‑good WCB).
• WCB network changes need a reboot — save, then REBOOT (or power‑cycle).
• Orange status LED at boot = WCB init failed; re‑check the credentials.

"Via WCB" can't flash firmware

• Correct — flashing needs a direct USB connection (esptool drives the chip's bootloader). Tether the board over USB to update firmware.

Board seems frozen when nothing's connected

• It isn't — hot‑path logging is non‑blocking and is dropped when no host is draining USB. Connect the config tool (or a serial terminal) and it resumes normally. Saved config and dispatch keep running regardless.

Recover a bad config / start fresh

• Config → Restore Defaults, or send RESET_DEFAULTS — this is what actually clears the saved config, which now lives in /config.json on the LittleFS partition.
• For a deeper reset (stale OTA/NVS state or partition trouble), use the flasher's ⚠ Full Wipe & Flash, which erases NVS + OTA data and rewrites the firmware. Note it does not erase the LittleFS config partition, so follow it with Restore Defaults if you also want to clear the saved config. See Flashing the Firmware.

---

Still stuck? Capture a #L09 dump and the boot banner, and open an issue on the repository.