ESP32-S3-AMOLED-1.91
| ||
| ||
Overview
Introduction
ESP32-S3-AMOLED-1.91 is a low-cost, high-performance and highly scalable ESP32_GUI development board designed by Waveshare. It is available in both touch and non-touch versions, both supporting 2.4GHz WiFi and BLE 5, integrated high-capacity Flash and PSRAM, onboard RTC, IMU and 1.91-inch AMOLED screen, exposed UART, GPIO, I2C and USB bus interfaces, and a large number of demos and technical support for you to quickly develop automation and IoT products.
Features
- Equipped with high-performance 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 SRAM and 384KB ROM, stacked with 16MB Flash and 8MB PSRAM
- Onboard 1.91-inch wide-capacitive AMOLED screen with 536 × 240 resolution and 65K color
- AMOLED display uses QSPI interface, enhancing speed while saving a large amount of IO
- The touch version uses an I2C interface to communicate with the touch chip, supporting 5-point touch and interrupt output
- Onboard IMU, TF card slot; the appearance is in the form of a development board, exposing a large number of GPIO, making it suitable for various occasions
Onboard Resources
Interfaces
Dimensions
AMOLED Parameters
Version Options
Usage instructions
ESP32-S3-AMOLED-1.91 currently provides two development tools and frameworks, Arduino IDE and ESP-IDF, providing flexible development options, you can choose the right development tool according to your project needs and personal habits.
Development tools
Each of these two development approaches has its own advantages, and developers can choose according to their needs and skill levels. Arduino are suitable for beginners and non-professionals because they are easy to learn and quick to get started. ESP-IDF is a better choice for developers with a professional background or high performance requirements, as it provides more advanced development tools and greater control capabilities for the development of complex projects.
Components preparation
- ESP32-S3-AMOLED-1.91 x1
- TF card x 1
- USB cable (Type-A to Type-C) x 1
Working with Arduino
This chapter introduces setting up the Arduino environment, including the Arduino IDE, management of ESP32 boards, installation of related libraries, program compilation and downloading, as well as testing demos. It aims to help users master the development board and facilitate secondary development.
Environment setup
Download and install Arduino IDE
- Click to visit the official website, select the corresponding system and system bit to download.
- Run the installer and install all by default.
Install Arduino-ESP32
- Regarding ESP32-related motherboards used with the Arduino IDE, the esp32 by Espressif Systems library must be installed first.
- It is generally recommended to use Install Online. If online installation fails, use Install Offline.
- To install the Arduino-ESP32 tutorial, please refer to Arduino board manager tutorial
- The ESP32-S3-AMOLED-1.91 development board comes with an offline package. Click here to download: esp32_package_3.0.7_arduino offline package
Board name | Board installation requirements | Version number requirements |
---|---|---|
ESP32-S3-AMOLED-1.91 | "Install Offline" / "Install Online” | 3.0.7 and above |
Install library
- When installing Arduino libraries, there are usually two ways to choose from: Install online and Install offline. If the library installation requires offline installation, you must use the provided library file
For most libraries, users can easily search and install them through the online library manager of the Arduino software. However, some open-source libraries or custom libraries are not synchronized to the Arduino Library Manager, so they cannot be acquired through online searches. In this case, users can only manually install these libraries offline. - For library installation tutorial, please refer to Arduino library manager tutorial
- ESP32-S3-AMOLED-1.91 library file is stored in the sample program, click here to jump: ESP32-S3-AMOLED-1.91 Demo
Library Name | Description | Version | Library Installation Requirements |
---|---|---|---|
LVGL | Graphical library | v8.4.0 | "Install Offline” |
Run the First Arduino Demo
New Project
void setup() { // put your setup code here, to run once: Serial.begin(115200); } void loop() { // put your main code here, to run repeatedly: Serial.println("Hello, World!"); delay(2000); }
- Save the project and select
File
->Save As...
. In the pop-up menu, select the path to save the project, and enter a project name, such as Hello_World, clickSave
Compile and Flash Demos
- Select the corresponding development board, take the ESP32S3 motherboard as an example:
①. Click to select the dropdown menu option Select Other Board and Port;
②. Search for the required development board model esp32s3 dev module and select;
③. Select COM Port;
④. Save the selection.
- Some development boards with specified version numbers support direct model selection, for example, "Waveshare ESP32-S3-LCD-1.69":
- If the ESP32S3 mainboard only has a USB port, you need to enable USB CDC, as shown in the following diagram:
- Compile and upload the program:
①. Compile the program; ②. Compile and download the program; ③. Download successful.
- Open the Serial Monitor window, and the demo will print "Hello World!" every 2 seconds, and the operation is as follows:
Demos
Demo | Basic Description | Dependency Library |
---|---|---|
ADC | Read the current voltage value of the system | - |
I2C_QMI8658 | Print the original data sent by the IMU | - |
LVGL | LVGL demo | LVGL |
SPI_SD | Load and display the information of the TF card | - |
WIFI_STA | Set to STA mode to connect to WiFi and obtain an IP address | - |
WIFI_AP | Set to AP mode to obtain the IP address of the access device | - |
Arduino_Playablity | Playability program demo | - |
Arduino project parameter settings
ADC
Code analysis
adc_bsp_init(void)
: Initializes ADC1, including creating an ADC one-time trigger unit and configuring channel 0 for ADC1.adc_get_value(float *value,int *data)
: Reads the value of ADC1 channel 0 and calculates the corresponding voltage value based on the reference voltage and resolution, stores it at the position where the incoming pointer points to, and stores 0 if the read fails.adc_example(void* parmeter)
: After initializing the ADC, in an infinite loop, read the value of the ADC channel on GPIO1, print the original ADC value, and calculate the system voltage value, performing this operation once every second.
Result demonstration
- Open the serial port monitoring, you can see the ADC value and voltage in the printed output, as shown in the following figure:
- The ADC sampling value is around 2518, and the actual voltage is greater than 3.3V, which is due to the voltage boost through the battery chip. For a detailed analysis, you can refer to the schematic diagram
I2C_QMI8658
Code analysis
qmi8658c_example(void* parmeter)
: The function initializes the QMI8658 device, reading and printing accelerometer data, gyroscope data, and temperature data in an infinite loop, once every second. During the rotation of the board, the gyroscope data increases with greater rotation speed, and the accelerometer calculates the corresponding acceleration based on the current position.
Result demonstration
- Open the serial port monitoring, and you can see the original data output from the IMU (Euler angles need to be converted by yourself), as shown in the following figure:
- Data is output once every second. If you need to modify or refer to it, you can directly access the qmi source file for operations.
LVGL
Code analysis
For LVGL, lvgl_conf.h is its configuration file, and below are explanations for some commonly used contents.
/*Color depth: 1 (1 byte per pixel), 8 (RGB332), 16 (RGB565), 32 (ARGB8888)*/ #define LV_COLOR_DEPTH 16//Color depth, a macro definition that must be concerned with porting LVGL #define LV_MEM_CUSTOM 0 #if LV_MEM_CUSTOM == 0 /*Size of the memory available for `lv_mem_alloc()` in bytes (>= 2kB)*/ #define LV_MEM_SIZE (48U * 1024U) /*[bytes]*/ /*Set an address for the memory pool instead of allocating it as a normal array. Can be in external SRAM too.*/ #define LV_MEM_ADR 0 /*0: unused*/ /*Instead of an address give a memory allocator that will be called to get a memory pool for LVGL. E.g. my_malloc*/ #if LV_MEM_ADR == 0 #undef LV_MEM_POOL_INCLUDE #undef LV_MEM_POOL_ALLOC #endif #else /*LV_MEM_CUSTOM*/ #define LV_MEM_CUSTOM_INCLUDE <stdlib.h> /*Header for the dynamic memory function*/ #define LV_MEM_CUSTOM_ALLOC malloc #define LV_MEM_CUSTOM_FREE free #define LV_MEM_CUSTOM_REALLOC realloc #endif /*LV_MEM_CUSTOM*/ //The above section is mainly for LVGL memory allocation, //which defaults to lv_mem_alloc() versus lv_mem_free().
There are also some LVGL demos and file systems that can be set in the conf configuration file.
Code modification
- For boards without touch, you need to find
EXAMPLE_USE_TOUCH
in the file where the main function is located, and change1
to0
- For boards with touch, you need to find
EXAMPLE_USE_TOUCH
in the file where the main function is located, and change0
to1
#define EXAMPLE_USE_TOUCH 0
Result demonstration
The LVGL demo has high requirements for RAM and ROM, so it is necessary to configure the demo according to the requirements of environment setup, and after the program is flashed, the running effect of the device is as follows (if it is a board with touch, you need to modify the macro definition EXAMPLE_USE_TOUCH to 1):
SPI_SD
Hardware connection
- Install a TF card on the board (you must insert a TF card with a capacity of less than 64G first), and use a USB cable to connect the board to the computer (if it is a V1 board, you need to comment out the macro definition VersionControl_V2, which is enabled by default)
Code analysis
SD_card_Init(void)
: This function initializes the TF card according to different configurations, including configuring the mounting parameters, host and card slot parameters, and then tries to mount the TF card, if successful, the card information and capacity are printed.
Result demonstration
- Click on the serial port monitoring device, you can see the information of the output TF card, practical_size is the actual capacity of the TF card, as shown in the figure below:
WIFI_STA
Code modification
The project realizes that the chip is connected to WIFI in STA mode and obtains the IP address, before compiling and downloading the firmware, some code needs to be modified, specifically changing the name and password of the WIFI router to those suitable for the environment.
Code analysis
wifi_init(void)
: This function is used to initialize the Wi-Fi connection of the ESP32. It sets the ESP32 to Wi-Fi site mode and tries to connect to the specified Wi-Fi network (via thessid
andpassword
). If the connection is successful, it prints the local IP address; if the connection fails within a certain period (20 * 500 milliseconds), it prints the connection failure message. At the same time, the function can also set the auto-connection and auto-reconnect functions.
WIFI_AP
Code analysis
- The code initializes serial communication on the ESP32 and then creates a WiFi access point named "bsp_esp_demo" with the password "waveshare", and no other continuous operations are performed in a loop while the program runs.
const char* ssid = "bsp_esp_demo"; const char* password = "waveshare"; WiFi.softAP(ssid,password);
Result demonstration
- Use your mobile phone or other device to connect to WIFI, the WiFi name is "bsp_esp_demo", and the password is "waveshare"
Arduino_Playablity
- We also provide some playable demos for your reference, but it should be noted that the following demos are based on ESP32_Arduino versions below V3.0. Environment setup can be referred to below
- Install the 2.0.9 environment directly by downloading the Arduino2.0.9 offline package, double-click to install it after the download is completed
- Click to download the required library files, the library file is installed in the same way as the Arduino library file installation above
- You can click ESP32-S3-AMOLED-1.91-Arduino_Playablity to download the demo
Hardware connection
- Connect the board to the computer using a USB cable
Working with ESP-IDF
This chapter introduces setting up the ESP-IDF environment setup, including the installation of Visual Studio and the Espressif IDF plugin, program compilation, downloading, and testing of example programs, to assist users in mastering the development board and facilitating secondary development.
Environment setup
Download and install Visual Studio
- Open the download page of VScode official website, choose the corresponding system and system bit to download
- After running the installation package, the rest can be installed by default, but here for the subsequent experience, it is recommended to check boxes 1, 2, and 3
- After the first two items are enabled, you can open VSCode directly by right-clicking files or directories, which can improve the subsequent user experience.
- After the third item is enabled, you can select VSCode directly when you choose how to open it.
Install Espressif IDF Plug-in
- It is generally recommended to use Install Online. If online installation fails due to network factor, use Install Offline.
- For more information about how to install the Espressif IDF plugin, see Install Espressif IDF Plugin
Run the First ESP-IDF Demo
New Project
Create Demo
- Using the shortcut F1, enter esp-idf:show examples projects
- Select your current IDF version
- Take the Hello world demo as an example
①Select the corresponding demo
②Its readme will state what chip the demo applies to (how to use the demo and the file structure are described below, omitted here)
③Click to create the demo
- Select the path to save the demo, and require that the demos cannot use folders with the same name
Modify COM Port
- The corresponding COM ports are shown here, click to modify them
- Please select the COM ports according to your device (You can view it from the device manager)
- In case of a download failure, please press the Reset button for more than 1 second or enter download mode, and wait for the PC to recognize the device again before downloading once more
Modify Driver Object
- Select the object we need to drive, which is our main chip ESP32S3
- Choose the path to openocd, it doesn't affect us here, so let's just choose one
Other Status Bar Functions
①.ESP-IDF Development Environment Version Manager, when our project requires differentiation of development environment versions, it can be managed by installing different versions of ESP-IDF. When the project uses a specific version, it can be switched to by utilizing it
②.Device flashing COM port, select to flash the compiled program into the chip
③.Select set-target chip model, select the corresponding chip model, for example, ESP32-P4-NANO needs to choose esp32p4 as the target chip
④.menuconfig, click it to Modify sdkconfig configuration file Project configuration details
⑤.fullclean button, when the project compilation error or other operations pollute the compiled content, you can clean up all the compiled content by clicking it
⑥.Build project, when a project satisfies the build, click this button to compile
⑦.Current download mode, the default is UART
⑧.flash button, when a project build is completed, select the COM port of the corresponding development board, and click this button to flash the compiled firmware to the chip
⑨.monitor enable flashing port monitoring, when a project passes through Build --> Flash, click this button to view the log of output from flashing port and debugging port, so as to observe whether the application works normally
⑩.Debug
⑪.Build Flash Monitor one-click button, which is used to continuously execute Build --> Flash --> Monitor, often referred to as "little flame"
Compile, Flash and Serial Port Monitor
- Click on the all-in-one button we described before to compile, flash and open the serial port monitor
- It may take a long time to compile especially for the first time
- During this process, the ESP-IDF may take up a lot of CPU resources, so it may cause the system to lag
- If it is the first time to flash the program for a new project, you will need to select the download method, and select UART
- This can also be changed later in the Download methods section (click on it to pop up the options)
- As it comes with the onboard automatic download circuit, it can be downloaded automatically without manual operation
- After successful download, it will automatically enter the serial monitor, you can see the chip output the corresponding information and be prompted to restart after 10S
Use the IDF Demos
Open In the Software
- Open VScode software and select the folder to open the demo
- Select the provided ESP-IDF example and click to select the file (located in the /Demo/ESP-IDF path under demo)
Open from Outside the Software
- Select the project directory correctly and open the project, otherwise it will affect the compilation and flashing of subsequent programs
- After connecting the device, select the COM port and model, click below to compile and flash to achieve program control
ESP-IDF Project Details
- Component: The components in ESP-IDF are the basic modules for building applications, each component is usually a relatively independent code base or library, which can implement specific functions or services, and can be reused by applications or other components, similar to the definition of libraries in Python development.
- Component reference: The import of libraries in the Python development environment only requires to "import library name or path", while ESP-IDF is based on the C language, and the importing of libraries is configured and defined through
CMakeLists.txt
. - The purpose of CmakeLists.txt: When compiling ESP-IDF, the build tool
CMake
first reads the content of the top-levelCMakeLists.txt
in the project directory to read the build rules and identify the content to be compiled. When the required components and demos are imported into theCMakeLists.txt
, the compilation toolCMake
will import each content that needs to be compiled according to the index. The compilation process is as follows:
- Component reference: The import of libraries in the Python development environment only requires to "import library name or path", while ESP-IDF is based on the C language, and the importing of libraries is configured and defined through
Demos
Demo | Basic Description | Dependency Library |
---|---|---|
ADC | Read the current voltage value of the system | - |
I2C_QMI8658 | Print the original data sent by the IMU | - |
LVGL | LVGL demo | LVGL |
SPI_SD | Load and display the information of the TF card | - |
WIFI_STA | Set to STA mode to connect to WiFi and obtain an IP address | - |
WIFI_AP | Set to AP mode to obtain the IP address of the access device | - |
FactoryProgram | Comprehensive project | LVGL |
ADC
Code analysis
adc_bsp_init(void)
: Initializes ADC1, including creating an ADC one-time trigger unit and configuring channel 0 for ADC1.adc_get_value(float *value)
: Reads the value of ADC1 channel 0 and calculates the corresponding voltage value based on the reference voltage and resolution, stores it at the position where the incoming pointer points to, and stores 0 if the read fails.adc_example(void* parmeter)
: After initializing the ADC, in an infinite loop, read the value of the ADC channel on GPIO1, print the original ADC value, and calculate the system voltage value, performing this operation once every second.
Result demonstration
After the demo is flashed, the running result of the device is as follows:
- Open the serial port monitoring, you can see the output ADC value and voltage, as shown in the following figure:
- It can be seen that the ADC sampling value is about 2511, and the actual voltage is greater than 3.3V, because this is the voltage after the battery chip is boosted. For specific analysis, you can click to view the schematic diagram
I2C_QMI8658
Code analysis
qmi8658c_example(void* parmeter)
: The function initializes the QMI8658 device, reading and printing accelerometer data, gyroscope data, and temperature data in an infinite loop, once every second.
Result demonstration
After the demo is flashed, the running result of the device is as follows:
- Open the serial port monitoring, and you can see the original data output from the IMU (Euler angles need to be converted by yourself), as shown in the following figure:
- You can see that it is output every 1 second. If you need to modify or refer to it, you can directly go to the qmi source file to modify it
LVGL
Code analysis
- There are two projects in the LVGL catalog, one is the original display, and the other is the 90-degree rotation display, which can be selected according to your needs.
- The original display and the 90-degree rotation display are mainly different from two points:
① and ②: There is a difference in the number of pixels
in the horizontal and vertical directions
③ and ④: The register at the 0x36
address under the lcd_init_cmds array is responsible for rotation, and modifying its value can achieve a rotation effect. If no rotation is needed, you can directly delete {0x36,(uint8_t []){0xF0,1,0}}
Code modification
- For boards without touch, you need to find
EXAMPLE_USE_TOUCH
in the file where the main function is located, and change1
to0
- For boards with touch, you need to find
EXAMPLE_USE_TOUCH
in the file where the main function is located, and change0
to1
#define EXAMPLE_USE_TOUCH 0
Result demonstration
SPI_SD
Hardware connection
- Install a TF card on the board (you must insert a TF card with a capacity of less than 64G first), and use a USB cable to connect the board to the computer (if it is a V1 board, you need to comment out the macro definition VersionControl_V2 in sd_card_bsp.c, which is enabled by default)
Code analysis
SD_card_Init(void)
: This function initializes the TF card according to different configurations, including configuring the mounting parameters, host and card slot parameters, and then tries to mount the TF card, if successful, the card information and capacity are printed.
WIFI_STA
Code analysis
espwifi_Init(void)
: This function is used for WiFi initialization on ESP32. It sequentially initializes non-volatile storage, the TCP/IP stack, creates a default event loop and a default WiFi site network interface, initializes WiFi with the default configuration, registers event handlers to handle WiFi and IP-related events, sets WiFi connection parameters, and starts WiFi.
WIFI_AP
Code analysis
wifi_init_softap(void)
: This function is used to initialize the ESP32's Wi-Fi soft access point, including setting up the network interface, registering event handling functions, configuring soft AP parameters, and starting the soft AP.
FactoryProgram
Hardware connection
- Use a USB cable to connect the board to the computer (if it is a V1 version, you need to comment out the CMake statement target_compile_definitions which is enabled by default in the CMakeLists.txt file under the ui_bsp directory)
Code modification
- For boards without touch, you need to find
EXAMPLE_USE_TOUCH
in the file where the main function is located, and change1
to0
- For boards with touch, you need to find
EXAMPLE_USE_TOUCH
in the file where the main function is located, and change0
to1
#define EXAMPLE_USE_TOUCH 0
Result demonstration
- The touch version supports BOOT button and touch switching
- Switch pages by using the BOOT button on the side of the board to display the analog clock interface first
- Switch to the Argument interface by pressing the BOOT button, where you can see a page with information on the onboard hardware
- Click the BOOT button again to jump to the Touch interface, which is the component interface
- Click the BOOT button again to jump to the WIFI interface
Resources
Schematic Diagram
Demos
Structure Diagram
Datasheets
ESP32-S3
Other Components
Software Tools
Arduino
- Arduino IDE Official download link
- ESP32-Arduino official documentation
- esp32_package_3.0.7_arduino offline package
- esp32_package_2.0.9_arduino offline package
VScode
Other Resource Links
FAQ
- Long press the BOOT button, press RESET at the same time, then release RESET, then release the BOOT button, at this time the module can enter the download mode, which can solve most of the problems that can not be downloaded.
- First consider the network issue, try switching to another network
- Check if the Arduino IDE -> Tools is correctly configured
- Modify LVGL display cache to the full screen size
- Modify the LV_IMG_CACHE_DEF_SIZE option in the configuration to 1000 to achieve some optimization
- Basic Chinese can be displayed, but if it is a rare character, it cannot be displayed
- You can transcode the required rare characters through the transcoding software, and then add them to the project font library
- It's normal for the first compilation to be slow, just be patient
- If there is a reset button on the development board, press the reset button; if there is no reset button, please power it on again
- Some AppData folders are hidden by default and can be set to show.
- English system: Explorer->View->Check "Hidden items"
- Chinese system: File Explorer -> View -> Display -> Check "Hidden Items”
- Windows system:
①View through Device Manager: Press the Windows + R keys to open the "Run" dialog box; input devmgmt.msc and press Enter to open the Device Manager; expand the "Ports (COM and LPT)" section, where all COM ports and their current statuses will be listed.
②Use the command prompt to view: Open the Command Prompt (CMD), enter the “mode” command, which will display status information for all COM ports.
③Check hardware connections: If you have already connected external devices to the COM port, the device usually occupies a port number, which can be determined by checking the connected hardware.
- Linux system:
①Use the dmesg command to view: Open the terminal.
①Use the ls command to view: Enter ls /dev/ttyS* or ls /dev/ttyUSB* to list all serial port devices.
③Use the setserial command to view: Enter setserial -g /dev/ttyS* to view the configuration information of all serial port devices.
Support
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)