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 openocd path, 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, please refer to 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-level CMakeLists.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 the CMakeLists.txt, the compilation tool CMake will import each content that needs to be compiled according to the index. The compilation process is as follows:

Demo description

• The analog voltage connected through the GPIO is converted to digital by the ADC, and then the actual lithium battery voltage is calculated and printed to the terminal.

Hardware connection

• Connect the board to the computer using a USB cable

Code analysis

• adc_bsp_init(void): Initializes ADC1, including creating an ADC one-time trigger unit and configuring channel 3 for ADC1.
• adc_get_value(float *value,int *data): Reads the value of ADC1 channel 3 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* parameter): Initialize ADC1 and then create an ADC task that reads the ADC value every 1 second and calculates the system's voltage based on the raw ADC value.

Result demonstration

• The program compilation download is complete, and opening the serial port monitor will show the printed ADC values and voltage, as shown in the following figure:
  

Demo description

• Through the I2C protocol, initialize the PCF85063 chip, set the time, and then periodically read the time and print it to the terminal

Hardware connection

• Connect the board to the computer using a USB cable

Code analysis

• void i2c_rtc_loop_task(void *arg) : Create an RTC task to implement RTC functionality, read the clock of the RTC chip every 1 seconds and then output it to the terminal

Result demonstration

• After the program is compiled and downloaded, open the serial port monitoring to see the RTC time of the printout, as shown in the following figure:
  

Demo description

• Initialize the SHTC3 chip through the I2C protocol, and then print the temperature and humidity information read every 1000 seconds to the terminal

Hardware connection

• Connect the board to the computer using a USB cable

Code analysis

• void i2c_SHTC3_loop_task(void *arg) : Create a SHTC3 sensor task to periodically obtain temperature and humidity.

Result demonstration

• Open the serial port monitoring, you can see the temperature and humidity data of the printout, as shown in the figure below:
  

Demo description

• Drive the TF card through SDMMC, and print the TF card information to the terminal after successfully mounting.

Hardware connection

• Install TF card in FatFs format on the board before powering on

Code analysis

• sdcard_init(void): Initialize the TF card using the 1-wire SDMMC method.
• sdcard_loop_task(void *arg): A task to test TF card read and write functionality. You need to uncomment the #define sdcard_write_Test macro definition.

//#define sdcard_write_Test

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:
  

Demo description

• This demo can set the development board as a hotspot, allowing phones or other devices in STA mode to connect to the development board.

Code analysis

• In the file softap_example_main.c, find SSID and PASSWORD, and then your phone or other device in STA mode can use the SSID and PASSWORD to connect to the development board.

#define EXAMPLE_ESP_WIFI_SSID      "waveshare_esp32"
#define EXAMPLE_ESP_WIFI_PASSWORD      "wav123456"

Result demonstration

After flashing the program, open the serial terminal, if the device is successfully connected to the hotspot, the MAC address and IP address of the device will be output, as shown in the figure: 

Demo description

• This example can configure the development board as a STA device to connect to the router and access the system network.

Code analysis

• In the file esp_wifi_bsp.c, find ssid and password, then modify them to the SSID and Password of the available router in your current environment.

wifi_config_t wifi_config = {
      .sta = {
        .ssid = "PDCN",
        .password = "1234567890",
      },
  };

Result demonstration

After flashing the program, open the serial terminal, if the device is successfully connected to the hotspot, the IP address obtained will be output, as shown in the figure:

Demo description

• Demonstrate how to control the power supply of the system through the PWR button when powered by a lithium battery.

Hardware connection

• Connect the board to the computer using a USB cable

Code analysis

• setup_ui(lv_ui *ui) : Initialize the UI interface to visualize control.
• user_button_init(): Initialize buttons and various trigger events.
• example_button_pwr_task(void* parmeter): A task triggered by a button event.

Result demonstration

• After the demo is flashed, disconnect the USB power supply, connect the lithium battery, and power on by pressing and holding the PWR button, as shown in the figure:

1. Press and hold the PWR button, wait for the screen to display "On", which means that the startup is successful, and release the button
2. Press and hold the PWR button again, wait for the screen to display "Off", which means that the power is turned off successfully, and release the button

Demo description

• Demonstrates how to get data from the microphone and then play it through the speaker

Hardware connection

• Connect the board to the computer using a USB cable

Code analysis

• i2c_master_Init() : Initialize I2C bus.
• user_ui_init(): Initialize the global UI.
• user_button_init(): Initialize the audio interface.

Result demonstration

• After the program is flashed, the main interface is as follows:
  

1. Double-click the BOOT button to enter recording mode, speak into the MIC, and it will automatically end after 3 seconds
2. Click the BOOT button to play the sound you just recorded
3. Double-click the PWR button to play a piece of music
4. Click the PWR button to interrupt music playback

Demo description

• By porting LVGL V8, it helps users quickly implement UI interface design.

Hardware connection

• Connect the board to the computer using a USB cable

Code analysis

• void loop_lvgl_img(void *arg): Create an img component task and switch images every 5s.
• void led_test_task(void *arg);: LED blinking task.

Result demonstration

• After the demo is flashed, the running result of the device is as follows:

Demo description

• By porting LVGL V9, it helps users quickly implement UI interface design.

Hardware connection

• Connect the board to the computer using a USB cable

Code analysis

• void loop_lvgl_img(void *arg): Create an img component task and switch images every 5s.
• void led_test_task(void *arg): LED blinking task.

Result demonstration

• After the demo is flashed, the running result of the device is as follows:

Demo description

• Comprehensive project, you can simply test the onboard hardware functions, or directly use the BIN firmware we provide for flashing.

Hardware connection

• Connect the board to the computer using a USB cable

Result demonstration

• The main interface is displayed as shown in the figure below:
  

1. You can check if the onboard hardware is working properly through the main interface
2. Click PWR to jump to the music interface. To view related settings, you can check the source code.

• The current demo provides test firmware, which can be used to test whether the onboard device functions properly by directly flashing the test firmware
• bin file path:

  ..\ESP32-S3-ePaper-1.54-Demo\Firmware