How To Set Up WisBlock Kit 4 and RAK Edge Gateway - Complete LoRaWAN Guide

Overview

This guide is about learning how to set up a complete LoRaWAN application from device, gateway up to network server.

This guide is composed of the following section:

• Setting Up the Gateway
• Setting Up the Network Server
• Setting Up the Device
• Setting Up IoT Dashboard using Ubidots

LoRaWAN gateway models like WisGate Edge have built-in network servers. It is also common that the LoRaWAN network server is external or in the cloud. The popular LoRaWAN network server in the cloud that you can use for free (but offers enterprise service, too) is TTN.

Setting Up the Gateway

WisGate Edge is the RAK flagship line of commercial-grade gateways. Gateways from this product line are designed to work either indoor or outdoor, customizable in terms of the backhaul connectivity options, antenna type, and power provisioning. Here are the products that you may look to as you build your LPWAN base station:

• RAK7240 WisGate Edge Prime
• RAK7249 WisGate Edge Max
• RAK7258 WisGate Edge Lite
• RAK7268 WisGate Edge Lite 2
• RAK7289 WisGate Edge Pro

Configuring the WisGate Edge Gateway

This section will guide you on how to set up your WisGate Edge Gateway.

Access the Gateway

In this section, several ways of accessing the gateway are provided to have different alternatives for you to choose from depending on the availability of the requirements needed.

Wi-Fi AP Mode

By default, the gateway will work in Wi-Fi AP Mode which means that you can find an SSID named RAK72XX_YYYY on your PC's Wi-Fi Network List. XX is the code of your chosen WisGate Edge Gateway and YYYY is the last two bytes of the gateway's MAC address.

Using your preferred Web browser, log in with the credentials provided below:

• Browser Address: 192.168.230.1
• Username: root
• Password: root

WAN Port (Ethernet)

Connect the Ethernet cable to the port marked ETH on the gateway and the other end to the PoE port of the PoE injector. Connect the LAN port of the PoE injector to your PC.

The default IP is 169.254.X.X. The last two segments (X.X) are mapped from the last four bits of the MAC address of your gateway.

For example, the last four bits of the MAC address are 0F:01, and the IP address is 169.254.15.1. Make sure to manually set the address of your PC to one in the same network (for example 169.254.15.100). Use the same credentials for the Web UI as for AP mode.

Setting Up the Network Server

Registering RAK7268 WisGate Edge Lite 2 to TTNv3

In this section, it will be shown how to connect RAK7268 WisGate Edge Lite 2 to TTNv3.

If you don’t have a TTN account, create an account first. Click the Sign up button, then login.

Make sure first you are in the right TTN cluster. Use your The Things ID credentials to log in. In this example, choose Europe 1.

After you have logged in, you need to register your commercial gateway to TTNv3. To register, choose Go to gateways. If you have already registered your gateways before, head on to Gateways > + Add gateway.

Fill in the needed information:

• Owner – Automatically filled by The Things Stack, based on your account or created Organization.
• Gateway ID – This will be the unique ID of your gateway in the Network. ID must contain only lowercase letters, numbers, and dashes (-).
• Gateway EUI - A 64 bit extended unique identifier for your gateway. This is where the gateway you get on the above section Configuring the RAK7268 WisGate Edge Lite 2.
• Gateway name – A name for your gateway.
• Gateway description (optional) - Optional gateway description; can also be used to save notes about the gateway.
• Gateway Server address - The address of the gateway server to connect to.
• Frequency plan - The frequency plan used by the gateway.

TTNv3 supports TLS server authentication and Client token, which requires a trust file and a key file to configure the gateway and successfully connect it to the network. Generating the token for the gateway is the next step in this guide. To generate a key file, from the Overview page of the registered gateway, navigate to API keys.

On the API keys page, choose + Add API key.

In the Name field, type the name of your key (for example - mykey). Choose Grant individual rights and select Link as Gateway to a Gateway for traffic exchange, i.e. read uplink and write downlink.

To generate the key, choose the Create API key. The following window will pop up, telling you to copy the key you just generated.

Click I have copied the key to proceed.

You will configure the gateway to connect it successfully to the TTN V3 Server. To configure the gateway, access it via the Web UI. To learn how to do that, check out the RAK7268 Quick Start Guide.

Navigate to LoRa Network > Network Settings > Mode drop-down menu, then choose Basics Station.

Select Switch mode to apply the change. After that, the Basics Station Configuration pane settings will show up. To connect the gateway to TTNv3, the following parameters must be configured:

• Server – For server, choose LNS Server.
• URI – This is the link to The Things Stack server. Note that, for this tutorial, you are connecting the gateway to the European cluster. For Europe, fill in the following: wss://eu1.cloud.thethings.network.
• Port – The LNS Server uses port 8887. Type in 8887.
• Authentication Mode – Choose TLS server authentication and Client token. When selected, the trust and the token field will show up.
• trust – For trust, you will use the Let’s Encrypt ISRG ROOT X1 Trust certificate. Download the certificate first.
• token - This is the generated API key. The key must start with Authorization:. Example:

Authorization: YOUR_API_KEY

To save the changes, click Save & Apply.

You can now see that your gateway is connected to TTNv3 as Basics Station:

Setting Up the Device

Connecting RAK4631 to TTN V3 Application

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

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

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-devices to your TTN application. LoRaWAN specification enforces that each end-device has to be personalized and activated. There are two options for registering devices depending on the activation mode you select. Activation can be done either via Over-The-Air-Activation (OTAA) or Activation-By-Personalization (ABP). You need to click + Add end device, as shown in Figure 21.

To register the module, you need to click Manually first.

Choose the following configurations in adding the end devices.

Click Show advanced activation, LoRaWAN class, and cluster settings, then select Over the air action (OTAA).

Then you need to put a unique End device ID and EUIs (DevEUI and AppEUI), as shown in Figure 25. Check if your RAK4631 module has a DevEUI on sticker or QR that you can scan then use this as the device unique DevEUI.

For AppEUI, you may click Fill with Zeros. Click Generate for the AppKey. Then the End Device ID will be automatically filled by the website. You can also put a different End Device ID if you need to. Finally, click Register End Device.

You should now be able to see the device on the TTN console after you fully register your device, as shown in Figure 26. Take note of these keys, such as the AppEUI, DevEUI, and the AppKey, as they are needed in the next part of this guide.

Creating Environment Monitoring Application

Hardware Setup

This step of the guide is about the actual device configuration.

RAK1906 WisBlock Environmental Sensor module can be connected to any slot of RAK5005-O WisBlock Base Board to communicate with the RAK4631 WisBlock LPWAN Module. It will work on SLOT A to D. Also, always secure the connection of the WisBlock module by using compatible screws.

Assembling and Disassembling of WisBlock Modules

Assembling

As shown in Figure 28, the location for Slot A, B, C, and D are properly marked by silkscreen. Slots C and D are located on the bottom of WisBlock Base. Follow carefully the procedure defined in RAK5005-O module assembly/disassembly instructions to attach a WisBlock module. Once attached, carefully fix the module with an M1.2 x 3 mm screw.

Disassembling

The procedure in disassembling any type of WisBlock modules is the same.

First, remove the screws.

Once the screws are removed, check the silkscreen of the module to find the correct location where force can be applied.

Apply force to the module at the position of the connector, as shown in Figure 31, to detach the module from the baseboard.

LoRa and BLE Antenna

Another important part component of RAK4631 is the antennas.

You need to ensure that the antenna is properly connected to have a good LoRa signal. Do not power the module without an antenna connected to the IPEX connector to avoid damage to the RF section of the chip.

RAK4631 has a label on its sticker where to connect the antennas, as shown in Figure 34.

After all this setup, you can now connect the battery (optional) and USB cable to start programming the RAK1906.

Software Setup

The RAK1906 is a 4-in-1 Environmental Sensor board that contains the Bosch BME680 chip. It is specially designed for wearables where size and low power consumption are critical requirements. The BME680 contains a small Metal-Oxide (MOX) sensor and an I2C interface used to communicate with WisBlock Core.

The RAK1906 module gives information about:

• Air pressure
• Air quality
• Ambient Air Temperature
• Environment Humidity

Software Configuration

Download the Arduino IDE, then install it on your PC or laptop.

Open the Arduino IDE, then install the RAKwireless BSP support for the Arduino Board Manager.

Click on File > Preferences. In the Preferences window, look for Additional Boards Manager URLs, then click the icon on the right side.

Copy https://raw.githubusercontent.com/RAKwireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless_index.json, paste it into the new window, then click OK > OK.

Go to Tools > Board: "Arduino Uno" > Boards Manager. Type RAK in the search bar, and the RAKwireless Core modules will be shown in the window.

Choose RAKwireless nRF Boards, then Install. After installing the core nRF core module, click Close.

After the installation of the RAKwireless nRF Board core module, you can get the program by navigating on the example code, as shown in Figure 46. Open it on the Arduino IDE, and save it as Environment_Monitoring.ino

Once the example code is open, install the Adafruit BME680 library, SX126x Arduino library, and the U8g2lib Library, by clicking the links highlighted in red. You will be directed to Arduino Library Manager for each link you will be clicking.

During the installation, you will be asked to install the Adafruit Unified Sensor library. Install it, as well.

Configuring LoRaWAN

Before uploading the Arduino Code, there are configurations that you need to set up to ensure that the device can join a LoRaWAN Network server.

The steps below will explain the default settings and how to configure them.

Set up the LoRa Region.

Default region is EU868.

LoRaMacRegion_t g_CurrentRegion = LORAMAC_REGION_EU868;

You can change this to a region that is applicable to you like LORAMAC_REGION_US915, LORAMAC_REGION_AU915, etc.

Set up the LoRaWAN activation method.

Default is OTAA.

bool doOTAA = true;

To configure the device to ABP, you need to make this boolean variable false.

Set up the message type if confirmed or not.

Default is confirmed message.

lmh_confirm g_CurrentConfirm = LMH_CONFIRMED_MSG;

You can change to unconfirmed message by changing the value to LMH_UNCONFIRMED_MSG.

Set up device class.

Default is Class A.

DeviceClass_t g_CurrentClass = CLASS_A;

You can change this to CLASS_B (still under development) or CLASS_C.

Setup the EUIs and KEY. Get these parameters from the Connecting RAK4631 to TTN V3 Application section of this guide. It is very important that the EUI and KEY will match the one configured in the TTN application. Otherwise, your device will not be able to connect to the TTN server. In this application, the device is activated via OTAA so you need to configure the Device EUI, Application EUI, and Application Key.

uint8_t nodeDeviceEUI[8] = {0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x33, 0x33};
uint8_t nodeAppEUI[8] = {0xB8, 0x27, 0xEB, 0xFF, 0xFE, 0x39, 0x00, 0x00};
uint8_t nodeAppKey[16] = {0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88};

Set up uplink period.

The default is 20000 mS.

#define LORAWAN_APP_INTERVAL 20000

LoRaWAN Payload

• This is the setup on the void send_lora_frame(void) function.

if (lmh_join_status_get() != LMH_SET)
{
  //Not joined, try again later
  return;
}
if (!bme.performReading()) {
  return;
}
bme680_get();

lmh_error_status error = lmh_send(&m_lora_app_data, g_CurrentConfirm);
if (error == LMH_SUCCESS)
{
  count++;
  Serial.printf("lmh_send ok count %d\n", count);
}
else
{
  count_fail++;
  Serial.printf("lmh_send fail count %d\n", count_fail);
}

• This is the setup on the void bme680_get() function. This will gather the data from the sensor and package them in a LoRaWAN payload.

char oled_data[32] = {0};
Serial.print("result: ");
uint32_t i = 0;
memset(m_lora_app_data.buffer, 0, LORAWAN_APP_DATA_BUFF_SIZE);
m_lora_app_data.port = gAppPort;

double temp = bme.temperature;
double pres = bme.pressure / 100.0;
double hum = bme.humidity;
uint32_t gas = bme.gas_resistance;

data = "Tem:" + String(temp) + "C " + "Hum:" + String(hum) + "% " + "Pres:" + String(pres) + "KPa " + "Gas:" + String(gas) + "Ohms";
Serial.println(data);

// display bme680 sensor data on OLED
u8g2.clearBuffer();         // clear the internal memory
u8g2.setFont(u8g2_font_ncenB10_tr); // choose a suitable font

memset(oled_data, 0, sizeof(oled_data));
sprintf(oled_data, "T=%.2fC", temp);
u8g2.drawStr(3, 15, oled_data);

memset(oled_data, 0, sizeof(oled_data));
snprintf(oled_data, 64, "RH=%.2f%%", hum);
u8g2.drawStr(3, 30, oled_data);

memset(oled_data, 0, sizeof(oled_data));
sprintf(oled_data, "P=%.2fhPa", pres);
u8g2.drawStr(3, 45, oled_data);

memset(oled_data, 0, sizeof(oled_data));
sprintf(oled_data, "G=%dOhms", gas);
u8g2.drawStr(3, 60, oled_data);

u8g2.sendBuffer(); // transfer internal memory to the display

uint16_t t = temp * 100;
uint16_t h = hum * 100;
uint32_t pre = pres * 100;

//result: T=28.25C, RH=50.00%, P=958.57hPa, G=100406 Ohms
m_lora_app_data.buffer[i++] = 0x01;
m_lora_app_data.buffer[i++] = (uint8_t)(t >> 8);
m_lora_app_data.buffer[i++] = (uint8_t)t;
m_lora_app_data.buffer[i++] = (uint8_t)(h >> 8);
m_lora_app_data.buffer[i++] = (uint8_t)h;
m_lora_app_data.buffer[i++] = (uint8_t)((pre & 0xFF000000) >> 24);
m_lora_app_data.buffer[i++] = (uint8_t)((pre & 0x00FF0000) >> 16);
m_lora_app_data.buffer[i++] = (uint8_t)((pre & 0x0000FF00) >> 8);
m_lora_app_data.buffer[i++] = (uint8_t)(pre & 0x000000FF);
m_lora_app_data.buffer[i++] = (uint8_t)((gas & 0xFF000000) >> 24);
m_lora_app_data.buffer[i++] = (uint8_t)((gas & 0x00FF0000) >> 16);
m_lora_app_data.buffer[i++] = (uint8_t)((gas & 0x0000FF00) >> 8);
m_lora_app_data.buffer[i++] = (uint8_t)(gas & 0x000000FF);
m_lora_app_data.buffsize = i;

Data Format

• Byte1 is a marker for the data type, here always 1.
• Every byte value is MSB first.
• Temperature is sent as two bytes, enlarged 100 times for accuracy. For example, 2510 means 25.01 C, sent as 0x09 0xCE.
• Humidity is sent as two bytes, enlarged 100 times for accuracy. For example, 4173 means 41.73%, sent as 0x10 0x4D.
• Barometric pressure is sent as four bytes, enlarged 100 times for accuracy. For example, 100945 means 1009.45 hPa, sent as 0x00 0x01 0x8A 0x51.
• Gas resistance is sent as four bytes. For example, 63560 Ohm, sent as 0x00 0x00 0xF8 0x48.

Uploading the Arduino Code

After a successful installation of the library and configuration of LoRaWan Network Server setup, you can now select the right serial port and upload the code, as shown in Figure 49 and Figure 50.

When you have successfully uploaded the example sketch, open the serial monitor of the Arduino IDE to see the sensor's reading logs. If you see the logs, as shown below, then your RAK1906 is properly communicating to the WisBlock core.

10:30:07.777 -> =====================================
10:30:07.777 -> Welcome to RAK4630 LoRaWan!!!
10:30:07.777 -> Type: OTAA
10:30:07.777 -> Region: EU868
10:30:07.777 -> =====================================
10:30:07.777 -> Chip ID=0x61
10:30:12.974 -> OTAA Mode, Network Joined!
10:30:33.999 -> Sending frame now...
10:30:33.999 -> result: Tem:28.70C Hum:67.00% Pres:948.50KPa Gas:27646Ohms
10:30:33.999 -> lmh_send ok count 1
10:30:53.979 -> Sending frame now...
10:30:53.979 -> result: Tem:28.70C Hum:67.00% Pres:948.50KPa Gas:242488Ohms
10:30:54.012 -> lmh_send ok count 2
10:31:14.006 -> Sending frame now...
10:31:14.006 -> result: Tem:28.70C Hum:67.00% Pres:948.50KPa Gas:457174Ohms
10:31:14.006 -> lmh_send ok count 3
10:31:33.997 -> Sending frame now...
10:31:33.997 -> result: Tem:28.69C Hum:67.00% Pres:948.50KPa Gas:74102Ohms
10:31:34.032 -> lmh_send ok count 4

Check again your The Things Stack account and go to Applications > <name of your application> > Live Data. Wait for the uplink data messages that are updated every 20 seconds.

Setting up IoT Dashboard using Ubidots

This section will guide you to integrate your application using Ubidots.

Go to ubidots.com then click SIGN UP.

Choose TAKE ME TO UBIDOTS STEM, and fill in all the requirements to sign up for an account.

Go to Devices > Devices, and click Create Device.

A window on the right side pops up, and choose the following:

• Connectivity: LoraWAN
• Hardware Type: Dev Kits
• Device: Blank Device

Then, a window will appear, and fill in Device name and Device label. Once done, press the check button.

• Device name: Environment Monitoring
• Device label: wisblock-kit4-environment-monitoring

After adding the device, fill in the Description and SET LOCATION.

After filling in, go to Plugins, then click Create Data Plugin.

A window on the right side pops up, and choose The Things Stack. Follow the instructions given by the plugin, then click the forward button.

Under the Ubidots Token, use Default token, then click again the forward button.

Finally, press the check button to install the plugin.

After installing the plugin, click on The Things Stack, then go to Decoder.

Ubidots The Things Stack default decoder supports the payload format of RAK1906 so there is no need for further decoder configuration. This is the section of the Ubidots decoder that gets the sensor values. Since this decoder is already in Ubidots, no extra decoder is needed in the TTN application console.

function decodeUplink(bytes) {
  // Decoder for the RAK1906 WisBlock Environmental Sensor (https://store.rakwireless.com/products/rak1906-bme680-environment-sensor)
  var decoded = {};
  if (bytes[0] == 1) {
      // If received data is of Environment Monitoring type
      decoded.temperature = (bytes[1] << 8 | (bytes[2])) / 100;
      decoded.humidity = (bytes[3] << 8 | (bytes[4])) / 100;
      decoded.pressure = (bytes[8] | (bytes[7] << 8) | (bytes[6] << 16) | (bytes[5] << 24)) / 100;
      decoded.gas = bytes[12] | (bytes[11] << 8) | (bytes[10] << 16) | (bytes[9] << 24);
  }
  return {"data": decoded};
}

Go back to The Things Stack account and Go to applications.

Head on to your device under the Applications menu, then click wisblock-kit4-environment-monitoring.

Under your device tab, choose Integrations > Webhooks, and then click the Add webhook button.

Choose Custom webhook, then fill in all the necessary fields like Webhook ID and Webhook format.

Go back again to your Ubidots account Environment Monitoring to obtain Base URL, X-Auth-Token, and Uplink message.

• X-Auth-Token is the Ubidots token and can be found in the ubidots console, as shown in Figure 76.

• Also, settings for the Uplink message can be found in Figure 77. You only need to get the part of the URL with /api/webhook/xxxxxxxxxxxxxxxxxxx.

After filling in the important fields, click the Add webhook button.

Now, you need to create a dashboard in Ubidots. Click Data > Dashboards, then click the Add new Dashboard button.

Edit the Add new Dashboard window to your desired details, then press check button.

Click Add new Widget. A window appears on the right side, and choose Thermometer.

Edit the Thermometer widget. Change it into Temperature, then click the Add Variables button.

A window will pop up. Click wisblock-kit4-environment-monitoring, select the temp variable, then press the check button.

Finally, click the check button to save.

After adding the Temperature widget, click on the plus sign at the right side to add another widget. This time, choose Gauge, and add the Humidity widget.

After editing the name into Humidity, click Add Variables. Select wisblock-kit4-environment-monitoring, choose the hum variable, then press the check button.

Finally, click the check button to save.

Use the same method in adding the Temperature and Humidity widgets. Just click on the plus sign at the right to add another widget, then choose Gauge.

This time, add the Pressure widget under Gauge, then click Add Variables.

After editing the name into Pressure, click wisblock-kit4-environment-monitoring, choose the press variable, then press the check button.

Edit the Range into 0-1000. After doing it, click the check button to save.

After adding the three widgets, go to Devices > Devices menu, and edit the variables.

• For the temp variable:
  • Description: Temperature
  • Unit: °C
    
    
    

• For the hum variable:
  • Description: Humidity
  • Unit: %RH
    
    
    

• For the press variable:
  • Description: Pressure
  • Unit: hkPa
    
    
    

After doing all these steps, you already finished the Wisblock Kit 4 Environment Monitoring Project using Ubidots.

Updated October 25, 2024 04:31