Working with Arduino

This chapter contains the following sections. Please read as needed:

Arduino Getting Started
Setting Up Development Environment
Demo

Arduino Getting Started

New to Arduino ESP32 development and looking for a quick start? We have prepared a comprehensive Getting Started Tutorial for you.

Note: This tutorial uses the ESP32-S3-Zero as a reference example, and all hardware code is based on its pinout. Before you start, we recommend checking the pinout of your development board to ensure the pin configuration is correct.

Setting Up Development Environment

1. Installing and Configuring Arduino IDE

Please refer to the tutorial Installing and Configuring Arduino IDE to download and install the Arduino IDE and add ESP32 support.

Demo Usage Instructions

Download the examples, navigate to ESP32-S3-LR1121-XF/esp32s3/Arduino, and copy waveshare_lora_1121 to the libraries folder of your project folder. The project folder path can be found under File -> Preferences -> Sketchbook location

After copying, open the Arduino IDE. You can find all examples under File -> Examples -> waveshare lora spi. Open one to flash and test. Once the environment is set up, select the correct board and port. If you are unsure how to flash, refer to the image below:

①: Compile the demo

②: Complie and upload

3. Arduino Parameter Settings

Note: Please ensure the configuration follows the parameters above; otherwise, the program may not function correctly.

Demo

The demos are located in the Arduino directory of the 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

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

This application will update the firmware on the LR1121.
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.