Hardware abstraction library for the Waveshare ESP32-S3 Touch 2.8" development board. Copy preconfigured lv_conf.h to your project and include <WS_ESP32_Touch28.h> and LVGL will work. Provides ready-to-use drivers for all onboard peripherals through a single header include.

https://www.waveshare.com/wiki/ESP32-S3-Touch-LCD-2.8

There is no added features for bluetooth or wifi, since the built in libraries for ESP32 is sufficient. Depending on the project other libraries would be required. The intent of this library is to make the specific hardware on the Waveshare ESP32-S3 Touch 2.8" easy to access.

LVGL library requires the configuration of the lv_conf.h file for the hardware you use. Since this library enables the drivers for the Waveshare ESP32-S3-Touch-LCD-2.8 device, the lv_conf.h is pre-configured for this device. You do need to copy the lv_conf.h from this library to your Sketch folder.

• ST7789 240×320 LCD — PSRAM-backed framebuffer with dirty-rectangle optimization and dual-core mutex safety
• CST328 Capacitive Touch — Interrupt-driven 5-point multitouch with a high-level gesture recognition system (tap, double-tap, swipe, drag, long-press)
• PCM5101 I2S Audio — MP3 playback from SD card via a dedicated FreeRTOS task
• SD_MMC Card — File I/O, directory operations, and hardware-accelerated JPG/PNG image loading
• QMI8658 6-axis IMU — Accelerometer + gyroscope with integrated orientation tracking (yaw/pitch/roll)
• PCF85063 Real-Time Clock — Date/time keeping, alarm support, epoch conversion
• Battery Monitoring — ADC voltage reading with rolling average and Li-ion percentage curve
• Power Management — Sleep, restart, and shutdown via power key
• Optional LVGL v9 Integration — Compiles to zero overhead when LVGL is not installed

1. Copy the entire WS_ESP32_Touch28/ folder into your Arduino libraries/ directory (typically ~/Arduino/libraries/ or Documents/Arduino/libraries/).
2. Restart the Arduino IDE.
3. The library will appear under Sketch → Include Library → WS_ESP32_Touch28.

1. Compress the WS_ESP32_Touch28/ folder into a .zip file.
2. In Arduino IDE: Sketch → Include Library → Add .ZIP Library… and select the file.

Install these via Library Manager (Sketch → Include Library → Manage Libraries):

• JPEGDEC by Larry Bank — required for JPG image loading
• PNGdec by Larry Bank — required for PNG image loading
• ESP32-audioI2S by Schreibfaul1 — required for MP3 audio playback

1. Install lvgl via Library Manager.
2. That's it — the library bundles its own lv_conf.h in src/ and LVGL auto-detects it at compile time via __has_include(<lvgl.h>). No manual copying required.

#include "WS_ESP32_Touch28.h"

void setup() {
  Serial.begin(115200);
  WS_ESP32_Init();

  // Draw directly to the framebuffer
  LCD_FB_Start();
  LCD_FB_Clear(LCD_Color565(0, 0, 0));
  LCD_FB_FillRect(50, 50, 140, 80, LCD_Color565(255, 255, 255));
  LCD_FB_End();
}

void loop() {
  WS_ESP32_Loop();
  delay(10);
}

#include <lvgl.h>
#include "WS_ESP32_Touch28.h"

void setup() {
  Serial.begin(115200);
  WS_ESP32_Init();    // Automatically calls LVGL_Init()

  // Create LVGL widgets
  lv_obj_t * label = lv_label_create(lv_screen_active());
  lv_label_set_text(label, "Hello LVGL!");
  lv_obj_center(label);
}

void loop() {
  WS_ESP32_Loop();    // Runs LVGL timer handler + LCD update
  delay(10);
}

The display can be rotated at any time — during setup() or on-the-fly at runtime. Touch coordinates, framebuffer layout, and LVGL resolution all update automatically.

// In setup(), after WS_ESP32_Init():
LCD_SetRotation(1);   // landscape 320×240

// Or change at runtime (e.g. in a touch callback):
LCD_SetRotation(0);   // back to portrait 240×320

Note: LCD_SetRotation() clears the framebuffer (the pixel layout changes), so you'll need to redraw your content afterward. If LVGL is active, call lv_obj_invalidate(lv_screen_active()) after rotation to force a full redraw.

All drawing functions must be called between LCD_FB_Start() and LCD_FB_End() unless noted.

Constants: LCD_WIDTH / LCD_HEIGHT (runtime, change with rotation), LCD_PANEL_W (240), LCD_PANEL_H (320)

Define rectangular or circular zones, specify which gestures to detect, and register callbacks. The gesture engine runs inside WS_ESP32_Loop().

TouchZone btn = Touch_MakeRect(
  1,                              // zone ID (0–255)
  80, 200, 80, 40,                // x, y, w, h
  GESTURE_CLICK | GESTURE_LONG_PRESS,  // gestures to detect
  myCallback                      // void myCallback(TouchEvent& evt)
);
Touch_Gesture_AddZone(&btn);

Gesture Flags (combine with |): GESTURE_CLICK, GESTURE_DOUBLE_CLICK, GESTURE_SWIPE_UP, GESTURE_SWIPE_DOWN, GESTURE_SWIPE_LEFT, GESTURE_SWIPE_RIGHT, GESTURE_DRAG, GESTURE_LONG_PRESS, GESTURE_SWIPE_ANY, GESTURE_ALL

TouchEvent fields: zoneID, gesture, x, y, startX, startY, deltaX, deltaY, dragPhase (DRAG_START/DRAG_MOVE/DRAG_END), duration

Image Loading (requires JPEGDEC and/or PNGdec libraries):

Rotation constants: IMG_ROTATE_0, IMG_ROTATE_90, IMG_ROTATE_180, IMG_ROTATE_270

MP3 playback from SD card via I2S DAC. Audio runs on a dedicated FreeRTOS task for glitch-free playback.

6-axis accelerometer + gyroscope with automatic orientation tracking. Calibrates at startup (hold the device still for ~1 second).

Global structs: Accel and Gyro (type IMUdata with .x, .y, .z fields).

Real-time clock on I2C bus 0 (shared with IMU). Provides date/time keeping and alarm functionality. The datetime global struct is updated automatically by PCF85063_Loop() every main loop iteration.

Global: datetime (type datetime_t) — automatically updated every loop iteration. Fields: year, month, day, dotw (day of week, 0=Sunday), hour, minute, second.

Long-press durations are configurable in PWR_Key.h: sleep (10s), restart (15s), shutdown (20s).

Automatically detected at compile time. When LVGL is not installed, all functions compile to empty stubs with zero overhead.

Compile-time check: Use #if HAS_LVGL to conditionally include LVGL-specific code.

Low-level I2C helper for Wire bus 0 (IMU). Touch uses Wire1 separately.

The library includes five example sketches (File → Examples → WS_ESP32_Touch28):

• Basic_NoLVGL — Framebuffer drawing and touch zones without LVGL
• LVGL_HelloWorld — Button and slider using LVGL widgets
• Touch_Gestures_Demo — All gesture types with visual feedback
• SD_ImageViewer — Browse JPG/PNG images with swipe navigation
• IMU_Orientation — Real-time yaw/pitch/roll tracking with tap-to-reset

The library is designed around a shared PSRAM framebuffer. All drawing — whether from raw LCD_FB_* calls, SD card image loading, or LVGL widget rendering — writes into the same 153,600-byte buffer. A FreeRTOS mutex (lcd_fb_mutex) protects concurrent access from both CPU cores, and the WS_ESP32_Loop() performs the maintaining features for updating the screen by burst streaming to the ST7789 via SPI at 80 MHz.

LVGL is integrated as an optional overlay: its flush callback copies rendered pixels into the existing framebuffer and marks the affected region dirty, so the existing SPI pipeline handles all hardware communication. The touch input callback reads from the gesture layer's raw position API, letting LVGL handle its own gesture recognition internally.

Audio playback runs on a dedicated FreeRTOS task (priority 19, core 0) to ensure the I2S DMA buffer stays filled regardless of display or application processing load.

See individual source files for license information.