RAK is a pioneer in providing innovative and diverse cellular and LoRa connectivity solutions for IoT edge devices. In the following tutorial you will learn how to integrate the data coming from RAKwireless devices to Ubidots using The Thing Network server. Turn real-time sensor data into valuable information for your customers.
Requirements
Before starting, attach the antennas (i.e. Wi-Fi, LPWAN, LTE, and GPS) found on your gateway. For RAK7258, attach those to the SMA connector, and for RAK7249, screw the antennas onto the gateway. After this, you can now turn on the gateway. Once powered, you may use either the Ethernet Port or Wi-Fi to connect the gateway. Both of these options let you access the Management UI via a web browser in which you can see the gateway’s EUI.
1. TTN Configuration
1.1 TTN Gateway and Node Registration
Connect the gateway to TTN and register here. Make sure to select the “I’m using the legacy packet forwarder” option before entering the Gateway EUI.
Select your frequency plan depending on your location and this should populate the router field.
With your same TTN account, go to “Applications” and fill-out the necessary information such as app ID, Description, app EUI, and handler registration to add an application. Register your device by also providing the node’s device ID and EUI. Depending on which authentication method you want to use, proceed to either the OTAA mode or the ABP mode section. For further information on the instructions, you may see this document from RAKwireless.
1.2 Decoder
While hexadecimals payloads are great for LoRaWan devices, most web APIs are designed to understand JSON payloads and Ubidots is not the exception. For that reason is necessary to configure a custom decoder that transform the data receive by the Gateway into a JSON compatible with Ubidots. To do this, follow the next steps:
1. Go to the "Console" of your TTN account.
2. Open the "Application" where your device is already registered.
3. Select the "Payload Formats" option. Then, select “Custom” as payload format, and make sure the "Decoder" option is selected.
Place the code below into the code block field available. To save the payload format assigned, make sure to press the "Save" button:
// TTN application function to decode uplink data.
// Decode decodes an array of bytes into an object.
// - port contains the LoRaWAN fPort number
// - bytes is an array of bytes, e.g. [225, 230, 255, 0]
// The function must return an object, e.g. {"temperature": 22.5}
function Decoder(bytes, port) {
var decoded = {};
var hexString=bin2HexStr(bytes);
return rakSensorDataDecode(hexString);
}
// convert array of bytes to hex string.
function bin2HexStr(bytesArr) {
var str = "";
for(var i=0; i<bytesArr.length; i++) {
var tmp = (bytesArr[i] & 0xff).toString(16);
if(tmp.length == 1) {
tmp = "0" + tmp;
}
str += tmp;
}
return str;
}
// convert string to short integer
function parseShort(str, base) {
var n = parseInt(str, base);
return (n << 16) >> 16;
}
// convert string to Quadruple bytes integer
function parseQuadruple(str, base) {
var n = parseInt(str, base);
return (n << 32) >> 32;
}
// decode Hex sensor string data to object
function rakSensorDataDecode(hexStr) {
var str = hexStr;
var myObj = {};
while (str.length > 4) {
var flag = parseInt(str.substring(0, 4), 16);
switch (flag) {
case 0x0768:// Humidity
myObj.humidity = parseFloat(((parseShort(str.substring(4, 6), 16) * 0.01 / 2) * 100).toFixed(1));
str = str.substring(6);
break;
case 0x0673:// Atmospheric pressure
myObj.barometer = parseFloat((parseShort(str.substring(4, 8), 16) * 0.1).toFixed(2));
str = str.substring(8);
break;
case 0x0267:// Temperature
myObj.temperature = parseFloat((parseShort(str.substring(4, 8), 16) * 0.1).toFixed(2));
str = str.substring(8);
break;
case 0x0188:// GPS
lat = parseFloat((parseQuadruple(str.substring(4, 12), 16) * 0.000001).toFixed(6));
lng = parseFloat((parseQuadruple(str.substring(12, 20), 16) * 0.000001).toFixed(6));
myObj.position = {"value":1, "context":{"lat":lat,"lng":lng}};
myObj.altitude = parseFloat((parseQuadruple(str.substring(20, 28), 16) * 0.01).toFixed(1)) ;
str = str.substring(28);
break;
case 0x0371:// Triaxial acceleration
myObj.acceleration_x = parseFloat((parseShort(str.substring(4, 8), 16) * 0.001).toFixed(3));
myObj.acceleration_y = parseFloat((parseShort(str.substring(8, 12), 16) * 0.001).toFixed(3));
myObj.acceleration_z = parseFloat((parseShort(str.substring(12, 16), 16) * 0.001).toFixed(3));
str = str.substring(16);
break;
case 0x0402:// air resistance
myObj.gasResistance = parseFloat((parseShort(str.substring(4, 8), 16) * 0.01).toFixed(2));
str = str.substring(8);
break;
case 0x0802:// Battery Voltage
myObj.battery = parseFloat((parseShort(str.substring(4, 8), 16) * 0.01).toFixed(2));
str = str.substring(8);
break;
case 0x0586:// gyroscope
myObj.gyroscope_x = parseFloat((parseShort(str.substring(4, 8), 16) * 0.01).toFixed(2));
myObj.gyroscope_y = parseFloat((parseShort(str.substring(8, 12), 16) * 0.01).toFixed(2));
myObj.gyroscope_z = parseFloat((parseShort(str.substring(12, 16), 16) * 0.01).toFixed(2));
str = str.substring(16);
break;
case 0x0902:// magnetometer x
myObj.magnetometer_x = parseFloat((parseShort(str.substring(4, 8), 16) * 0.01).toFixed(2));
str = str.substring(8);
break;
case 0x0a02:// magnetometer y
myObj.magnetometer_y = parseFloat((parseShort(str.substring(4, 8), 16) * 0.01).toFixed(2));
str = str.substring(8);
break;
case 0x0b02:// magnetometer z
myObj.magnetometer_z = parseFloat((parseShort(str.substring(4, 8), 16) * 0.01).toFixed(2));
str = str.substring(8);
break;
default:
str = str.substring(7);
break;
}
}
return myObj;
}
Important note: This code is an adaptation of the decoder made by RAKWireless team.
2. Ubidots integration setup
First of all, if you're new to Ubidots, please create an account here to complete the following steps.
To establish the communication with Ubidots, you have to set up a new integration in the same application used in the previous step.
Next, give a customized name to your new integration and select "default key" in the Access Key drop-down menu. The default key represents a "password" that is used to authenticate your application in TTN. Finally, enter your Ubidots TOKEN where indicated in the TTN user interface.
Once all the information is provided, you can now press the “Add integration” button.
3. Data visualization / Dashboard Creation
Once the TTN integration is set, you can see that the Ubidots device is automatically created in the “Devices” tab in your Ubidots account. By default, the device will be named with the Device EUI, but you can change its name for a friendlier one (How to adjust the Device Name and Variable Name).
Now it’s time to build your own dashboard to start monitoring the data sensed by RAKwireless devices.
1. Go to the Dashboard (Data -> Dashboard) section of your Ubidots account.
2. Select the plus (+) icon located at the right-upper side of the page. Then select the widget types desired to display your data. Learn more about Ubidots’ Dashboards.
With Ubidots you can easily visualize and comprehend data, making information palatable to users and allowing them to generate informed decisions in business.