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.
• Connect opens a method modal — pick USB for a direct tether, Via WCB to relay through a USB‑tethered WCB gateway, or Shared port to join a port another same‑origin browser tab already owns. See Connecting.
• Only one program can hold the raw serial port — but a second config‑tool (or WCB Wizard) tab on the same origin now shares one port instead of conflicting, so you don't have to close it; use Shared port to join. A non‑sharing program (Arduino IDE Serial Monitor, another terminal) still blocks the port — close that.
• 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 is a WCB ID 1–20 (broadcast isn't supported). NaviCore no longer specifies a port; it sends ;H,… and the receiving WCB routes it to its own configured HCR port (set on that WCB with ?HCR,PORT). See WLED and HCR Audio.

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.
• Discrete servo commands to a Remote slot now go WCB‑native: NaviCore sends a ;M<dev>,<verb> text verb (e.g. ;M12,setTarget,0,6000) and the WCB builds the Pololu frame itself. It's unicast to the WCB that advertises that device number over WDP, so:
  • the receiving WCB firmware must support the native Maestro verb (a recent WCB build) and have a Maestro port configured — check with ?MAESTRO;
  • that WCB must have advertised the device# over WDP. If WDP hasn't converged yet, NaviCore falls back to the legacy raw broadcast, which needs Kyber forwarding enabled on the WCB (?KYBER,REMOTE; check ?KYBER,LIST doesn't say "Not used"). Passthrough / scrub / replay streams also stay on the raw path.
• 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.

WLED doesn't light up

• WLED rides NaviCore's per‑id routing table (buttons/switches fire a ;L<id>,<verb> command). Check the slot in Config → WLED: it needs the right WLED id (1–9) and a valid destination.
• Local WLED: the slot's transport is a local aux port (S3/S4/S5). WLED wants 115200 baud, which only S3 (hardware UART0) drives reliably — S4/S5 are bit‑banged SoftwareSerial. Put a local WLED on S3 and set that port to 115200 in Config → Aux Serial.
• Remote WLED: the slot targets a WCB ID 1–20; that WCB must have its own WLED configured. NaviCore forwards the full ;L<id>,… string to it.
• A bare ;L, command acts on this board's lowest‑id local WLED; if none is configured it's a no‑op. Confirm the id in your action matches a configured slot.
• See WLED and HCR Audio.

Record won't capture / clip won't replay

• Recording buffers dispatched actions in PSRAM. If ?REC,START answers busy / no buffer, either a record/replay is already running (?REC,STOP first) or the PSRAM buffer couldn't be allocated — confirm the board actually has PSRAM.
• Saved clips persist to a separate LittleFS "clips" partition, independent of /config.json. Run ?REC,LS to list clips and see partition usage — a full clips partition can make SAVE fail. Remove old clips with ?REC,RM,<name>.
• See Record and Replay.

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.

See also: Connecting · Config Tool Guide · CLI Commands · Failsafe and Signal Loss