LCD-ESP32-Driver

Introduction

Project includes component for controlling LCD displays. Currently supports only one LCD controller - SSD1283A but it may change in the future. It is compatible with ESP32 microcontrollers. Source code of the driver has been written in C.

It is written and tested for v4.4.2 of the ESP-IDF environment using the xtensa-esp32-elf toolchain (gcc version 8.4.0).

Build

To include the component into your ESP-IDF project, you need to create CMakeLists.txt file containing:

idf_component_register(
    SRC_DIRS "." "com" "controllers"
    INCLUDE_DIRS "/include" "com/include" "controllers/include"
)

Consult ESP-IDF documentation for more details about build system.

Features

✔️ Instantiation - using many driver instances simultaneously is possible

✔️ Supports the following LCD controllers:

• SSD1283A (SPI interface only)

✔️ Very basic display control - turning it on and off, clearing the entire screen

✔️ Basic shape drawing function - rectangles in the desired positions on the screen

✔️ Supports drawing texts on the screen using included default font:

• Possibility to add your own fonts - please check the documentation for details

✔️ Supports drawing images on the screen:

• Your image have to be converted and embed in the code as an array of the pixels - please check the documentation for more details and the example below

✔️ Supports color formats:

• RGB565 (16-bit)

❌ Supports touch screens

❌ Static memory allocation - creating driver instance requires dynamic allocation

Example

Below are some examples of using the driver.

• Creating, initializing and destroying the concrete driver instance (SSD1283A + SPI interface)

  #define LCD_SPI_HOST        VSPI_HOST           // SPI host selected for LCD display 
  #define LCD_SPI_DMA         SPI_DMA_CH_AUTO     // SPI DMA channel selected for LCD display
   
  #define LCD_MISO_GPIO       19                  // GPIO for SPI MISO pin selected for LCD display (not required)
  #define LCD_MOSI_GPIO       23                  // GPIO for SPI MOSI pin selected for LCD display
  #define LCD_SCLK_GPIO       18                  // GPIO for SPI SCLK pin selected for LCD display
  #define LCD_CS_GPIO         5                   // GPIO for SPI CS pin selected for LCD display
  #define LCD_DC_GPIO         22                  // GPIO for DC (data/command) pin selected for LCD display
  #define LCD_RST_GPIO        21                  // GPIO for RESET pin selected for LCD display
  #define LCD_WP_GPIO         -1                  // GPIO for WP signal selected for LCD display (not used)
  #define LCD_HOLD_GPIO       -1                  // GPIO for HD signal selected for LCD display (not used)
   
  spi_device_handle_t spi;
  if (SPI_OK != spi_init(LCD_MISO_GPIO, LCD_MOSI_GPIO, LCD_SCLK_GPIO, LCD_WP_GPIO, LCD_HOLD_GPIO, LCD_CS_GPIO, 
      SSD1283A_SPI_MAX_TRANSFER_SIZE, SSD1283A_SPI_QUEUE_SIZE, SSD1283A_SPI_CLOCK_SPEED, LCD_SPI_HOST, LCD_SPI_DMA, &spi))
  {
      // Error handling
  }
   
  LCD_handle_t lcd = lcd_ssd1283a_spi__Create(spi, LCD_DC_GPIO, LCD_RST_GPIO);
   
  if (LCD_OK != lcd__Init(lcd))
  {
      // Error handling
  }
   
  // Do something here (clearing the entire screen is preferred before start working)
   
  if (LCD_OK != lcd__Destroy(&lcd))
  {
      // Error handling
  }

• Drawing example rectangle on the screen

  // Create and initialize the concrete driver instance here (first example)
   
  if (LCD_OK != lcd__DrawRect(lcd, SSD1283A_WIDTH / 2, SSD1283A_HEIGHT / 2, SSD1283A_WIDTH / 4, SSD1283A_HEIGHT / 4, RGB565_RED))
  {
      // Error handling
  }

• Drawing example text on the screen

  // Create and initialize the concrete driver instance here (first example)
   
  if (LCD_OK != lcd__DrawText(lcd, 120, 10, "An example text\nwith two lines", -2, 0, &LCD_BASIC_FONT, RGB565_BLACK, RGB565_WHITE))
  {
      // Error handling
  }

• Drawing example image on the screen

lcd_example_image.h:

extern const LCD_image_t LCD_EXAMPLE_IMAGE;

lcd_example_image.c:

#define LCD_EXAMPLE_IMAGE_WIDTH   15
#define LCD_EXAMPLE_IMAGE_HEIGHT  15
 
static const uint8_t pixels[] = 
{
    // Pixels of the image
};
 
const LCD_image_t LCD_IMAGE_SUN_FULL =
{
    .width      = LCD_IMAGE_SUN_FULL_WIDTH,
    .height     = LCD_IMAGE_SUN_FULL_HEIGHT,
    .pixels     = pixels,
};

main.c:

// Create and initialize the concrete driver instance here (first example)
 
if (LCD_OK != lcd__DrawImage(lcd, 4, 17, &LCD_EXAMPLE_IMAGE))
{
    // Error handling
}

Documentation

Generated API documentation is available here.

Source Code

The source code is available on GitHub.

License

The code in this project is licensed under the MIT license - see LICENSE.md for details.

Links

• ESP-IDF
• SSD1283A Datasheet