Hardware Peripheral Drivers
Section titled “Hardware Peripheral Drivers”Purpose
Section titled “Purpose”The Hardware_Peripheral_Drivers module is the Hardware Abstraction Layer (HAL) for all on-board peripheral devices across the supported ESP32 and ESP32-S3 board family. It provides self-contained, board-agnostic C drivers for every hardware peripheral — displays, touch controllers, physical inputs, I/O expanders, buses, sensors, and the buzzer — with board-specific wiring injected at runtime through typed configuration structures.
The module is shared across all board variants (boards/*/components/bsp/) without modification. Each Board Support Package (BSP) selects, configures, and composes these drivers in its board_init.c.
Architecture Overview
Section titled “Architecture Overview”Sub-Module Architecture
Section titled “Sub-Module Architecture”Display Driver Stack
Section titled “Display Driver Stack”Three parallel-bus families are supported. Each implements the standard esp_lcd_panel_t vtable, allowing LVGL and the BSP to call the same uniform panel API regardless of the underlying controller.
| Family | Framebuffer | Flush trigger | Boards |
|---|---|---|---|
| SPI | Controller GRAM | on_color_trans_done ISR | pibot_pendant_v1_0, esp32_2432s028r, esp32_3248s035*, esp32s3_bzm_tft35_gt911, ESP32_S3_TOUCH_LCD_1_47 (JD9853), ESP32_S3_LCD_1_47B (ST7789) |
| I80 | Controller GRAM | notify_flush_ready ISR | esp32s3_hmi43v3, esp32s3_zx3d50ce02s_usrc_4832 |
| RGB | ESP32-S3 PSRAM | VSync semaphore | esp32s3_4827s043c, esp32s3_8048s043c, esp32s3_8048s050c, esp32s3_8048s070c, esp32s3_8048_touch_lcd_7 |
Touch and Input Stack
Section titled “Touch and Input Stack”Sound — Two-Layer Stack
Section titled “Sound — Two-Layer Stack”The former Buzzer class (esp3d_buzzer.h) is replaced by the sound module: callers play a semantic event (ESP3DSoundEvent::selection, error, startup, …) and the backend interface keeps the door open for an audio decoder later. See sound_system.md.
Native USB Device (ESP32-S2 / S3)
Section titled “Native USB Device (ESP32-S2 / S3)”hardware/drivers_usb_device/usb_cdc_device/ is the sole owner of TinyUSB (espressif/esp_tinyusb ^1): driver installation, descriptors, two CDC-ACM interfaces and the low-level RX/TX primitives. CDC #0 (USB_CDC_DEVICE_PORT_COMMAND) carries the ESP3D command / monitoring client (or the CNC output with [ESP950]USB-CDC); CDC #1 (USB_CDC_DEVICE_PORT_LOG) carries the log backend. usb_cdc_device_init() is idempotent and the driver is never uninstalled at runtime. Once installed, TinyUSB owns the USB PHY: USB-Serial-JTAG and esptool auto-reset are gone, flashing needs BOOT + RESET. Only boards that set BOARD_USB_CDC_DEVICE_SUPPORTED add this component (USB_CDC_DEVICE_SERVICE). Study: usb_device_cdc_client_study.md. It is not the USB host (OTG) driver used for a USB-serial CNC link (hardware/drivers_usb_otg/, see usb_serial).
AXS5106L note — unlike the other touch drivers (legacy I²C API through bus_i2c), it uses the new driver/i2c_master.h API: the 1.47” BSP creates the bus with i2c_new_master_bus() and passes the handle in touch_axs5106_config_t.i2c_bus (see i2c_new_api_migration.md). The controller does not support an I²C repeated start: the driver writes the register address, then reads in a separate transaction (i2c_master_transmit_receive did not work on hardware, as in the Waveshare reference).
Key Design Constraints
Section titled “Key Design Constraints”| Constraint | Applies to |
|---|---|
| No heap allocation in drivers — all state is static | All sub-modules |
| Single driver instance per chip type — singleton pattern | IO expanders, touch, sensor |
| No blocking in LVGL task (Core 1) — ISR-only flush signals | Display drivers (SPI, I80, RGB) |
FreeRTOS-safe ISRs — only xQueueSendFromISR / volatile flags | Encoder PCNT ISR, touch INT ISRs |
I²C bus deduplication — s_installed[] guard prevents double-init | bus_i2c |
| ADC2 / WiFi conflict — always use ADC1 when WiFi active | sensor_analog, phy_potentiometer |
Core Components Documentation
Section titled “Core Components Documentation”| Sub-Module | Documentation |
|---|---|
| Display — SPI (ILI9341, ST7796S, JD9853, ST7789, backlight) | docs/architecture/display_drivers.md |
| Display — I80 parallel (RM68120, ST7796-i80) | docs/architecture/display_drivers.md |
| Display — RGB parallel (EK9716, ILI9485, ST7262) | docs/architecture/display_drivers.md |
| Touch controllers (FT5x06, FT6336U, GT911, XPT2046, AXS5106L) | docs/architecture/display_drivers.md, docs/architecture/Input_system.md |
| Bus drivers (bus_i2c, bus_sw_spi) | docs/architecture/display_drivers.md |
| Physical inputs (buttons, encoder, potentiometer, switch) | docs/architecture/Input_system.md |
| I/O expanders (CH422G, TCA9554) | docs/architecture/shared_sd_mechanism_V2.0.md |
| Analog sensor (ADC oneshot) | docs/features/features.md |
| Sound (LEDC driver + sound module) | docs/architecture/sound_system.md, docs/Factory/factory_app_technical_doc.md (factory buzzer) |
| Native USB CDC device (TinyUSB) | docs/ongoing_reflection/usb_device_cdc_client_study.md |
| Board build guidelines and porting | docs/guides/board_build_guidelines.md |
| ESP32 memory constraints | docs/guides/esp32_memory_constraints.md |
| UI resources (icons, fonts, partition) | docs/ui_resources/development.md |
Legacy documents (phase-1 naming duplicates)
Section titled “Legacy documents (phase-1 naming duplicates)”- sensor_analog
- physical_inputs
- display_drivers_spi
- display_drivers_i80
- display_drivers_rgb
- touch_controllers