CloudLocate premium extension

Introduction

If you are using one of u-blox IoT Communication-as-a-Service solution like MQTT Anywhere, MQTT Now, MQTT Here or MQTT Flex, the most efficient way to leverage CloudLocate is using the premium extension.

With Data Flow Manager you can build your own logic or manipulate data, by creating a flow made up by multiple nodes (premium extension), each of them implementing a basic functionality

The Flow Editor provides a simple drag and drop interface where you can quickly build powerful flows to work with payloads published by your Things, and get that data out to wherever you need it.

CloudLocate flow

To create your first flow, just select Flows from the sidebar and click create flow on the top right corner of the screen to create a new flow. Assign it a name and then create your flow adding the CloudLocate node and any other other nodes you need. You'll find details of the input and output parameters for each node in the info tab on the right-hand side of the editor.

The following picture shows an example of how to build a flow that receives a measurement, calculates the position and sends the result by email.

The logic behind a flow is that:

all devices (Things) send the data to the platform on a given topic using one of the above mentioned Communication solutions
the flow subscribe to this given topic using the thingstream subscribe node. All data that comes on this topic, triggers the execution of the flow. Of course the device can publish data also on other topics not connected to that flow
you can connect multiple nodes, with a simple drag and drop, creating complex functions and logic, manipulating data before sending it to your cloud application, and using multiple channels (SMS, mail, MQTT, https, ftp etc) to send out data.

Simulate a device

After that you have created the above flow, as next step you need to simulate your device to be able to inject/publish data in the flow and trigger the execution. The easiest way to do that is to create an IP Thing (you can also create more than one to simulate a fleet):

Select the Things item on the left sidebar
Click on Add Thing and then on 'Add new IP Thing'; give it a name
Select a plan. For test purpose you can select the developer plan

In the credential section of each IP Thing you can find the MQTT credentials and endpoint. Use these information to configure an MQTT client in your laptop o in your real device.

In the next steps you will get also the information about the topic to be used to publish data

In the following sections you can get more information about each node used in the sample flow in the picture

Thingstream inject node

This node is used to test the flow by injecting sample data directly to the flow from the user interface (just filling the proper fields in the configuration panel of the node). This is very helpful as a very first step, especially if you do not have an MQTT client in your PC/device

You can position this node anywhere in your flow and use it to test without the need to deploy the flow.

To configure this node, double-click on it:

In the search field type the name of the IP thing that you have just created before to filter the list of the Things available in the box below and select it
specify the MQTT topic where your message would be published to . This is a mandatory field for this node, but for the on going test you can specify any topic/string, like 'CloudLocate/mytestopic'
select JSON as Payload Format
give a JSON payload of the measurement (you can simply copy and paste the sample measurement given here below)
Click "Save Flow" to save your changes

To run this node, simply click on the filled square on the left-hand side of the node. You'll be able to review any debug output in the debug tab on the right-hand side of the editor.

Before running the flow, you will be asked to save it (the Save button is on the top right of the editor window).

{

"body": "tWICFMQBAQAAAHjedx2oYxweyKd3HXjedx143ncdAAD//wAAAAAAABEuAAAAAAAAAAABeykB/wsAAJwMAAAkA40CZisZAAAAAAABiCgBCAwAAKUMAAAdAq4BmO8QAAAAAAAAGyIBP8T//zPB///9AKECP+8HAAAFAAAAHCUB9wsAAJQMAADuArEAQncXAAAAAAACBCgB5+P//3ji//9qA5gCB1wbAAAAAAAAEScBKEUAAK9IAABhAGgAlAkDAAAAAAAADiYBc/b///b1//8uAvoAU3YRAAAAAAACJC4BRgIAAGQCAABUCkQDObsSAAIAAAAACiMBGc7//47L//9lALEALSoDAAAAAAACBSoCakAAALNDAAAHCF4B0EoAAAIAAAACCS4BWRUAAG8WAABqCaMAIGQLAAIAAAAAIC0Bv+7//97t//8LAmoB7F4QAAAAAAAAFjABPRgAAHoZAAAoABMCeEQBAAAAAAAAFS4BwQYAABoHAACOAy4AfHccAAAAAAAACCwB7dD//4bO//9JAG0DcE8CAAAAAAAAAy0BFzoAAA49AABNAiMC5HASAAAAAAAAATABWB0AANceAAAKAUgDplgIAAAAAABDOA==",

"headers": {"UTCDateTime": "2021-05-28T17:19:37" }

}

Others sample measurements are available in this section

Thingstream subscribe node

Instead of using the 'thingstream inject' node, in a real use case you want to send the measurement from your devices. This node acts as an input to the flow.

This subscription represents the MQTT topic(s) that will trigger the flow when a message from a device is pushed on that topic. In other wards, all the devices shall publish the raw measurements into this topic.

The topic selection happens during the flow deployment phase: you will be asked to create a subscription for this node. You can change the topic at any time by clicking on Manage button

CloudLocate node

This node calls the CloudLocate service to calculate a position based on incoming measurement data. The result becomes an input to the next node in the flow.

The node accepts the input in two format:

a pure binary payload:
- for UBX-RXM-MEAS50/MEAS20 remember to remove the header and the checksum injecting only the payload
- for UBX-RXM-MEASX, send the entire GNSS message including the header and the checksum as it comes from GNSS
the JSON format with or without date and time field, depending if you are sending fresh data or measurements generated more than 60 seconds ago
- the body shall contain the Base64 encoded measurements. As above, in case of UBX-RXM-MEAS50/MEAS20, strip-out the header and the checksum

Set email recipient (function) node

This JavaScript function node can be used to set an email address to be used by the email node by using the following code

Set the email "to" address to the

domain owners email address.

msg.to = msg.domainOwner.email;

return msg;

You can also specify any email address if you want to send an email to a recipient other than the domain owner, like:

msg.to ="me@mydomain.com";

return msg;

You need to add the above code in the function node by double-clicking on the node to open the configuration options and click "Done" to save your changes.

Msg.payload (debug) node

This node is used for debugging purposes. It will output debug data to the "debug" tab on the right-hand side, so that you can immediately see if the position has been calculated

Email payload node

This node will send an email with the estimated position. You don't need to configure the email recipient details directly in the node as they are set in the previous JavaScript function node.

Deploy and test the flow

When you have finished setting up and testing your flow with the thingstream inject node, you can deploy the flow to start using it with real devices. For detailed information about deploying Flows, have a look at the Flows documentation. The steps are listed here in summary:

Click "Deploy" at top right corner of the screen
In the panel that appears, click "Edit" in the "Subscription" option to configure it.
- Enter the topic that your device will publish to. If the topic already exists it will appear in the search results, otherwise just click Add and create a new one, like for example 'Mytest/MyTopic'.
Click "Done"
Click "Deploy" to deploy the flow.
You'll see a warning that the flow contains premium extension nodes with a link to the pricing page for details of the costs.
If you're fine, click "Deploy".

You can see the topic (i.e. 'Mytest/MyTopic') that the flow is subscribed to at the top of the editor screen. To change it, use the manage button at the top-right corner and repeat the procedure

Test the CloudLocate flow

You are now almost ready to test the flow using your real device or a simulated device.

Configure the MQTT client on your laptop or on your device to publish data in the topic selected in the previous paragraph (i.e. Mytest/MyTopic.
generate the GNSS raw measurement as explained in the Getting started guide (or use the above one)
Publish the measurement in the topic and verify that you get the response.

Note: the position estimation is done real time, therefore the time to get a response depends on: i) the connectivity between the device and the CloudLocate service endpoint and ii) the way you decide to send out the estimated position (SMS, mail, MQTT) to your cloud application.

Position in the cloud

If you want to get the position directly to your cloud application, the easier way to do it is to:

connect the CloudLocate node to a Thingstream publish node
Configure the publish node with a topic where to publish the position:
- create a new topic in the Topic section in the side bar and put it here in the proper field (i.e. MyCloud/MyTopic)
Create a new IP Thing and configure the MQTT client in the server application with the credential and the endpoint specified in the credential tab.
Set-up the MQTT client to subscribe to that topic (that is MyCloud/MyTopic)

In this section