Troubleshooting
Start with the symptom you can observe. Apply one change at a time, then retry the smallest Quick Start example.
| Symptom | Check | Fix |
|---|---|---|
| Board does not appear as a serial port | CH340K driver not installed | Install the CH340 driver for your OS, then reconnect the USB-C cable. Linux needs no separate driver. |
| Upload fails, or the wrong board is selected | Board target in the IDE | Select ESP32S3 Dev Module under Tools → Board → esp32 in Arduino IDE, or esp32s3 as the ESP-IDF target. |
| No output in the Serial Monitor | Wrong baud rate | Set the Serial Monitor to 115200 baud and reset the board. |
| PWR, PPS, Wi-Fi-on, or ADS-B-live LED stays off | The matching jumper (JP2-JP5) has been cut | Each status LED has its own jumper. Cutting it disables only that LED; it does not affect the board's function. |
| No aircraft ever appear | No antenna connected to the IPEX connector | Connect the included FXUB1900 antenna. The TT-SC1 receiver needs it to pick up any 1090 MHz signal. |
| No aircraft appear even with an antenna connected | No aircraft broadcasting ADS-B are currently in range | Reception depends on line of sight to transmitting aircraft. Try again later, or check a public ADS-B coverage map for your area. |
| MicroPython firmware boot loops with "Invalid image block, can't boot" | The flash write did not fully complete, or the wrong firmware variant was used | Re-run esptool.py write_flash, confirm it ends with "Hash of data verified", and make sure you flashed the SPIRAM_OCT build for this board's octal-PSRAM module. |
mpremote fails with "could not enter raw repl" right after flashing | The serial port has not settled yet from esptool's reset | Run the same mpremote command again. If it still fails, press the board's reset button once and retry. |
idf.py is "not recognized as an internal or external command" | The ESP-IDF environment is not activated in this terminal | Use the ESP-IDF Command Prompt/ESP-IDF PowerShell shortcut on Windows, or run . $HOME/esp/esp-idf/export.sh on Linux/macOS, before running idf.py. This is per-terminal, not a one-time setup step. |