Troubleshooting
Start with the symptom you can observe. Apply one change at a time, then retry the smallest Quick Start example.
Connection and upload
The board does not show up as a port
Some USB cables only carry power. Try a cable you know transfers data, and plug it straight into the computer rather than through a hub. The board talks to your computer through a CH340K USB-to-serial chip, so install the CH340 driver if your system does not recognise it.
The upload fails or cannot connect
Check that Tools → Board and Tools → Port match this board. Close anything else that has the port open (Serial Monitor or another terminal), because only one program can use it at a time. If it still fails, put the board into bootloader mode and upload again: hold the USER button, press and release RESET, then release USER.
Serial output
Serial Monitor shows random characters
The baud rate in Serial Monitor does not match the one in the sketch. Set the
dropdown in the corner of Serial Monitor to the value in Serial.begin().
Serial Monitor stays empty
Press the board's RESET button with Serial Monitor open: the sketch may
have printed before the monitor connected. Also check that Tools → USB CDC
On Boot is Disabled. This board's USB-C connector reaches the ESP32-S3
through the CH340K on UART0, so Serial has to stay on UART0.
The MicroPython REPL does not respond
Press Ctrl-C to stop a running program, then Ctrl-D for a soft reset.
If there is still no >>> prompt, check that the terminal is set to 115200
baud, close other programs using the port, and check that you flashed the
ESP32_GENERIC_S3 firmware with Octal-SPIRAM support (SPIRAM_OCT), the one
for this board's module.
Power and voltage
The board resets on its own, often when Wi-Fi starts
The supply cannot keep up with the current peaks, and the chip restarts when the voltage dips (on an ESP32 the log says the brownout detector was triggered). Use a USB port on the computer itself or a powered hub, a shorter cable, or a charged battery.
A connected sensor or module does not work
The GPIO pins use 3.3 V logic. A 5 V signal on a GPIO pin can damage the board, so connect 5 V parts through a level shifter, and power each part from the voltage its own documentation asks for.
Nothing lights up, or the board gets warm
Unplug it straight away and disconnect everything wired to it. Look for a
short between power and ground, then reconnect one part at a time. If a
battery is connected, check its polarity against the + and - marking next
to the connector: battery plugs from different makers are not all wired the
same way.
First program
The upload worked but the LED does not light
The RGB LED is a WS2812B on GPIO6. It needs colour data, which
rgbLedWrite() sends, and the generic board's LED_BUILTIN points at GPIO48,
not at this LED. Use rgbLedWrite(6, ...) as in the Quick Start, and check
that nothing else is wired to the 6 header pin, which is the same line.
Board-specific issues
CAN works on USB but not on battery
The CAN transceiver needs 4.5 to 5.5 V, which it takes from USB or from the
VCC pin. On battery power alone it switches off on undervoltage, while the
ESP32-S3 keeps running. Power the board over USB-C, or feed 4.5 to 5.5 V into
VCC, whenever it needs to talk on the bus.
You need to remove the board's CAN termination
The board connects a 120 Ω termination resistor between CAN_H and CAN_L by default. Cut JP3 on the underside to remove it. See Jumpers in Hardware Details.