RAK11720 WisDuo LPWAN+BLE Module Quick Start Guide

This guide covers the following topics:

• RAK11720 as a Stand-Alone Device Using RUI3
• RAK11720 as a LoRa/LoRaWAN Modem via AT Command

Prerequisites

What Do You Need?

Before going through the steps of installing the RAK11720 WisDuo LPWAN Module, make sure to prepare the necessary items listed below.

Hardware

• RAK11720 WisDuo LPWAN+BLE Module
• Computer
• USB to UART TTL adapter

Software

• Download and install the Arduino IDE.

warning

If you are using Windows 10. Do NOT install the Arduino IDE from the Microsoft App Store. Install the original Arduino IDE from the Arduino official website. The Arduino app from the Microsoft App Store has problems using third-party Board Support Packages.

• Add RAK11720 as a supported board in Arduino IDE by updating Board Manager URLs in Preferences settings of Arduino IDE with this JSON URL https://raw.githubusercontent.com/RAKWireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless.com_rui_index.json. After that, you can then add RAKwireless RUI Apollo3 Boards via Arduino board manager.
• RAK Serial Port Tool

Product Configuration

RAK11720 as a Stand-Alone Device Using RUI3

This section of the guide covers the following:

1. Hardware Setup and Access to IO pins of RAK11720
2. LoRaWAN OTAA and ABP Example with Arduino IDE

Hardware Setup

The RAK11720 requires a few hardware connections before you can make it work. The bare minimum requirement is to have the power section properly configured, the reset pull-up resistor, the antenna, the SWD pins, the BOOT pin (used for recovery), the UART connection used for AT commands and FW updates, and (optional) a USB-UART chip for USB connection.

Figure 5826: RAK11720 Minimum Schematic

Ensure the antennas are properly connected to have a good LoRa and BLE signal. Also, note that you can damage the RF section of the chip if you power the module without an antenna connected to the IPEX MHF4 connectors.

Figure 5827: LoRa Antenna

Figure 5828: BLE Antenna

RAK11720 has a label on its sticker indicating where to connect the antennas, as shown in Figure 4.

Figure 5829: RAK11720 Antenna Label

NOTE

• Detailed information about the RAK11720 BLE and LoRa IPEX MHF4 antenna can be found on the 863-870 MHz antenna datasheet or the 902-928 MHz antenna datasheet.

• If the RAK11720 is not an IPEX MHF4 variant, the connection to the antenna is done via the RF pins. RAKwireless offers RF Antenna Design Service for custom PCB designs.

warning

• Standard IPEX connector will not work on RAK11720! The IPEX antenna connector of RAK11720 is a different variant called IPEX MHF4. This is specially designed for low-profile circuit boards with limited spaces.

• When using the LoRa or Bluetooth Low Energy transceivers, make sure that an antenna is always connected. Using these transceivers without an antenna can damage the module.

Software Setup

The default firmware of the RAK11720 is based on RUI3, which allows you to develop your own custom firmware to connect sensors and other peripherals to it. To develop your custom firmware using the Arduino IDE, you need to first add RAKwireless RUI Apollo3 Boards to the Arduino board manager, which will be discussed in this guide. You can then use RUI3 APIs for your intended application. You can send AT commands and upload custom firmware via UART or wirelessly via BLE. The AT commands in RAK11720 are still available even if you compile custom firmware via RUI3, and you also have the option to disable them.

RAK11720 RUI3 Board Support Package in Arduino IDE

If you don't have an Arduino IDE yet, you can download it from the Arduino official website.

NOTE

For Windows 10 and up users: If your Arduino IDE is installed from the Microsoft App Store, you need to reinstall your Arduino IDE by getting it from the Arduino official website. The Arduino app from the Microsoft App Store has problems using third-party Board Support Packages.

Once the Arduino IDE has been successfully installed, you can now configure the IDE to add the RAK11720 to its board selection by following these steps.

1. Open Arduino IDE and go to File > Preferences.

Figure 5830: Arduino Preferences

2. To add the RAK11720 to your Arduino Boards list, edit the Additional Board Manager URLs. Click the icon, as shown in Figure 6.

Figure 5831: Modifying Additional Board Manager URLs

3. Copy the URL https://raw.githubusercontent.com/RAKWireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless.com_rui_index.json and paste it on the field, as shown in Figure 7. If other URLs are already there, just add them on the next line. After adding the URL, click OK.

Figure 5832: Add Additional Board Manager URLs

4. Restart the Arduino IDE.
5. Open the Boards Manager from Tools Menu.

Figure 5833: Opening Arduino Boards Manager

6. Write RAK in the search bar, as shown in Figure 9. It will show you the available RAKwireless module boards you can add to your Arduino board list. Select and install the latest version of the RAKwireless RUI Apollo3 Boards.

Figure 5834: Installing RAKwireless RUI Apollo3 Boards

7. Once the BSP is installed, select Tools > Boards Manager > RAKWireless RUI APOLLO3 Modules > WisBlock Core RAK11720 Board.

Figure 5835: Selecting RAK11720 Module

Compile an Example with Arduino LED Breathing

1. After completing the steps for adding your RAK11720 to the Arduino IDE, you can now try to run a simple program to test your setup. You need to add two LEDs to the bare minimum schematic of the RAK11720 module, as shown in Figure 11.

Figure 5836: RAK11720 with Two LEDs

2. Connect the RAK11720 via USB and check the RAK11720 COM port using Windows Device Manager. Double-check the USB cable and USB port if the module is not detected.

Figure 5837: Device Manager Ports (COM & LPT)

3. Choose RAK11720 on the board selection. Navigate to Tools > Boards Manager > RAKWireless RUI APOLLO3 Modules > WisBlock Core RAK11720 Board.

Figure 5838: Selecting RAK11720 Module

4. Open the Tools Menu and select a COM port. COM12 is currently used.

Figure 5839: Select COM Port

5. You can see the serial monitor icon and click it to connect to the COM port.

Figure 5840: Open Arduino Serial Monitor

6. If the connection is successful, you can send the AT commands to RAK11720. For example, to check the RUI version, type AT+VER=? on the text area, then click on the Send button, as shown in Figure 16.

Figure 5841: Arduino Serial Monitor COM4

7. Open Arduino_Led_Breathing example code.

Figure 5842: LED Breathing Example

8. Click the Verify icon to check if you can successfully compile the example code.

Figure 5843: Verify the Example Code

9. If the compilation is successful, click the Upload icon to send the compiled firmware to your RAK11720.

NOTE

• RAK11720 should automatically go into BOOT mode when the firmware is uploaded via the Arduino IDE.
• You can also manually force BOOT mode by sending the AT+BOOT command. On BOOT mode, standard AT commands will not work anymore unless you send AT+RUN, which will escape BOOT mode.

Figure 5844: Upload the Example Code

10. If the upload is successful, you will see the Device programmed message.

Figure 5845: Device Programmed Successfully

11. After the Device Programmed is completed, you will see that the LEDs are blinking.

RAK11720 IO Pins and Peripherals

This section discusses how to use and access the pinouts of the RAK11720 using RUI3 APIs. It shows basic code for using digital IO, analog input, UART, and I2C.

How to Use Digital IO

Figure 5846: Available Digital I/O Pins in RAK11720

You can use any of the pins, as shown in Figure 21. Other pins with a specific purpose like UARTs and I2C can still be used, but with limitations. These dedicated pins were removed from this illustration of digital IO pins.

Click to view the example code.

/*
 RAK11720 Digital I/O Example

 You can use any of the following as Digital I/O:

P44
P45
P1
P5
P6
P7
P38
P4
P37
P31
P12
P36
P32
*/

void setup()
{
  pinMode(P44, OUTPUT); //Change the P44 to any digital pin you want. Also, you can set this to INPUT or OUTPUT
}

void loop()
{
  digitalWrite(P44,HIGH); //Change the P44 to any digital pin you want. Also, you can set this to HIGH or LOW state.
  delay(1000); // delay for 1 second
  digitalWrite(P44,LOW); //Change the P44 to any digital pin you want. Also, you can set this to HIGH or LOW state.
  delay(1000); // delay for 1 second
}

How to Use Analog Input

Figure 5847: Available Analog Input Pins in RAK11720

You can use any of the pins, as shown in Figure 22, as Analog Input Pin. See the example code below.

Click to view the example code.

/*
RAK11720 Analog Input Pins

PIN_A0 P13
PIN_A1 P33
PIN_A3 P5
PIN_A4 P31
PIN_A5 P32
PIN_A6 P36
PIN_A7 P7

You can use either format: PIN_A0 or P13
*/

#define analogPin PIN_A0  // or you can use PIN_A0

int val = 0;  // variable to store the value read

void setup()
{
  Serial.begin(115200);
}

void loop()
{
  val = analogRead(analogPin);  // read the input pin
  Serial.println(val);          // debug value
}

How to Use Serial Interfaces

• UART

There are two UART peripherals available on the RAK11720. There are also different Serial Operating Modes possible in RUI3, namely Binary Mode, AT Mode, and Custom Mode.

Serial Port	Serial Instance Assignment	Default Mode
UART0 (Pin 5 - GP39/RX0)/(Pin 4 - GP40/TX0)	Serial	AT Command
UART1 (Pin 1 - GP43/RX1)/(Pin 2 - GP42/TX1)	Serial1	Custom Mode
BLE Serial	Serial6	Custom Mode

Figure 5848: Available UART Pins in RAK11720

Click to view the example code.

void setup()
{
  Serial.begin(115200);                   // By default Serial is used for FW update and AT command.
  Serial1.begin(9600,RAK_AT_MODE);        // By default AT is disabled. With RAK_AT_MODE, AT command is activated. Baud rate can be configured to other values as well.
  Serial6.begin(115200, RAK_CUSTOM_MODE); // BLE UART is accessible via Serial6.
}

void loop()
{
  Serial1.println("RAK11720 TEST!");
  delay(1000); // delay for 1 second
}

• I2C

Figure 5849: Available I2C Pins in RAK11720

Make sure you have an I2C device connected to the specified I2C pins to run the example code below.

Click to view the example code.

#include <Wire.h>

void setup()
{
  Wire.begin();

  Serial.begin(115200);
  while (!Serial);
  Serial.println("\nI2C Scanner");
}

void loop()
{
  byte error, address;
  int nDevices;

  Serial.println("Scanning...");

  nDevices = 0;
  for(address = 1; address < 127; address++ )
  {
    // The i2c_scanner uses the return value of
    // the Write.endTransmisstion to see if
    // a device did acknowledge to the address.
    Wire.beginTransmission(address);
    error = Wire.endTransmission();

    if (error == 0)
    {
      Serial.print("I2C device found at address 0x");
      if (address<16)
        Serial.print("0");
      Serial.print(address,HEX);
      Serial.println("  !");

      nDevices++;
    }
    else if (error==4)
    {
      Serial.print("Unknown error at address 0x");
      if (address<16)
        Serial.print("0");
      Serial.println(address,HEX);
    }
  }
  if (nDevices == 0)
    Serial.println("No I2C devices found\n");
  else
    Serial.println("done\n");

  delay(5000);           // wait 5 seconds for next scan
}

• SPI

Figure 5850: Available SPI Pins in RAK11720

LoRaWAN Example

This example illustrates how to program the RAK11720 as a stand-alone LoRaWAN end-device via RUI3 Arduino APIs. To use RAK11720 as a LoRaWAN end-device, it needs to be within reach of a working LoRaWAN gateway registered to a LoRaWAN network server (LNS) or with a built-in network server.

NOTE

If you are new to LoRaWAN, here are a few good references about LoRaWAN and gateways:

• LoRaWAN 101
• What is a LoRaWAN Gateway
• How do LoRaWAN Gateways work?
• Things to Consider When Picking A LoRaWAN Gateway

To enable the RAK11720 module as a LoRaWAN end-device, a device must first be registered with the LoRaWAN network server. This guide covers both TTN and ChirpStack LoRaWAN network servers and the associated Arduino codes and AT commands for the RAK11720.

• TheThingsNetwork Guide - How to login, register new accounts, and create new applications on TTN.
• RAK11720 TTN OTAA Guide - How to add OTAA device on TTN and what AT commands to use on RAK11720 OTAA activation.
• RAK11720 TTN ABP Guide - How to add ABP device on TTN and what AT commands to use on RAK11720 ABP activation.
• ChirpStack Guide - How to create new applications on ChirpStack.
• RAK11720 ChirpStack OTAA Guide - How to add OTAA device to ChirpStack and what AT commands to use on RAK11720 OTAA activation.
• RAK11720 ChirpStack ABP Guide - How to add ABP device on ChirpStack and what AT commands to use on RAK11720 ABP activation.

Connecting to The Things Network (TTN)

In this section, it shows how to connect the RAK11720 module to the TTN platform.

NOTE

You need to have a working gateway that is connected to TTN, or you have to be within the coverage of a TTN community network.

Figure 5851: The Things Stack

As shown in Figure 26, The Things Stack (TTN V3) is an open-source LoRaWAN network server suitable for global, geo-distributed public and private deployments as well as for small local networks. The architecture follows the LoRaWAN Network Reference Model for standards compliance and interoperability. This project is actively maintained by The Things Industries.

LoRaWAN is a protocol for low-power wide-area networks. It allows large-scale Internet of Things deployments where low-powered devices efficiently communicate with internet-connected applications over long-range wireless connections.

The RAK11720 WisDuo module can be part of this ecosystem as a device, and the objective of this section is to demonstrate how simple it is to send data to The Things Stack using the LoRaWAN protocol. To achieve this, the RAK11720 WisDuo module must be located inside the coverage of a LoRaWAN gateway connected to The Things Stack server.

1. The first step is to go to The Things Network and sign up for an account, as shown in Figure 27. Then select a cluster as shown in Figure 29.

Figure 5852: Signing up an Account in TTN

Figure 5853: Signing up an Account in TTN

Figure 5854: Selecting Cluster in TTN

Figure 5855: Signing up Through the Things ID

Figure 5856: Creation of an Account Through the Things ID

Figure 5857: Creation of an Account Through the Things ID

You can use the same login credentials on the TTN V2 if you have one. If you have no account yet, you need to create one.

2. Now that you are logged in to the platform, the next step is to create an application. Click Create an application.

Figure 5858: The Things Stack Platform

Figure 5859: Creating TTN Application for Your Lorawan Devices

3. To have an application registered, input first the specific details and necessary information about your application, then click Create application.

Figure 5860: Details of the TTN Application

Figure 5861: Details of the TTN Application

4. If you had no errors in the previous step, you should now be on the application console page. The next step is to add end-devices to your TTN application.

LoRaWAN specifications enforce that each end-device has to be personalized and activated. There are two options for registering devices, depending on the activation mode selected. Activation can be done either via Over-The-Air-Activation (OTAA) or Activation-By-Personalization (ABP).

TTN OTAA Device Registration

1. Go to your application console to register a device. To start adding an OTAA end-device, click + Register end device, as shown in Figure 37.

Figure 5862: Register end device

2. To register the board, click Enter end device specifics manually.

Figure 5863: Enter end device specifics manually

3. The next step is to configure the Frequency plan, compatible LoRaWAN version, and supported Regional Parameters version. Then provide the JoinEUI credentials by entering zeros into them.

Figure 5864: Setting up your device

Figure 5865: Setting up your device

Figure 5866: Setting up your device

Figure 5867: Setting up your device

4. Click Show advanced activation, LoRaWAN class and cluster settings and configure the following and then click Confirm.

• Activation mode: Over the air activation (OTAA)
• Additional LoRaWAN class capabilities: None (class A only)

Figure 5868: Setting up your device

Figure 5869: Setting up your device

5. Once done, provide the DevEUI credentials of your device into the DevEUI portion. This will automatically generate the specific end-device ID of your board. Click Generate under AppKey in the Provisioning Information section, then click Register end device.

NOTE

• The AppEUI, DevEUI, and AppKey are hidden in this section as these are unique to a specific device. The DevEUI credential is unique to every RAK11720 device. Also, you should generate your own AppEUI and AppKey credentials for your specific device and application.

• The AppEUI is the same as JoinEUI.

Figure 5870: Setting up your device

Figure 5871: Setting up your device

Figure 5872: Register end device

6. You should now be able to see the device on the TTN console after you fully register your device, as shown in Figure 48.

NOTE

• The AppEUI, DevEUI, and AppKey are the parameters you will need to activate your LoRaWAN end-device via OTAA. The AppKey is hidden by default for security reasons, but you can easily show it by clicking the show button. You can also copy the parameters quickly using the copy button.
• The three OTAA parameters on the TTN device console are MSB by default.
• These parameters are always accessible on the device console page, as shown in Figure 48.

Figure 5873: OTAA Device Successfully Registered to TTN

Uploading OTAA LoRaWAN Example to RAK11720

After a successful registration of the RAK11720 device to the LoRaWAN Network Server, you can now proceed with running the LoRaWAN OTAA demo application example.

NOTE

If you use RAK3172 as a LoRaWAN modem using AT commands instead of a stand-alone device, there is a dedicated section for the OTAA AT Commands guide in the later portion of this document.

1. Open the example code under RAK WisBlock RUI examples.

Figure 5874: OTAA LoRaWAN Application Example

2. In the example code, you need to modify the device EUI (DEVEUI) and application key (APPKEY).

• The device EUI (DEVEUI) should match the device EUI registered in your network server. This is the same DEVEUI in the RAK11720 sticker if this is the one you used in the previous section device registration in the network server. DEVEUI is MSB.

  // OTAA Device EUI MSB
  uint8_t node_device_eui[8] = {0xAC, 0x1F, 0x09, 0xFF, 0xFE, 0x03, 0xEF, 0xAB};

• Another important parameter to change is the application key (APPKEY). This parameter should also be the same as the APPKEY in the network server you configured in the previous section adding RAK11720 to the network server section. APPKEY is an MSB.

// OTAA Application Key MSB
  uint8_t node_app_key[16] = {0xD9, 0xB8, 0x70, 0x18, 0x3E, 0xF1, 0x00, 0x1D, 0x1B, 0x4F, 0x2B, 0x4C, 0xBF, 0x60, 0xCA, 0x83};

Figure 5875: Updating DEVEUI and APPKEY

3. This guide uses the EU868 regional band. There is no need to change the band in the example code. If the region you are in is different, you need to update the band in the code as well.

NOTE

RAK11720 supports the following regions:

• RAK_REGION_EU433 = 0
• RAK_REGION_CN470 = 1
• RAK_REGION_RU864 = 2
• RAK_REGION_IN865 = 3
• RAK_REGION_EU868 = 4
• RAK_REGION_US915 = 5
• RAK_REGION_AU915 = 6
• RAK_REGION_KR920 = 7
• RAK_REGION_AS923-1 = 8
• RAK_REGION_AS923-2 = 9
• RAK_REGION_AS923-3 = 10

In addition to that, if you are using US915 you also need to set up the channel mask (channels 8 to 15 are the most commonly used channels in the US915 band).

This is the additional code on how to do it.

  if(!(ret = api.lorawan.band.set(5)))      // configure to US915
  {
       Serial.printf("LoRaWan OTAA - set band is incorrect! \r\n");
       return;
  }

  uint16_t maskBuff = 0x0002;               // configure the mask for channels 8-15
  api.lorawan.mask.set(&maskBuff);

4. The last step is to upload the code by clicking the Upload icon. Take note that you should select the right board and port, as shown in the previous example LED Blinking.

NOTE

• RAK11720 should automatically go to BOOT mode when the firmware is uploaded via Arduino IDE.
• If BOOT mode is not initiated, you have to send AT+BOOT manually to force BOOT mode.

Figure 5876: Uploading the Code

5. You should now be able to see the terminal logs in the Serial Monitor of the Arduino IDE. Sometimes the COM port will be disconnected, so you won't be able to see the terminal output immediately. You can reconnect the module or try to push the reset button to see the terminal output.

Figure 5877: Output Logs

6. You can also check on the LoRaWAN network server Live data if your device has been successfully joined with the join request and join accept logs.

Figure 5878: TTN Live Data

TTN ABP Device Registration

1. To register an ABP device, go to your application console and select the application to which you want your device to be added. Then click + Register end device, as shown in Figure 54.

Figure 5879: Adding ABP Device

2. To register the board, click Enter end device specifics manually.

Figure 5880: Enter end device specifics manually

3. Next step is to set up Frequency plan, compatible LoRaWAN version, and Regional Parameters version supported.

Figure 5881: Setting up your device

Figure 5882: Setting up your device

Figure 5883: Setting up your device

4. Click Show advanced activation, LoRaWAN class and cluster settings and configure the following:

• Activation mode: Activation by personalization (ABP)
• Additional LoRaWAN class capabilities: None (class A only)
• Network defaults (tick off the box): Use network's default MAC settings

Figure 5884: Setting up your device

Figure 5885: Setting up your device

5. Once done, provide the DevEUI credentials of your device into the DevEUI portion. You can also generate a DevEUI via the Generate button. Then click Generate under Device address, AppSKey, and NwkSKey under the Provisioning information section. Then click Register end device.

NOTE

• The DevEUI, Device address, AppSKey, and NwkSKey are hidden in this section as these are unique to a specific device. The DevEUI credential is unique to every RAK11720 device. Also, you should generate your own Device address, AppSKey, and NwkSKey credentials for your specific device and application.

Figure 5886: Setting up your device

Figure 5887: Setting up your device

Figure 5888: Setting up your device

Figure 5889: Setting up your device

Figure 5890: Setting up your device

Figure 5891: Register end device

6. You should now be able to see the device on the TTN console after you fully register your device, as shown in Figure 67.

Figure 5892: ABP device successfully registered to TTN

Uploading ABP LoRaWAN Example to RAK11720

After a successful registration of the RAK11720 module to the LoRaWAN Network Server as an ABP device, you can now proceed with running the LoRaWAN ABP demo application example.

NOTE

If you use RAK3172 as a LoRaWAN modem using AT commands instead of a stand-alone device, there is a dedicated section for ABP AT Commands guide in the later portion of this document.

1. Open the example code under RAK WisBlock RUI examples.

Figure 5893: ABP LoRaWAN Application Example

2. In the example code, you need to modify the device address (DEVADDR), application session key (APPSKEY), and network session key (NWKSKEY). All these parameters should match the ones generated on the LoRaWAN network server.

Figure 5894: Updating DEVADDR, APPSKEY, and NWKSKEY

3. This guide uses the EU868 regional band. There is no need to change the band in the example code. If the region you are in is different, you need to update the band in the code as well.

NOTE

RAK11720 supports the following regions:

• RAK_REGION_EU433 = 0
• RAK_REGION_CN470 = 1
• RAK_REGION_RU864 = 2
• RAK_REGION_IN865 = 3
• RAK_REGION_EU868 = 4
• RAK_REGION_US915 = 5
• RAK_REGION_AU915 = 6
• RAK_REGION_KR920 = 7
• RAK_REGION_AS923-1 = 8
• RAK_REGION_AS923-2 = 9
• RAK_REGION_AS923-3 = 10

In addition to that, if you are using US915 you also need to set up the channel mask (channels 8 to 15 are the most commonly used channels in the US915 band).

This is the additional code on how to do it.

  if(!(ret = api.lorawan.band.set(5)))      // configure to US915
  {
       Serial.printf("LoRaWan OTAA - set band is incorrect! \r\n");
       return;
  }

  uint16_t maskBuff = 0x0002;               // configure the mask for channels 8-15
  api.lorawan.mask.set(&maskBuff);

4. The last step is to upload the code by clicking the Upload icon. Note that you should select the right board and port, as shown in the previous example LED Blinking.

NOTE

RAK11720 should automatically go into BOOT mode when the firmware is uploaded via Arduino IDE. If BOOT mode is not initiated, you have to send AT+BOOT manually to force BOOT mode.

Figure 5895: Uploading the Code

5. You should now be able to see the terminal logs in the Serial Monitor of the Arduino IDE. Sometimes the COM port will be disconnected, so you won't be able to see the terminal output immediately. You can reconnect the module or try to push the reset button to see the terminal output.

Figure 5896: Output Logs

6. You can also check on the LoRaWAN network server Live data if your device can successfully send uplink packets.

Figure 5897: TTN Live Data

7. On ABP, frame counters for both uplink and downlink need to be tracked by the device firmware. However, on RUI3 ABP, there is no tracking, and frame counts will go back to zero when the device resets. This will result in failures on uplinks and downlinks. To counter this behavior, Resets frame counters option must be enabled by following the steps shown in Figure 73 up to Figure 76.

Figure 5898: General Settings

8. Click Expand on Network Layer.

Figure 5899: Expand Network Layer

9. Select Advanced MAC settings.

Figure 5900: Advance MAC settings

10. Check Resets frame counters. With this enabled, all uplinks and downlinks will be successful even if the device resets/restarts.

Figure 5901: Resets Frame Counters

Connecting with ChirpStack

This section shows how to connect the RAK11720 module to the ChirpStack platform.

Figure 5902: RAK11720 Module in the Context of the ChirpStack Platform

The ChirpStack, previously known as the LoRaServer project, provides open-source components for building LoRaWAN networks. In the case of TTN, the RAK11720 module is located in the periphery and will transmit the data to the backend servers through a LoRaWAN gateway. Learn more about ChirpStack.

NOTE

In this guide, it is assumed that you are using a RAK Gateway and its built-in ChirpStack. Also, the gateway with the ChirpStack must be configured successfully. The frequency band of the nodes should be consistent with the frequency band of the gateway and ChirpStack installation.

Create a New Application

1. Log in to the ChirpStack server using your account and password.
2. Go to the Applications section, as shown in Figure 78. By default, you should create a new application, although you can reuse existing ones. For this setup, create a new Application by clicking the CREATE button and filling in the required parameters, as shown Figure 80.

Figure 5903: Applications Section

Figure 5904: Creating a New Application

• For this setup, create an Application named rak_node_test.

ChirpStack LoraServer supports multiple system configurations, with only one by default.

• Service profile: Field is to select the system profile.
• Payload codec: It is the parsing method for selecting load data, such as parsing LPP format data.

Figure 5905: Filling in the Parameters of an Application

Register a New Device

1. Choose the application created in the previous step, then select the DEVICES tab, as shown in Figure 81 and Figure 82.

Figure 5906: List of Applications Created

Figure 5907: Device Tab of an Application

2. Once inside the DEVICE tab, create a new device (LoRaWAN node) by clicking the + CREATE button.

Figure 5908: Add a New Device

Figure 5909: ChirpStack Adding Node into the RAK11720 Module

3. Once the node is created, fill in the necessary data. You can generate a Device EUI automatically by clicking the following icon. Or, you can type the correct Device EUI in the edit box.

Fill in the parameters requested:

• Device name and Device description: These are descriptive texts about your device.
• Device EUI: This interface allows you to generate a Device EUI automatically by clicking the generate icon. You can also add a specific Device EUI directly in the form.
• Device Profile:
  • If you want to join in OTAA mode, select DeviceProfile_OTAA.
  • If you want to join in ABP mode, select DeviceProfile_ABP.

NOTE

Device profiles DeviceProfile_OTAA and DeviceProfile_ABP are only available if you are using the built-in ChirpStack LoRaWAN Server of RAK Gateways.
If you have your own ChirpStack installation, you can set up the device profile with LoRaWAN MAC version 1.0.3 and LoRaWAN Regional Parameters revision B to make it compatible with RAK11720.

Figure 5910: Generate a New Device EUI

ChirpStack OTAA Device Registration

1. If you have selected DeviceProfile_OTAA, as shown in Figure 86, after the device is created, an Application Key must be created for this device.

Figure 5911: ChirpStack OTAA Activation

2. A previously created Application Key can be entered here, or a new one can be generated automatically by clicking the icon highlighted in red in Figure 87.

Figure 5912: ChirpStack OTAA Set Application Keys

3. Once the Application Key is added to the form, the process can be finalized by clicking the SET DEVICE-KEYS button.

• As shown in Figure 88, a new device should be listed in the DEVICES tab. The most important parameters, such as the Device EUI, are shown in the summary.

Figure 5913: ChirpStack OTAA List of the Device in the Device Tab

4. To end the process, it is a good practice to review that the Application Key is properly associated with this device. The Application Key can be verified in the KEYS (OTAA) tab, as shown in Figure 89.

Figure 5914: Application Key Associated With the New Device

5. After registering the RAK11720 in ChirpStack as an OTAA device, you can now create a custom firmware using the Arduino IDE for the RAK11720 or use OTAA AT Commands with an external MCU host.

NOTE

Standard OTAA mode requires the Device EUI, Application Key, and Application EUI, but in ChirpStack’s implementation, only the Device EUI and the Application Key are mandatory. The Application EUI is not required and not recorded in the Application tab. Nevertheless, you can reuse the Device EUI as the Application EUI during the configuration on the side of the node.

ChirpStack ABP Device Registration

1. During the registration of a new device, if you select DeviceProfile_ABP, as shown in Figure 90, then the ChirpStack platform will assume that this device will join the LoRaWAN network using the ABP mode.

NOTE

Check Disable counting frame verification. During the test, when the module is restarted, the frame counting number will also be restarted to zero. This would cause a synchronization problem with the ChirpStack server, which would treat it as a replay attack. For testing purposes, it is safe to disable this feature but remember to activate it in a production environment. That note indicates that frame counters in RAK11720 will reset to zero when the device restarts.

Figure 5915: ChirpStack Console, Configuring a Device

2. After selecting the ABP mode, the following parameters appear in the ACTIVATION tab. Then, you can see that there are some parameters for ABP in the ACTIVATION item:

• Device Address
• Network Session Key
• Application Session Key

Figure 5916: ChirpStack ABP Activation Parameters Needed

3. The parameters can be generated as random numbers by the platform or can be set with user values. Once these parameters are filled in properly, the process is completed by clicking on the ACTIVATE DEVICE button.
4. After registering the RAK11720 in ChirpStack as an ABP device, you can now create a custom firmware using Arduino IDE for RAK11720 or use ABP AT Commands with external MCU host.

RAK11720 as a LoRa/LoRaWAN Modem via AT Command

The RAK11720 module can be configured using AT commands via the UART0 interface by default (UART1 can be used as well if configured correctly). You need a USB to UART TTL adapter to connect the RAK11720 to your computer's USB port and a serial terminal tool. It is highly recommended to use the WisToolBox, so you can easily send AT commands and view the replies from the console output. You can configure the RAK11720 in two ways:

• LoRaWAN End-Device
• LoRa P2P - Point-to-point communication between two RAK11720 modules.

UART Parameters for AT Commands:

• Baud Rate: 115200 baud (Default but configurable)
• Data Bits: 8 bits
• Stop Bits: 1 stop bit
• Parity: NONE

OTAA Configuration for TTN via WisToolBox Console

The RAK11720 module can be configured using WisToolBox to do the OTAA configuration. WisToolBox is a software tool that supports RAK11720 module. It automatically detects the RAK11720 module once connected to the PC. Below are the options in WisToolBox through which the OTAA configuration can be done.

Below are the steps for setting up your RAK11720 using WisToolBox Console.

1. To start the configuration, type ATE so you can echo the commands you input during your configuration. Then press Enter.

It is recommended to start by testing the console and verifying that the current configuration is working by sending these two AT commands:

AT

ATE

ATE is useful for tracking the commands and troubleshooting.

You will receive OK when you input the two commands. After setting ATE, you can now see all the commands you input together with the replies.

NOTE

If there is no OK or any reply, check if the device is powered correctly. If you are getting power from a USB port, ensure that you have a good USB cable.

Figure 5917: Setting up Your Console

Figure 5918: Setting up Your Console

Figure 5919: Setting up Your Console

2. Then configure the LoRaWAN join mode to OTAA. You can check what parameter you will input by typing AT+NJM? and then Enter into the console terminal. For OTAA, you should input AT+NJM=1 and then press Enter as shown in Figure 97.

Figure 5920: Setting up Your Console

Figure 5921: Setting up Your Console

Figure 5922: Setting up Your Console

3. Once done, set your LoRaWAN region to EU868. You can check what parameter you will input by typing AT+BAND? and then Enter into the console terminal. For EU868, you should input AT+BAND=4 then press Enter. If you wish to work on other regional bands, you may check the list of band parameter options below.

Set the frequency/region to EU868.

AT+BAND=4

NOTE

Depending on the Regional Band you selected, you might need to configure the sub-band of your RAK11720 to match the gateway and LoRaWAN network server. This is especially important for Regional Bands like US915, AU915, and CN470.

To configure the masking of channels for the sub-bands, you can use the AT+MASK command that can be found on the AT Command Manual.

To illustrate, you can use sub-band 2 by sending the command AT+MASK=0002.

List of band parameter options

Code	Regional Band
0	EU433
1	CN470
2	RU864
3	IN865
4	EU868
5	US915
6	AU915
7	KR920
8	AS923-1
9	AS923-2
10	AS923-3
11	AS923-4

Figure 5923: Setting up Your Console

Figure 5924: Setting up Your Console

Figure 5925: Setting up Your Console

4. Then next to this will be updating the OTAA credentials of your device. First to this will be the Application EUI (AppEUI). Go back to your console, where your RAK11720 end device was created, to copy the AppEUI credential. Paste it into the WisToolBox console, then press Enter.

Figure 5926: Your Created OTAA Device from Your TTN Console

Figure 5927: Setting up Your Console

Figure 5928: Setting up Your Console

Figure 5929: Setting up Your Console

Figure 5930: Copying the AppEUI Credential from TTN to WisToolBox

Figure 5931: Setting up Your Console

5. Once done, do the same procedure for the Application key (AppKey) and the Device EUI (DevEUI).

• For Application key (AppKey)

Figure 5932: Setting up Your Console

Figure 5933: Setting up Your Console

Figure 5934: Setting up Your Console

Figure 5935: Copying the AppKey credential from TTN to WisToolBox

Figure 5936: Setting up Your Console

• For Device EUI (DevEUI)

Figure 5937: Setting up Your Console

Figure 5938: Setting up Your Console

Figure 5939: Copying the DevEUI credential from TTN to WisToolBox

Figure 5940: Setting up Your Console

6. Now that you have a configured OTAA device using the WisToolBox console, you can join the network using the WisToolBox console.
7. To do this, go back to the WisToolBox console and type AT+JOIN. Edit it to AT+JOIN=1, then press Enter to join the network.

NOTE

AT+JOIN command parameters are optional. You can configure the settings for auto-join, reattempt interval, and the number of join attempts if your application needs them. If not configured, it will use the default parameter values.

AT+JOIN and AT+JOIN=1 also share the common functionality of trying to join the network.

Join command format: AT+JOIN=w:x:y:z

Parameter	Description
w	Join command - 1: joining, 0: stop joining.
x	Auto-join config - 1: auto-join on power-up, 0: no auto-join
y	Reattempt interval in seconds (7-255) - 8 is the default.
z	Number of join attempts (0-255) - 0 is the default.

After 5 or 6 seconds, if the request is successfully received by a LoRa gateway, you should see a +EVT:JOINED status reply.

NOTE

If the OTAA device failed to join, you need to check if your device is within reach of a working LoRaWAN gateway that is configured to connect to TTN. It is also important to check that all your OTAA parameters (DEVEUI, APPEUI, and APPKEY) are correct using the AT+DEVEUI=?, AT+APPEUI=?, and AT+APPKEY=? commands. Lastly, ensure that the antenna of your device is properly connected.

After checking all the things above, try to join again.

Figure 5941: Joining Mode Using WisToolBox Console

Figure 5942: Joining Mode Using WisToolBox Console

Figure 5943: Joining Mode Using WisToolBox Console

Figure 5944: Joining Mode Using WisToolBox Console

Figure 5945: OTAA Device Successfully Joined the Network

Figure 5946: OTAA Device Successfully Joined the Network

9. With the end-device properly joined to the TTN, you can now try to send some payload after a successful join. Send command format: AT+SEND=<port>:<payload>

AT+SEND=2:12345678

Figure 5947: OTAA Device Sending Payload to the Network

Figure 5948: OTAA Device Sending Payload to the Network

Figure 5949: OTAA Device Sending Payload to the Network

Figure 5950: OTAA Device Sending Payload to the Network

10. You can see the data sent by the RAK11720 module on the TTN device console Live data section. Also, the Last seen info should have been a few seconds or minutes ago.

Figure 5951: OTAA Test Sample Data Sent Viewed in TTN

ABP Configuration for TTN via WisToolBox Console

This section shows the ABP configuration guide using WisToolBox console. Below are the steps for setting up your RAK11720 using WisToolBox Console.

1. To start the configuration, type ATE so you can echo the commands you input during your configuration. Then press Enter.

It is recommended to start by testing the console and verifying that the current configuration is working by sending these two AT commands:

AT

ATE

ATE is useful for tracking the commands and troubleshooting.

You will receive OK when you input the two commands. After setting ATE, you can now see all the commands you input together with the replies.

NOTE

If there is no OK or any reply, check if the device is powered correctly. If you are getting power from a USB port, ensure that you have a good USB cable.

Figure 5952: Setting up Your Console

Figure 5953: Setting up Your Console

Figure 5954: Setting up Your Console

2. Then configure the LoRaWAN join mode to ABP. You can check what parameter you will input by typing AT+NJM? and then Enter into the console terminal. For ABP, you should input AT+NJM=0 and then press Enter, as shown in Figure 132.

Figure 5955: Setting up Your Console

Figure 5956: Setting up Your Console

Figure 5957: Setting up Your Console

3. Once done, set your LoRaWAN region to EU868. You can check what parameter you will input by typing AT+BAND? and then Enter into the console terminal. For EU868, you should input AT+BAND=4 then press Enter. If you wish to work on other regional bands, you may check the List of band parameter options below.

AT+BAND=4

NOTE

Depending on the Regional Band you selected, you might need to configure the sub-band of your RAK11720 to match the gateway and LoRaWAN network server. This is especially important for Regional Bands like US915, AU915, and CN470.

To configure the masking of channels for the sub-bands, you can use the AT+MASK command that can be found in the AT Command Manual.

To illustrate, you can use sub-band 2 by sending the command AT+MASK=0002.

List of band parameter options

Code	Regional Band
0	EU433
1	CN470
2	RU864
3	IN865
4	EU868
5	US915
6	AU915
7	KR920
8	AS923-1
9	AS923-2
10	AS923-3
11	AS923-4

Figure 5958: Setting up Your Console

Figure 5959: Setting up Your Console

Figure 5960: Setting up Your Console

4. Next, update the ABP credentials on your device, the Application session key (AppSKey). Go back to your console, where your RAK11720 End device was created to copy the AppSKey credential, paste it into the WisToolBox console, then press Enter.

Figure 5961: Your Created ABP Device From Your TTN Console

Figure 5962: Setting up Your Console

Figure 5963: Setting up Your Console

Figure 5964: Setting up Your Console

Figure 5965: Copying the AppSKey credential from TTN to WisToolBox

Figure 5966: Setting up Your Console

5. Once done, do the same procedure to Device address and Network session key (NwkSKey).

• For Device address

Figure 5967: Setting up Your Console

Figure 5968: Setting up Your Console

Figure 5969: Setting up Your Console

Figure 5970: Copying the Device Address Credential from TTN to WisToolBox

Figure 5971: Setting up Your Console

• For Network session key (NwkSKey)

Figure 5972: Setting up Your Console

Figure 5973: Setting up Your Console

Figure 5974: Setting up Your Console

Figure 5975: Copying the NwkSKey Credential from TTN to WisToolBox

Figure 5976: Setting up Your Console

6. Now, you have a configured ABP device using the WisToolBox console. ABP-configured devices are directly tied to the network once done with the above procedures, so a joining procedure is not needed.
7. You can try sending the payload to TTN. Open again the terminal console of WisToolBox to send some payload using it. Send command format: AT+SEND=<port>:<payload>

AT+SEND=2:12345678

Figure 5977: ABP Device Sending Payload to the Network

Figure 5978: ABP Device Sending Payload to the Network

Figure 5979: ABP Device Sending Payload to the Network

Figure 5980: ABP Device Sending Payload to the Network

8. You can see the data sent by the RAK11720 module on the TTN device console Live data section. Also, the Last seen info should have been a few seconds or minutes ago.

Figure 5981: ABP Test Sample Data Sent Viewed in TTN

LoRa P2P Mode

This section shows how to set up and connect two RAK11720 units to work in the LoRa P2P mode. The configuration of the RAK11720 units is done by connecting the two modules to a general-purpose computer using a USB-UART converter. The setup of each RAK11720 can be done separately, but testing the LoRa P2P mode will require having both units connected simultaneously. This could be done by having one computer with two USB ports or two computers with one USB port each.

It is recommended to start by testing the serial communication and verifying the current configuration is working by sending these two AT commands:

AT

ATE

ATE will echo the commands you input to the module, which is useful for tracking the commands and troubleshooting.

You will receive OK when you input the two commands. After setting ATE, you can now see all the commands you input together with the replies.

Try again AT and you should see it on the terminal followed by OK.

Figure 5982: AT Command Response

1. To set up the RAK11720 to work in LoRa P2P mode, you need to input the work mode command on both RAK11720 modules. You might need to disconnect and reconnect the module as it changes its mode of operation if you are sending commands via USB.

AT+NWM=0

2. For this P2P setup, the LoRa parameters are the following:

• Link frequency: 868000000 Hz
• Spreading factor: 7
• Bandwidth: 125 kHz
• Coding Rate: 0 = 4/5
• Preamble Length: 10
• Power: 14 dBm

AT+P2P=868000000:7:125:0:10:14

Figure 5983: P2P Setup

NOTE

Refer to the P2P Mode section of the AT command documentation to learn more about the definition of the parameters used.

3. To set one module as a receiver (RX), set the value of the P2P to receive a command to 65535.

AT+PRECV=65535

With one module configured as RX, the other device will be the TX. You can now try to send a P2P payload.

AT+PSEND=11223344

NOTE

• If the AT+PRECV value is set to 65534, the device will continuously listen to P2P LoRa TX packets without any timeout. This is the same as setting the device in RX mode.
• If the AT+PRECV value is set to 65535, the device will listen to P2P TX without a timeout. But it will stop listening once a P2P LoRa packet is received to save power.
• If the AT+PRECV value is 0, the device will stop listening to P2P TX data. The device is in TX mode.

Figure 5984: P2P Sending and Receiving LoRa Packets

AT Command over BLE

This section shows how to use AT commands over BLE using a Serial Bluetooth Terminal app.

NOTE

To enable AT command via BLE, upload first a custom firmware with initialization of the BLE UART. This can be done by adding BLE UART initialization code in the void setup() function - api.ble.uart.start(0);. You can also run the example code BLE_Uart example as a direct alternative.

All available commands can be found in the AT Command Manual section of this document.

1. Download and install the Serial Bluetooth Terminal to connect the device.
2. Make sure the Bluetooth on your mobile is turned on.
3. Select Category, then Devices.

Figure 5985: Available Serial Bluetooth Terminal

4. Select the Bluetooth LE icon and click the SCAN icon to scan the device.
5. Look for a BLE device named RAK.XXXXXX in the scanner list of the app and connect to this device.

Figure 5986: Scanning Devices

6. Make sure the connection is successful with RAK.XXXXXX.

Figure 5987: Connect with the Device

7. Send an AT command and check whether the remote console is received or not.

at+ver=?

Figure 5988: RAK11720 AT Command Testing

Miscellaneous

There are different ways to update the firmware of the RAK11720 (as well as to recover from a crash).

1. Using Arduino IDE
2. Using Jlink
3. Recovery via UART

Firmware Update via Arduino IDE

Whenever you upload a custom firmware, it will be updated or downgraded depending on the version of the RUI3 BSP version installed in the Arduino IDE.

Firmware Update using Jlink

You can upload the latest RAK11720 HEX firmware using Jlink. The RAK11720 must be powered up, and you have to connect the SWD lines of the RAK11720 (SWDIO, SWCLK, VDD, and GND) to the Jlink connector.

1. Download and install the Jlink software pack, which includes the J-Flash software you need.
2. Open the J-Flash software and click Start J-Flash. You should be able to see in this step that the MCU is already detected in Log section of J-Flash. Then, you can select Create new project to get started. You can also save this newly created project so that it will be easier for you to do firmware uploads in the future.

Figure 5989: Starting J-Flash

3. The next step is to select the specific Apollo3 Blue chip inside the RAK11720 module.

Figure 5990: Selecting the Apollo3 MCU

Figure 5991: Selecting the Apollo3 MCU

Figure 5992: Selecting the Apollo3 MCU

4. Opening the latest firmware you need to upload.

Figure 5993: Starting J-Flash

5. Upon selecting the HEX file, you should see the binary/hex outline in the J-Flash. Then you can proceed with uploading by clicking Production Programming.

Figure 5994: Starting J-Flash

Figure 5995: Starting J-Flash

Figure 5996: Starting J-Flash

Firmware Recovery

The RAK11720 has a recovery mode procedure in the event that a custom firmware upload will result in the halting of the device. If the device does not respond to any commands, it is recommended that you do the recovery to make the device usable again.

1. You have to connect the SWO/BOOT pin to VDD and then pull the reset pin to GND momentarily. This will restart the module and also skip the application code and proceed to recovery mode. Do not pull the reset pin to GND permanently, or else the module will be halted in the reset state.

Figure 5997: BOOT Pin Configuration for BOOT MODE

2. Then on the Arduino IDE, you must select the APOLLO3 Board and connect to the right COM port.

Figure 5998: Apollo3 Board and COM Port

3. To proceed with the recovery procedure, select Ambiq SBL. Before proceeding with the process of recovery, you need to prepare to reset the module after the prompt that will show as you click Burn Bootloader. You need to be fully attentive because this should be quick.

Figure 5999: Burning Bootloader

Figure 6000: Indicator When to Reset the Module

4. When the initiation of uploading starts, you can now release the reset pin connection to GND and wait until the process is finished.

Figure 6001: Successful Recovery

5. The final step is to reset the module again and upload any custom firmware. The RAK11720 will be in the RUI3 Boot Mode state after the recovery, so the RUI3 firmware must be uploaded via Arduino IDE to activate the device again.