Skip to main content

RAK10701-L Field Tester for LoRaWAN Quick Start Guide

The Field Tester is an inexpensive tool used to map the coverage of LoRaWAN gateways to ensure that LoRaWAN nodes can connect and send data.

It does this by sending out uplink packets then a backend server is checking which gateways receive this payload. Using the Field Tester location data and the gateways' locations, the backend then calculates an average distance and submits the min and max RSSI plus SNR values of the receiving gateways. This data is then shown on the Field Testers touch screen display.

The backend server can be a dedicated server, but it can be implemented as well using platforms like Datacake.

Prerequisites

What Do You Need?

Before going through each and every step in the installation guide of the RAK10701-L Field Tester for LoRaWAN, make sure to prepare the necessary items listed below:

Hardware Tools

  1. RAK10701-L Field Tester for LoRaWAN
  2. LoRa SubGhz Antenna with RP-SMA connector
  3. USB Type-C Cable
  4. Windows/Linux/macOS for PC or iOS/Android for mobile

Software Tools

WisToolBox for configuration and firmware update.

NOTE

It is mandatory that you are within the coverage of the LoRaWAN Gateway of the network you are trying to join. Without the coverage, the Field Tester will not be useable.

Product Configuration

RAK10701-L Field Tester Physical Interface

The user interface of the RAK10701-L Field Tester for LoRaWAN is via TFT Touchscreen LCD and one push button at the side. There is also an external LoRA antenna port via RP-SMA connector and USB-C port for charging and configuration if connected to a PC.

Zoomable
Figure 1: Parts of RAK10701-L
NOTE

You have to ensure that the LoRa antenna is attached before turning on the device.

  1. To turn on the device, you have to press and hold the button for at least five seconds.
Zoomable
Figure 1: RAK10701-L button to turn on
NOTE

The same button can be used to power off. You have to hold it as well for at least five seconds.

Zoomable
Figure 1: RAK10701-L power off
  1. When the device initializes, it will show the RAK logo on the screen. If there is any initialization error, it will be shown on the upper right section of the screen as well. A properly working device should not have any errors shown.
Zoomable
Figure 1: RAK10701-L power up successful
Zoomable
Figure 1: GPS error on boot up sequence
  1. After the successful boot up, the main home screen will be shown. Take note, that there will be no data at the first start of the device.
NOTE

The field tester must be outside and has a clear view of the sky to get GPS coordinates. The GPS antenna is located on top of the device beside the RP-SMA connector of the LoRa Antenna.

If you are indoors, there will be no reception of the GPS signal. The latitude and longitude data will be empty.

Zoomable
Figure 1: RAK10701-L Main Page waiting for valid data
  1. Once fully powered on, the external button at the side can sleep or wake up the display on the LCD screen via a single press on it.

  2. If the device is connected via USB-C to a computer, then the button is pressed, it will not remove the display but will lock the screen (touch screen behavior is disabled).

Zoomable
Figure 1: RAK10701-L locked screen

LoRaWAN Network Servers Guide for RAK10701-L Field Tester

The field tester supports different network servers and can be used as well on others not listed in this guide as long as the uplink and downlink packets are configured correctly.

You can check each guide on how to use the RAK10701-L Field Tester for LoRaWAN in the following network servers.

Additional information:

NOTE

This section will focus on the configuration of each network server. The procedure of Device Configuration of RAK10701-L via WisToolBox is the same for all network server and will be covered in a separate section of the guide.

RAK10701-L Field Tester Guide for the Helium Network

RAK10701-L can be manually registered to Helium Console. This is a public LoRaWAN network server that you can use for your LoRaWAN end-devices powered by community-driven Helium Hotspots. This guide will show every detail of how to prepare the Helium Console for your RAK10701-L field tester.

NOTE

This guide is based on disk19 guide for the Field Tester configuration for the Helium Console.

  1. You need to register an account and then purchase data credits (DC) to use the network. If you are a new user, there are free data credits (DC) included in your new account to get you started quickly.
Zoomable
Figure 1: Helium Console
Zoomable
Figure 1: Console Home Page
  1. Once you are logged in, you can start adding your device. You have two ways to add a device as shown in the image.
Zoomable
Figure 1: Adding Device
  1. The newly added device parameters will be shown. You have to put a device name and click save.
NOTE

The DEVEUI, APPEUI, and APPKEY are important in this step. These values must be configured on your RAK10701-L device using WisToolBox which will be covered later in this guide.

Zoomable
Figure 1: Configuring Device Name
  1. The device will be added to the blockchain and it will show pending beside its name.
Zoomable
Figure 1: Pending Device Status
  1. While waiting for the device to be added to the blockchain, you can create a Label. This will allow you to group your device to have a common setting. This will be needed to attach the needed integrations to the backend server of dev.disk91.com. You have to click the folder with the + icon and add a Label name then click Save Label. The newly created label should now be shown in the Devices console.
Zoomable
Figure 1: Add Label icon
Zoomable
Figure 1: Add Label Name
Zoomable
Figure 1: Label created successfully
  1. Once the Label is created you have to associate it on the RAK10701 device. You can attach the Label on the device by clicking the Add Label button.
Zoomable
Figure 1: Attach the label to the device
  1. A pop-up will be shown and you have to select the correct Label created for RAK10701 then click Add Label.
Zoomable
Figure 1: Drop-down on label selection
  1. After successful attachment of Label on the devices, it should show one (1) device is under that Label. The device is properly labeled which is needed for the next steps - Integrations and Flow.
Zoomable
Figure 1: Label added on the RAK10701 device
  1. To connect the backend server, you have to create an Integration.
Zoomable
Figure 1: Add integration
Zoomable
Figure 1: HTTP integration
  1. Then you must proceed to steps 2 and 3 sections of the Integration settings. You have to select POST then on the Endpoint URL, you must put https://dev.disk91.com/fieldtester/helium/v3. It is also needed to put the integration name before the clicking Add Integration button.
Zoomable
Figure 1: Details of HTTP Integration
  1. After preparing the device and the integration, you can now proceed with creating the flow to connect them. You have to click Flows and then the + icon on NODES.
Zoomable
Figure 1: Setting up the Flows
  1. You must select Labels and Integrations and then drag the correct blocks on the flows canvas.
Zoomable
Figure 1: Drag the rak10701-devices label
Zoomable
Figure 1: Drag the RAK1070x_Integration
  1. You then have to connect the Label block to the Integration block via the tiny connector indicated by the red arrows by using your mouse cursor and dragging the line connector.
NOTE

There is no need to save the changes created on the flows canvas since it is automatically saved as you do changes.

Zoomable
Figure 1: Connecting Labels to Integrations
  1. The final step in the setting up of the Helium Console for RAK10701 is the setting up of packets. You have to click on Packets and then the Add New Packet Config icon.
Zoomable
Figure 1: Creating Packets
  1. You must also input a name on the Packet Config Name, select Multiple Packets and drag the slider, so it will show All Available Packets. Once done, you can now click on + Create Packet Config.
Zoomable
Figure 1: Multiple packets configuration
Zoomable
Figure 1: Successful packets creation
  1. You must associate the multiple packet setup with the rak10701-devices label. To do this, you have to go back on Flows, double-click on the rak10701-devices label, choose the Packets tab under rak10701-devices settings then enable ALL Packets. After this, you can now proceed with the configuration of RAK10701 using WisToolBox.
Zoomable
Figure 1: Attaching multiple packets to the rak10701-devices label
  1. You can now proceed on device configuration so that the proper EUIs and KEY will match the one in the Helium network.

RAK10701-L Field Tester Guide for The Things Network

This section shows how to use the RAK10701-L Field Tester for LoRaWAN to The Things Stack.

  1. Log in to TTNv3. To do so, head to the TTNv3 site and select your cluster. If you already have a TTN account, you can use your The Things ID credentials to log in.
Zoomable
Figure 1: The Things Stack home page
Zoomable
Figure 1: Console page after a successful login
NOTE
  • To connect RAK10701-L Field Tester to TTNv3, you should already have connected a gateway in range to TTNv3. Or, you have to be sure that you are in the range of a public gateway.
  1. Now that you are logged in to the platform, the next step is to create an application. In your console, click Create an application.
Zoomable
Figure 1: Create an application
  1. To have an application registered, you need to input first the specific details and necessary information about your application then click Create application.
Zoomable
Figure 1: Creating an Application
  1. If you had no error during the previous step, you should now be on the application console page. The next step is to Add end device to your TTN application.
Zoomable
Figure 1: Add end-devices to your TTN application
  1. To register the RAK10701-L Field Tester, you need to click Manually first.
Zoomable
Figure 1: Adding end devices manually
  1. Choose the following configurations in adding the end devices. You must choose the correct Frequency Plan and the LoRaWAN version must be 1.0.3.
Zoomable
Figure 1: Configurations for adding end devices
  1. Click Show advanced activation, LoRaWAN class, and cluster settings, then select Over the air action (OTAA).
Zoomable
Figure 1: OTAA settings
  1. Then input the LoRaWAN OTAA parameters. For AppEUI, you may click Fill with Zeros. For AppKey and DevEUI, you can click Generate. Then the parameters will be automatically filled by the TTS platform. Finally, click Register end device.
Zoomable
Figure 1: Registering the end device
  1. You should now be able to see the device on the TTN console after you fully registered your device. Take note of these OTAA parameters, such as the AppEUI, DevEUI, and the AppKey, as they are needed in the configuration of the RAK10701-L Field Tester hardware later on in this guide.
Zoomable
Figure 1: OTAA device successfully registered to TTN
  1. After adding the device to the LoRaWAN application, link it to the backend server. The first step is to create an API key.
Zoomable
Figure 1: Creating API key
Zoomable
Figure 1: Creating API key
  1. Configure the API key parameters. You can put any names that will easily track your API. You have to set the expiration date as well. Then you must check Write downlink application traffic. After the configuration, you can now click Create API key.
Zoomable
Figure 1: API key parameters
  1. This step is critical. You need to copy the API key because this will be used on Webhook integration.
Zoomable
Figure 1: Copy API key
  1. With the API key created, you can proceed with creating the Webhook integration.
Zoomable
Figure 1: Webhook Integration
  1. Select Custom Webhook.
Zoomable
Figure 1: Custom Webhook
  1. Configure the necessary parameters on the Webhook. You can select any name for the webhook. You then need to set the base URL going to disk19 server https://dev.disk91.com/fieldtester/ttn/v3, add the API key from the previous step and lastly put a check on the Uplink message under Enabled event types.
Zoomable
Figure 1: Webhook parameters
  1. After setting all the configurations, you can now add the webhook.
Zoomable
Figure 1: Add Webhook
  1. You should see now the newly created webhook.
Zoomable
Figure 1: Add Webhook
  1. After adding the application, device, and webhook integration to the console, you have to configure the parameters in your device to match the parameters on the TTN console. You can use WisToolBox via USB connection or wirelessly via BLE. You can now proceed on the RAK10701-L Configuration using WisToolBox. You also have the option to update device parameters directly via RUI3 AT Commands (if you prefer AT commands instead of WisToolBox).

  2. Once you configured the RAK10701-L with the correct Frequency Band and EUIs/Key by following the guide on the RAK10701-L Configuration using WisToolBox, you should see the join request/accept, uplinks and downlinks to The Things Stack console. These uplinks contains the coordinates of the field tester and the downlinks contains the data calculated by the disk91 server. The uplink uses fport 1 and the downlink uses fport 2. To view the actual coordinates on the console, you need to add a payload decoder on your uplink data.

Zoomable
Figure 1: Adding Uplink Payload Decoder

Uplink payload decoder script.

Click to view the code
function Decoder(bytes, port) {
var decoded = {};
// avoid sending Downlink ACK to integration (Cargo)
if (port === 1) {
var lonSign = (bytes[0] >> 7) & 0x01 ? -1 : 1;
var latSign = (bytes[0] >> 6) & 0x01 ? -1 : 1;

var encLat = ((bytes[0] & 0x3f) << 17) +
(bytes[1] << 9) +
(bytes[2] << 1) +
(bytes[3] >> 7);

var encLon = ((bytes[3] & 0x7f) << 16) +
(bytes[4] << 8) +
bytes[5];

var hdop = bytes[8] / 10;
var sats = bytes[9];

const maxHdop = 2;
const minSats = 5;

if ((hdop < maxHdop) && (sats >= minSats)) {
// Send only acceptable quality of position to mappers
decoded.latitude = latSign * (encLat * 108 + 53) / 10000000;
decoded.longitude = lonSign * (encLon * 215 + 107) / 10000000;
decoded.altitude = ((bytes[6] << 8) + bytes[7]) - 1000;
decoded.accuracy = (hdop * 5 + 5) / 10
decoded.hdop = hdop;
decoded.sats = sats;
} else {
decoded.error = "Need more GPS precision (hdop must be <" + maxHdop +
" & sats must be >= " + minSats + ") current hdop: " + hdop + " & sats:" + sats;
}
return decoded;
}
return null;
}
  1. With the correct payload decoder, you should now see GPS coordinates data which you can also use to other integration.
Zoomable
Figure 1: Decoded payload and TTS console

RAK10701-L Field Tester Guide for Chirpstack

How Does It Work?

There are two steps under the hood of the Field Tester. In step one, the Field Tester is sending out data packets over LoRaWAN. These packets are received by one or multiple gateways. These packets are forwarded from the LoRaWAN network server to another backend server. When the packets are forwarded, they include information about signal strength and the number of gateways that have received the packet.

Zoomable
Figure 1: Step 1 - Field Tester Sending Uplink Payload

In the second step, the backend server is calculating the minimum and maximum distance between the Field Tester Pro and the gateways that received the data. Together with the minimum and maximum RSSI levels, this information is then sent back to the Field Tester Pro as a LoRaWAN downlink.

Zoomable
Figure 1: Step 2 - Backend Server Sending Useful Information as Downlink

To use Chirpstack for RAK10701-L, you must have a working installation of the Chirpstack LoRaWAN network server. It can be on a dedicated machine, Raspberry Pi, or in a cloud VPS instance. It should have a fixed IP address and port to where Datacake.co will connect to.

  1. To start with Chirpstack, you must create a device profile for your RAK10701-L Field Tester device. You must select LoRaWAN MAC version 1.0.3 which is the LoRaWAN specification version that the RAK10701 Field Tester supports.
Zoomable
Figure 1: Creating Device Profile in Chirpstack
  1. You must enable Device supports OTAA as the network join method as well.
Zoomable
Figure 1: Enable support for OTAA
  1. You can also include a custom javascript decoder under the CODEC tab. This will allow you to see the specific information transmitted by the device.
Zoomable
Figure 1: Custom Javascript Decoder for RAK10701 Field Mapper

Here's the complete decoder script:

Click to view the code
function Decode(fPort, bytes, variables) {
var decoded = {};
// avoid sending Downlink ACK to integration (Cargo)
if ((fPort === 1) || (fPort === 2)){
var lonSign = (bytes[0] >> 7) & 0x01 ? -1 : 1;
var latSign = (bytes[0] >> 6) & 0x01 ? -1 : 1;

var encLat = ((bytes[0] & 0x3f) << 17) +
(bytes[1] << 9) +
(bytes[2] << 1) +
(bytes[3] >> 7);

var encLon = ((bytes[3] & 0x7f) << 16) +
(bytes[4] << 8) +
bytes[5];

var hdop = bytes[8] / 10;
var sats = bytes[9];

var maxHdop = 2;
var minSats = 5;

if ((hdop < maxHdop) && (sats >= minSats)) {
// Send only acceptable quality of position to mappers
decoded.latitude = latSign * (encLat * 108 + 53) / 10000000;
decoded.longitude = lonSign * (encLon * 215 + 107) / 10000000;
decoded.altitude = ((bytes[6] << 8) + bytes[7]) - 1000;
decoded.accuracy = (hdop * 5 + 5) / 10
decoded.hdop = hdop;
decoded.sats = sats;
} else {
decoded.error = "Need more GPS precision (hdop must be <" + maxHdop +
" & sats must be >= " + minSats + ") current hdop: " + hdop + " & sats:" + sats;
decoded.latitude = latSign * (encLat * 108 + 53) / 10000000;
decoded.longitude = lonSign * (encLon * 215 + 107) / 10000000;
decoded.altitude = ((bytes[6] << 8) + bytes[7]) - 1000;
decoded.accuracy = (hdop * 5 + 5) / 10
decoded.hdop = hdop;
decoded.sats = sats;
}
return decoded;
}
return null;

NOTE

This decoder script can be found on RAKwireless Standardize Payload repository which also includes a custom decoder script for TTN and Helium.

  1. After creating the device profile, you can now create an application and add the RAK10701 device. And then attached the Device-profile you created. Note the DEVEUI and APPKEY in this section. These parameters must match the ones in our RAK10701 Field Tester.
Zoomable
Figure 1: Create application in Chirpstack
Zoomable
Figure 1: Create device in Chirpstack.
Zoomable
Figure 1: Device APPKEY
  1. You also need to ensure that you have a Gateway registered in Chirpstack and with the correct Network Server profile.
Zoomable
Figure 1: Gateways registered in Chripstack
  1. The next step after setting up the network server, devices, and gateway, is the integration of the Chirpstack application to Datacake. You must choose HTTP, then click Edit. Then you have to use this endpoint going to datacake https://api.datacake.co/integrations/lorawan/chirpstack/.
Zoomable
Figure 1: Creating integration
Zoomable
Figure 1: Creating endpoint for Datacake.co
  1. The last step on the Chirpstack side, is the creation of the API key. This is needed to allow Datacake in sending downlink packets to the RAK10701 Field Tester. Make sure the key is copied and saved somewhere, it is only retrievable during the key creation. Copy the Token and save it in a text editor.
Zoomable
Figure 1: Creation of API Key
Zoomable
Figure 1: Creation of API Key
  1. You can now proceed on Datacake and add a LoRaWAN device that will be linked to your RAK10701 created in ChirpStack. You have to create an account if you do not have one yet.
Zoomable
Figure 1: Device list dashboard
Zoomable
Figure 1: Selecting LoRaWAN
Zoomable
Figure 1: Add new product
Zoomable
Figure 1: Selecting chirpstack
Zoomable
Figure 1: Adding device name
  1. Next step is to enable the downlink. This is the step where you'll be needing the previously created API key in step 7 of this guide. Take note that the ChirpStack URL should be based on your deployed Chirpstack network server. After doing all configurations, click update and save.
Zoomable
Figure 1: Configuration settings
Zoomable
Figure 1: Chirpstack downlink configuration
Zoomable
Figure 1: Chirpstack URL and API key
  1. Just below the LoRaWAN section in datacake.co, you'll see the Payload Decoder. This is a very critical step to ensure that all important data will be covered.
Click to view the code
function distance(lat1, lon1, lat2, lon2) {
if ((lat1 == lat2) && (lon1 == lon2)) {
return 0;
}
else {
var radlat1 = Math.PI * lat1 / 180;
var radlat2 = Math.PI * lat2 / 180;
var theta = lon1 - lon2;
var radtheta = Math.PI * theta / 180;
var dist = Math.sin(radlat1) * Math.sin(radlat2) + Math.cos(radlat1) * Math.cos(radlat2) * Math.cos(radtheta);
if (dist > 1) {
dist = 1;
}
dist = Math.acos(dist);
dist = dist * 180 / Math.PI;
dist = dist * 60 * 1.1515;
dist = dist * 1.609344;
return dist;
}
}

function Decoder(bytes, fPort) {
var decoded = {};
// avoid sending Downlink ACK to integration (Cargo)
if (fPort === 1) {
var lonSign = (bytes[0] >> 7) & 0x01 ? -1 : 1;
var latSign = (bytes[0] >> 6) & 0x01 ? -1 : 1;

var encLat = ((bytes[0] & 0x3f) << 17) +
(bytes[1] << 9) +
(bytes[2] << 1) +
(bytes[3] >> 7);

var encLon = ((bytes[3] & 0x7f) << 16) +
(bytes[4] << 8) +
bytes[5];

var hdop = bytes[8] / 10;
var sats = bytes[9];

var maxHdop = 2;
var minSats = 5;

if ((hdop < maxHdop) && (sats >= minSats)) {
// Send only acceptable quality of position to mappers
decoded.latitude = latSign * (encLat * 108 + 53) / 10000000;
decoded.longitude = lonSign * (encLon * 215 + 107) / 10000000;
decoded.altitude = ((bytes[6] << 8) + bytes[7]) - 1000;
decoded.accuracy = (hdop * 5 + 5) / 10
decoded.hdop = hdop;
decoded.sats = sats;
decoded.location = "(" + decoded.latitude + "," + decoded.longitude + ")";
} else {
decoded.error = "Need more GPS precision (hdop must be <" + maxHdop +
" & sats must be >= " + minSats + ") current hdop: " + hdop + " & sats:" + sats;
decoded.latitude = latSign * (encLat * 108 + 53) / 10000000;
decoded.longitude = lonSign * (encLon * 215 + 107) / 10000000;
decoded.altitude = ((bytes[6] << 8) + bytes[7]) - 1000;
decoded.accuracy = (hdop * 5 + 5) / 10
decoded.hdop = hdop;
decoded.sats = sats;
decoded.location = "(" + decoded.latitude + "," + decoded.longitude + ")";
}
// decoded.raw = rawPayload.uplink_message.rx_metadata[0].location;
decoded.num_gw = normalizedPayload.gateways.length;
decoded.minRSSI = 0;
decoded.maxRSSI = 0;
decoded.minSNR = 0;
decoded.maxSNR = 0;
decoded.minDistance = 0;
decoded.maxDistance = 0;

var server_type = 0;
// Check if payload comes from TTN
if (typeof (rawPayload.uplink_message) != "undefined") {
console.log("Found TTN format");
server_type = 1;
}
// Check if payload comes from Helium
else if (typeof (rawPayload.hotspots) != "undefined") {
console.log("Found Helium format");
server_type = 2;
}
// Check if payload comes from Chirpstack
else if (typeof (rawPayload.rxInfo) != "undefined") {
console.log("Found Chirpstack format");
server_type = 3;
decoded.is_chirpstack = 1;
}
else {
console.log("Unknown raw format");
}

var gw_lat = {};
var gw_long = {};

decoded.num_gw = 0;
for (idx_tst = 0; idx_tst < 10; idx_tst++)
{
if (typeof (normalizedPayload.gateways[idx_tst]) != "undefined")
{
console.log("Found gateway with IDX " + idx_tst);
decoded.num_gw += 1;
}
}

for (idx = 0; idx < decoded.num_gw; idx++) {
var new_rssi = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[idx] && normalizedPayload.gateways[idx].rssi) || 0;
var new_snr = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[idx] && normalizedPayload.gateways[idx].snr) || 0;
if ((new_rssi < decoded.minRSSI) || (decoded.minRSSI == 0)) {
decoded.minRSSI = new_rssi;
}
if ((new_rssi > decoded.maxRSSI) || (decoded.maxRSSI == 0)) {
decoded.maxRSSI = new_rssi;
}
if ((new_snr < decoded.minSNR) || (decoded.minSNR == 0)) {
decoded.minSNR = new_snr;
}
if ((new_snr > decoded.maxSNR) || (decoded.maxSNR == 0)) {
decoded.maxSNR = new_snr;
}

// var gw_lat = 0.0;
// var gw_long = 0.0;
switch (server_type) {
//TTN
case 1:
gw_lat[idx] = rawPayload.uplink_message.rx_metadata[idx].location.latitude;
gw_long[idx] = rawPayload.uplink_message.rx_metadata[idx].location.longitude;
break;
// Helium
case 2:
gw_lat[idx] = rawPayload.hotspots[idx].lat;
gw_long[idx] = rawPayload.hotspots[idx].long;
break;
// Chirpstack
case 3:
gw_lat[idx] = rawPayload.rxInfo[idx].location.latitude;
gw_long[idx] = rawPayload.rxInfo[idx].location.longitude;
break;
default:
console.log("Unknown LNS");
break;
}

console.log("IDX " + idx + " lat " + gw_lat[idx] + " long " + gw_long[idx]);
// decoded.gw_lat[idx] = gw_lat;
// decoded.gw_long[idx] = gw_long;

// Calculate distance
var new_distance = distance(gw_lat[idx], gw_long[idx], decoded.latitude, decoded.longitude);
if ((new_distance < decoded.minDistance) || (decoded.minDistance == 0)) {
decoded.minDistance = new_distance * 1000;
}
if ((new_distance > decoded.maxDistance) || (decoded.maxDistance == 0)) {
decoded.maxDistance = new_distance * 1000;
}
}

switch (decoded.num_gw) {
case 20:
decoded.hotspot_10 = "(" + gw_lat[19] + "," + gw_long[19] + ")";
case 19:
decoded.hotspot_09 = "(" + gw_lat[18] + "," + gw_long[18] + ")";
case 18:
decoded.hotspot_08 = "(" + gw_lat[17] + "," + gw_long[17] + ")";
case 17:
decoded.hotspot_07 = "(" + gw_lat[16] + "," + gw_long[16] + ")";
case 16:
decoded.hotspot_06 = "(" + gw_lat[15] + "," + gw_long[15] + ")";
case 15:
decoded.hotspot_05 = "(" + gw_lat[14] + "," + gw_long[14] + ")";
case 14:
decoded.hotspot_04 = "(" + gw_lat[13] + "," + gw_long[13] + ")";
case 13:
decoded.hotspot_03 = "(" + gw_lat[12] + "," + gw_long[12] + ")";
case 12:
decoded.hotspot_02 = "(" + gw_lat[11] + "," + gw_long[11] + ")";
case 11:
decoded.hotspot_01 = "(" + gw_lat[10] + "," + gw_long[10] + ")";
case 10:
decoded.hotspot_10 = "(" + gw_lat[9] + "," + gw_long[9] + ")";
case 9:
decoded.hotspot_09 = "(" + gw_lat[8] + "," + gw_long[8] + ")";
case 8:
decoded.hotspot_08 = "(" + gw_lat[7] + "," + gw_long[7] + ")";
case 7:
decoded.hotspot_07 = "(" + gw_lat[6] + "," + gw_long[6] + ")";
case 6:
decoded.hotspot_06 = "(" + gw_lat[5] + "," + gw_long[5] + ")";
case 5:
decoded.hotspot_05 = "(" + gw_lat[4] + "," + gw_long[4] + ")";
case 4:
decoded.hotspot_04 = "(" + gw_lat[3] + "," + gw_long[3] + ")";
case 3:
decoded.hotspot_03 = "(" + gw_lat[2] + "," + gw_long[2] + ")";
case 2:
decoded.hotspot_02 = "(" + gw_lat[1] + "," + gw_long[1] + ")";
case 1:
decoded.hotspot_01 = "(" + gw_lat[0] + "," + gw_long[0] + ")";
default:
break;
}

decoded.maxMod = parseInt((decoded.maxDistance / 250), 10);
decoded.minMod = parseInt((decoded.minDistance / 250), 10);
decoded.maxDistance = parseInt((decoded.maxMod * 250), 10);
decoded.minDistance = parseInt((decoded.minMod * 250), 10);
if (decoded.maxDistance <= 1) {
decoded.maxDistance = parseInt(250, 10);
}
if (decoded.minDistance <= 1) {
decoded.minDistance = parseInt(250, 10);
}
return decoded;
}
return null;

}

This decoder is not only decoding data from the LoRaWAN packet but is as well reading gateway information from the additional data that the LoRaWAN server added to the data it forwarded to Datacake.

Each LoRaWAN server uses a different format for this additional information, so there is a code section that tries to detect whether the data came from a Chirpstack LSN, from TTN, or from a Helium Console:

Click to view the code
var server_type = 0;
// Check if payload comes from TTN
if (typeof (rawPayload.uplink_message) != "undefined") {
console.log("Found TTN format");
server_type = 1;
}
// Check if payload comes from Helium
else if (typeof (rawPayload.hotspots) != "undefined") {
console.log("Found Helium format");
server_type = 2;
}
// Check if payload comes from Chirpstack
else if (typeof (rawPayload.rxInfo) != "undefined") {
console.log("Found Chirpstack format");
server_type = 3;
decoded.is_chirpstack = 1;
}
else {
console.log("Unknown raw format");
}

Once the data is extracted, it calculates the distance between the RAK10701 Field Tester location and the different gateways that received the LoRaWAN packet. This version of the decoder can handle up to 10 gateways, but it can be extended.

Click to view the code
function distance(lat1, lon1, lat2, lon2) {
if ((lat1 == lat2) && (lon1 == lon2)) {
return 0;
}
else {
var radlat1 = Math.PI * lat1 / 180;
var radlat2 = Math.PI * lat2 / 180;
var theta = lon1 - lon2;
var radtheta = Math.PI * theta / 180;
var dist = Math.sin(radlat1) * Math.sin(radlat2) + Math.cos(radlat1) * Math.cos(radlat2) * Math.cos(radtheta);
if (dist > 1) {
dist = 1;
}
dist = Math.acos(dist);
dist = dist * 180 / Math.PI;
dist = dist * 60 * 1.1515;
dist = dist * 1.609344;
return dist;
}
}

In the next step, it analyzes the different distances and RSSI levels to find the closest and farthest gateway and the lowest and highest RSSI and SNR levels.

The result of the decoding is then put into different data fields that are used by Chirpstack for the visualization and by the rule, we will define to create the downlink to the RAK10701 Field Tester.

  1. The next step is to create the different data fields that are filled by the data decoder. This is done in the Fields section of the device configuration, just below the data encoder section.
Zoomable
Figure 1: Creation of data field

The following fields are required:

Field NameIdentifier (returned value from the decoder)Field Type
Field TesterLOCATIONLocation
MinDistanceMINDISTANCEInteger
MaxDistanceMAXDISTANCEInteger
MinRSSIMINRSSIFloat
MaxRSSIMAXRSSIFloat
MinSNRMINSNRFloat
MaxSNRMAXSNRFloat
minModMINMODInteger
maxModMAXMADInteger
hotspot_01HOTSPOT_01Location
hotspot_02HOTSPOT_01Location
hotspot_0…HOTSPOT_...Location
hotspot_09HOTSPOT_09Location
hotspot_10HOTSPOT_10Location
is_chirpstackIS_CHIRPSTACKBoolean

There are more variables created by the decoder, but this is the minimum set required for the dashboard and to configure the download.

  1. This is the most critical step so that the RAK10701 will be able to display the necessary details helpful in Field Testing the LoRaWAN network. This section is responsible for the "backend-server functions". In this step, we create the automatic downlink to the device that is executed every time a data packet from the RAK10701 Field Tester arrives. Take note that port number 2 is used by RAK10701 for downlinks and Trigger on measurements should be checked.
Zoomable
Figure 1: Chirpstack downlink configuration
Zoomable
Figure 1: Chirpstack downlink configuration

In this guide, the downlink is only created when the Field Tester is connected through a Chirpstack server. When TTN or Helium is used, the downlink would be created by the original backend server.

This is controlled by the “Fields used” where you can see the IS_CHIRPSTACK.

The Payload Encoder is preparing a downlink packet that will be sent back to the RAK10701 Field Tester. The downlink packet is only 6 bytes large to avoid problems in LoRaWAN regions with limited downlink packet sizes.

This is the complete decoder script. The first byte is usually a counter, but it works well if the counter is ignored and always set to 1.

Click to view the code
function Encoder(measurements, port) {
var buf = [];
buf[0] = 1;
buf[1] = measurements.MINRSSI.value + 200;
buf[2] = measurements.MAXRSSI.value + 200;
// var temp = parseInt(measurements.MINMOD.value,10);
if (measurements.MINMOD.value == 0) {
measurements.MINMOD.value = 1;
}
console.log(measurements.MINMOD.value);
buf[3] = measurements.MINMOD.value;
if (measurements.MAXMOD.value == 0) {
measurements.MAXMOD.value = 1;
}
buf[4] = measurements.MAXMOD.value;
buf[5] = measurements.NUM_GW.value;
return buf;
}
  1. You can now proceed on device configuration so that the proper EUIs and KEY will match the one in the network server.

RAK10701-L Field Tester Pro Guide for LORIOT and Datacake

In this document, you will find a step-by-step guide for performing a field mapping test using LORIOT network management system and Datacake's platform to visualize your results. This solution will help you in your network planning ventures and ensure your decisions are data-driven and adequate to your surroundings.

Prerequisites
Setting LORIOT as the LNS
  1. Forward a gateway to LORIOT, which will be the LNS (LoRa Network Server) for this use case. For registration of the gateway to LORIOT, you will need the gateway’s MAC and EUI, which can be found on the Overview page of WisGateOS 2.
Zoomable
Figure 1: WisGate Edges web UI
  1. Go to your LORIOT profile. From the menu on the left, navigate through Networks > [your_network] > +Add Gateway.
Zoomable
Figure 1: LORIOT console
NOTE

The LORIOT platform provides you with a Sample Network at the point of your profile creation. You can use it for free. If you wish to create a new one, or delete the provided one, you will need a paid plan to continue.

  1. For the base platform select Basics Station Semtech. You will be asked to provide eth0 MAC address and EUI, which you obtained in step 1. After filling in these values, press the Register Basics Station Semtech gateway at the bottom of the page.
Zoomable
Figure 1: Registering The Gateway To LORIOT
  1. The last thing you need to do to connect your gateway with LORIOT LNS is to provide the Basics Station configuration to the gateway. This can be done by going to the gateway's web UI > LoRa > Configuration and doing a Basics station server setup.
Zoomable
Figure 1: Gateway Configuration Page

You can find the Trust (CA Certificate), the Server URL, and the Server port in LORIOT by navigating to the newly registered Gateway > Certificate. Use the configuration provided by LORIOT as it may differ from the guide depending on your region.

Zoomable
Figure 1: Certificate
  1. If the steps are followed correctly, the gateway should show a Connected status.
Adding the Device and LORIOT to Datacake Integration
  1. Add the device to LORIOT. In the LORIOT platform, navigate to Applications > [your_application] and use the Enroll Device utility from the menu on the left. Fill out your Device EUI, Join (APP) EUI, and Application Key.
Zoomable
Figure 1: Adding The Device To The LORIOT Platform
NOTE

The LORIOT platform provides you with a Sample Application at the point of your profile creation. You can use it for free. If you wish to create a new one or delete the provided one, you will need a paid plan to continue.

  1. Use the Output utility to set up the Datacake integration. For now, just give it a name. The Authorization requires additional settings that will not be covered by this guide. For more information regarding this process, refer to Datacake's guide.
Zoomable
Figure 1: Add Output
  1. Now, you need to add the device in Datacake. To register a new device, navigate to the Devices tab in your Datacake account. Click the +Add Device button.
Zoomable
Figure 1: Datacake Platform
  1. Choose New Product under Datacake Product. Enter the device name in the Product name input box, and proceed by clicking Next.
Zoomable
Figure 1: Add Lorawan Device 1
  1. Select LORIOT as the Network Server and click Next.
Zoomable
Figure 1: Add Lorawan Device 2
  1. On the next page, you will have to enter the name and DEVEUI of the device. Select the plan for Datacake according to your needs and finish the device-adding procedure.

  2. Now, navigate to Configuration in the newly created device at Datacake and scroll down to the Network Server configuration. Click Change.

Zoomable
Figure 1: Device Network Server Configuration
  1. You will need the LORIOT Access Token, which is generated from the LORIOT console. Navigate to LORIOT > Access Tokens and copy the token to put it in Datacake.
Zoomable
Figure 1: LORIOT Access Token
Zoomable
Figure 1: Access Token Field In Datacake

You can generate a new access token or use the existing one.

  1. If everything is done correctly, you should see a trickle of RAW data in the Debug window of Datacake.
Setting Up the Uplink Payload Decoder and the Downlink Encoder
  1. In the Datacake console, navigate to the Configuration tab of your RAK10701 device. At the bottom of the page, you will find the Payload Decoder field. Copy the decoder code provided below and paste it in the payload decoder field. This decoder will calculate the values displayed on the screen of the Field Tester.
Click to view the code
function distance(lat1, lon1, lat2, lon2) {
if ((lat1 == lat2) && (lon1 == lon2)) {
return 0;
}
else {
var radlat1 = Math.PI * lat1 / 180;
var radlat2 = Math.PI * lat2 / 180;
var theta = lon1 - lon2;
var radtheta = Math.PI * theta / 180;
var dist = Math.sin(radlat1) * Math.sin(radlat2) + Math.cos(radlat1) * Math.cos(radlat2) * Math.cos(radtheta);
if (dist > 1) {
dist = 1;
}
dist = Math.acos(dist);
dist = dist * 180 / Math.PI;
dist = dist * 60 * 1.1515;
dist = dist * 1.609344;
return dist;
}
}

function Decoder(bytes, fPort) {
var decoded = {};
// avoid sending Downlink ACK to integration (Cargo)
if (fPort === 1) {
var lonSign = (bytes[0] >> 7) & 0x01 ? -1 : 1;
var latSign = (bytes[0] >> 6) & 0x01 ? -1 : 1;

var encLat = ((bytes[0] & 0x3f) << 17) +
(bytes[1] << 9) +
(bytes[2] << 1) +
(bytes[3] >> 7);

var encLon = ((bytes[3] & 0x7f) << 16) +
(bytes[4] << 8) +
bytes[5];

var hdop = bytes[8] / 10;
var sats = bytes[9];

var maxHdop = 2;
var minSats = 5;

if ((hdop < maxHdop) && (sats >= minSats)) {
// Send only acceptable quality of position to mappers
decoded.latitude = latSign * (encLat * 108 + 53) / 10000000;
decoded.longitude = lonSign * (encLon * 215 + 107) / 10000000;
decoded.altitude = ((bytes[6] << 8) + bytes[7]) - 1000;
decoded.accuracy = (hdop * 5 + 5) / 10
decoded.hdop = hdop;
decoded.sats = sats;
decoded.location = "(" + decoded.latitude + "," + decoded.longitude + ")";
} else {
decoded.error = "Need more GPS precision (hdop must be <" + maxHdop +
" & sats must be >= " + minSats + ") current hdop: " + hdop + " & sats:" + sats;
decoded.latitude = latSign * (encLat * 108 + 53) / 10000000;
decoded.longitude = lonSign * (encLon * 215 + 107) / 10000000;
decoded.altitude = ((bytes[6] << 8) + bytes[7]) - 1000;
decoded.accuracy = (hdop * 5 + 5) / 10
decoded.hdop = hdop;
decoded.sats = sats;
decoded.location = "(" + decoded.latitude + "," + decoded.longitude + ")";
}
// decoded.raw = rawPayload.uplink_message.rx_metadata[0].location;
decoded.num_gw = normalizedPayload.gateways.length;
decoded.minRSSI = 0;
decoded.maxRSSI = 0;
decoded.minSNR = 0;
decoded.maxSNR = 0;
decoded.minDistance = 0;
decoded.maxDistance = 0;
var server_type = 0;
// Check if payload comes from TTN
if (typeof (rawPayload.uplink_message) != "undefined") {
console.log("Found TTN format");
server_type = 1;
decoded.is_chirpstack = 1;
}
// Check if payload comes from Helium
else if (typeof (rawPayload.hotspots) != "undefined") {
console.log("Found Helium format");
server_type = 2;
}
// Check if payload comes from Chirpstack
else if (typeof (rawPayload.rxInfo) != "undefined") {
console.log("Found Chirpstack format");
server_type = 3;
decoded.is_chirpstack = 1;
}
// Check if payload comes from LORIOT
else if (typeof (rawPayload.cmd) != "undefined") {
console.log("Found LORIOT format");
server_type = 4;
decoded.is_chirpstack = 1;
}
else {
console.log("Unknown raw format");
}

var gw_lat = {};
var gw_long = {};

decoded.num_gw = 0;
for (idx_tst = 0; idx_tst < 10; idx_tst++)
{
if (typeof (normalizedPayload.gateways[idx_tst]) != "undefined")
{
console.log("Found gateway with IDX " + idx_tst);
decoded.num_gw += 1;
}
}

for (idx = 0; idx < decoded.num_gw; idx++) {
var new_rssi = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[idx] && normalizedPayload.gateways[idx].rssi) || 0;
var new_snr = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[idx] && normalizedPayload.gateways[idx].snr) || 0;
if ((new_rssi < decoded.minRSSI) || (decoded.minRSSI == 0)) {
decoded.minRSSI = new_rssi;
}
if ((new_rssi > decoded.maxRSSI) || (decoded.maxRSSI == 0)) {
decoded.maxRSSI = new_rssi;
}
if ((new_snr < decoded.minSNR) || (decoded.minSNR == 0)) {
decoded.minSNR = new_snr;
}
if ((new_snr > decoded.maxSNR) || (decoded.maxSNR == 0)) {
decoded.maxSNR = new_snr;
}
switch (server_type) {
//TTN
case 1:
gw_lat[idx] = rawPayload.uplink_message.rx_metadata[idx].location.latitude;
gw_long[idx] = rawPayload.uplink_message.rx_metadata[idx].location.longitude;
break;
// Helium
case 2:
gw_lat[idx] = rawPayload.hotspots[idx].lat;
gw_long[idx] = rawPayload.hotspots[idx].long;
break;
// Chirpstack
case 3:
gw_lat[idx] = rawPayload.rxInfo[idx].location.latitude;
gw_long[idx] = rawPayload.rxInfo[idx].location.longitude;
break;
//LORIOT
case 4:
gw_lat[idx] = rawPayload.gws[0].lat;
gw_long[idx] = rawPayload.gws[0].lon;
break;
default:
console.log("Unknown LNS");
break;
}

console.log("IDX " + idx + " lat " + gw_lat[idx] + " long " + gw_long[idx]);

// Calculate distance
var new_distance = distance(gw_lat[idx], gw_long[idx], decoded.latitude, decoded.longitude);
if ((new_distance * 1000 < decoded.minDistance) || (decoded.minDistance == 0)) {
decoded.minDistance = new_distance * 1000;
}
if ((new_distance * 1000 > decoded.maxDistance) || (decoded.maxDistance == 0)) {
decoded.maxDistance = new_distance * 1000;
}
}

var hotspot_name = ""
for (idx = 0; idx < decoded.num_gw; idx++) {
var index = idx + 1;
if (index < 9) {
hotspot_name = "hotspot_0" + index.toString();
} else {
hotspot_name = "hotspot_" + index.toString();
}
console.log(hotspot_name);
decoded[hotspot_name] = "(" + gw_lat[idx] + "," + gw_long[idx] + ")";
}

decoded.maxMod = 1 + parseInt((Math.round(decoded.maxDistance / 250.0)), 10);
decoded.minMod = 1 + parseInt((Math.round(decoded.minDistance / 250.0)), 10);

return decoded;
}
return null;

}
Zoomable
Figure 1: Datacake Payload Decoder Field
  1. After saving the payload decoder it is time to set the downlink payload encoder. Navigate to Downlinks and copy-paste the provided encoder in the field. Set the port to 2 and use the IS_CHIRPSTACK field to trigger the downlink.
Click to view the code
function Encoder(measurements, port) {
var buf = [];
buf[0] = 1;
buf[1] = measurements.MINRSSI.value + 200;
buf[2] = measurements.MAXRSSI.value + 200;
// var temp = parseInt(measurements.MINMOD.value,10);
if (measurements.MINMOD.value == 0) {
measurements.MINMOD.value = 1;
}
console.log(measurements.MINMOD.value);
buf[3] = measurements.MINMOD.value;
if (measurements.MAXMOD.value == 0) {
measurements.MAXMOD.value = 1;
}
buf[4] = measurements.MAXMOD.value;
buf[5] = measurements.NUM_GW.value;
return buf;
}
Zoomable
Figure 1: Downlink Configuration
  1. You should now be able to see the data from the downlink on your Field Tester's screen.

RAK10701-L Field Tester Guide for Chirpstack and NodeRED

How Does It Work?

The Field Tester performs two steps:

  • In the first step, it sends data packets over LoRaWAN, which are then received by one or multiple gateways. These packets are forwarded by the LoRaWAN network server to a backend server, including information about signal strength and the number of gateways that received the packet.
Zoomable
Figure 1: Step 1 - Field Tester Sending Uplink Payload
  • In the second step, the backend server calculates the minimum and maximum distances from the Field Tester to the gateways, along with the minimum and maximum RSSI levels, and sends information back to the Field Tester as a LoRaWAN downlink.
Zoomable
Figure 1: Step 2 - Backend Server Sending Useful Information as Downlink

To use Chirpstack and NodeRED for RAK10701-L, you need a working Chirpstack LoRaWAN network server. This can be on a dedicated machine, a Raspberry Pi, or a cloud VPS. You also need NodeRED installed and connected to the Chirpstack MQTT broker.

  1. To start with Chirpstack, you must create a device profile for your RAK10701-L Field Tester Pro device. You must select LoRaWAN MAC version 1.0.3 which is the LoRaWAN specification version that the RAK10701 Field Tester supports.
Zoomable
Figure 1: Creating Device Profile in Chirpstack
  1. You must enable Device supports OTAA as the network join method as well.
Zoomable
Figure 1: Enable support for OTAA
  1. Once done with the device profile, you can now create an application and add the RAK10701 device. And then attached the Device-profile you created.
Zoomable
Figure 1: Create application in Chirpstack
NOTE

Take note of the DEVEUI and APPKEY in this section. These parameters must match the ones in our RAK10701 Field Tester.

Zoomable
Figure 1: Create device in Chirpstack.
Zoomable
Figure 1: Device APPKEY
  1. Make sure your Gateway is registered in Chirpstack with the correct Network Server profile.
Zoomable
Figure 1: Gateways registered in Chripstack
  1. After setting up the network server, devices, and gateway, install the NodeRED. This is required to run the backend server, which is in this case a NodeRED flow.
NOTE

Check the NodeRED documentation about installation options.

  • Once the NodeRED is installed, start it and select a flow to add the required nodes.
  1. Install the Field Tester Service node

a. Before starting to set up the flow, the Field Tester Service node needs to be added to the NodeRED palette.
Use the top-right icon in NodeRED and select Manage Palette from the new menu:

Zoomable
Figure 1: Manage Palette

b. In the new window, select the Install tab and type rakwireless/field-tester-server in the search box. The node will show up in the search result. Install the node by clicking the Install button.

Zoomable
Figure 1: Install Palette

c. Once the node is installed, we can start to setup the NodeRED flow.

  1. Setup the input Node

a. For Chirpstack V4 we need first an input node that can receive information from Chirpstacks MQTT broker. Pull the mqtt in node from the left side bar to your flow:

Zoomable
Figure 1: Prepare input node

b. Then set up the MQTT connection, double click the mqtt in node to open the setup window. Then click on the Server Edit icon.

Zoomable
Figure 1: Setup input node

c. In the setup window, add your server connection in the Connection tab:

Zoomable
Figure 1: Add MQTT Broker

d. Server can be an URL or an IP address where your Chirpstack MQTT broker can be reached. This and the port number depends on your Chirpstack installation and MQTT settings.

e. Next go to the Security tab and enter the required username and password. Again, this depends on your MQTT settings:

Zoomable
Figure 1: Add credentials

f. To receive the data from the MQTT broker, we need to set up the topic we want to listen to. The first step is to get the ID of the application in Chirpstack:

Zoomable
Figure 1: Get Chirpstack application ID

g. Copy the application ID, to use it in the MQTT input node to set up the topic.

h. Open the MQTT input settings in the NodeRED flow by double clicking on the icon in the flow.
Then edit the topic field. The syntax is:
application = fixed
application ID = from the Chirpstack LNS application
# = get all messages

In this example the topic is:

application/57184973-d64d-4656-be1d-84d4427bcb1a/#

i. Select as Output the option a parsed JSON object.

Zoomable
Figure 1: Setup MQTT topic
  1. Set up the output node

a. We need an output node as well to be able to send downlinks to the Chirpstack MQTT Broker.

b. Pull the mqtt out node from the left side bar to your flow:

Zoomable
Figure 1: Prepare output node

c. The only setup required is to select the same server that is used in the mqtt in node.

  1. Setup the Field Tester Backend Node

a. Now we can add and setup the Field Tester Server node.

b. Pull the field tester service node from the left side bar to your flow:

Zoomable
Figure 1: Add Field Tester Service node

c. Double click on the new node to setup the parser:

Zoomable
Figure 1: Set up the parser

For this example, the required parser is Chirpstack v3 and v4.

NOTE

The Field Tester Service node can be used with other LoRaWAN servers as well. Depending on the server and the options to receive uplinks and create downlinks, additional nodes might be required to convert this data into Raw data before sending it to the Field Tester Service.
However, guides on how to use it with other LNS are not available at this time.

  1. Connect the nodes
  • The last step is to connect the nodes:
Zoomable
Figure 1: Connect the node
NOTE
  • For debugging, it will be helpful to add a debug output node to the flow. This helps to check whether the output of the parser is correct:

Zoomable
Figure 1: Device
  • Select complete msg object as output.
    The result of parser can then be checked on the right side in the debug window:
Zoomable
Figure 1: Device

That's all, a simple implementation of a backend server for the RAK10701 Field Tester with NodeRED.

On the other hand, the uplink packets from the Field Tester can be sent in parallel to Datacake for a visualization of the locations, but in this case, there is no need to set up the downlink procedure in Datacake.

NOTE

All credits for the Field Tester Service node go to Xose from RAKwireless.

Configuration of RAK10701-L Using WisToolBox

The Field Mapper should have the correct credentials to connect to the Helium Console. This can be done using WisToolBox and also with the help of the touchscreen LCD user interface.

  1. Connect the RAK10701-L to the PC via USB Type-C cable and open the WisToolBox application. You can find more info on how to install and use the WisToolbox from its documentation.

  2. Click the CONNECT DEVICE button to launch WisToolBox Dashboard.

Zoomable
Figure 1: WisToolBox Desktop splash screen
  1. Review the Connection settings parameters on the dashboard, then click on the CONNECT button.
Zoomable
Figure 1: WisToolBox Desktop connection settings
  1. On the WisToolBox Dashboard screen, select the RAK4630 module. This is the module inside the RAK10701-L Field Tester device.
Zoomable
Figure 1: Detected module by WisToolBox
  1. You can now update the APPEUI, DEVEUI, and APPKEY. It must be the same as the parameters you have in the Setting up of Network Server. Then you can click APPLY COMMANDS.
Zoomable
Figure 1: Changing device parameters
NOTE

These are the only parameters that you need to change via WisToolBox. Other configurations like frequency plan, the interval of uplinks, TX power, and data rate can be done on the touchscreen of RAK10701.

For the frequency plan change, the device must be restarted to activate this newly configured frequency band. There will be a notification on the UI touchscreen LCD. If you use WisToolBox to configure the band, you have to restart the device manually, and there will be no notification from the UI of the LCD.

  1. You will see the summary of commands that were applied successfully. If the update is unsuccessful, just resend the needed changes. After the successful update, click the CLOSE button to return to Dashboard.
Zoomable
Figure 1: Successful update of parameters
  1. You can now remove the USB Type-C cable and proceed to the screen of RAK10701. You can click the settings icon and then update the frequency plan, the interval of uplinks, TX power, and data rate as needed. You can use the arrows for navigation and click OK to save changes.
Zoomable
Figure 1: RAK10701-L settings button
Zoomable
Figure 1: Configurable parameters

Miscellaneous

This part of the guide shows the Field Tester interface and how to update the firmware.

Field Tester Display Interface

This section discusses the interfaces on the device's LCD and its pages.

Display Status and Indicator

The RAK10701-L WisNode Field Tester has status indicators that show the current state of the device.

Zoomable
Figure 1: Device status and indicator
Zoomable
Figure 1: Different device status

Status:

  • IDLE: RAK10701-L Field Tester state is in between the previous uplink and the next uplink. The duration of an IDLE depends on the interval configured on the device.
  • JOINING: RAK10701-L Field Tester is trying to join the network. This status is triggered when a Join request is sent.
  • JOINED: RAK10701-L Field Tester successfully received the Join accept the packet. This status will be displayed until refreshed when new data is sent.
  • FAILED: RAK10701-L Field Tester failed to join the network. Triggered by receive timeout. There might be no available gateway reachable by the Field Tester.
  • SENDING: RAK10701-L Field Tester's data such as GPS is being uploaded via an uplink. It will be displayed until the reception is completed or timed out.
Settings

The field tester has configurable parameters: Band, TX power, TX interval, backlight intensity, and DR. You can navigate the settings using the arrow widgets plus the back and ok buttons. The OTAA parameters APPEUI, DEVEUI, and APPKEY are also displayed but can't be changed on the touchscreen. WisToolBox or another Serial Port terminal tool is needed to send the AT commands to update the EUIs and key.

Zoomable
Figure 1: Settings button
Zoomable
Figure 1: Settings page
Data Plots

There are four different data plots on the field tester: number of gateways, RSSI, SNR, and approximate distance. These graphs are accessible by touching the respective icons assigned to the parameter.

Zoomable
Figure 1: Accessing different data plots
Zoomable
Figure 1: Distance plot
Zoomable
Figure 1: RSSI plot
Zoomable
Figure 1: SNR plot
GPS Data

The main page shows the last GPS data captured by the device.

Zoomable
Figure 1: GPS display
Zoomable
Figure 1: GPS data

Packet Frame Format

The Uplink packet format send on Fport 1:

ByteUsage
0 - 5GSP position see here for details. Decoding see below
6 - 7Altitude in meters + 1000 m ( 1100 = 100 m )
8HDOP * 10 (11 = 1.1)
9Sats in view

When the GPS position is invalid of GPS is disable, the frame is fill with 0's.

The downlink response format sends on Fport 2:

ByteUsage
0Sequence ID % 255
1Min Rssi + 200 (160 = -40 dBm)
2Max Rssi + 200 (160 = -40 dBm)
3Min Distance step 250 m
4Max Distance step 250 m
5Seen hotspot

The distance is calculated from the GPS position and the gateways position returned by LoRaWAN server meta-data. Under 250 m value is 250 m, over 32 km value is 32 km. 0 is considered as an invalid response.

The following integration and payload transformation allows to decode the gps position and report is to mapper.

Discovery uplink format send on Fport 3 (no ack):

ByteUsage
0 - 5GPS position

Discovery is sending 10 messages SF10 every 40 seconds. All the other information comes from the metadata provided by the network server.

Upgrading the Firmware

It is recommended to update to the latest version of the firmware. To do this, download the latest RAK10701-L WisNode Field Tester firmware and use the WisToolBox to update the custom firmware.

  1. Drag the downloaded firmware to the WisToolBox custom firmware section.
Zoomable
Figure 1: WisToolBox firmware
  1. After the firmware file is uploaded to the application, you can now select UPGRADE DEVICE.
Zoomable
Figure 1: Upload the latest firmware
Zoomable
Figure 1: Confirm upgrading of firmware
  1. If all proceed with no error, you should see Firmware update successful notification, and the RAK10701-L will restart automatically.
Zoomable
Figure 1: Ongoing upgrading of firmware
Zoomable
Figure 1: Successful upload of latest firmware