From Waveshare Wiki
Jump to: navigation, search

Type C USB






The ESP32-S3-Touch-LCD-1.28 (hereinafter referred to as "the development board") is a low-cost, high-performance microcontroller development board designed by Waveshare. It features a 1.28-inch capacitive touch LCD screen, a lithium battery charging chip, a six-axis sensor (three-axis accelerometer and three-axis gyroscope), and other peripherals. The board is based on the ESP32-S3R2, which is a system-on-chip (SoC) integrated with low-power Wi-Fi and BLE 5.0. It also includes an external 16MB Flash and 2MB PSRAM. The SoC features hardware encryption accelerators, RNG, HMAC, and digital signature modules, meeting the security requirements of the Internet of Things (IoT). Its various low-power operating modes are suitable for power requirements in IoT, mobile devices, wearable electronics, smart home applications, and other 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 (LE), 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.28inch capacitive touch display, 240×240 resolution, 65K color.
  • Onboard QMI8658 6-axis IMU (3-axis accelerometer and 3-axis gyroscope) for detecting motion gestures.
  • Onboard 3.7V MX1.25 lithium battery charging and discharging header.
  • Adapting 6 × GPIO pins via SH1.0 connector.
  • 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 Parameters
Touch Chip CST816S Touch Interface I2C
Display Chip GC9A01A Display Interface SPI
Resolution 240(H)RGB x 240(V) Display Size Φ32.4mm
Display Panel IPS Pixel Size 0.135(H)x0.135(V)mm

IMU Parameters
Sensor QMI8658
Accelaeration Parameters Resolution: 16-bit
Range (Optional): ±2, ±4, ±8, ±16g
Gyrometer Resolution: 16-bit
Range (Optional): ±16, ±32, ±64, ±128, ±256, ±512, ±1024, ±2048°/sec


  1. It is a normal phenomenon that the touch sensitivity and accuracy on the edge of the round touch screen will be reduced.
  2. When using the development board, you need to pay attention to the ceramic antenna area and avoid the PCB board, metal, and plastic parts covering the ceramic antenna.
  3. Onboard high-efficiency charge/discharge power management chip ETA6096 and MX1.25 battery header, the current charging current is set to 1A, the user can replace the R15 resistor to change the charging current, access to the 3.7V single-cell lithium battery. Please refer to the schematic for more details and connect a 3.7V single-cell lithium battery with appropriate capacity.
  4. When setting up the environment, please be careful to use the provided library files with the specific ESP32 firmware version.

Hardware Description

Interface Description


  • Type-C interface: using CH343P chip for USB to UART to connect the ESP32-S3's UART_TXD (GPIO43) and UART_RXD (GPIO44), which is for firmware burning and log printing. With the automatic download circuit, you can download the firmware directly after connecting the Type-C interface.
  • SH1.0 connector: The development board leads to 6 GPIOs that can be used for other external connections, GPIO can be flexibly configured to I2C, SPI, and other peripheral functions, and VSYS can be directly input 5V to power the entire development board.
  • LCD interface: Onboard a 1.28inch screen with 4-wire SPI communication, the touch using I2C communication, and SPI rate can be improved to 80MHz. (The development board uses GPIO2 to control backlight brightness, 2x MOS tubes to control the switch pad around the battery holder, connected to GPIO4 and GPIO5, and you can solder low-current devices such as vibration motors. For more details, please refer to the schematic.
  • I2C interface: The ESP32-S3 provides multiple hardware I2C. Currently, GPIO6 (SDA) and GPIO7 (SCL) pins are used for the I2C bus, mounting the QMI8658 six-axis inertial measurement unit and LCD touch control chip on the development board. Please refer to the schematic for more information.
  • MX1.25 battery header: GPIO1 on the development board is used for measuring battery voltage. The battery voltage is divided using a series connection of 200K and 100K resistors, connected to GPIO1. The ESP32-S3 series has 2 channels of 12-bit SAR ADC measurement units. The code converts this into a voltage formula: 3.3 / (1<<12) * 3 * AD_Value.
ESP32-S3R2 LCD SH1.0 MX1.25 QMI8658 other


ESP32-S3-Touch-LCD-1.28 05.jpg

Environment Setting

The software framework for ESP32 series development boards is completed, and you can use MicroPython and C/C++ (Arduino, ESP-IDF) for rapid prototyping of product development. Here's a brief introduction to these two 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.

Please install the 2.0.12 version firmware, the demo may not be compatible if the version is too high.

  • Fill in the following link in the Additional Boards Manager URLs section of the Settings interface under File -> Preferences and save.

ESP32-C3-Zero -05.jpg

  • Search esp32 on Board Manager to install, and restart Arduino IDE to take effect.
  • Enter Arduino IDE, and select Tools -> 16MB Flash and enable QSPI PSRAM as shown below:

ESP32-C3-Zero -16.jpg

ESP32-C3-Touch-LCD1.28 -06.jpg

Library Installation

  • After installing the TFT_SPI and lvgl libraries, configuration files are required. It is suggested to directly copy the TFT_eSPI_Setups, TFT_eSPI, and lvgl folders from the Esp32-s3-touch-lcd-lib into the directory C:\Users\xxxx\Documents\Arduino\libraries. 'xxxx' represents your computer's username. Please be careful while identifying.



1. Download and install the latest Thonny, open Thonny IDE -> Configure interpreter... as shown below:
CircuitPython Thonny06.jpg
2. Connect the Type-C interface to the USB cable, find the device manager or the corresponding COM port, and download or run the program, 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 development board's Flash content will be cleared before download, the entire download process lasts about 1 minute, MPY firmware can be downloaded from the official website.
CircuitPython Thonny033.jpg
4. Currently, the development board is developed using customized firmware, open the flash_download_tool_3.9.5, the firmware is in the sample demo, the firmware can refer to this link and is combined into a single file. Please note that the download address is 0x0.
  • After connecting ESP32-S3-Touch-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.
ESP32-C3-Zero Thonny90.png
  • 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.
ESP32-C3-Zero Thonny91.pngESP32-C3-Zero Thonny92.png
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.

ESP32-C3-Zero Thonny93.jpg
ESP32-C3-Zero Thonny94.png

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

ESP32-C3-Zero Thonny95.png

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

ESP32-C3-Zero Thonny-05.jpg
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 ESP32-S3 application firmware address is 0x10000, the partition_tables.bin address is 0x8000, the bootloader.bin address is 0x0.

ESP32-C3-Zero 09.jpg

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

  • For Arduino examples, please refer to File -> examples in Arduino-esp32 or Arduino IDE (e.g. ESP32 GPIO, WIFI and other common examples), and for screen drivers, please refer to the sample demo.


Use Arduino Demo

1. Select the demo, here we choose the demo to get the chip ID.

ESP32-S3-Pico 43.jpg

2. Select the board as ESP32S3 Dev Module.

ESP32-S3-Pico 44.jpg

3. Choose the COM5 port of ESP32-S3 USB.

ESP32-S3-Pico 45.jpg

4. Click the download button, then it compiles and downloads automatically. If the download fails, please press and hold the boot button to power up again and release the button, and then download again.

ESP32-S3-Pico 47.jpg

5. Finish.

ESP32-S3-Pico 48.jpg

6. Open the Serial Port Monitor.

ESP32-S3-Pico 49.jpg

7. See the chip ID of the loop output.

ESP32-S3-Pico 50.jpg

  • Note: this demo cannot make LED on.


esp32-s3-touch-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, 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.

c. After checking the sensors, long-press the red area labeled 'LongPress Quit' to enter the touch test phase. Touch dot program in the white area of the Touch test.
  • If the screen fails to be on, please check whether the onboard parameters are set correctly.

ESP32-S3-Touch-LCD-1.28 Add 1.png

  • If the screen fails to be on, please check whether the ESP32 firmware version is 2.0.12.

ESP32-S3-Touch-LCD-1.28 Add 2.png


  • Arduino_LVGL sample is for displaying LVGL benchmark, music, and so on. For LVGL, you can refer to LVGL development tutorial.
  • The callback function of LVGL library for displaying refreshing, refresh the the contents of 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: The display driver structure pointer provided, 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: The defined 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 and 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, where the counter "count", each call increases the counter by one, triggering an operation when the count reaches a certain value, here is a simulation of performing a restart operation after 30 timer triggers, the specific behavior can be adjusted according to needs.
void example_increase_reboot(void *arg)
  • The input device read callback function in the LVGL library is used to handle touchscreen input events:
void my_touchpad_read( lv_indev_drv_t * indev_drv, lv_indev_data_t * data )
     lv_indev_drv_t *indev_drv: the input device driver structure pointer of the LVGL. This structure includes information related input device and a callback function.
     lv_indev_data_t *data: the input device data structure pointer of the LVGL. This structure is for storing the status and data of the input device, including the current touch status (press or release) and the coordinates of the touch points.
  • If the screen fails to be on, please check whether the onboard parameters are set correctly.

ESP32-S3-Touch-LCD-1.28 Add 1.png

  • If the screen fails to be on, please check whether the ESP32 firmware version is 2.0.12.

ESP32-S3-Touch-LCD-1.28 Add 2.png


  • Arduino_Chinese_Font is for displaying the LVGL built-in 1000 common Chinese fonts.
  • If the screen fails to be on, please check whether the onboard parameters are set correctly.

ESP32-S3-Touch-LCD-1.28 Add 1.png

  • If the screen fails to be on, please check whether the ESP32 firmware version is 2.0.12.

ESP32-S3-Touch-LCD-1.28 Add 2.png


  • 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.
  • If the screen fails to be on, please check whether the onboard parameters are set correctly.

ESP32-S3-Touch-LCD-1.28 Add 1.png

  • If the screen fails to be on, please check whether the ESP32 firmware version is 2.0.12.

ESP32-S3-Touch-LCD-1.28 Add 2.png


Note: Before using the Micropython demos, please check whether the ESP32-S3-Touch-LCD-1.28 has burned the mpy firmware (Please note that this firmware is for MicroPython environment configuration, not for LCD lighting 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.









Yes, just specify the pins directly when initializing the UART:



Press and hold the boot key to connect the device, and release the boot key.



It uses an MX1.25 2P connector, which can be connected to a 3.7V battery and supports charging and discharging.
ESP32-S3-Touch-LCD-1.28 FAQ.png



Please use our sample program and follow the tutorials to install our libraries, please do not upgrade the version of the libraries, it may cause incompatibility.



Please install drivers and check again
Here are some suggestions that might help:

  • Check the USB Cable and Port: Make sure you're using a data-capable USB cable (not just a charging cable) and try a different USB port on your computer.
  • Correct Serial Port: Ensure that the correct serial port is selected in your IDE. You can check this by disconnecting your device, noting the available ports within the IDE, then reconnecting your device and seeing which new port appears.
  • Manual Reset: Try manually resetting the board during the upload process. To do this, hold down the BOOT button, press and release the RESET button, then release the BOOT button.
  • Update the IDE and Libraries: Make sure you're using the latest version of your chosen IDE and that all relevant libraries are up to date.
  • Check the Drivers: Ensure that the correct drivers are installed on your computer. You might need to reinstall CH343P driver or update them.



Technical Support

If you need technical support or have any feedback/review, please click the Submit Now button to submit a ticket, Our support team will check and reply to you within 1 to 2 working days. Please be patient as we make every effort to help you to resolve the issue.
Working Time: 9 AM - 6 PM GMT+8 (Monday to Friday)