Waveshare ESP32-S3 TouchLCD

WS-S3-Touch

The Waveshare S3 TouchLCD is a development board featuring the ESP32-S3 module. It includes a small 1.69-inch touchscreen display, a buzzer, a 6-axis IMU, and a real-time clock (RTC).

The espp::WsS3Touch component provides a singleton hardware abstraction for initializing the touch, display, IMU, and audio subsystems.

API Reference

Header File

Classes

class WsS3Touch : public espp::BaseComponent

The WsS3Touch class provides an interface to the Waveshare ESP32-S3 TouchLCD development board(s).

The class provides access to the following features:

  • Touchpad (CST816T)

  • Display (ST7789V2, 240x280)

  • Audio (buzzer)

  • Interrupts

  • Buttons (boot)

  • I2C

  • IMU (Inertial Measurement Unit), 6-axis QMI8658

  • RTC (Real-Time Clock), PCF85063

The class is a singleton and can be accessed using the get() method.

Example

Public Types

using button_callback_t = espp::Interrupt::event_callback_fn

Alias for the button callback function.

using Pixel = lv_color16_t

Alias for the pixel type.

using DisplayDriver = espp::St7789

Alias for the display driver.

using TouchDriver = espp::Cst816

Alias for the touch driver.

using TouchpadData = espp::TouchpadData

Alias for the touchpad data.

using Imu = espp::Qmi8658<qmi8658::Interface::I2C>

Alias the IMU.

using Rtc = espp::Pcf85063

Alias the RTC.

using touch_callback_t = std::function<void(const TouchpadData&)>

Alias for the touch callback when touch events are received.

Public Functions

bool enable()

Initialize system power control and enable the device

Note

This is automatically called by the constructor

Returns:

true if the system was successfully initialized, false otherwise

bool disable()

Disable system power

Returns:

true if the system power control was successfully disabled

inline I2c &internal_i2c()

Get a reference to the internal I2C bus

Note

The internal I2C bus is used for the touchscreen, IMU, and RTC

Returns:

A reference to the internal I2C bus

inline espp::Interrupt &interrupts()

Get a reference to the interrupts

Returns:

A reference to the interrupts

bool initialize_touch(const touch_callback_t &callback = nullptr)

Initialize the touchpad

Note

This will configure the touchpad interrupt pin which will automatically call the touch callback function when the touchpad is touched

Warning

This method should be called after the display has been initialized if you want the touchpad to be recognized and used with LVGL and its objects.

Parameters:

callback – The touchpad callback

Returns:

true if the touchpad was successfully initialized, false otherwise

inline std::shared_ptr<TouchpadInput> touchpad_input() const

Get the touchpad input

Returns:

A shared pointer to the touchpad input

inline TouchpadData touchpad_data() const

Get the most recent touchpad data

Returns:

The touchpad data

void touchpad_read(uint8_t *num_touch_points, uint16_t *x, uint16_t *y, uint8_t *btn_state)

Get the most recent touchpad data

See also

touchpad_data()

Note

This method is a convenience method for integrating with LVGL, the data it returns is identical to the data returned by the touchpad_data() method

Parameters:

  • num_touch_points – The number of touch points

  • x – The x coordinate

  • y – The y coordinate

  • btn_state – The button state (0 = button released, 1 = button pressed)

TouchpadData touchpad_convert(const TouchpadData &data) const

Convert touchpad data from raw reading to display coordinates

Note

Uses the touch_invert_x and touch_invert_y settings to determine if the x and y coordinates should be inverted

Parameters:

data – The touchpad data to convert

Returns:

The converted touchpad data

bool initialize_lcd()

Initialize the LCD (low level display driver)

Returns:

true if the LCD was successfully initialized, false otherwise

bool initialize_display(size_t pixel_buffer_size)

Initialize the display (lvgl display driver)

Note

This will also allocate two full frame buffers in the SPIRAM

Parameters:

pixel_buffer_size – The size of the pixel buffer

Returns:

true if the display was successfully initialized, false otherwise

inline std::shared_ptr<Display<Pixel>> display() const

Get a shared pointer to the display

Returns:

A shared pointer to the display

void brightness(float brightness)

Set the brightness of the backlight

Parameters:

brightness – The brightness of the backlight as a percentage (0 - 100)

float brightness() const

Get the brightness of the backlight

Returns:

The brightness of the backlight as a percentage (0 - 100)

Pixel *vram0() const

Get the VRAM 0 pointer (DMA memory used by LVGL)

Note

This is the memory used by LVGL for rendering

Note

This is null unless initialize_display() has been called

Returns:

The VRAM 0 pointer

Pixel *vram1() const

Get the VRAM 1 pointer (DMA memory used by LVGL)

Note

This is the memory used by LVGL for rendering

Note

This is null unless initialize_display() has been called

Returns:

The VRAM 1 pointer

void write_command(uint8_t command, std::span<const uint8_t> parameters, uint32_t user_data)

Write command and optional parameters to the LCD

Note

This method is designed to be used by the display driver

Note

This method queues the data to be written to the LCD, only blocking if there is an ongoing SPI transaction

Parameters:

  • command – The command to write

  • parameters – The command parameters to write

  • user_data – User data to pass to the spi transaction callback

void write_lcd_frame(const uint16_t x, const uint16_t y, const uint16_t width, const uint16_t height, uint8_t *data)

Write a frame to the LCD

Note

This method queues the data to be written to the LCD, only blocking if there is an ongoing SPI transaction

Parameters:

  • x – The x coordinate

  • y – The y coordinate

  • width – The width of the frame, in pixels

  • height – The height of the frame, in pixels

  • data – The data to write

void write_lcd_lines(int xs, int ys, int xe, int ye, const uint8_t *data, uint32_t user_data)

Write lines to the LCD

Note

This method queues the data to be written to the LCD, only blocking if there is an ongoing SPI transaction

Parameters:

  • xs – The x start coordinate

  • ys – The y start coordinate

  • xe – The x end coordinate

  • ye – The y end coordinate

  • data – The data to write

  • user_data – User data to pass to the spi transaction callback

bool initialize_boot_button(const button_callback_t &callback = nullptr)

Initialize the boot button (middle button)

Parameters:

callback – The callback function to call when the button is pressed

Returns:

true if the button was successfully initialized, false otherwise

bool boot_button_state() const

Get the boot button state

Returns:

The button state (true = button pressed, false = button released)

bool initialize_buzzer()

Initialize the audio (buzzer)

Returns:

true if the audio was successfully initialized, false otherwise

bool buzzer(float pwm, size_t frequency_hz = 1000)

Play audio

Parameters:

  • pwm – The PWM value to use for the audio output (0.0 - 100.0)

  • frequency_hz – The frequency of the audio output in Hz (default is 1000)

bool initialize_imu (const Imu::filter_fn &orientation_filter=nullptr, const Imu::ImuConfig &imu_config={ .accelerometer_range=Imu::AccelerometerRange::RANGE_8G,.accelerometer_odr=Imu::ODR::ODR_250_HZ,.gyroscope_range=Imu::GyroscopeRange::RANGE_2048_DPS,.gyroscope_odr=Imu::ODR::ODR_250_HZ, })

Initialize the IMU

Parameters:

  • orientation_filter – The orientation filter, if provided

  • imu_config – The IMU configuration

Returns:

true if the IMU was successfully initialized, false otherwise

std::shared_ptr<Imu> imu() const

Get the IMU

Returns:

A shared pointer to the IMU

bool initialize_rtc()

Initialize the RTC

Returns:

true if the RTC was successfully initialized, false otherwise

std::shared_ptr<Rtc> rtc() const

Get the RTC

Returns:

A shared pointer to the RTC

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:

A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:

tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:

The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:

level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:

level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:

The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:

rate_limit – The rate limit to use for the logger

Public Static Functions

static inline WsS3Touch &get()

Access the singleton instance of the WsS3Touch class.

Returns:

Reference to the singleton instance of the WsS3Touch class

static inline constexpr size_t lcd_width()

Get the width of the LCD in pixels

Returns:

The width of the LCD in pixels

static inline constexpr size_t lcd_height()

Get the height of the LCD in pixels

Returns:

The height of the LCD in pixels

static inline constexpr auto get_lcd_dc_gpio()

Get the GPIO pin for the LCD data/command signal

Returns:

The GPIO pin for the LCD data/command signal