Integration - Datacake
Overview#
Datacake is an IoT platform that helps the user to create custom IoT applications.
We use the MQTT interface to integrate the Datacake with our Supernode. The Uplink data will feed to the Datacake, then they will be decoded and stored at Datacake. With the features of Datacake, the user could visualise their data easily.
Prerequisite#
Created an account on Datacake.
Created an account on our Supernode.
You have a LoRa device.
You are within the range of a LoRaWAN gateway (for example an M2Pro) that is connected to our Supernode.
The following example is using our US Supernode (ussn.matchx.io). You may change the domain name to the Supernode that suits you.
Get the organization ID#
You need this ID when getting the MQTT Auth Token.
Login to the Supernode and go to the Gateway page or Device page. Then look at the URL bar of your browser. The number on the URL is the organization ID.
Get the HTTP Auth Token#
This is a temporary step to get an Auth Token. After the new Supernode Web UI is released, you can get the Token from the Web UI directly.
The HTTP Auth Token will be used in the next step to get the MQTT Auth Token.
Login to the Supernode.
Enable the developer tools of your browser.
For Chrome, click the right menu button, select the "More tools" and then the "Developer tools".
Select the "Network" tool. We need to get the token from the HTTP request.
Refresh the page and let the tool capture some HTTP traffic.
Select one of the requests, scroll down and find the "Request Headers".
You can get the token from the header "Grpc-Metadata-Authorization".
Get the MQTT Auth Token#
When connecting to the Supernode with MQTT, an Auth Token is needed.
Get via command line (curl).#
Replace the value of the header "Grpc-Metadata-Authorization" on the following command line with the HTTP Auth Token you got above.
curl -X POST --header 'Content-Type: application/json' --header 'Grpc-Metadata-Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -d '{ "organizationId": "27", "ttlInSeconds": "31557600"}' 'https://ussn.matchx.io/api/mosquitto-auth/login'Run the command.
The responses will be like this. The string of the characters is the MQTT Auth Token.
{"jwtMqttAuth":"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"}
Get via Postman (GUI).#
Open an request, and set the URL to
https://ussn.matchx.io/api/mosquitto-auth/login. Add the headerContent-Type=application/json.
Set the Authorization Type to Bearer and enter the HTTP Auth Token you got from above.
Set the method to
POST, and set a raw body of your login information. The organizationId is the number you got from the Supernode above. The ttlInSeconds is the expiration time, this example is set to 1 year.{ "organizationId": "27", "ttlInSeconds": "31557600"}Then click the [Send] button to issue the request. You will get the MQTT Auth Token.
Create Device profile#
The device profile is the LoRaWAN setting of the devices. It is needed when creating a device at Supernode.
Login to the Supernode, go to "Devices" page, then "SMB Device Profile" Tab. Click the [Create] button to create a profile.
At the "General" tab, enter the name for the new profile. Select the Network Server (it should only one available). Then select the LoRaWAN MAC Version that matches your device.
Go the the "Join" tab, enable the OTAA. If the device supports OTAA, you should use it. At last, click [Create] button to create the Device Profile.
Create Application#
One Application on Supernode will map to one Product on Datacake. At Datacake, data decoding is separated by the product. You should group the same (or close similar) type of devices into one Application.
After the Application creation, you will get the Application ID, which is needed for the MQTT topic.
At "Device" page, select the "Application" tab and click [Create] button to create an Application.
Enter the name and description for the Application. Then select the "Service Profile". If you cannot see any Service Profile, please contact our support team to help you.
Click [Create] button to save the settings.
After the Application is created, you can see the Application ID in the Application list.
Create Datacake Device#
Login to Datacake and go to "Devices" page. Click the [Add Device] button to create a device.
Select the type as "API" and select "New Product". When you create an additional device of the same type next time, select the "Existing Product".
Give a name for the Product, and click [Next] button.
Enter the device name and click [Next] button.
Select the Datacake service plan. Click [Add device] button to finish the creation.
Go to the newly created device page, and you will see the "Serial Number" of this device. You need this as the device name on Supernode.
Create Supernode Device#
Login to the Supernode, go to the "Devices" page and "Applications" Tab. Click the [Add Device] button to create a device.
Select the "Application" and "Device Profile" you created above.
Enter the Device EUI, you should find it on your device (normally on a label).
Copy the "Serial Number" from the Datacake device and paste it as the "Device Name" here.
Enter the "Device Description", we suggested using the Datacake device name for easier reference in the future.
Click the [Create] button.
For LoRaWAN 1.0.x OTAA, you need an AppKey (called NwkKey on 1.1). Same as the Device EUI, you should find it on your device.
Click [Update] button, then the device will be created.
Back to the "Application" Tab, click the application to show the devices list.
Click the newly created device to show its detail.
Go to the "LoRaWAN Frames" Tab to check the frame received.
Power up (or reset) your device to kick start the OTAA process.
You should see a "JoinRequest" frame sent from the device.
If the Key is correct, Supernode will send back a "JoinAccept" to the device.
After that, there will be some data frames sent from the device. If you got this, you are ready to decode them at Datacake.
Setup MQTT at Datacake#
Go to the device page at Datacake and switch to the "Configuration" tab.
Scroll down to the "MQTT Configuration" panel. Click the [Add new MQTT server] button to add our Supernode to Datacake.
For the next device on the same Supernode, you just need to select the MQTT server from the list.
Select the "Protocol" as "MQTTS".
Enter the Supernode domain to "Hostname" and set the "Port" as
8883.Select "SSL/TLS Mode" as "CA signed server certification".
Enter the MQTT Auth Token you got from above to the "Username" field.
Enter
defaultto the "Password" field.Click [Test Connection] to check the settings are good. You will see the result in the upper right message box.
Click [Add MQTT Server] to save the settings.
At the "MQTT Configuration" panel, click [Add Uplink Decoder].
In the following string, replace the
YOUR_APP_IDto the Application ID you got from above. Then set it to the MQTT topic.application/YOUR_APP_ID/device/+/event/+If you are using the MatchX LoRa Device, copy the content of our generic uplink decoder to the "Decoder function". For other devices, you may modify the raw data decoder to fit it.
Click the [Add uplink decoder] button to save the configuration.
At the "MQTT Configuration", check the MQTT Server and MQTT Uplink decoder is selected.
Click the [Save] button to save the configuration.
Go to the "Integration" page. You should see the new MQTT server on the list.
Wait for the server status to be changed to "Connected". You may need to refresh this page to get it updated.
Setup MatchX Analog Shield (Data fields)#
We show you here to set up our Analog Shield at Datacake. The data from the decoder is a list of data (pair of field and value). The Datacake store the values to the device fields with the same "Identifier" (in all upper case).
For other devices, you need to adjust the decoder and fields.
Go to the device page at Datacake and switch to the "Configuration" tab. Scroll down to the "MQTT Configuration" panel.
You should see the "LAST DATA" has been updated. If not, double-check the MQTT setting.
Click the icon button to check the MQTT message received.
At the latest "up" message, copy the "PAYLOAD". We will use it to test the decoder.
Click the upper-right cross button to close the list.
At the "MQTT Configuration" panel, click the Menu button of the MQTT topic and click "Edit Decoder".
At the decoder dialog, click the [Show] button to expand the "Try decoder function".
Paste the copied "PAYLOAD" to the "Payload" field.
Click the [Try decoder function] to decode the payload.
If successful, you can see a list of paired fields and values. That is the data decoded from the LoRa payload, which means the data sent by the device.
Click the upper-right cross button to close the dialog.
Now, we can add fields to the device. So the decoded values will be stored at Datacake.
Click the [Add Field] at the "Fields" Panel.
Setup a field for Device EUI (the unique LoRaWAN device id). It is the basic field of the device and you need it when sending data (Downlink).
Setup fields for raw data. These two are optional, but it is good for debugging.
Setup fields for the data of MatchX Analog Shield. For other devices, you will have a different set of fields.
After all fields are added, wait for a while at the "Fields" panel. You will see the values being updated.
Here is the table to map the hardware signal of the Analog Shield and the decoded fields.
Field Hardware Signal voltage0 AIN1 voltatge1 AIN2 digital0 DIN1 digital1 DIN2 digital2 Current DOUT1
To make the AIN1&2 show meaningful value, you could add a mapping field to achieve it.
Click the menu button on the right of the field, then select "Add Mapping Field".
Here, we show an example to convert the voltage to current, with the onboard 240Ω resistor.
Wait for a while for the next data, you will see the converted result.
Setup MatchX Analog Shield (Downlinks)#
Go to the device page at Datacake and switch to the "Configuration" tab. Scroll down to the "Fields" panel. Then add a field for controlling the DOUT1.
Switch to the "Downlinks" tab. Click the [Add Downlink] button.
Enter the name and description.
Select the new added field "control0" and "digital2".
Mark the "Trigger on measurement" checkbox.
Copy the content of the following file to the "Payload encoder".
Modify the application ID to the one you got above.
Click the [Add downlink] button to save the Downlink.
Clink the [Configure and send downlink] button to test the created Downlink.
Mark the "control0" checkbox and click the [Save & send downlink] button.
After that, the downlink will enqueue to Supernode.
You can check the queue on Supernode.
Wait for the downlink to be sent to the device. The DOUT1 of the Analog Shield will change.
Setup MatchX Analog Shield (Dashboard)#
The dashboard is the place to visualise your data. Here is an example of our Analog Shield.
Go to the device page at Datacake and switch to the "Dashboard" tab.
Click the most right switch to enter edit mode.
Click the [Add Widget] button to add the first widget.
Select the "Value" type. This will show a single value of the device.
At the "Edit Value Widget" dialog, select the "Data" Tab.
Select the "Field" as "devEUI". We want to show the Device EUI on the dashboard for reference.
Switch to the "Basics" tab, enter the title for this widget.
Click the [Save] button.
You can see the newly created widget on the dashboard.
Click the [Add Widget] button to add a Chart Widget. This one will show the reported battery level of the device.
At the "Data" tab, select the "Field" as "batteryLevel". Select the "Line Chart".
At the "Axes" tab, set the "Domain From" to 2 and "Domain To" to 5. This will fix the y-axis from 2 to 5.
At the "Timeframe" Tab, select the "Week". This will show you the data from now to the past 7 days (week).
At the "Reference Lines" Tab, add two reference lines for battery "Full" and "Low".
Back to the "Basics" tab, enter the title for this widget and click the [Save] button.
Click the [Add Widget] button to add a Switch Widget. This one will use to control the DOUT1 of the Analog Shield.
Enter the title, select the "Field" as "control0".
Click the [Save] button.
Click the [Add Widget] button to add a Boolean Widget. This one will show the reported DOUT1 status.
At the "Data" tab, select the "Field" as "digital2".
At the "Basics" tab, enter the title and click the [Save] button to finish.
Continue adding the widgets that fit your need.
At last, click the most right switch to end the edit mode.
Wait for a while and you can see data will update on the Dashboard.
