• sales


ESP32-S3-LCD-1.28 User Guide

User Guide: https://www.spotpear.com/index/study/detail/id/1249.html







The ESP32-S3-LCD-1.28 (referred to as the development board hereafter) is a low-cost, high-performance microcontroller development board designed by Waveshare. It features a 1.28-inch LCD screen, a lithium battery charging chip, and peripherals such as a six-axis sensor (three-axis accelerometer and a three-axis gyroscope). The board utilizes the ESP32-S3R2, an integrated system-on-chip (SoC) with low-power Wi-Fi and BLE5.0 capabilities. Additionally, it comes with an external 16MB Flash and 2MB PSRAM.
The SoC includes hardware encryption accelerators, RNG (Random Number Generator), HMAC (Hash-based Message Authentication Code), and a Digital Signature module, meeting the security requirements of the Internet of Things (IoT). Its various low-power operating modes cater to power consumption needs in IoT, mobile devices, wearable electronics, smart homes, and other application scenarios.


  • Equipped with Xtensa® 32-bit LX7 dual-core processor, up to 240MHz main frequency.
  • Supports 2.4GHz Wi-Fi (802.11 b/g/n) and Bluetooth® 5 (BLE), with onboard antenna.
  • Built-in 512KB of SRAM and 384KB ROM, with onboard 2MB PSRAM and an external 16MB Flash memory.
  • Type-C connector, keeps it up to date, easier to use.
  • Onboard 1.28-inch LCD display, round IPS panel, 240×240 resolution, 65K color.
  • Onboard QMI8658 6-axis IMU (3-axis accelerometer and 3-axis gyroscope) for detecting motion gestures.
  • Onboard 3.7V lithium battery recharge/discharge header and GPIO headers.
  • Supports flexible clock, module power supply independent setting, and other controls to realize low power consumption in different scenarios.
  • Integrated with USB serial port full-speed controller, GPIO pins allow flexible configuring pin functions.


LCD Parameter
Display ChipGC9A01ADisplay InterfaceSPI
Resolution240(H)RGB x 240(V)Display SizeΦ32.4mm
Display PanelIPSPixels0.135(H)x 0.135(V)mm

IMU Paramters
Sensor NameQMI8658
AcceleratorResolution: 16-bit
Measurement Range (Optional): ±2, ±4, ±8, ±16g
Gyroscope CharacteristicsResolution: 16 bits
Measuremnet Range (Optional): ±16, ±32, ±64, ±128, ±256, ±512, ±1024, ±2048°/sec


  • When using the development board, pay attention to the ceramic antenna area and avoid covering the ceramic antenna with PCB boards, metal, or plastic components.
  • The board is equipped with an efficient charging and discharging management chip, ETA6096, and an MX1.25 battery interface. The charging current is currently set to 1A, and users can change the charging current by replacing the R15 resistor. Connect a 3.7V single-cell lithium battery, and for more details, please refer to the schematic diagram. It is recommended to use a 3.7V single-cell lithium battery with a capacity of 500mAh or below.
  • To prevent overcharging and over-discharging of the battery, stop discharging when the fully charged 4.2V lithium battery discharges to 3.7V.

Hardware Description

Onboard Interface

  • Type-C Interface : The development board uses the CH343P chip for USB to UART, connecting the UART_TXD (GPIO43) and UART_RXD (GPIO44) of ESP32-S3 for firmware programming and log printing. With the automatic download circuit, the firmware can be downloaded directly after connecting the Type-C cable.
  • 1.27mm Pitch Headers : The development board leads to most of the GPIOs for external connection, GPIOs can be configured to I2C, SPI, and other peripheral functions, VSYS can directly input 5V to power the development board.
  • LCD Interface : Development board on-board 1.28-inch screen with 4-wire SPI communication, SPI rate can be increased to 80MHz, touch using I2C communication (development board using GPIO2 to control the brightness of the backlight, in addition to lead out of the two MOS tubes to control the switching contacts around the battery holder, respectively, connected to the GPIO4, GPIO5, can be welded on their own with small-current devices such as vibration motors, etc., for more information, please see the Schematic).
  • I2C Interface : ESP32-S3 provides multiple hardware I2C, currently using GPIO6 (SDA) and GPIO7 (SCL) pins for I2C bus. Onboard the QMI8658 six-axis inertial measurement unit and LCD touch control chip. For more information, please see the Schematic.
  • MX1.25 Connector : GPIO1 of the development board is used to measure the battery voltage pin, the battery voltage is connected to GPIO1 using 200K and 100K series voltage divider, the ESP32-S3 series has two 12Bit SAR ADC measurement units, the source code is converted to the voltage formula is 3.3 / (1<<12) * 3 * AD_Value.


Environment Setting

The software framework for ESP32 series development boards is completed, and you can use CircuitPython, MicroPython, and C/C++ (Arduino, ESP-IDF) for rapid prototyping of product development. Here's a brief introduction to these three development approaches:

  • Official C/C++ library installation:
    • ESP32 series Arduino development tutorial.
    • ESP32 series ESP-IDF development tutorial.
  • MicroPython is an efficient implementation of the Python 3 programming language. It includes a small subset of the Python standard library and has been optimized to run on microcontrollers and resource-constrained environments.
  • Environment setting is supported on Windows 10. Users can select Arduino/Visual Studio Codes (ESP-IDF) as IDE to develop. For Mac/Linux, users can refer to official introduction.



  • Download and install Arduino IDE.
  • Install ESP32 on the Arduino IDE as shown below, and you can refer to this link.
  • Fill in the following link in the Additional Boards Manager URLs section of the Settings screen under File -> Preferences and save.

  • Search esp32 on Board Manager to install, and restart Arduino IDE to take effect.

  • Open the Arduino IDE and note that Tools in the menu bar selects the corresponding 16MB Flash and enables QSPI PSRAM, as shown in the following figure.

Library Installation

  • TFT_SPI, lvgl libraries need to be configured after installation, it is recommended to directly use the TFT_eSPI_Setups, TFT_eSPI, lvgl folder in Esp32-s3-lcd-1.28-lib and copy it to the C:\Users\xxxx\Documents\Arduino\libraries directory. xxxx represents the user name of your computer, please be careful in identifying it.


1. Download and install the latest Thonny, open ThonNY ide -> Configure interpreter... as shown below:
2. Connect the Type-C interface to the USB cable, find the device manager or the corresponding COM port, and download or run the demo, please refer to the section on hardware connection.
3. Please ignore this step in this tutorial (Please skip to Step 4). According to the steps shown in the figure below to select the ESP32-S3 series of online MPY firmware download, the download will be cleared before the development of the board's Flash content, the entire download process lasts about 1 minute, MPY firmware can be downloaded from the official website!
The current development board uses customized firmware for development, open flash_download_tool_3.9.5 to download the firmware tool, firmware in the example demo, firmware production from this link, firmware merged into a single file, note that the download address is 0x0.
  • After connecting ESP32-S3-LCD-1.28 to the PC, long-press BOOT key, single-click the RESET key, and then release the BOOT key to enable it to enter Download Mode.
  • Select chip: ESP32-S3, download mode: USB.
  • Download S3-Touch-LCD-1.28-MPY.bin, and the downloaded address is 0X0. Select ESP32-S3-Touch-LCD-1.28's COM, click to start, and wait for it to program.
5. Program the firmware and press the RESET key, input the sample demo in the mpy directory to the development board as shown below:
  • Enter Thonny, select ESP32, and the corresponding COM port.

  • Click the following button and you can see the shell output the sentence, which indicates the firmware of the development board can be used successfully.

  • Upload the mpy file folder of the sample demo to the ESP32-S3-LCD-1.28.

For programming, you can refer to NicrPython Documentation and release note.

Download Other Firmwares

If you use flash_download_tool_3.9.5 to download the firmware, please operate it according to the following picture. Note that the ESO32-S3 application firmware address is 0x10000, THE partition_tables.bin address is 0x8000, the bootloader.bin address is 0x0.

Sample Demo


Note: Before using the Arduino demo, please check whether the Arduino IDE environment can be correctly matched with the download setting, and you can refer to Arduino Environment Configuration.

Arduino IDE Sample

  • Arduino example demo can be used arduino-esp32 or Arduino IDE File -> examples in the example demo (such as ESP32 GPIO, WIFI, and other general examples to use), if you need to use the screen driver, you can refer to the screen driver. Please refer to the example demo in the esp32-s3-lcd- 1.28-demo demo for the screen driver.


esp32-s3-lcd-1.28-demo is for testing the screen, 6-axis sensor, BAT, and touch screen.

  • The following is the demo effect:
After powering on, the screen will display white, red, green, and blue colors sequentially with a 2-second interval. Check the screen for any light leakage or black spots. If the screen changes too quickly to inspect, press the RESET button to restart the process.

a. Proceed to the sensor testing phase after the color display. After the colors, sensor data will be shown on the screen. When stationary, ACC_X and ACC_Y values should be below 200, ACC_Z around 1000, GYR_X, GYR_Y, GYR_Z values should be around 0 to 10. Any erratic readings might indicate damage to the six-axis sensor.

b. Connect the 3.7V lithium battery at this point. Normally, the BAT (V) value will decrease.


  • Arduino_LVGL sample is for displaying LVGL benchmark, music, and so on. For LVGL, you can refer to LVGL development tutorial.
  • LVGL library is the callback function for displaying refreshing, refreshing the LVGL drawing buffer to TFT LCD.
void my_disp_flush( lv_disp_drv_t *disp_drv, const lv_area_t *area, lv_color_t *color_p )
     lv_disp_drv_t *disp_drv: LVGL: Provides the display driver structure pointer, including the display-related information and the function pointer. This function can be used to notify LVGL that the refresh is finished.
     const lv_area_t *area: LVGL: defines the pointer to area structure, indicating the area to be refreshed. This area is a rectangular area relative to the entire display screen.
     lv_color_t *color_p: LVGL: the defined color structure pointer, indicating the color data displayed in the refreshing area. This function is used to draw by writing this color data to the TFT buffer.
  • The timer's callback function. The LVGL is notified of the past time by calling the LVGL function lv_tick_inc so that the LVGL can update its internal time state to handle time-related tasks such as animations, timers, etc. In the example, it is called every EXAMPLE_LVGL_TICK_PERIOD_MS milliseconds.
void example_increase_lvgl_tick(void *arg)
  • The timer's callback function. The counter count, each call will be added to the counter, in the count reaches a certain value to trigger an operation, here is a simulation of the timer triggered 30 times after the restart operation, the specific behavior can be adjusted according to needs.
void example_increase_reboot(void *arg)


  • Arduino_Chinese_Font is for displaying the LVGL built-in 1000 common Chinese fonts.


  • Arduino_Chinese_7500_Char is for displaying LVGL's 7500 Chinese fonts. As the font file is large, the download of firmware time is relatively long.


Note: Before using the Micropython demos, please check whether the ESP32-S3-LCD-1.28 has burned the mpy firmware and whether the Thonny environment is correctly configured, for details, please see #MicroPython.
  • mpy file includes the following examples, and you can click here to see more details.