RAK3172 WisDuo Module for LoRaWAN®as a Stand-Alone LoRaWAN End Device
This guide demonstrates how to program RAK3172 as a stand-alone LoRaWAN end-device using RUI3 Arduino APIs. To utilize RAK3172 as a LoRaWAN end-device, it must be in proximity to a functioning LoRaWAN gateway registered to a LoRaWAN network server (LNS) or a built-in server available on gateways such as WisGate Edge.
Before proceeding, make sure you have completed the hardware setup and RUI3 development environment preparation described in the RAK3172 Quick Start Guide.
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
RAKwireless LoRaWAN gateway models like WisGate Edge have built-in network servers. It is also common that the LoRaWAN network server is external or in the cloud. The popular LoRaWAN network server in the cloud that you can use for free (but offers enterprise service, too) is TTN.
To run this example correctly, make sure a LoRaWAN gateway is connected to your network server, and create an OTAA application on the network server.
Register the LoRaWAN Gateway on TTN
Choose the appropriate guide below to register and connect your gateway to The Things Stack (TTN):
- How to Register a RAK Gateway in TTN V3
- How to Connect RAK Gateways to TTN v3 via UDP
- How to Connect RAK Gateways to TTN v3 Using Basics™ Station (LNS)
- How to Auto-Connect RAK Gateway to TTN (EU1) in Packet Forwarder Mode
- How to Connect RAK Gateways to TTN v3 Using Basics™ Station (CUPS)
Register the RAK3172 on TTN
Step 1: Create a TTN Application
-
Log in to The Things Stack using the account and cluster where your gateway is registered.
-
Once logged in, click **Create application **to create a new application.
Figure 1: The Things Stack Platform- To register an application, enter the required details and necessary information about your application, then click Create application.
Figure 1: Details of the TTN application- If you have no error 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.
Step 2: Register an End Device
Each LoRaWAN end device must be registered and activated using either Over-The-Air Activation (OTAA) or Activation By Personalization (ABP). Follow the steps below to register the module on TTN. Some configuration steps and credentials may differ depending on the selected activation method.
- Go to your application console to register a device. To start adding an OTAA end-device, click + Register end device.
Figure 1: Register end device- To register the board, select Enter end device specifics manually.
Figure 1: Enter end device specifics manually- Set up the appropriate Frequency plan, compatible LoRaWAN version, and Regional Parameters version supported by your device. For OTAA activation, set the JoinEUI to all zeros. This step is not required for ABP activation.
Figure 1: Setting up for your device
Figure 1: Setting the Frequency plan
Figure 1: Setting the LoRaWAN version
Figure 1: Setting the JoinEUI- Click Show advanced activation, LoRaWAN class and cluster settings. Select the activation method supported by your device and set Additional LoRaWAN class capabilities to Class A only.
- OTAA: Select Over the air activation (OTAA). In the JoinEUI field, enter all zeroes to allow the DevEUI to be configured, then click Confirm.
- ABP: Select Activation by personalization (ABP).
Figure 1: Setting up for your device
Figure 1: Configuring OTAA activation settings
Figure 1: Configuring ABP activation settings- Enter the DevEUI credentials of your device into the DevEUI portion. This will automatically generate the specific End device ID of your board. Then generate the credentials required by the selected activation method:
- OTAA: Generate the AppKey, then click Register end device.
- ABP: Generate the Device address, AppSKey, and NwkSKey.
- The DevEUI is unique to each RAK device. Depending on the activation mode, the following credentials are hidden in this section and must be generated for your specific device and application:
- ABP: Device address, AppSKey, and NwkSKey.
- OTAA: AppEUI and AppKey.
- For OTAA, the AppEUI is the same as the JoinEUI.
Figure 1: Generating OTAA credentials
Figure 1: Generating ABP credentials- Finally, click Register end device.
Figure 1: Register end device- You should now be able to see the device on the TTN console after you fully register your device
Figure 1: OTAA device successfully registered to TTN
Figure 1: ABP device registered on TTNUpload the LoRaWAN Example to RAK3172
After a successful registration of the RAK3172 module on the LNS, you can now proceed with running the LoRaWAN OTAA demo application example.
- Launch Arduino IDE and configure WisDuo RAK3172 Evaluation Board on board selection.
Figure 1: Selecting RAK3172 Module- Connect the RAK3172 via UART and check RAK3172 COM Port.
Figure 1: Select COM port- Open the example code under RAK WisBlock RUI examples: File -> Examples -> RAK WisBlock RUI examples -> Example -> LoRaWan_OTAA.
Figure 1: OTAA LoRaWAN application example- In the example code, you need to modify the device EUI OTAA_DEVEUI, the application EUI OTAA_APPEUI, and the application key OTAA_APPKEY.
- The OTAA_DEVEUI parameter should match the device EUI registered in your network server. Note that your RAK3172 module has a sticker with a QR code printed on it. You can use the QR code information to configure the OTAA_DEVEUI parameter. The OTAA_DEVEUI format is MSB first.
// OTAA Device EUI MSB
#define OTAA_DEVEUI {0x70, 0xB3, 0xD5, 0x7E, 0xD0, 0x04, 0xF1, 0xC0}
- The OTAA_APPEUI parameter. This parameter should also be the same as the APPEUI in the network server you configured.
// OTAA Application EUI MSB
#define OTAA_APPEUI {0x70, 0xB3, 0xD5, 0x7E, 0xD0,0x03, 0xAB, 0xA2}
- Another important parameter to change is the application key, OTAA_APPKEY. This parameter should also be the same as the APPKEY in the network server you configured. The OTAA_APPKEY format is MSB first.
// OTAA Application Key MSB
#define OTAA_APPKEY {0xB4, 0x85, 0x7E, 0xFE, 0x1C, 0xB5, 0x15, 0xEB, 0x44, 0x61, 0x0D, 0x9B, 0x20, 0x6A, 0xF3, 0x3A}
Figure 1: Configuring DEVEUI, APPEUI and APPKEY- Depending on the regional band you selected, you might need to configure the sub-band of your RAK module to match the gateway and LoRaWAN network server. This is especially important for regional bands like US915, AU915, and CN470.
This guide uses the US915 regional band, so you need to update the band in the code as well. In addition, you also need to set up the channel mask (channels 8 to 15 are the most commonly used channels in the US915 band).
if (!api.lorawan.band.set(OTAA_BAND)) {
Serial.printf("LoRaWan OTAA - set band is incorrect! \r\n");
return;
}
uint16_t maskBuff = 0x0002;
if (!api.lorawan.mask.set(&maskBuff)) {
Serial.printf("LoRaWan OTAA - set mask is incorrect! \r\n");
return;
}
RAK3172 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 = 8
- RAK_REGION_AS923-2 = 9
- RAK_REGION_AS923-3 = 10
- RAK_REGION_AS923-4 = 11
Figure 1: Updating to US915 and setting up channel mask- Open the Tools Menu and select a COM port. COM28 is currently used.
Figure 1: Select COM port- The last step is to upload the code by clicking the Upload icon on Arduino IDE. Note that you should select the correct board and COM port.
Figure 1: Uploading the code- You should now be able to see the console logs using the Arduino IDE's serial monitor. Sometimes the COM port will disconnect, so you may not see the terminal output immediately. You can reconnect the module or try pressing the reset button to see the terminal output.
Figure 1: Arduino serial monitor logs- Check on the LoRaWAN network TTN console logs to see if your device has been successfully joined with the
join-requestandjoin-acceptmessages.
Figure 1: TTN console logThe modified LoRaWAN_OTAA project is available below.
Click to view the code
#define OTAA_PERIOD (20000)
/*************************************
LoRaWAN band setting:
RAK_REGION_EU433
RAK_REGION_CN470
RAK_REGION_RU864
RAK_REGION_IN865
RAK_REGION_EU868
RAK_REGION_US915
RAK_REGION_AU915
RAK_REGION_KR920
RAK_REGION_AS923
*************************************/
#define OTAA_BAND (RAK_REGION_US915)
#define OTAA_DEVEUI {0x70, 0xB3, 0xD5, 0x7E, 0xD0, 0x04, 0xF1, 0xC0}
#define OTAA_APPEUI {0x70, 0xB3, 0xD5, 0x7E, 0xD0,0x03, 0xAB, 0xA2}
#define OTAA_APPKEY {0xB4, 0x85, 0x7E, 0xFE, 0x1C, 0xB5, 0x15, 0xEB, 0x44, 0x61, 0x0D, 0x9B, 0x20, 0x6A, 0xF3, 0x3A}
/** Packet buffer for sending */
uint8_t collected_data[64] = { 0 };
void recvCallback(SERVICE_LORA_RECEIVE_T * data)
{
if (data->BufferSize > 0) {
Serial.println("Something received!");
for (int i = 0; i < data->BufferSize; i++) {
Serial.printf("%x", data->Buffer[i]);
}
Serial.print("\r\n");
}
}
void joinCallback(int32_t status)
{
Serial.printf("Join status: %d\r\n", status);
}
void sendCallback(int32_t status)
{
if (status == 0) {
Serial.println("Successfully sent");
} else {
Serial.println("Sending failed");
}
}
void setup()
{
Serial.begin(115200, RAK_AT_MODE);
Serial.println("RAKwireless LoRaWan OTAA Example");
Serial.println("------------------------------------------------------");
// OTAA Device EUI MSB first
uint8_t node_device_eui[8] = OTAA_DEVEUI;
// OTAA Application EUI MSB first
uint8_t node_app_eui[8] = OTAA_APPEUI;
// OTAA Application Key MSB first
uint8_t node_app_key[16] = OTAA_APPKEY;
if (!api.lorawan.appeui.set(node_app_eui, 8)) {
Serial.printf("LoRaWan OTAA - set application EUI is incorrect! \r\n");
return;
}
if (!api.lorawan.appkey.set(node_app_key, 16)) {
Serial.printf("LoRaWan OTAA - set application key is incorrect! \r\n");
return;
}
if (!api.lorawan.deui.set(node_device_eui, 8)) {
Serial.printf("LoRaWan OTAA - set device EUI is incorrect! \r\n");
return;
}
if (!api.lorawan.band.set(OTAA_BAND)) {
Serial.printf("LoRaWan OTAA - set band is incorrect! \r\n");
return;
}
uint16_t maskBuff = 0x0002;
if (!api.lorawan.mask.set(&maskBuff)) {
Serial.printf("LoRaWan OTAA - set mask is incorrect! \r\n");
return;
}
if (!api.lorawan.deviceClass.set(RAK_LORA_CLASS_A)) {
Serial.printf("LoRaWan OTAA - set device class is incorrect! \r\n");
return;
}
if (!api.lorawan.njm.set(RAK_LORA_OTAA)) // Set the network join mode to OTAA
{
Serial.printf
("LoRaWan OTAA - set network join mode is incorrect! \r\n");
return;
}
if (!api.lorawan.join()) // Join to Gateway
{
Serial.printf("LoRaWan OTAA - join fail! \r\n");
return;
}
/** Wait for Join success */
while (api.lorawan.njs.get() == 0) {
Serial.print("Wait for LoRaWAN join...");
api.lorawan.join();
delay(10000);
}
if (!api.lorawan.adr.set(true)) {
Serial.printf
("LoRaWan OTAA - set adaptive data rate is incorrect! \r\n");
return;
}
if (!api.lorawan.rety.set(1)) {
Serial.printf("LoRaWan OTAA - set retry times is incorrect! \r\n");
return;
}
if (!api.lorawan.cfm.set(1)) {
Serial.printf("LoRaWan OTAA - set confirm mode is incorrect! \r\n");
return;
}
/** Check LoRaWan Status*/
Serial.printf("Duty cycle is %s\r\n", api.lorawan.dcs.get()? "ON" : "OFF"); // Check Duty Cycle status
Serial.printf("Packet is %s\r\n", api.lorawan.cfm.get()? "CONFIRMED" : "UNCONFIRMED"); // Check Confirm status
uint8_t assigned_dev_addr[4] = { 0 };
api.lorawan.daddr.get(assigned_dev_addr, 4);
Serial.printf("Device Address is %02X%02X%02X%02X\r\n", assigned_dev_addr[0], assigned_dev_addr[1], assigned_dev_addr[2], assigned_dev_addr[3]); // Check Device Address
Serial.printf("Uplink period is %ums\r\n", OTAA_PERIOD);
Serial.println("");
api.lorawan.registerRecvCallback(recvCallback);
api.lorawan.registerJoinCallback(joinCallback);
api.lorawan.registerSendCallback(sendCallback);
}
void uplink_routine()
{
/** Payload of Uplink */
uint8_t data_len = 0;
collected_data[data_len++] = (uint8_t) 't';
collected_data[data_len++] = (uint8_t) 'e';
collected_data[data_len++] = (uint8_t) 's';
collected_data[data_len++] = (uint8_t) 't';
Serial.println("Data Packet:");
for (int i = 0; i < data_len; i++) {
Serial.printf("0x%02X ", collected_data[i]);
}
Serial.println("");
/** Send the data package */
if (api.lorawan.send(data_len, (uint8_t *) & collected_data, 2, true, 1)) {
Serial.println("Sending is requested");
} else {
Serial.println("Sending failed");
}
}
void loop()
{
static uint64_t last = 0;
static uint64_t elapsed;
if ((elapsed = millis() - last) > OTAA_PERIOD) {
uplink_routine();
last = millis();
}
//Serial.printf("Try sleep %ums..", OTAA_PERIOD);
api.system.sleep.all(OTAA_PERIOD);
//Serial.println("Wakeup..");
}
