Flashing & Serial

Symptom	Likely cause & fix
Port doesn't appear in the web flasher or terminal	Charge-only USB cable — swap to a known data cable. Close any other program holding the port (only one owner at a time).
Web flasher won't connect at all	Use Chrome or Edge on desktop; Web Serial isn't available in Safari, Firefox, or on mobile.
Flash fails or stalls	Put the board in download mode: hold BOOT, tap RESET, release BOOT, then retry.
Flashes fine but won't boot / crashes	Wrong target. Rebuild for the consumer chip: idf.py set-target esp32c5.
Console shows nothing after connect	Press RESET to see boot logs; confirm the terminal is on the POOM port at 115200 baud.

SD Card & Captures

Symptom	Likely cause & fix
SD not detected / FILES empty	Reseat the card; format as FAT32; the mount point is /sdcard (SPI mode).
Capture starts but no file is written	No SD present — the sniffer falls back to UART streaming. Insert a card for a .pcap file.
Lua script "not found"	Scripts must be under /sdcard with an absolute path (e.g. /sdcard/main.lua).
Portal doesn't appear in CAPTIVE	Put a root.html under /portals on the SD card before starting.

Wireless, BLE & NFC

Symptom	Likely cause & fix
CLI: "Command not found"	Typo, or the command isn't in this build. Run help to list what's actually available.
cfg-154-* says "not supported"	The 802.15.4 radio is only on esp32c5. Confirm your target.
Zigbee capture is empty	Wrong channel. Use cfg-154-hop-start to find activity, then pin it with cfg-154-ch.
BLE device won't pair	Remove/forget POOM on the host first, then re-pair. Only one host connects at a time.
NFC won't scan a tag	Run nfc-start first, select the right technology (nfc-tech/nfc-a), and hold the tag steady on the antenna. Try nfc-tune-auto.
IR replay doesn't trigger the device	IR is line-of-sight — aim directly and get closer. Only NEC is decoded currently.

Frequently Asked Questions

Do I need the cable after the first flash? No — use the wireless updater. See OTA / DFU Updates.

Which board target do I have? If unsure, check the silkscreen/marketing for ESP32-C5, and match idf.py set-target accordingly. A wrong target simply won't boot.

Where do captures, dumps and scripts live? On the SD card: PCAP captures, NFC dumps, CAPTIVE portals (/portals), captured portal data (/captive_data), and Lua scripts (/sdcard/*.lua).

Is any of this legal to use? The tools are for authorized testing, controlled labs, and defensive research only. Use them exclusively on devices and networks you own or are explicitly permitted to assess.

Can I add features without rebuilding firmware? Yes — write a Lua script for small automations, or drive the device from the CLI.

How do I reset stored settings? Credentials and config live in the nvs partition; a full USB re-flash that erases NVS clears them (otherwise they persist across app updates).

Still Stuck?

Cross-check the Hardware Reference for pinout and storage, and the Technologies Matrix to confirm a feature is present in your build. For build-from-source issues, revisit Getting Started & Flashing.