This board pack describes Waveshare hardware using Board Manager YAML files and board-specific setup code. It follows the component-pack workflow in demo_boards, with Waveshare definitions, bilingual documentation, and generation/build checks.
 |
ESP32-S3-Touch-AMOLED-1.75C Board definition · Product documentation |
 |
ESP32-S3-Touch-AMOLED-1.8 Board definition · Product documentation |
 |
ESP32-S3-Touch-AMOLED-2.16 Board definition · Product documentation |
 |
ESP32-S3-Touch-LCD-7 Board definition · Product documentation |
 |
ESP32-S3-LR1121-OLED-1.54-XF Board definition · Product documentation |
||
|
ESP32-S3-LR1121-ePaper-2.9 Board definition · Product documentation |
 |
ESP32-P4-NANO-WIFI6-DB Board definition · Product documentation |
 |
ESP32-P4-WIFI6-DB Board definition · Product documentation |
 |
ESP32-P4-NANO Board definition · Product documentation |
 |
ESP32-P4-WIFI6 Board definition · Product documentation |
 |
ESP32-P4-WIFI6-Touch-LCD-4B Board definition · Product documentation |
 |
ESP32-P4-WIFI6-Touch-LCD-7B Board definition · Product documentation |
 |
ESP32-P4-WIFI6-Touch-LCD-3.5 Board definition · Product documentation |
 |
ESP32-P4-WIFI6-Touch-LCD-4.3 Board definition · Product documentation |
 |
ESP32-P4-WIFI6-Touch-LCD-X Board definition · Product documentation |
 |
ESP32-P4-WIFI6-Touch-LCD-XC Board definition · Product documentation |
 |
ESP32-P4-Knob-Touch-AMOLED-1.75 Board definition · Product documentation |
|
ESP32-S31-Touch-LCD-4.3C Board definition · Product documentation |
Some boards support display configuration with -a.
Device and peripheral definitions
The table lists definitions present in this repository. Peripheral declarations
such as spi_sd describe a bus; they do not imply a complete storage application.
| Board | Chip | Device definitions | Peripheral definitions |
|---|---|---|---|
esp32_p4_knob_touch_amoled_1_75 |
ESP32-P4 | display_lcd, lcd_touch, audio_dac, audio_adc, fs_spiffs, fs_sdcard, wireless |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_knob_cw, gpio_knob_ccw, gpio_haptic_in1, gpio_haptic_in2, gpio_boot, gpio_power, gpio_rtc_int, gpio_imu_int1, gpio_imu_int2, ldo_mipi, dsi_display |
esp32_p4_nano |
ESP32-P4 | audio_dac, audio_adc, sdcard_power_ctrl, fs_sdcard, display_lcd, lcd_brightness, fs_spiffs, lcd_touch, camera |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display |
esp32_p4_nano_wifi6_db |
ESP32-P4 | audio_dac, audio_adc, camera, display_lcd, lcd_brightness, fs_spiffs, sdcard_power_ctrl, fs_sdcard, lcd_touch |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display |
esp32_p4_wifi6 |
ESP32-P4 | camera, audio_dac, audio_adc, display_lcd, lcd_brightness, fs_spiffs, lcd_touch, fs_sdcard, sdcard_power_ctrl |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display |
esp32_p4_wifi6_db |
ESP32-P4 | camera, audio_dac, audio_adc, display_lcd, lcd_brightness, fs_spiffs, lcd_touch, fs_sdcard, sdcard_power_ctrl |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display |
esp32_p4_wifi6_db_poe_eth |
ESP32-P4 | camera, audio_dac, audio_adc, display_lcd, lcd_brightness, fs_spiffs, lcd_touch, fs_sdcard, sdcard_power_ctrl |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display |
esp32_p4_wifi6_touch_lcd_3_5 |
ESP32-P4 | audio_dac, audio_adc, fs_spiffs, fs_sdcard, display_lcd, lcd_touch, lcd_brightness, camera |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, ldo_mipi, spi_lcd, ledc_backlight |
esp32_p4_wifi6_touch_lcd_4_3 |
ESP32-P4 | audio_dac, audio_adc, fs_spiffs, sdcard_power_ctrl, fs_sdcard, display_lcd, lcd_touch, lcd_brightness, camera |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display, ledc_backlight |
esp32_p4_wifi6_touch_lcd_4b |
ESP32-P4 | audio_dac, audio_adc, fs_spiffs, sdcard_power_ctrl, fs_sdcard, display_lcd, lcd_touch, lcd_brightness, camera |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display, ledc_backlight |
esp32_p4_wifi6_touch_lcd_7b |
ESP32-P4 | fs_sdcard, sdcard_power_ctrl, audio_adc, audio_dac, camera, display_lcd, lcd_touch, lcd_brightness, fs_spiffs |
gpio_sd_power, i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, ldo_mipi, dsi_display, ledc_backlight |
esp32_p4_wifi6_touch_lcd_x |
ESP32-P4 | audio_dac, audio_adc, fs_spiffs, fs_sdcard, display_lcd, lcd_touch, lcd_brightness, camera |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, ldo_mipi, dsi_display, ledc_backlight |
esp32_p4_wifi6_touch_lcd_xc |
ESP32-P4 | audio_dac, audio_adc, fs_spiffs, sdcard_power_ctrl, fs_sdcard, display_lcd, lcd_touch, backlight_power_ctrl, lcd_brightness, camera |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, gpio_sd_power, ldo_mipi, dsi_display, ledc_backlight, gpio_backlight_control |
esp32_s31_touch_lcd_4_3c |
ESP32-S31 | display_lcd, lcd_touch, lcd_brightness, sdcard_power_ctrl, fs_sdcard, audio_dac, audio_adc, rtc_pcf85063, imu_qmi8658, bat_bq27220, canfd |
i2c_master, i2s_audio_out, i2s_audio_in, ledc_backlight, gpio_sd_power, gpio_power_amp, uart_rs485 |
esp32_s3_lr1121_epaper_2_9 |
ESP32-S3 | status_led, epaper_power_ctrl, epaper_ssd16xx, rtc_pcf85063a, bat_axp2602, radio_lr1121 |
i2c_master, spi_shared, gpio_boot, gpio_epaper_power |
esp32_s3_lr1121_oled_1_54_xf |
ESP32-S3 | button_boot, button_power, button_menu, button_ptt, button_rtc_irq, radio, oled, rtc, battery, audio, sdcard |
i2c_main, spi_radio, gpio_boot, gpio_power, gpio_menu, gpio_ptt, gpio_rtc_irq, gpio_amplifier, gpio_radio_cs, gpio_radio_irq, gpio_radio_reset, gpio_radio_busy, i2s_speaker, i2s_microphone |
esp32_s3_touch_amoled_1_75c |
ESP32-S3 | axp2101_power_manager, audio_dac, audio_adc, display_lcd, lcd_touch |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, spi_display |
esp32_s3_touch_amoled_1_8 |
ESP32-S3 | gpio_expander, axp2101_power_manager, audio_dac, audio_adc, display_lcd, lcd_touch, fs_sdcard |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, spi_display |
esp32_s3_touch_amoled_2_16 |
ESP32-S3 | axp2101_power_manager, audio_dac, audio_adc, display_lcd, lcd_touch, fs_sdcard |
i2c_master, i2s_audio_out, i2s_audio_in, gpio_pa_control, spi_display |
esp32_s3_touch_lcd_7 |
ESP32-S3 | display_lcd, lcd_touch |
i2c_master, uart_rs485, uart_external, adc_sensor, spi_sd |
Definitions live under boards/<full_model>/. The three AMOLED profiles come
from Espressif Brookesia; see board revisions and migration notes.
CI validates generation and compilation; physical operation requires board testing.
The LR1121 OLED XF profile provides hardware definitions and requires application-side custom device adapters; see its support scope.
The LR1121 ePaper 2.9 profile defines the display, radio, RTC, battery gauge and status LED. Custom devices require application-side adapters; see its support scope.
ESP32-S31-Touch-LCD-4.3C uses target esp32s31; the ESP32-S3 quick-start commands
below do not apply to it. See board notes
for preview/development toolchain requirements, initialization and current CI limits.
ESP32-P4-Knob-Touch-AMOLED-1.75 uses target esp32p4. Its SD card, wireless
co-processor and SPIFFS entries have application-side prerequisites; see
its support scope.
Activate ESP-IDF first. For a local checkout, clone this pack into an existing ESP-IDF application's component directory:
mkdir -p components
git clone https://github.com/waveshareteam/waveshare_boards.git components/waveshare_boards
python -m pip install esp-bmgr-assist==0.8.3
idf.py set-target esp32s3
idf.py bmgr -l
idf.py bmgr -b esp32_s3_touch_lcd_7
idf.py buildUse the Component Manager version from the active IDF environment; the tested versions for each IDF line are listed in the CI guide.
set-target resolves the pack dependencies before discovery. In an already
configured ESP32-S3 application, use idf.py reconfigure instead to preserve
its configuration.
Keep the local directory name waveshare_boards: ESP-IDF uses the directory name as
the component name. The pack declares espressif/esp_board_manager as a public
dependency. Applications can include esp_board_manager.h and initialize the
selected board using esp_board_manager_init().
Published versions can be installed from the registry:
idf.py add-dependency "waveshare/waveshare_boards"
idf.py reconfigure
idf.py bmgr -lFind available versions in the Component Registry.
Some boards provide display amendments selected with -a:
| Board | Display amendment |
|---|---|
esp32_p4_wifi6_touch_lcd_x |
lcd_7_dsi_touch_a, lcd_8_dsi_touch_a |
esp32_p4_wifi6_touch_lcd_xc |
lcd_3_4_dsi_touch_c |
For example, select the 7-inch configuration in an ESP32-P4 application:
idf.py bmgr -b esp32_p4_wifi6_touch_lcd_x -a lcd_7_dsi_touch_aRe-run the command after changing the board or amendment. Without an amendment,
esp32_p4_wifi6_touch_lcd_x uses its 10.1-inch base configuration.
ESP32-P4 boards with an external MIPI-DSI connector (esp32_p4_nano,
esp32_p4_nano_wifi6_db, esp32_p4_wifi6, esp32_p4_wifi6_db, and
esp32_p4_wifi6_db_poe_eth) can use the shared
DSI display overlays for 5_dsi_touch_a,
7_dsi_touch_c, 8_dsi_touch_a, 10_1_dsi_touch_a, and 10_1_dsi_touch_b.
The overlay path is resolved relative to the selected board directory:
idf.py bmgr -b esp32_p4_wifi6_db -a ../esp32_p4_dsi_overlay/7_dsi_touch_cSee the Board Manager amend guide.
boards/<full_model>/ Board metadata, peripherals, devices, and setup code
include/ Framework-independent AMOLED brightness helper
idf_component.yml Component metadata and managed dependencies
CMakeLists.txt Board-pack component registration
ci/test_app/ Board Manager integration compile test
ci/scripts/ Discovery, change routing, and validation tests
ci/versions.json Exact ESP-IDF and Python tooling versions
scripts/ Generated board catalog maintenance
docs/ Board revisions, CI, and registry publication guides
.github/ Workflows and contribution templates
The integration test is maintained under ci/; this repository currently has
no first-party application examples, Arduino sketches, or delivery firmware.
python scripts/update_supported_boards_table.py
python ci/scripts/board_pack.py check
python -m unittest discover -s ci/scripts -p 'test_*.py' -vUse one boards/ container and keep the chip prefix in each model name. Do not
add another chip/category directory: the layout must fit Board Manager scanning
from an application's components/ root. Each model directory must match its
unique board value. The catalog is regenerated from the definitions.
- Board organization, hardware revisions, and migration
- AMOLED brightness control
- CI coverage and local validation
- Registry credentials and publication
- Contributing
- Support
- ESP Board Manager documentation
Apache License 2.0, with imported files retaining their original SPDX notices, including CC0-1.0. See source attribution.