esp32s3_4827s043c — Board Support Package

Overview

The esp32s3_4827s043c module is the complete Board Support Package (BSP) for the ESP32-S3 board equipped with a 4.3-inch RGB parallel LCD panel (480 × 272 pixels, ILI9485 controller) and a GT911 capacitive touch controller. The board name encodes its key hardware: 48=480px wide, 27=272px tall, S043=4.3″ diagonal, C=Capacitive touch.

This BSP covers three layers:

Layer	Path	Purpose
Factory App	`boards/esp32s3_4827s043c/Factory/`	Self-contained recovery application for OTA and resource updates
BSP Component	`boards/esp32s3_4827s043c/components/bsp/`	Hardware abstraction for the main LVGL-based firmware
Build Scripts	`boards/esp32s3_4827s043c/build_scripts/`	Python variant management and build automation

Key Hardware Characteristics

MCU: ESP32-S3 (dual-core Xtensa, 240 MHz)
Display: RGB parallel panel, 480 × 272, ILI9485 — driven via esp_lcd_rgb_panel (not SPI)
Touch: GT911 capacitive controller over I2C (auto-calibrated resolution, up to 5 simultaneous touch points)
Flash: 16 MB (all shipping variants)
Physical inputs: None — buttons, encoder, and buzzer pins are all GPIO_NUM_NC; navigation is touch-only
SD card: SPI interface (used by Factory app for firmware/resource delivery)
Entry into recovery: Software-triggered only via [ESP444]FACTORY from the main firmware (no physical boot button)

Important: Because this board has no physical buttons, the Factory recovery UI draws virtual UP / DOWN / OK buttons at the bottom of the screen and maps touch hit-test regions to them. The BSP code that handles encoder, switch, and physical button events is compiled in (for portability across the board family) but is entirely inert at runtime on this hardware.

Architecture Overview

Display Architecture: RGB Parallel vs. SPI

This board uses an RGB parallel panel rather than the SPI panels found on older boards (ST7796, ILI9341). The difference is architecturally significant for the flush path:

Aspect	SPI Panel (e.g. ST7796)	RGB Parallel (ILI9485)
Bus	SPI (MOSI/CLK/CS)	Parallel RGB + HSYNC/VSYNC/PCLK/DE
Frame buffer ownership	None — CPU sends pixels on demand	Panel scans the frame buffer in SPIRAM autonomously
Tearing prevention	N/A (each SPI transfer is atomic)	Requires VSYNC synchronization
LVGL flush signal	`notify_lvgl_flush_ready` in DMA done callback	Semaphore pair coordinated with VSYNC ISR
PSRAM requirement	Optional	Mandatory — frame buffer lives in SPIRAM

Because the panel continuously scans from the SPIRAM frame buffer, the BSP must synchronize LVGL’s partial-buffer copy with the display’s scan-out to prevent visible tearing. This is achieved through a semaphore pair (sem_gui_ready / sem_vsync_end):

Sub-Modules

1. Factory Application — esp32s3_4827s043c_factory.md

The self-contained recovery app flashed to the factory OTA partition. It provides:

A touch-navigated menu (virtual UP/DOWN/OK buttons rendered at the bottom of the screen) to select recovery actions
Firmware OTA update from SD card (/sdcard/esp3dfw.bin → app0 or app1 partition) using esp_ota_* APIs with a 1 KB streaming buffer and live progress display
UI resources partition update from SD card (/sdcard/ui_resources.bin → ui_resources partition) with variant header validation
OTADATA backup/restore: on startup, restores the OTA boot target that the main firmware backed up before switching to factory, ensuring power-off from recovery returns to the correct app partition
Optional snapshot capture (ENABLE_SNAPSHOT) for development — pressing GPIO0 saves a raw RGB565 screen capture to the SD card

Key source files:

File	Responsibility
`main.c`	Recovery menu, OTA actions, touch dispatch, main event loop
`gfx.c`	Lightweight graphics over ILI9485 (no LVGL): `gfx_clear`, `gfx_draw_string`, `gfx_fill_rect`, `gfx_snapshot_*`
`touch.c`	GT911 I2C polling via the shared `touch_gt911` driver
`sdcard.c`	SPI SD mount/unmount via `esp_vfs_fat`
`buttons.c`	GPIO button driver (all pins `GPIO_NUM_NC` → inert on this board)
`encoder.c`	PCNT rotary encoder driver (pins `GPIO_NUM_NC` → inert on this board)
`buzzer.c`	Bit-bang buzzer driver (pin `GPIO_NUM_NC` → inert on this board)
`factory_log.h`	Compile-time debug log gate (`FACTORY_LOGD`)

→ Full details: esp32s3_4827s043c_factory.md

2. BSP Component — esp32s3_4827s043c_bsp.md

The hardware abstraction layer consumed by the main LVGL firmware (board_init() is the single entry point called from ESP3DX::begin()). It provides:

board_init() — top-level initialization sequence: backlight PWM, ILI9485 RGB panel, GT911 touch controller, LVGL engine, VSYNC semaphores, activity manager
lvgl_flush_cb() — VSYNC-synchronized LVGL flush callback with optional snapshot write path
touch_read_cb() — GT911 read with coordinate scaling to display pixels and activity-manager wake-up gate
increase_lvgl_tick() — ESP periodic timer callback that advances the LVGL tick counter
disp_on_vsync_event() — VSYNC ISR handler that drives the tear-free semaphore protocol
control_events_init() — registers custom LVGL event IDs for switch and potentiometer input
control_event_t — unified control event struct carried to UI screens

→ Full details: esp32s3_4827s043c_bsp.md

3. Build Scripts — esp32s3_4827s043c_build_scripts.md

Python scripts for variant-aware firmware building:

Script	Responsibility
`variants.py`	Declares all firmware variants as dicts of CMake flags, build directories, and working directories
`common.py`	`build_variant()`, `check_variant()`, UI resource generation, factory artifact copy, installer packaging, flash-map generation
`build_one.py`	CLI entry point: `python build_one.py <variant_name> [--clean] [--check]`

Defined firmware variants:

Variant name	Transport	CNC firmware	Features
`16mb_wifi_fluidnc`	WiFi (SOCKET_CLIENT) + Serial	FluidNC	mDNS, Lua, Update
`16mb_serial_fluidnc`	Serial only	FluidNC	Update
`16mb_serial_grbl`	Serial only	GRBL	Update
`16mb_wifi_grblhal`	WiFi (SOCKET_CLIENT) + Serial	GrblHAL	mDNS, Lua, Update
`factory_16mb`	—	Recovery app	—

→ Full details: esp32s3_4827s043c_build_scripts.md

Component Interaction and Boot Flow

Relation to Other Boards

The esp32s3_4827s043c follows the same factory application and BSP pattern as other boards in this repository. The table below highlights the most relevant architectural differences:

Board	Display bus	Touch	Physical inputs	VSYNC sync needed
`esp32s3_4827s043c` (this)	RGB parallel (ILI9485)	GT911 I2C	None (touch-only)	✓
`esp32s3_8048s043c`	RGB parallel (ST7262)	GT911 I2C	None	✓
`esp32s3_8048s070c`	RGB parallel	GT911 I2C	None	✓
`esp32s3_hmi43v3`	i80 parallel (RM68120)	GT911 I2C	Buttons + encoder	✗ (i80 done CB)
`pibot_pendant_v1_0`	SPI (ILI9341)	XPT2046 SPI	Buttons + encoder	✗ (notify_flush_ready)

For shared hardware drivers (touch_gt911, disp_ili9485, bus_i2c, disp_backlight) see the Hardware Peripheral Drivers — RGB Displays documentation.

For the main firmware systems that consume board_init() output see:

UI Framework & Screens — Core — LVGL UIManager and screen system
Core Platform & Infrastructure — ESP3DX entry point and settings
CNC Firmware Integration — GCode Host — GCode host and CNC protocol handling