How To Set Up RAK Developer Kit 4 (Air Quality Kit)

Overview

This guide is about learning how to set up a complete LoRaWAN application from device, gateway up to network server. It composes of the following sections:

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

Setting Up the Gateway

Configuring the RAK7246 WisGate Developer D0

This section will guide you on how to set up and configure your gateway.

Here are the steps in configuring the RAK7246G WisGate Developer D0:

By default, the gateway will work in Wi-Fi AP Mode, which means that you can find an SSID named Rakwireless_XXXX on your PC Wi-Fi network list.

• Wi-Fi Password: rakwireless

• Default IP Address: 192.168.230.1

Log into the Gateway.

• • Windows OS SSH (Secure Shell) is typically used to log in to a remote machine and execute commands. There are a lot of free and good SSH Clients out there, namely Putty, BitVise SSH Client, MobaXterm and many more. Feel free to choose one that fits your needs, but in this guide, Putty is used.
    

• Mac OS Open the Terminal of Mac OS. Launch the Terminal application found in the /Applications/Utilities/ directory, but you can also launch it from Spotlight. Press Command + Spacebar and type Terminal, then return.
  

If you have connected to the gateway through Wi-Fi AP Mode, the IP Address is 192.168.230.1. It will then prompt you to enter the username and password. Enter the default credentials:

• • Username: pi
  • Password: raspberry

From the previous step, get the Gateway ID by typing sudo gateway-config to your chosen SSH Client terminal editor. It can be found on top of the terminal console, as shown in the red box in Figure 5. You may copy it on a txt file or any notepad software. It will be used in setting up the gateway in TTN V3. See Figure 5 for reference. You will use it also as Gateway EUI in the latter part of this guide.

Like for RAK WisGate Edge Gateways, it has built-in LNS that you can use.

You can now connect your gateway through Wi-Fi to access TTN. It can easily be done with the wireless capabilities of the Raspberry Pi Zero W by choosing 5 Configure WIFI. By default, the RAK7246 WisGate Developer D0 Gateway works in Wi-Fi AP Mode. For the gateway to connect to the router, it must work in Wi-Fi Client Mode.

There are 5 options to choose from in the Wi-Fi configuration menu:

1. Enable AP Mode/Disable Client Mode - the gateway will work in Wi-Fi Access Point Mode after rebooting, while the Wi-Fi Client Mode will be disabled (this is the default mode).
2. Enable Client Mode/Disable AP Mode - the gateway will work in Wi-Fi Client mode after rebooting, while Wi-FI AP Mode will be disabled.
3. Modify SSID and pwd for AP Mode - used to modify the SSID and password of the Wi-Fi AP. Only works if the Wi-Fi AP Mode is enabled.
4. Add New SSID for Client - this is used if you want to connect to a new Wi-Fi network. Only works in Wi-Fi Client mode.
5. Change Wi-Fi Country - this is used to modify the Resident Country to match Wi-Fi standards.

Once Wi-Fi AP Mode has been disabled by choosing 2 Enable Client Mode/Disable AP Mode, you can now then connect to a new Wi-Fi Network by choosing 4 Add New SSID for Client.

• Start by selecting your country of residence.
  

• Enter the SSID of the network you want to connect.

• Enter the SSID of the network you want to connect.
  

• Lastly, reboot the gateway using the command sudo reboot in the command line, and it will connect to the router successfully.

sudo reboot

After rebooting the RAK7246 WisGate Developer D0, you should check if it is connected successfully to your Wi-Fi network. You may use your local network modem/router admin console to check if RAK7246 is successfully connected.

In this example, the admin console can be accessed via http://192.168.0.1. It is also common to have it on http://192.168.1.1 on some routers. Take note of the IP address allotted to the RAK7246 by your Wi-Fi network.

You can also use Advance IP Scanner for Windows OS, or Angry IP Scanner for Mac OS, and locate the IP address of RAK7246 WisGate Developer D0 in your Wi-Fi device.

As seen in Figure 12, it is 192.168.0.28, where the company is Raspberry Pi Foundation. You can use that IP address to configure other related parameters of RAK7246 WisGate Developer D0 by logging in to the SSH Client Software, as stated in the previous step, now with the IP address of RAK7246 WisGate Developer D0 from your Wi-Fi network.

To link your gateway to TTN, you need to set up first the RAK Gateway LoRa by choosing 2 Setup RAK Gateway LoRa concentrator.

Then, you need to select Server is TTN as the LoRaWAN server and select the right frequency that will match your gateway and region. The supported frequency plan of TTN can be found on their website.

For this example, you will be using EU868 Frequency Plan. Choose 4 EU_863_870.

After choosing the correct frequency, the success message will appear, as shown in Figure 16.

You need to check if the right SERVER_ADDRESS is used to connect to TTN V3. To do this, choose 4 Edit packet-forwarder config from the configuration options.

You will be editing a JSON file to configure the server_address to eu1.cloud.thethings.network. To save the changes you made, if there is any, press CTRL + X to exit the editor and select yes to confirm the changes.

Restart the Packet-forwarder by choosing 3 Restart Packet-forwarder from the configuration options.

Setting Up the Network Server

Connect RAK7246 WisGate Developer D0 to TTN V3

This section shows how to connect RAK7246 WisGate Developer D0 to TTN.

Create a TTN account if you don't have one yet.

Make sure you are in the right TTN cluster, and then log in to TTN. 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 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. (e.g. rak-discovery)
• Gateway ID – This will be the unique ID of your gateway in the Network. ID must contain only lowercase letters, numbers, and dashes (-). (e.g. rak-d0-ph-las-pinas)
• Gateway EUI - A 64 bit extended unique identifier for your gateway. This is where the gateway you get on the above section Configuring the RAK7246 WisGate Developer D0. (e.g. B827EBFFFE81)
• Gateway name – A name for your gateway. (e.g. RAK D0 Pilar Las Pinas PH)
• 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 (i.e. eu1.cloud.thethings.network).
• Frequency plan - The frequency plan used by the gateway.

Once the RAK7246 WisGate Developer D0 is set to the eu1.cloud.thethings.network server address, and the gateway account is created, you will now see the connected status, as seen in Figure 26.

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 29.

To register for 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 33. 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 can click Fill with Zeros. Click Generate for the AppKey. Then the End Device Name 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 34. 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 36, 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 39, 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 43.

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 and 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 click Install. After installing the RAK4631 Arduino BSP (Board Support Package), 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 54. 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, as shown in Figure 55. You will be directed on the Arduino Library Manager for each link you click.

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.

Set up 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 57 and Figure 58.

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 select Go to applications.

Head on to your device under the Applications menu, then click the <name of your application>.

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 the 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 81.
• Also, settings for the Uplink message can be found in Figure 82. 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 the 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 on the right side to add another widget. This time, choose Gaugeand 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 the 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:23