Skip to main content
X

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.

Figure 10882: 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.
Figure 10883: 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.

Figure 10884: 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.
Figure 10885: RAK10701-L power up successful
Figure 10886: 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.

Figure 10887: 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).

Figure 10888: 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.
Figure 10889: Helium Console
Figure 10890: 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.
Figure 10891: 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.

Figure 10892: Configuring Device Name
  1. The device will be added to the blockchain and it will show pending beside its name.
Figure 10893: 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.
Figure 10894: Add Label icon
Figure 10895: Add Label Name
Figure 10896: 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.
Figure 10897: 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.
Figure 10898: 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.
Figure 10899: Label added on the RAK10701 device
  1. To connect the backend server, you have to create an Integration.
Figure 10900: Add integration
Figure 10901: 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.
Figure 10902: 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.
Figure 10903: Setting up the Flows
  1. You must select Labels and Integrations and then drag the correct blocks on the flows canvas.
Figure 10904: Drag the rak10701-devices label
Figure 10905: 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.

Figure 10906: 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.
Figure 10907: 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.
Figure 10908: Multiple packets configuration
Figure 10909: 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.
Figure 10910: 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.
Figure 10911: The Things Stack home page
Figure 10912: 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.
Figure 10913: 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.
Figure 10914: 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.
Figure 10915: Add end-devices to your TTN application
  1. To register the RAK10701-L Field Tester, you need to click Manually first.
Figure 10916: 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.
Figure 10917: Configurations for adding end devices
  1. Click Show advanced activation, LoRaWAN class, and cluster settings, then select Over the air action (OTAA).
Figure 10918: 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.
Figure 10919: 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.
Figure 10920: 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.
Figure 10921: Creating API key
Figure 10922: 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.
Figure 10923: API key parameters
  1. This step is critical. You need to copy the API key because this will be used on Webhook integration.
Figure 10924: Copy API key
  1. With the API key created, you can proceed with creating the Webhook integration.
Figure 10925: Webhook Integration
  1. Select Custom Webhook.
Figure 10926: 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.
Figure 10927: Webhook parameters
  1. After setting all the configurations, you can now add the webhook.
Figure 10928: Add Webhook
  1. You should see now the newly created webhook.
Figure 10929: 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.

Figure 10930: 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.
Figure 10931: 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.

Figure 10932: 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.

Figure 10933: 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.
Figure 10934: Creating Device Profile in Chirpstack
  1. You must enable Device supports OTAA as the network join method as well.
Figure 10935: 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.
Figure 10936: 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.
Figure 10937: Create application in Chirpstack
Figure 10938: Create device in Chirpstack.
Figure 10939: Device APPKEY
  1. You also need to ensure that you have a Gateway registered in Chirpstack and with the correct Network Server profile.
Figure 10940: 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/.
Figure 10941: Creating integration
Figure 10942: 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.
Figure 10943: Creation of API Key
Figure 10944: 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.
Figure 10945: Device list dashboard
Figure 10946: Selecting LoRaWAN
Figure 10947: Add new product
Figure 10948: Selecting chirpstack
Figure 10949: 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.
Figure 10950: Configuration settings
Figure 10951: Chirpstack downlink configuration
Figure 10952: 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.
Figure 10953: 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.
Figure 10954: Chirpstack downlink configuration
Figure 10955: 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.
Figure 10956: WisGate Edges web UI
  1. Go to your LORIOT profile. From the menu on the left, navigate through Networks > [your_network] > +Add Gateway.
Figure 10957: 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.
Figure 10958: 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.
Figure 10959: 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.

Figure 10960: 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.
Figure 10961: 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.
Figure 10962: 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.
Figure 10963: Datacake Platform
  1. Choose New Product under Datacake Product. Enter the device name in the Product name input box, and proceed by clicking Next.
Figure 10964: Add Lorawan Device 1
  1. Select LORIOT as the Network Server and click Next.
Figure 10965: 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.

Figure 10966: 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.
Figure 10967: LORIOT Access Token
Figure 10968: 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;

}
Figure 10969: 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;
}
Figure 10970: 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.
Figure 10971: 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.
Figure 10972: 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.
Figure 10973: Creating Device Profile in Chirpstack
  1. You must enable Device supports OTAA as the network join method as well.
Figure 10974: 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.
Figure 10975: 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.

Figure 10976: Create device in Chirpstack.
Figure 10977: Device APPKEY
  1. Make sure your Gateway is registered in Chirpstack with the correct Network Server profile.
Figure 10978: 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:

Figure 10979: 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.

Figure 10980: 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:

Figure 10981: 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.

Figure 10982: Setup input node

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

Figure 10983: 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:

Figure 10984: 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:

Figure 10985: 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.

Figure 10986: 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:

Figure 10987: 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:

Figure 10988: Add Field Tester Service node

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

Figure 10989: 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:
Figure 10990: 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:

Figure 10991: Device
  • Select complete msg object as output.
    The result of parser can then be checked on the right side in the debug window:
Figure 10992: 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.

Figure 10993: WisToolBox Desktop splash screen
  1. Review the Connection settings parameters on the dashboard, then click on the CONNECT button.
Figure 10994: 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.
Figure 10995: 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.
Figure 10996: 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.
Figure 10997: 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.
Figure 10998: RAK10701-L settings button
Figure 10999: 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.

Figure 11000: Device status and indicator
Figure 11001: 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.

Figure 11002: Settings button
Figure 11003: 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.

Figure 11004: Accessing different data plots
Figure 11005: Distance plot
Figure 11006: RSSI plot
Figure 11007: SNR plot
GPS Data​

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

Figure 11008: GPS display
Figure 11009: 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.
Figure 11010: WisToolBox firmware
  1. After the firmware file is uploaded to the application, you can now select UPGRADE DEVICE.
Figure 11011: Upload the latest firmware
Figure 11012: 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.
Figure 11013: Ongoing upgrading of firmware
Figure 11014: Successful upload of latest firmware