First Flash

This tutorial takes you from an unboxed board to a running program. You will connect the board, enter download mode, flash a simple demo, and verify the output over the serial monitor.

Connect the board

1. Locate the Type-C UART port on the board. This is the port used for programming and serial output. It is labeled on the silkscreen — do not confuse it with the Type-C USB OTG port.

2. Connect a USB Type-A to Type-C cable between your computer and the Type-C UART port.

3. Verify the connection:

   Linux

   ls /dev/ttyUSB* /dev/ttyACM*

   You should see a new device, typically /dev/ttyUSB0 or /dev/ttyACM0.

   If no device appears, install the CH343 or CP210x driver for your kernel. The board uses a USB-to-UART bridge chip.

   macOS

   ls /dev/cu.usbserial-* /dev/cu.usbmodem*

   You should see a new serial device listed.

   If nothing appears, install the CH343 macOS driver from WCH.

   Windows

   Open Device Manager and expand Ports (COM & LPT). You should see a new COM port (e.g., COM3).

   If the device shows with a warning icon, download and install the CH343 Windows driver from WCH.

Enter download mode

The ESP32-P4 must be in download (bootloader) mode to receive firmware over UART.

1. Hold the BOOT button on the board.

2. While holding BOOT, press and release the RST (reset) button.

3. Release the BOOT button.

The board is now in download mode. There will be no visible indication on the board itself — this is normal. The serial port will still be enumerated by your OS.

When is download mode needed?

You only need to manually enter download mode if automatic reset is not working. Most USB-UART bridge chips support automatic bootloader entry via RTS/DTR signaling. If your flashing tool can reset the board automatically, you can skip the manual button sequence.

Build and flash

ESP-IDF (VSCode)

1. Open the hello_world example project you created during ESP-IDF setup.

2. In the VSCode status bar at the bottom, verify the target chip is set to ESP32-P4.

3. Click the serial port selector in the status bar and choose the port your board is connected to (e.g., /dev/ttyUSB0 or COM3).

4. Click the Build button (or press Ctrl+E then B). Wait for the build to complete successfully.

   Project build complete. To flash, run:
    idf.py flash

5. Click the Flash button (or press Ctrl+E then F). The tool will upload the firmware to the board.

6. When the flash completes, press the RST button on the board to start the program.

Alternatively, from the ESP-IDF terminal:

idf.py set-target esp32p4
idf.py build
idf.py -p /dev/ttyUSB0 flash
idf.py -p /dev/ttyUSB0 monitor

Arduino IDE

1. Open a simple sketch. If you do not have one ready, use this minimal example:

   void setup() {
     Serial.begin(115200);
     delay(1000);
     Serial.println("ESP32-P4 is running!");
   }
   
   void loop() {
     Serial.println("Hello from ESP32-P4");
     delay(2000);
   }

2. Go to Tools > Board and select ESP32P4 Dev Module.

3. Go to Tools > Port and select the correct serial port.

4. Click Upload (right-arrow icon). Arduino IDE will compile the sketch and flash it to the board.

5. When the upload completes, the board resets automatically and begins running the sketch.

Verify the output

1. Open the serial monitor:

   • ESP-IDF: Click the Monitor button in the status bar, or run idf.py -p /dev/ttyUSB0 monitor.
   • Arduino: Go to Tools > Serial Monitor and set the baud rate to 115200.

2. You should see output from your program:

   Hello from ESP32-P4
   Hello from ESP32-P4
   Hello from ESP32-P4

3. If you have a display connected, display demos will render on the screen after flashing the appropriate firmware. See the Display guide for details.

Exit the serial monitor

In ESP-IDF, press Ctrl+] to exit the monitor. In Arduino IDE, simply close the Serial Monitor window.

Troubleshooting

Serial port not found

Symptom	Cause	Fix
No /dev/ttyUSB* or COM port appears	Missing USB-UART driver	Install the CH343 or CP210x driver for your OS (links above)
Device appears then disappears	Damaged or charge-only cable	Try a different USB cable — it must support data transfer
Permission denied (Linux)	User not in dialout group	Run sudo usermod -aG dialout $USER and log out/in

Flash fails

Symptom	Cause	Fix
”Failed to connect”	Board not in download mode	Repeat the BOOT + RST button sequence
”Timed out waiting for packet header”	Wrong serial port selected	Check the port selection in your IDE
”Wrong chip/target”	Target set to wrong ESP32 variant	Set target to ESP32-P4 specifically
Flash succeeds but program does not start	Board stuck in download mode	Press the RST button to restart normally

Build errors

Symptom	Cause	Fix
”Toolchain not found”	ESP-IDF installation incomplete	Re-run the EXPRESS setup wizard in VSCode
Missing component errors	ESP-IDF version too old	Upgrade to v5.3.1 or later
Arduino “Board not supported”	Board package too old or missing	Install esp32 board package v3.2.0+

Note

If you encounter issues not covered here, check the Waveshare wiki FAQ section for board-specific troubleshooting, or the ESP-IDF GitHub issues for framework-level problems.

What to do next

Your board is flashed and responding. From here you can explore the peripheral guides:

• Display (MIPI-DSI) — connect a screen and build a UI
• Camera (MIPI-CSI) — capture images and video
• Audio System — play and record audio
• WiFi 6 and Bluetooth — get connected wirelessly