Sending Data Frames
Last updated
Last updated
The Libelium Cloud Bridge service receives data frames from the sensor nodes and sends all the data values to the different final cloud services configured of the list of available connectors: Alibaba Cloud, AWS IoT, Cumulocity, IBM Cloud, Microsoft Azure Event Hubs, Microsoft Azure IoT Hubs, MQTT, SAP Hana and Telefonica IoT Cloud.
Data may be received with direct HTTPS connections from the sensor nodes, using the Libelium Cloud Bridge service connector available in the Meshlium gateway and configuring the callback services of the LPWAN providers.
Sensor nodes using NB-IoT, 4G and WiFi may be programmed to send data directly to the Libelium Cloud Bridge service.
The Programming Cloud Service includes the option "Send to Libelium Cloud Bridge" in the section "Select protocol and destination". The valid API Key of the sensor node and all the encryption layers are implemented transparently by default in the binary program that the Programming Cloud Service generates.
In the Waspmote API documentation there is a sketch available (the HTTPS example) that may be used for the user as the basis for coding on the Waspmote IDE, a valid call to the Libelium Cloud Bridge service.
Parameters needed for the HTTPS call to the Libelium Cloud Bridge service are:
Host: hw.libelium.com
Action: GET /hw/ps?frame=[FRAME TO SEND] HTTP/1.1
Authorization: Bearer [API KEY FROM BRIDGE]
Meshlium gateways can be configured to send data to the Libelium Cloud Bridge service. Meshlium gateways that are going to be used to send data to the Libelium Cloud Bridge service have to be registered in the Services Cloud Manager using their associated activation code.
The Libelium Cloud Bridge service connector must be configured with the same user account used to register the Meshlium gateway in the Services Cloud Manager. The Libelium Cloud Bridge service connector can be found in the “Cloud Connectors” “IoT Premium” section of the Manager System.
The Meshlium gateway will make the HTTPS request to the Libelium Cloud Bridge service sending the data gathered from the nodes that are linked to the Meshlium gateway using RF communication protocols, 4G or WiFi.
Sigfox deploys a Low Power Wide Area Network in many countries, and Sigfox owns the infrastructure. The Libelium Cloud Bridge service enhances the Sigfox network features giving access out-of-the-box to send the data to any of the final cloud services available (Alibaba Cloud, AWS IoT, Cumulocity, IBM Cloud, Microsoft Azure Event Hubs, Microsoft Azure IoT Hubs, MQTT, SAP Hana and Telefonica IoT Cloud).
The user must have a valid Sigfox account to integrate the Libelium Cloud Bridge service in the Sigfox backend as a callback. Registering new Sigfox accounts can be done at https://build.sigfox.com/sign-up.
As a mandatory process for all Sigfox accounts, the user must register a new device and a new device type. Steps for registering a new device can be followed on this address: https://resources.sigfox.com/document/register-a-device
As a summary, the user should do the following steps:
Click on the “Device” menu.
Click on the "New" button in the upper right part of the screen.
Choose the desired group.
Complete the device information fields:
ID/PAC couple, location information is optional.
Name.
Select device type.
if your device is Sigfox Ready, enter your product certificate.
The device default setting is "Activable". If this option is disabled, all messages will be dropped and the device cannot consume any token. This option could be updated by editing the device.
Click "OK" to validate.
Steps to create a new device type are also simple. On the following URL it is explained how to do that: https://resources.sigfox.com/document/create-a-new-device-type
Summary of the actions to be done by the user:
Go to the “Device type” tab.
Click on "New" button in the top right corner.
Fill in the device type information:.
Name of your device type.
Description of your device type.
Set the keep-alive value in minutes (optional).
Contract: Link your device type to an active BSS order.
Alert e-mail: If a callback fails, an email will be sent to the address below so that you can take action to fix the problem.
Configure the downlink callback mode.
Configure the display type, cf: Downlink callbacks.
Using the "Edit" button on the top right corner you can edit a device type.
Go to the “Device” menu and click on the device type of your device. A new menu will open and on the left side a "CALLBACKS" option is displayed, click on it.
A new screen is displayed, there you can create a new callback request, For that, click on the "New" button on the top right corner and now your can type the data for a new callback request:
Select "Custom callback", it is the first option on the options panel for a new kind of callback:
The main configuration panel will display your custom callback:
We need to understand this statements to clarify the values of the configuration creating the Sigfox custom callback for the Libelium Cloud Bridge service:
There are three different callback types.
You have a set of available variables for each type of callback.
These variables are replaced by their value when a callback is called.
When receiving a callback, the client system must return an HTTP 2xx code within 10 seconds.
If the client system fails to process the callback during this time, an automatic retry will be scheduled 1 minute later.
We will explain now the values chosen to properly create a Sigfox custom callback for sending data to the Libelium Cloud Bridge service:
We will set the type to "DATA" and "UPLINK". As we want to upload the information to a given URL, the Channel option must be "URL".
The URL pattern is the Libelium Cloud Bridge service endpoint for Sigfox callbacks, .https://hw.libelium.com/hw/sigfox
The request type is "POST". As we want to send data to a remote server, leave unchecked the "Send SNI" option.
The Libelium Cloud Bridge service uses an API Key as the method to identify and authenticate to the user and the sensor node. Including the authentication API Key in the custom callback created is done adding to the headers option an authorization field with the value "Bearer LIBELIUM_CLOUD_TOKEN" (without quotes). The LIBELIUM_CLOUD_TOKEN can be copied from the Libelium Cloud Bridge service backend as explained in the section of this guide.
The value for Content-type option must be application/json.
The body of the request will contain the data that will be sent to the Libelium Cloud Bridge service. It has to be short and properly formatted, JSON syntax will be used.
Data fields that will be used to upload the information are:
device (string): device identifier (in hexadecimal -- up to 8 characters \<=> 4 bytes)
data (string): the user data (in hexadecimal)
time (int): the event timestamp (in seconds since the Unix Epoch)
seqNumber (int): the sequence number of the message, if available
duplicate (bool):
"true" if the message is a duplicate one, meaning that the backend has already processed this message from a different base station.
"false" otherwise. To receive duplicate messages, you have to check the "send duplicate" box in the callback configuration page.
The Body field will be set with a JSON payload as the following one:
Click "Ok" to confirm changes and create the new callback.
The callback configuration should be as follows:
After confirming changes, the new callback entry is listed on the "Callbacks" section:
The callback entry may be edited anytime. For further information about callback function please check out this Sigfox documentation link: https://backend.sigfox.com/apidocs/callback.
On the device list, click on the "ID" field of your device and a new screen with a right menu will be shown. On the "Messages" option you can see a list of messages sent to the callback and you can watch if they arrived properly (green circle with up arrow) or they had some kind of problem:
If you click on the callback icon, you get full information about the callback request:
Loriot is a backend for LoRaWAN devices. It gathers information from many base stations and works as a data hub. We will configure the Loriot backend to send data to the Libelium Cloud Bridge service.
A valid Loriot account is needed to configure properly the backend. New Loriot accounts can be obtained at https://www.loriot.io/register.html.
You should register your device or gateway in Loriot before starting. This process is different and depends on the device you want to register, you can do this step on the “Gateways” section on the bottom left part of the web.
In the dashboard you can create a new application for your device, this is needed to send data to Libelium Cloud. Follow the on-screen steps to create an application.
Once you created your application, click on it to get the details and extended actions.
There is a “Controls” section on the top left menu where you can configure the data output to redirect the incoming data to another service. Click on "Data output" to configure the data forwarding. Then you can choose among many services to redirect your data; for using the Libelium Cloud Bridge service, select "HTTP Push":
Select "HTTP Push" to have access to its documentation.
The configuration for this callback service is straightforward, you just type the Libelium URL and the value for the authentication field, in this case is "Bearer LIBELIUM_CLOUD_TOKEN".
The Libelium Cloud Bridge service uses an API Key as the method to identify and authenticate to the user and the sensor node. Including the authentication API Key in the custom callback created is done adding to the headers option an authorization field with the value "Bearer LIBELIUM_CLOUD_TOKEN" (without quotes). The LIBELIUM_CLOUD_TOKEN can be copied from the Libelium Cloud Bridge service backend as explained in the section “API Keys” of this guide.
Target URL for POSTs: https://hw.libelium.com/hw/loriot.
Custom "Authorization" header value: Bearer LIBELIUM_CLOUD_TOKEN.
The HTTP Push configuration should be as follows:
Click on the button "Confirm change" to save your changes and the data will be forwarded to the Libelium Cloud Bridge service.
A JSON payload is not needed in this backend, the Loriot backend supplies a reliable JSON object that contains all information that Libelium Cloud Bridge service needs to manipulate the data.
The Actility backend is suitable for the user that has a good knowledge of IoT systems, because it is very flexible and full of useful features.
You will need an account to configure the Actility backend. If you do not have an account, get one on https://www.actility.com or contact your Sales agent.
The Actility service needs an Application Server and an Application Server Routing Profile (AS routing profile) to create a communication between Actility and the callback server.
First of all, create a new Application Server using the left side menu:
The first section allows you to create a new Application Server. The second section shows a list of all the Application Servers created. Click the "Add" button in the first section to create a new Application Server.
You must type a name and select the option "HTTP Application Server". Then click the "Create" button to continue:
The new window shows the name from the previous pop-up and many other new fields. Set the value "JSON" for the "Content Type" field.
The Libelium Cloud Bridge service adds another security layer to Actility cloud. It is mandatory to fulfil the “Uplink/downlink security" section for data integrity. Click on the "Activate" button and a new pop-up will appear:
In the new pop-up there are three fields: AS ID, LRC-AS Key and Max timestamp deviation, let's explain each one:
AS ID: It is a field to identify the user that is sending data, this information is supplied in the Actility Screen on the Libelium Cloud Bridge service.
LRC-AS key: A passphrase supplied by Actility Configuration on Libelium Services Cloud Manager.
Max timestamp deviation: Leave it empty.
AS ID and LRC-AS key are mandatory fields, these values can be copied from the Libelium Cloud Bridge service backend. If the fields are not properly filled the data will not arrive to the Libelium Cloud Bridge service.
Now it is time to add a new route to send the data:
Click on the button "Add" from "Add a route" section, and a new window will be displayed. Then set the values for these fields:
Source ports: *
Routing strategy: Sequential
On the above destination box, click the "Add" button to type a new URL to callback the data:
A pop-up appears, type the Libelium cloud URL on the text box: https://hw.libelium.com/hw/actilityClick.
Click the "Add" button to save the changes.
The "Route" section should be as follows:
In the main menu on the left side click on “AS routing profiles” section.
All existing AS routing profiles are listed in the “AS routing profiles” section. Click the "Create" button shown in the irst section to create a new AS routing profile. A new AS routing profile gives the capability to add new AS routing profiles.
You must supply a name in the new window displayed. After that, click on "Create" to continue the process.
Uncheck the option "Is default" and click on "Add" on the route section:
A new pop-up will appear with two fields. "Type" is the kind of application for our destination, in this case "Local application server". Then, in the "Destination" field, all application servers created will be loaded in the drop-down. The application server previously created must be selected.
Navigate back to the AS routing profile form and click "Save" to create it.
At this point the user can add as many devices as they need by clicking on the "Devices" option on the left menu. Then, in the new form loaded on the right frame, create a new device by hitting on the "Create" button.
A new form will be displayed in a pop-up to fulfil the device information:
After this configuration you are ready to send data to Libelium Cloud Bridge service. It is not necessary to create a JSON payload because Actility creates a JSON structure that the Libelium Cloud Bridge service can process.
The user can install the application from the www.libelium.com site. It does not require a big knowledge, just create a new folder into the MultiTech base station and download the file into the MultiTech base station, unzip the downloaded file. It is important to unzip all the files in the same folder.
The Libelium application needs some parameter configuration, The user should know that some parameters are mandatory to execute the application properly. The configuration parameters are:
log: This parameter can have the value 0 or 1. This parameter enables (value 1) or disables (value 0) the log file. If it is disabled the user just has an on-screen log. Default value is 0. This is a mandatory parameter to configure Libelium application.
host: MutiTech Base Station host. As the Libelium application is installed onto a base station, the value will be localhost, but the user can also pull the data from other base station. Default value is localhost. This is a mandatory parameter to configure Libelium Application.
username: MutiTech Base Station username to login into the web interface. Default value is admin. This is a mandatory parameter to configure Libelium Application.
password: MutiTech Base Station password to login into the web interface. Default value is admin. This is a mandatory parameter to configure Libelium Application.
appeui: The user can register a new appeui using the MultiTech Base Station web interface to get only the frames from the given appeui. Default value is empty. This is an optional parameter to configure Libelium Application.
libelium_cloud_token: This is a token given by the Libelium Cloud Bridge service., The user must create an account in the Libelium Cloud Bridge service to get this token. There is no default value as the user must get the token and set it in the configuration file. This is a mandatory parameter to configure Libelium Application.
All these parameters should be in a file called config.ini. There is a file called config.in.template where the user can rename to config.ini and fulfil the configuration parameters.
This is a sample of configuration for a config.ini file:
The Libelium application can be executed periodically as a cron job. To install a new cron job with the Libelium application you can use the script install_cloud_meshlium_multitech.sh, which installs a new line on your cron application and run the main Libelium application every 5 minutes.
Grant execution permission and execute the script with the following commands:
Do not forget to restart your cron application to apply the changes with the following command:
In this chapter the user will learn how to run the Libelium application for MultiTech Base Stations and how the application works.
Execute the application. Once you have configured the application you must give execution permission to the main application:
Before running the application, it is very important to set the MultiTech Base Station as NETWORK SERVER. You can change this setting on your MultiTech Base Station web interface on “LoRaWAN” “Network Settings”.
Now the user is ready to execute the application:
The application shows an on-screen log with all operations. The application performs these steps in the MultiTech Base Station:
The application logs in the base station.
The application gets a login token given by the base station.
The application queries the frames provided by the base stations.
The application processes all the frames to upload them to the Libelium Cloud Bridge service and split the frame to reduce request time between the base station and the Libelium Cloud Bridge service.
The application starts uploading frames to Libelium Cloud Bridge service.
The application logs out from the base station and the application ends execution.
This is an on-screen sample log that shows all the processes from the beginning to the end of the execution where the data is uploaded to Libelium Cloud Bridge service:
You can run the Libelium application every time you need to upload new frames to the Libelium Cloud Bridge service. All this information is summarized on the README file.
First of all, to avoid network connection or connectivity problems between the MutiTech Base Station and the Libelium Cloud Bridge service, make sure that your internet connection is working.
If you experience some low performance on your Base Station using the Libelium application, make sure that it does not have a stressful application running that drains the CPU usage.
If the MultiTech Base Station is not able to get new data frames, make sure that your devices are sending new data and the configuration of the LoRaWAN Network Settings on the MultiTech Base Station is set as NETWORK SERVER.
If you obtain a misconfiguration error, please review your configuration setting on config.ini and fill the missing parameters.
If your obtain a bad response from the Libelium Cloud Bridge service once you have upload your new frames, please review your configuration, specially your Libelium Cloud Token.
If you experience a lack of connection between the MutiTech Base Station and the Libelium Cloud Bridge service and your network settings are correct, please write a post at the Libelium Forum and we will help you to solve your issue: https://www.libelium.com/forum.
Data is not stored in the Libelium Cloud Bridge service, in the process of syncing data with the cloud services only a limited buffer is needed.
The synchronization process is also optimized to group values before sending them to the cloud services and to run parallelized when needed. The buffering process is design to work properly with a huge amount of sensor nodes sending data.
Before programming any single sensor node to send data to the Libelium Cloud Bridge service, it is recommended to configure at least one cloud service to synchronize data to. If sensor nodes are sending data to the Libelium Cloud Bridge service but there is not any cloud service properly configured, the buffer will get full and the sensor nodes will start receiving errors when trying to send data.
It is possible to check the current percentage of the buffer usage in the Libelium Cloud Service license panel.
The Libelium Cloud Bridge service implements connectors for the following cloud services: Alibaba Cloud, AWS IoT, Cumulocity, IBM Cloud, Microsoft Azure Event Hubs, Microsoft Azure IoT Hubs, MQTT, SAP Hana and Telefonica IoT Cloud.
Several instances of any of them may be configured. Data received in the Libelium Cloud Bridge service will be buffered waiting to be synchronized with all the active connectors instances. Only values that can be synchronized with all the active connector instances will be cleared from the buffer.
A misconfiguration problem in any single connector instance may lead to fill the buffer.
Data is sent to the cloud services implementing the HTTPS REST API calls and MQTT protocols.
The Libelium Cloud Bridge service measures the synchronized values with the cloud services. The current percentage of the synchronization limit of the active license may be checked in the Libelium Cloud Service license panel.
There are several encryption levels used when communicating the sensor nodes with the Libelium Cloud Bridge service using TCP/IP protocol:
Application level encryption: AES256 (symmetric key known by the sensor node and the final cloud service).
Application level encryption: AES128 (secret symmetric key stored in the sensor node and the Libelium Cloud Bridge service. This encryption key is protected in the sensor node so it cannot be read "under any circumstances".
HTTPS encryption: Node models including a communication module which is able to send to the Internet (WiFi or 4G) implement HTTPS with the Libelium Cloud Bridge service (SSL/TLS securized).
