Waveshare ESP32-P4 Platform

Examples and bring-up resources for Waveshare ESP32-P4 development boards

中文 · 🌐 ESP32-P4 Products · 📚 Product Documentation · 🧩 ESP-IDF Examples · 🔧 Arduino Examples

---

✨ Overview

This repository collects first-party ESP-IDF and Arduino examples for the Waveshare ESP32-P4 development board family. The examples cover GPIO, I2C, Wi-Fi, Ethernet, SD card, audio codec, display, LVGL, camera, video streaming, and ESP-Brookesia UI workflows.

Because this is a multi-board platform repository, select your board below and use its official product documentation for hardware-specific setup, interfaces, and accessories.

The firmware/ tree contains the ESP-Brookesia source project and prebuilt factory firmware packages. See Firmware for the boundary between them.

🤝 Supported Boards

Select a product image to open its store page, or use the documentation link below each board for setup and hardware details.

ESP32-P4-NANO Documentation	ESP32-P4-Module-DEV-KIT Documentation	ESP32-P4-WIFI6-DEV-KIT Documentation	ESP32-P4-WIFI6 Documentation
ESP32-P4-ETH Documentation	ESP32-P4-Pico Documentation	ESP32-P4-WIFI6-POE-ETH Documentation	ESP32-P4-Core-DEV-KIT Documentation

🗂️ Repository Layout

Path	Purpose
examples/esp-idf/	First-party ESP-IDF projects
examples/arduino/	First-party Arduino sketches and bundled libraries
firmware/	ESP-Brookesia source firmware and prebuilt factory firmware packages
assets/	Product images used by the documentation
config/	Shared ESP-IDF configuration overlays
docs/	Getting-started, example, CI, and maintainer documentation
.github/	CI workflows and contribution templates

Start with docs/GETTING_STARTED.md if this is your first time using the repository. See docs/PROJECT_STRUCTURE.md for more details about where new examples and documentation should live.

📚 Documentation

Document	Audience	Purpose
ESP32-P4 Product Documentation	All users	Official board setup and hardware documentation
Getting Started	Beginners	First build, flash, and monitor workflow
Examples Guide	All users	Choose examples by difficulty and peripheral
Arduino Guide	Arduino users	Board settings, bundled libraries, and example index
Firmware	All users	Source firmware and prebuilt factory package boundaries
ESP32-P4 Revision Config	All users	Use default rev3_x/v3.00+ or explicit legacy rev1_3/pre-v3 profiles
Troubleshooting	All users	Build, flash, runtime, and peripheral checks
Continuous Integration	Contributors	GitHub Actions coverage for ESP-IDF and Arduino examples
Managed Components	Contributors	Dependency policy and example-local component classification
P4 + C6 Hosted Wi-Fi	Network users	Version lanes, firmware boundary, and runtime validation
Example Roadmap	Contributors	Suggested examples that would improve coverage
Project Structure	Contributors	Repository layout and example expectations

🚀 Quick Start

ESP-IDF Examples

1. Install an ESP-IDF version listed in the CI guide. Check the selected example's README for any additional version requirements.
2. Clone this repository.
3. Start with 00_board_check if you are new to the board or this repository.
4. Set the target and build:

cd examples/esp-idf/00_board_check
idf.py set-target esp32p4
idf.py build

5. The default profile is rev3_x/MIN_300 for v3.x silicon. For pre-v3 silicon, including v1.3, explicitly select legacy rev1_3/MIN_100 with SELECTS_REV_LESS_V3; do not reuse generated sdkconfig or binaries between profiles. Read ESP32-P4 Revision Config before flashing.
6. Flash and monitor, replacing PORT with your serial port:

idf.py -p PORT flash monitor

Run idf.py menuconfig before building examples that need board-specific settings, network credentials, display options, camera sensors, or PHY configuration.

Arduino Examples

The Arduino examples are under examples/arduino. Start with examples/arduino/README.md for the recommended Arduino-ESP32 core, bundled LVGL version, Arduino_GFX version, and the I2C driver compatibility note.

🛠️ Toolchains and CI

Surface	Repository coverage	CI status
ESP-IDF	First-party projects under examples/esp-idf/	Built for ESP-IDF v5.5.5 and v6.0.2 on target esp32p4
Arduino	First-party sketches and bundled libraries under examples/arduino/	Compiled with Arduino-ESP32 3.3.11, PSRAM, and default ChipVariant=postv3 (v3.00+, 400 MHz); legacy pre-v3/v1.3 uses explicit prev3/360 MHz; successful builds produce split-file diagnostic artifacts, but still require ESP32-P4 hardware validation

The ESP-IDF examples workflow discovers changed projects automatically and also supports manual runs for one example or the full matrix. The Arduino examples workflow does the same for the nine first-party sketches while excluding examples bundled inside libraries. See Continuous Integration for details.

🧪 Example Index

No.	Example	Area
00	board_check	First-run board and toolchain check
01	HowToCreateProject	Minimal ESP-IDF project layout
02	HelloWorld	Basic ESP-IDF application
03	nvs_counter	Persistent settings with NVS
04	freertos_tasks	Tasks and queues
05	gpio_io	GPIO input/output
06	gpio_interrupt	GPIO interrupt and debounce
07	uart_loopback	UART send/receive loopback
08	i2c_tools	I2C scanning and command-line tools
09	sdmmc	SD card and SDMMC
10	wifistation	Wi-Fi station connection
11	ethernetbasic	Ethernet bring-up
12	I2SCodec	I2S audio codec
13	Displaycolorbar	LCD display color bar
14	lvgl_demo_v9	LVGL v9 display demo
15	eth2ap	Ethernet-to-AP networking
16	video_lcd_display	Camera video to LCD
17	simple_video_server	HTTP camera streaming
18	esp_brookesia_phone	ESP-Brookesia phone UI
19	system_monitor	Serial diagnostics and runtime monitor

For a fuller map of ESP-IDF and Arduino examples, see examples/README.md and docs/EXAMPLES_GUIDE.md.

✅ ESP-IDF Compatibility Matrix

Legend: ✅ means the example is expected to run on that board. ❌ means the required peripheral is not available or is not supported by the example.

Note

This matrix summarizes the repository's current example support declarations. CI checks compilation; use the official product documentation above to verify board-specific interfaces and hardware setup.

No.	Example	ESP32-P4-NANO	ESP32-P4-Module-DEV-KIT	ESP32-P4-WIFI6-DEV-KIT	ESP32-P4-WIFI6	ESP32-P4-ETH	ESP32-P4-Pico	ESP32-P4-WIFI6-POE-ETH	ESP32-P4-Core-DEV-KIT
00	board_check	✅	✅	✅	✅	✅	✅	✅	✅
01	HowToCreateProject	✅	✅	✅	✅	✅	✅	✅	✅
02	HelloWorld	✅	✅	✅	✅	✅	✅	✅	✅
03	nvs_counter	✅	✅	✅	✅	✅	✅	✅	✅
04	freertos_tasks	✅	✅	✅	✅	✅	✅	✅	✅
05	gpio_io	✅	✅	✅	✅	✅	✅	✅	✅
06	gpio_interrupt	✅	✅	✅	✅	✅	✅	✅	✅
07	uart_loopback	✅	✅	✅	✅	✅	✅	✅	✅
08	i2c_tools	✅	✅	✅	✅	✅	✅	✅	✅
09	sdmmc	✅	✅	✅	✅	✅	✅	✅	❌
10	wifistation	✅	✅	✅	✅	❌	❌	✅	❌
11	ethernetbasic	✅	✅	✅	❌	✅	❌	✅	❌
12	I2SCodec	✅	✅	✅	✅	✅	✅	✅	❌
13	Displaycolorbar	✅	✅	✅	✅	✅	✅	✅	✅
14	lvgl_demo_v9	✅	✅	✅	✅	✅	✅	✅	✅
15	eth2ap	✅	✅	✅	❌	❌	❌	✅	❌
16	video_lcd_display	✅	✅	✅	✅	✅	✅	✅	✅
17	simple_video_server	✅	✅	✅	✅	✅, Ethernet	❌	✅	❌
18	esp_brookesia_phone	✅	✅	✅	✅	✅	✅	✅	✅
19	system_monitor	✅	✅	✅	✅	✅	✅	✅	✅

🤝 Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request. Useful contributions include:

• Fixing build issues on a supported board.
• Adding board-specific notes to an existing example README.
• Improving setup instructions or troubleshooting notes.
• Adding focused examples for peripherals that are not covered yet.

When reporting problems, please include the board name, ESP-IDF or Arduino-ESP32 version, sanitized serial logs, and the exact example path. Remove credentials, tokens, private network details, unique device identifiers, and local filesystem paths before posting logs publicly.

For support channel guidance, see SUPPORT.md.

🔒 Security

Do not publish vulnerability details in public issues. Use the actionable private reporting channel in SECURITY.md.

📦 Third-Party Code

Some examples include third-party components or libraries for convenience, including LVGL, Arduino_GFX, ESP-Brookesia-related components, and Espressif managed components. See THIRD_PARTY.md for the high-level inventory and check each bundled component for its own license file.

📄 License

This repository is licensed under the Apache License 2.0. See LICENSE.txt for details.