Working with ESP-IDF

This chapter includes the following sections:

• ESP-IDF Getting Started
• Setting Up Development Environment
• Demo

ESP-IDF Getting Started

New to ESP32 ESP-IDF development and looking to get started quickly? We have prepared a general Getting Started Tutorial for you.

• Section 1: Environment Setup
• Section 2: Running Examples
• Section 3: Creating a Project
• Section 4: Using Components
• Section 5: Debugging
• Section 6: FreeRTOS
• Section 7: Peripherals
• Section 8: Wi-Fi Programming
• Section 9: BLE Programming

Please Note: This tutorial uses the ESP32-S3-Zero as a teaching example, and all hardware code is based on its pinout. Before you start, it is recommended that you check the pinout of your development board to ensure the pin configuration is correct.

Setting Up Development Environment

note

The following guide uses Windows as an example, demonstrating development using VS Code + the ESP-IDF extension. macOS and Linux users should refer to the official documentation.

Install the ESP-IDF Development Environment

1. Download the installation manager from the ESP-IDF Installation Manager page. This is Espressif's latest cross-platform installer. The following steps demonstrate how to use its offline installation feature.

   Click the Offline Installer tab on the page, then select Windows as the operating system and choose your desired version from the filter bar.

   

   After confirming your selection, click the download button. The browser will automatically download two files: the ESP-IDF Offline Package (.zst) and the ESP-IDF Installer (.exe).

   

   Please wait for both files to finish downloading.

2. Once the download is complete, double-click to run the ESP-IDF Installer (eim-gui-windows-x64.exe).

   The installer will automatically detect if the offline package exists in the same directory. Click Install from archive.

   

   Next, select the installation path. We recommend using the default path. If you need to customize it, ensure the path does not contain Chinese characters or spaces. Click Start installation to proceed.

   

3. When you see the following screen, the ESP-IDF installation is successful.

   

4. We recommend installing the drivers as well. Click Finish installation, then select Install driver.

   

Install Visual Studio Code and the ESP-IDF Extension

1. Download and install Visual Studio Code.

2. During installation, it is recommended to check Add "Open with Code" action to Windows Explorer file context menu to facilitate opening project folders quickly.

3. In VS Code, click the Extensions icon in the Activity Bar on the side (or use the shortcut Ctrl + Shift + X) to open the Extensions view.

4. Enter ESP-IDF in the search box, locate the ESP-IDF extension, and click Install.

   

5. For ESP-IDF extension versions ≥ 2.0, the extension will automatically detect and recognize the ESP-IDF environment installed in the previous steps, requiring no manual configuration.

Demo

The example programs are located in the ESP-IDF directory of the example package: ESP32-S3-LR1121-XF-Demo.zip

The following example names align with the directory structure of the ESP32-S3-LR1121-XF example package, allowing for quick location of corresponding functionalities:

Demo	Basic Description
lr1121_cad	Perform Channel Activity Detection (CAD) - LoRa only
lr1121_firmware_update	LR1121 firmware update tool
lr1121_lr_fhss	Transmit LR-FHSS data packets
lr1121_per	Perform Packet Error Rate (PER) test — Tx and Rx roles
lr1121_ping_pong	Initiate data exchange between two devices
lr1121_read	Enter receive mode
lr1121_sigfox	Send Sigfox-compliant uplink
lr1121_spectral_scan	Obtain inst-RSSI values in Rx mode to form a heatmap
lr1121_spetrum_display	Obtain inst-RSSI values in Rx mode to form a dynamic spectrum curve
lr1121_tx_cw	Tx Continuous Wave mode
lr1121_tx_infinite_preamble	Transmit infinite preamble
lr1121_write	Send data periodically
lr1121_LoRaWAN	Simple LoRaWAN Class A application

---

Demo Framework

Download the examples, navigate to ESP32-S3-LR1121/esp32s3/ESP-IDF, and open the example using VS Code. Using ESP-IDF examples requires configuring the script file ESP32-S3-LR1121/esp32s3/ESP-IDF/main/CMakeLists.txt. It defaults to the lr1121_ping_pong example. To use other examples, uncomment the corresponding line as shown in the figure below:

Once the environment is set up, select the correct board and port. If you are unsure how to flash, refer to the image below:

①. Select UART ②. Select Port ③. Select Chip ④. Compile and Flash

lr1121_cad

• This application will perform Channel Activity Detection (CAD) - LoRa only.
• Flash one device with CAD_EXIT_MODE set to TX, and another with CAD_EXIT_MODE set to RX to start testing.
• The effect is as follows:

  

lr1121_firmware_update

• By default, it flashes the transceiver firmware version 0101. To test other firmware versions, comment out #include "lr1121_transceiver_0101.h" in lr1121_firmware_update.h and uncomment other header files, then compile and flash. Only one firmware can be selected for flashing at a time.
• The effect is as follows:

  

lr1121_lr_fhss

• This application will configure the device to transmit data packets in LR-FHSS mode.
• The effect is as follows:

  

lr1121_per

• PER (Packet Error Rate) test. In lr1121_per.h, set one device as transmitter by defining #define RECEIVER 1, and set the other device as receiver by defining #define RECEIVER 0.
• The effect is as follows:

  

lr1121_ping_pong

• This application sets the device to ping-pong mode (point-to-point bidirectional communication test).
• The effect is as follows:

  

lr1121_read

• This application sets the device to read mode, automatically recognizing strings and hexadecimal numbers. Used with lr1121_write to achieve point-to-point communication.
• The effect is as follows:

  

lr1121_write

• This application sets the device to write mode, automatically sending data. Used with lr1121_read to achieve point-to-point communication.
• The effect is as follows:

  

lr1121_sigfox

• This application configures the device to send Sigfox-compliant uplinks.
• The effect is as follows:

  

lr1121_spectral_scan

• This application implements spectrum scanning by setting the device to Rx continuous mode and periodically reading the instantaneous RSSI of each frequency channel.
• Can be tested in conjunction with lr1121_tx_cw.
• Use lr1121_tx_cw to emit a signal at 868MHz with a power of 22dBm for testing. The results are as follows:

  

lr1121_spetrum_display

• This application implements spectrum display by setting the device to Rx continuous mode and periodically reading the instantaneous RSSI of each frequency channel.
• Can be tested in conjunction with lr1121_tx_cw.
• The plotting function requires support for VT100 control codes, e.g., MobaXterm.
• Use lr1121_tx_cw to emit a signal at 868MHz with a power of 22dBm for testing. The results are as follows:

  

lr1121_tx_cw

• This application configures the device to continuously transmit an unmodulated carrier wave.
• The effect is as follows:

  

lr1121_tx_infinite_preamble

• This application configures the device to continuously transmit an unmodulated carrier wave.
• It continuously transmits a waveform. This waveform is modulated (LoRa format), mainly used for testing LoRa transmission performance, spectrum, and certification (LoRa mode).
• Does not send a complete packet, but uses a valid LoRa preamble modulation.

LoRa and LoRaWAN

What is LoRa?

Semtech's LoRa is a long-range, low-power wireless platform for the Internet of Things (IoT). Generally, it refers to radio frequency chips using LoRa technology. Its main features are as follows:

• LoRa (short for long range) uses a spread spectrum modulation technology derived from Chirp Spread Spectrum (CSS) technology. It is a type of long-distance wireless transmission technology and LPWAN communication technology. Spread spectrum technology trades bandwidth for sensitivity. Technologies like Wi-Fi and ZigBee also use spread spectrum, but LoRa modulation is characterized by approaching the Shannon-Hartley theorem limit, maximizing sensitivity improvement. Compared to traditional FSK technology, at the same communication rate, LoRa has 8~12 dBm better sensitivity than FSK. Currently, LoRa primarily operates in the Sub-GHz ISM bands.
• LoRa technology integrates digital spread spectrum, digital signal processing, and forward error correction coding, significantly improving long-distance communication performance. LoRa's link budget is superior to any other standardized communication technology; the link budget is the main factor determining distance in a given environment.
• LoRa RF chips mainly include the SX127X series, SX126X series, and SX130X series. The SX127X and SX126X series are used for LoRa nodes, while the SX130X series is used for LoRa gateways. For details, refer to Semtech's product list.

What is LoRaWAN?

• LoRaWAN is an open protocol for Low-Power Wide-Area Networks (LPWAN) built on top of the LoRa radio modulation technique. It is designed to wirelessly connect battery-powered "things" to the internet in regional, national, or global networks, targeting key IoT requirements such as bidirectional end-to-end communication, end-to-end security, mobility, and localization services. Nodes require network join authentication to connect wirelessly to the internet, establishing an encrypted communication channel between the node and the server. The LoRaWAN protocol layers are shown in the figure below.

• The Class A/B/C node device types in the MAC layer cover almost all IoT application scenarios. The difference between them lies in the transmission and reception time slots of the nodes.

• In the Modulation layer, parameters like EU868 and AS430 indicate different frequency bands used in different countries. Please refer to the link for regional parameters.

  

• Implementing a LoRaWAN network covering a city or other area requires four components: nodes (LoRa node RF chips), gateways (or base stations, LoRa gateway RF chips), servers, and the cloud, as shown in the figure below.

• A DEVICE (node device) must first initiate a join request packet to the GATEWAY and then to the server. Only after successful authentication can it normally send and receive application data with the server.

• The GATEWAY can communicate with the server via wired networks or 3/4/5G wireless networks.

• Major server-side operators include TTN, etc. For setting up your own cloud service, please refer to lorawan-stack or chirpstack.

  

Application

• This application is based on the official LoRaWAN example ModemE_application_examples and only demonstrates the basic LoRaWAN Class A application. Other advanced examples can be ported from the official repository, including: Join Request, LoRaWAN Class B application, LoRaWAN Multicast Class B/C examples, and FUOTA examples.

Component Preparation

• Raspberry Pi 4B (with compatible power supply)

• TF card (TF card with a capacity greater than 8GB is recommended)

• Card reader

• Gateway device

• Node device

• Development board (optional models): ESP32, Raspberry Pi, STM32, and Raspberry Pi Pico

  

Server Setup

• This example uses ChirpStack as the LoRaWAN network server. Please follow the official Raspberry Pi installation steps for configuration.

• First, download the ChirpStack Gateway OS image, extract it, and use Win32DiskImager to write the image to the TF card.

  Downloading the Image

  

  Writing the Image

  

• After writing, please refer to the official documentation for detailed configuration. This document only provides a brief installation guide. For details, see: ChirpStack Gateway OS Getting Started Guide.

• Insert the TF card into the Raspberry Pi and power it on. After booting, your computer's Wi-Fi should detect a wireless hotspot named ChirpStackAP-XXXXXX with the password ChirpStackAP. After connecting successfully, access 192.168.0.1 in a browser to open the ChirpStack management interface. No password is required for the first login.

  Connecting to Wi-Fi

  

  Accessing the Web Interface

  

• After booting, you can connect to an external network via Ethernet or Wi-Fi. Here, connecting via Ethernet is used as an example. To configure Wi-Fi, please refer to: Wi-Fi Configuration. After connecting to the network, you can view the current IP address in the web management interface.

  

Adding a Gateway

• After the server configuration is complete and the IP address is obtained, power off the Raspberry Pi and disconnect the power. Connect the SX1303-868M-LoRaWAN-Gateway-HAT (gateway device) to the Raspberry Pi and attach the antenna. After powering on the Raspberry Pi, use the previously obtained IP address to remotely access the device via an SSH tool (such as MobaXterm). The default username is root. After a successful connection, enter the following command in the terminal to get the gateway ID: gateway-id. The system will output the current device's gateway ID. Make a note of this ID; it will be needed when adding the gateway later.

  

• Enter the previously obtained IP address in a browser to access the ChirpStack management interface. Navigate to ChirpStack -> Concentratord and enable the gateway function. Using the SX1303 (868 MHz) as an example, configure it as shown below, then click "Save & Apply":

  

  Enabling the Gateway

  

  Configuring Gateway Parameters

• Navigate to Applications -> ChirpStack. The first time you enter, you need to log in. The default username and password are both admin. After logging in, click Gateways -> Add gateway, fill in the gateway-id obtained earlier on the Add page, and save it. Return to the Gateway page to see if the gateway has been successfully launched.

  

  Adding Gateway to Server

  

  Checking if Gateway is Online

Adding a Node

• First, add a device profile in the web interface: Device Profiles -> Add device profile. Configure as shown in the figure below:

  

• Then, add an application: Applications -> Add application, fill in the relevant information, and save:

  

  

  Setting EUI

  

  Setting Key

• Note: The ESP32-S3-LR1121 module operates in transceiver mode by default. To run the LoRaWAN protocol, you must first flash the corresponding firmware via the development board. Refer to the lr1121_firmware_update example in the Demo and run lr1121_firmware_update + lr1121_modem_05020001.

  

  ESP-IDF Demo

  

  Arduino ESP32 Demo

• The effect after successful flashing is shown below:

  

• If you need to restore transceiver mode (non-LoRaWAN) later, please re-flash the lr1121_transceiver_0101 firmware.

• After the firmware is flashed, download the LoRaWAN example program. Open it and navigate to the directory ESP32-S3-LR1121\esp32s3\ESP-IDF\main\examples\lr1121_LoRaWAN. Edit the lorawan_commissioning.h file and fill in the previously generated EUI, key, and other information in the corresponding positions. After completion, compile and flash.

  

  Filling in EUI

  

  Filling in Key

• After flashing, the node will automatically request to join the LoRaWAN network. Upon successful joining, the node will periodically send uplink data. You can view device events and communication status through the web interface:

  ①. Click Events to view the node's operating status.

  ②. Check for join failures.

  ③. If joining is successful, you can see the join event.

  ④. View the data reported by the node.

  ⑤. View debug information via the serial port.

  

• The server also supports sending downlink data to the node:

  ①. Click Queue.

  ②. Enter the hexadecimal data to be sent.

  ③. Click Send.

  ④. The node receives the data and prints it on the serial port.