Waveshare ESP32-S3 LCD 1.47”

WS-S3-LCD-1.47

The Waveshare S3 LCD 1.47” is a small USB-A dongle which has a 1.47” display, a button, a neopixel RGB LED, and a TF card slot. It also has through-hole expansion headers for connecting to other devices.

The espp::WsS3Lcd147 class provides a convenient way to access the display, the button, and the neopixel RGB LED. It also provides a way to access the TF card slot for reading and writing files.

• Waveshare ESP32-S3-LCD-1.47 Example
  • How to use example
    • Hardware Required
      • Waveshare ESP32-S3-LCD-1.47 Pin Configuration
    • Build and Flash
    • Example Output

API Reference

Header File

• components/ws-s3-lcd-1-47/include/ws-s3-lcd-1-47.hpp

Classes

class WsS3Lcd147 : public espp::BaseComponent

The WsS3Lcd147 class provides an interface to the Waveshare ESP32-S3-LCD-1.47 development board.

The class provides access to the following features:

• Button (boot button)

• Display

• RGB LED

• micro-SD (uSD) card

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

Example

  using Bsp = espp::WsS3Lcd147;
  Bsp &board = Bsp::get();
  board.set_log_level(espp::Logger::Verbosity::INFO);

  // initialize the LCD
  if (!board.initialize_lcd()) {
    logger.error("Failed to initialize LCD!");
    return;
  }
  // set the pixel buffer to be a full screen buffer
  static constexpr size_t pixel_buffer_size = board.lcd_width() * 50;
  // initialize the LVGL display for the WsS3Lcd147
  if (!board.initialize_display(pixel_buffer_size)) {
    logger.error("Failed to initialize display!");
    return;
  }

  // initialize the uSD card
  using SdCardConfig = Bsp::SdCardConfig;
  SdCardConfig sdcard_config{};
  if (!board.initialize_sdcard(sdcard_config)) {
    logger.warn("Failed to initialize SD card, continuing without it.");
  }

  // initialize the LED
  if (!board.initialize_led()) {
    logger.error("Failed to initialize LED!");
    return;
  }

  // initialize the button, which we'll use to cycle the rotation of the display
  logger.info("Initializing the button");
  auto on_button_pressed = [&](const auto &event) {
    if (event.active) {
      // lock the display mutex
      std::lock_guard<std::mutex> lock(lvgl_mutex);
      static auto rotation = LV_DISPLAY_ROTATION_0;
      rotation = static_cast<lv_display_rotation_t>((static_cast<int>(rotation) + 1) % 4);
      fmt::print("Setting rotation to {}\n", (int)rotation);
      lv_display_t *disp = lv_disp_get_default();
      lv_disp_set_rotation(disp, rotation);
    }
  };
  board.initialize_button(on_button_pressed);

  // set the background color to black
  lv_obj_t *bg = lv_obj_create(lv_screen_active());
  lv_obj_set_size(bg, board.lcd_width(), board.lcd_height());
  lv_obj_set_style_bg_color(bg, lv_color_make(0, 0, 0), 0);

  // add text in the center of the screen
  lv_obj_t *label = lv_label_create(lv_screen_active());
  lv_label_set_text(label, "Drawing circles\nto the screen.");
  lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);
  lv_obj_set_style_text_align(label, LV_TEXT_ALIGN_CENTER, 0);

  // start a simple thread to do the lv_task_handler every 16ms
  espp::Task lv_task({.callback = [](std::mutex &m, std::condition_variable &cv) -> bool {
                        {
                          // lock the display mutex
                          std::lock_guard<std::mutex> lock(lvgl_mutex);
                          lv_task_handler();
                        }
                        std::unique_lock<std::mutex> lock(m);
                        cv.wait_for(lock, 16ms);
                        return false;
                      },
                      .task_config = {
                          .name = "lv_task",
                          .core_id = 1,
                      }});
  lv_task.start();

  // set the display brightness to be 75%
  board.brightness(75.0f);

  espp::Task led_task({.callback = [](std::mutex &m, std::condition_variable &cv) -> bool {
                         static auto &board = Bsp::get();
                         auto start = std::chrono::steady_clock::now();
                         // set the LED color
                         static float hue = 0;
                         hue = std::fmod(hue + 1.0f, 360.0f);
                         board.led(espp::Hsv(hue, 100.0f, 100.0f));
                         // wait for 100ms
                         std::unique_lock<std::mutex> lock(m);
                         cv.wait_until(lock, start + 10ms);
                         return false;
                       },
                       .task_config = {
                           .name = "led_task",
                           .core_id = 1,
                       }});
  led_task.start();

  while (true) {
    auto start = esp_timer_get_time();
    // if there are 10 circles on the screen, clear them
    static constexpr int max_circles = 10;
    if (circles.size() >= max_circles) {
      // lock the lvgl mutex
      std::lock_guard<std::mutex> lock(lvgl_mutex);
      clear_circles();
    } else {
      // draw a circle of circles on the screen (just draw the next circle)
      static constexpr int middle_x = Bsp::lcd_width() / 2;
      static constexpr int middle_y = Bsp::lcd_height() / 2;
      static constexpr int radius = 50;
      float angle = circles.size() * 2.0f * M_PI / max_circles;
      int x = middle_x + radius * cos(angle);
      int y = middle_y + radius * sin(angle);

      // handle the rotation of the display to ensure the circles are centered
      auto rotation = lv_display_get_rotation(lv_disp_get_default());
      switch (rotation) {
      default:
      case LV_DISPLAY_ROTATION_0:
      case LV_DISPLAY_ROTATION_180:
        break;
      case LV_DISPLAY_ROTATION_90:
      case LV_DISPLAY_ROTATION_270:
        std::swap(x, y);
        break;
      }

      // lock the lvgl mutex
      std::lock_guard<std::mutex> lock(lvgl_mutex);
      draw_circle(x, y, 10);
    }
    auto end = esp_timer_get_time();
    auto elapsed = end - start;
    std::this_thread::sleep_for(100ms - std::chrono::microseconds(elapsed));
  }

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 used by the display.

Public Functions

espp::Interrupt &interrupts()

Get a reference to the interrupts

Returns:

A reference to the interrupts

bool initialize_button(const button_callback_t &callback = nullptr)

Initialize the button

Parameters:

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

Returns:

true if the button was successfully initialized, false otherwise

bool button_state() const

Get the button state

Returns:

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

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

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

uint8_t *frame_buffer0() const

Get the frame buffer 0 pointer

Note

This memory is designed to be used by the application developer and is provided as a convenience. It is not used by the display driver.

Note

This is null unless initialize_display() has been called

Returns:

The frame buffer 0 pointer

uint8_t *frame_buffer1() const

Get the frame buffer 1 pointer

Note

This memory is designed to be used by the application developer and is provided as a convenience. It is not used by the display driver.

Note

This is null unless initialize_display() has been called

Returns:

The frame buffer 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_sdcard(const SdCardConfig &config)

Initialize the uSD card

Parameters:

config – The configuration for the uSD card

Returns:

True if the uSD card was initialized properly.

inline sdmmc_card_t *sdcard() const

Get the uSD card

Note

The uSD card is only available if it was successfully initialized and the mount point is valid

Returns:

A pointer to the uSD card

bool initialize_led()

Initialize the RGB LED

Returns:

true if the LED was successfully initialized, false otherwise

inline std::shared_ptr<Neopixel> led() const

Get a shared pointer to the RGB LED

Returns:

A shared pointer to the RGB LED

bool led(const Hsv &hsv)

Set the color of the LED

Parameters:

hsv – The color of the LED in HSV format

Returns:

true if the color was successfully set, false otherwise

bool led(const Rgb &rgb)

Set the color of the LED

Parameters:

rgb – The color of the LED in RGB format

Returns:

true if the color was successfully set, false otherwise

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 WsS3Lcd147 &get()

Access the singleton instance of the WsS3Lcd147 class.

Returns:

Reference to the singleton instance of the WsS3Lcd147 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

Public Static Attributes

static constexpr char mount_point[] = "/sdcard"

Mount point for the uSD card on the TDeck.

struct SdCardConfig

Configuration for the uSD card.

Public Members

bool format_if_mount_failed = false

Format the uSD card if mount failed.

int max_files = 5

The maximum number of files to open at once.

size_t allocation_unit_size = 2 * 1024

The allocation unit size in bytes.