CloudLocate getting started

Introduction

CloudLocate enables positioning in the cloud to extend the life of energy-constrained IoT applications, with up to 10X energy savings over a standalone GNSS approach. The service uses IoT device measurements to calculate a location and deliver it to the enterprise. CloudLocate is ideally suited for IoT asset tracking applications that require large power autonomy, a few position updates per day, reasonable position accuracy, and for which location is needed in the cloud as opposed to on the device itself.

Take advantage of:

  • Up to 10X energy savings over stand-alone GNSS approach

  • Expanded market reach by building enterprise solutions that leverage CloudLocate

  • Guaranteed global availability and quality of service

  • An end-to-end solution that works with any connectivity technology

  • Increased device lifetime in the field and lower operational burdens

u-blox service platform sign-up

u-blox Thingstream is a service delivery platform providing a management console that you can use to enable and manage the entire suite of u-blox services , including IoT Location-as-a-Services and your Location Things (the logical representation of your location device in the Thingstream platform).

Sign-up is free, quick and easy. Just go to the management console and register with your company information. If you already have a Thingstream domain for IoT Communication-as-a-Service (MQTT Anywhere, MQTT Here or MQTT Now), or for IoT Security-as-a-Service you do not need to register again.

Still need help?

Getting MEASX messages using u-center

Getting real-time MEASX messages from GNSS

If you need more help or have any questions, please send an email to support@thingstream.io.

Service configuration

There are two options to activate and use CloudLocate:

  1. Create a Location Thing for each of your devices. This option is applicable if you do not plan to combine the use CloudLocate with any of the IoT Communication-as-a-Service products (MQTT Anywhere, MQTT Here or MQTT Now). It allows you to use the service in standalone mode where the device simply uses MQTT protocol to publish the measurement data to the CloudLocate service which in turn calculates a position and publishes the result to another MQTT topic.

  2. Use the CloudLocate node as part of a Flow. The Thingstream Data Flow Manager provides simple and effective manipulation of any data that are published to the platform using one of the u-blox IoT Communication-as-a-Service products. For more information about Flows, see the Data Flow Manager documentation.

    • CloudLocate node can be used also to access in Service to Service mode, where you send the the GNSS measurements to your application platform that will request the position to Cloudlocate by sending the measurement. You can find more information in the relevant links at the end of this guide, that shall consider a prerequisite for that guides

Location Thing mode

Service configuration

To use the service using the Location Thing, select Location Services from the side bar of the Thingstream console and click on Add Location Thing in the top right of the screen.

Then select the Add CloudLocate Thing, and give it a name.

Once you have created your CloudLocate Thing, you'll need to select a plan to link to it. To get started, use the Developer plan which offers 100 free requests per device per month or purchase a plan from the selection available. You can find more information about the CloudLocate plans on our pricing page.

To configure the MQTT client in the device to use with the CloudLocate service you need the credential information available in the Credentials tab of the Thing Details window.

Details of the MQTT topics used by the service can be found on the Permissions tab:

  • the MQTT topic where the device shall publish measurements: CloudLocate/GNSS/request

  • the MQTT topic to which the CloudLocate service will publish the calculated position: CloudLocate/{device}/GNSS/response

    • this topic shall be used by your application to retrieve the position information

Generate the measurement

At the end of this guide you can find some indication on how to get real-time measurements as in a real use case both using u-center and without using it by simulating a real device application. To speed up your initial testing we provide in this section a valid sample measurements, so that you can do an very fast testing of the service even without any real GNSS hardware

You can use the MQTT client code in the next section (written in Python) to send measurement data and get the location response. The script:

  • publishes GNSS sample measurement into the specified MQTT topic CloudLocate/GNSS/request

  • subscribes to topic CloudLocate/{device}/GNSS/response to receive the calculated position.

The CloudLocate service endpoint expects to receive a JSON formatted payload like the one below:

{

"body":"Base64 encoded measurement (String)",

"headers":{"UTCDateTime":"yyyy-mm-ddThh:mm:ss"}

}

where the measurement is the UBX-RXM-MEASX message sent in output from the GNSS and the "UTCDateTime" is required only if you cannot send the measurements within 1 min from when it has been generated in the GNSS.

Note: in the testing phase when using your PC to run the script, we suggest to always append UCTDateTime

To encode the measurement in Base64:

  • if you are using u-center to obtain the UBX-RXM-MEASX, the output is a binary file with .ubx extension. To convert the file to Base64, you can use to this online converter.

  • If you are using the sample measurement provided below in this guide, the body field contains the GNSS measurement (UBX-RXM-MEASX message) already Base64 encoded

  • if you are getting the UBX-RXM-MEASX message directly from the GNSS receiver, you have to encode in Base64. For testing phase, you can simply save it to a file and use the above mentioned converter

Note: When using the sample python code below you don't need to encode the measurement in base64 as script automatically does that for you.

This is an example of a payload in base64 encoded format.

{

"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" }

}

The escaped version for the above payload is (using for example this free tool)

{\r\n\"body\": \"tWICFMQBAQAAAHjedx2oYxweyKd3HXjedx143ncdAAD\/\/wAAAAAAABEuAAAAAAAAAAABeykB\/wsAAJwMAAAkA40CZisZAAAAAAABiCgBCAwAAKUMAAAdAq4BmO8QAAAAAAAAGyIBP8T\/\/zPB\/\/\/9AKECP+8HAAAFAAAAHCUB9wsAAJQMAADuArEAQncXAAAAAAACBCgB5+P\/\/3ji\/\/9qA5gCB1wbAAAAAAAAEScBKEUAAK9IAABhAGgAlAkDAAAAAAAADiYBc\/b\/\/\/b1\/\/8uAvoAU3YRAAAAAAACJC4BRgIAAGQCAABUCkQDObsSAAIAAAAACiMBGc7\/\/47L\/\/9lALEALSoDAAAAAAACBSoCakAAALNDAAAHCF4B0EoAAAIAAAACCS4BWRUAAG8WAABqCaMAIGQLAAIAAAAAIC0Bv+7\/\/97t\/\/8LAmoB7F4QAAAAAAAAFjABPRgAAHoZAAAoABMCeEQBAAAAAAAAFS4BwQYAABoHAACOAy4AfHccAAAAAAAACCwB7dD\/\/4bO\/\/9JAG0DcE8CAAAAAAAAAy0BFzoAAA49AABNAiMC5HASAAAAAAAAATABWB0AANceAAAKAUgDplgIAAAAAABDOA==\",\r\n\"headers\": {\"UTCDateTime\": \"2021-05-28T17:19:37\" }\r\n}

This sample measure corresponds to this location response

{

"Lat":47.2852123,

"Lon":8.5652996,

"Alt":549.473,

"Acc":13.393,

"MeasxTime":"2021-05-28T17:19:37",

"Epochs":1

}

Note: the accuracy of 13 m has been achieved collecting data for just one epoch, as clarified in the response. Usually a better accuracy can be achieved collecting a measurement after 3-4 epochs.

Script configuration

To test the service you need before to configure below script as follows:

  1. Set Hostname, DeviceID, username and password for the MQTT client; you can retrieve these information in the Credential tab in the Thing details section of the Location Thing created previously

  2. The topic CloudLocate/GNSS/request is already set in the MQTT_TOPIC variable. This is the topic where the script publish the measurement. It is the default one and cannot be changed.

  3. Set the subscription topic in MQTT_SUB_TOPIC variable, where the location result will be published by the CloudLocate node. Also in this case the topic path is fixed (CloudLocate/{device}/GNSS/response ). You need only to replace the {device} variable with the device ID that you have configured at step 1 removing the brackets

  4. Update UBX_File variable with your measurement file name and your measurement time in MEASUREMENT_TIME variable.

  5. run the script; the calculated position should be now visible in output.

If you do not know how to setup Python and run the script, refer to the section at the end of the guide

Note: to make it simple, in this initial example, we are using a unique script to simulate at the same time both the device that publishes the measurement and your application server that gets the result by subscribing to the response topic. In a real scenario you will have:

  • the device MQTT client that publishes the payload using the credential of the Location Thing.

  • The location response then can be retrieved by the MQTT client of your application platform. More information are provided in the next section.


import paho.mqtt.client as mqtt

import time

import base64


Hostname = "mqtt.thingstream.io"

DeviceID = ""

Username = ""

Password = ""



UBX_File = "<YOUR_FILE_NAME>"

# PATH to your ubx file (e.g. measurement.ubx) if in same directory just update

# name otherwise provide full path

MEASUREMENT_TIME = "<TIME_OF_YOUR_MEASUREMENT>" #e.g. 2021-05-28T17:19:37

BASE64_ENC_PAYLOAD = ""

with open(UBX_File,'rb') as f:

BASE64_ENC_PAYLOAD = base64.b64encode(f.read()).decode()


#JSON Payload

MQTT_MSG = f"{{\"body\": \"{BASE64_ENC_PAYLOAD}\",\"headers\": {{\"UTCDateTime\": \"{MEASUREMENT_TIME}\" }}}}"

MQTT_PUB_TOPIC = "CloudLocate/GNSS/request"

MQTT_SUB_TOPIC = ""

#The topic is CloudLocate/{DeviceID}/GNSS/response " #It is mandatory to

# specify #your device ID without brackets.


def message_handler(client, userdata, message):

print("\n\nReceived message\n" + str(message.payload.decode("utf-8")) + "\n" + message.topic + "\nQoS: " + str(message.qos))

client.disconnect()



client = mqtt.Client(DeviceID)

client.username_pw_set(username = Username, password = Password)

client.connect(Hostname)

client.on_message = message_handler

if MQTT_SUB_TOPIC:

client.subscribe(MQTT_SUB_TOPIC)



client.publish(MQTT_PUB_TOPIC, MQTT_MSG)

print("message published")

client.loop_forever()

Get the location from your application server

In a real use case you would like to publish the measurement from your devices and get the response back from your application server. You can do as follows:

  • use the previous script as it is without any change to simulate your device (location will still be published also there. If you do not want it, you can comment the lines related to the subscription )

  • duplicate the previous code and save it in a file with a different name

  • Comment the lines containing

    • MQTT_MSG and MQTT_TOPIC

    • the while loop

  • increase the time.sleep to 60 secs

  • the new script looks like this one


import paho.mqtt.client as mqtt

import time

DeviceID = ""

Username = ""

Password = ""



# GNSS Sample measurement

#MQTT_MSG = "" #Escaped payload

#MQTT_TOPIC = "CloudLocate/GNSS/request"

MQTT_SUB_TOPIC = "CloudLocate/+/GNSS/response"

#Replacing the {DeviceID} with a + in the subscription topic you can get the

#the output for all devices


def message_handler(client, userdata, message):

print("\n\nReceived message\n" + str(message.payload.decode("utf-8")) + "\n" + message.topic + "\nQoS: " + str(message.qos))


client = mqtt.Client(DeviceID)

client.username_pw_set(username = Username, password = Password)

client.connect(Hostname)

client.on_message = message_handler

msg_counter = 0

if MQTT_SUB_TOPIC:

client.subscribe(MQTT_SUB_TOPIC)


client.loop_start()

#while msg_counter < 2:

# msg_counter += 1

# client.publish(MQTT_TOPIC, MQTT_MSG)

# print("msg #{0} published".format(msg_counter))

time.sleep(60)

client.loop_stop()

Finally, before running the script you shall:

  • create an IP Thing in the Thingstream platform

    • 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

  • configure the credentials in the new script using this IP Things credentials that can be retrieved in the Credential tab of the IP Thing details section (as you did before for the Location thing)

  • Save the file

Now you should have:

  1. the old script configured with the Location Thing credentials and the measurement, to simulate the device. If you want to simulate multiple devices, just create a new Location Thing, duplicate the old script and configure it with the credential of the new Location Thing

  2. the new script configured with the IP thing credential used to simulate your application platform. This code will receive the position for all the Location things.

Now run the new server side script and then the client side scripts (one or more, depending on how many device you are simulating). You should receive in output one measurement for each device that you are simulating

The script print out also the full topic path that contains the device id, so that you can recognize to which device belongs the calculated position

CloudLocate node (flow)

The second option for using the service is via the CloudLocate node in the Data Flow Manager accessible from the Flows option on the sidebar of the Thingstream console. 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.

You need this approach if you are already using one of the MQTT Anywhere, MQTT Now, MQTT Here plans or you need a Service to Service approach. For this latest use case, we suggest to read this section before and then move to the dedicated guides for the Service to Service access.

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.

Note: before you can test the flow, or deploy it, you need to create a an "IP Thing". You can use the one created before or repeat this procedure to create a new one.

  • 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

Now drag and drop the nodes that you see in the picture to create your flow and connect them as shown. You'll find details of how to configure each node below:


thingstream inject node (optional)

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). You can position this node anywhere in your flow and use it to test without the need to deploy the flow. Once done:

To configure this node, double-clickn it:

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

  2. specify the MQTT topic you 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'

  3. select JSON as Payload Format

  4. give a JSON payload of the measurement (you can simply copy and paste the sample measurement given below)

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

You'll need to save your flow changes before you can run it (the Save button is on the top right of the editor window).

thingstream subscribe node (no configuration required)

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

When you deploy the flow, you will be asked to create a subscription for it. This subscription represents the MQTT topic(s) that will trigger the flow when a message arrives.

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.

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 position data. 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 the Flow

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

  1. Click "Deploy" at top right corner of the screen

  2. In the panel that appears, click "Edit" in the "Subscription" option to configure it.

    • Enter the topic name that your device will publish to. If the topic already exists (because you have created it for other purposes using the Topic section on the left side menu) it will appear in the search results, otherwise just click Add and create a new one, like for example 'Mytest/MyTopic'.

  3. Click "Done"

  4. Click "Deploy" to deploy the flow.

  5. You'll see a warning that the flow contains premium extension nodes with a link to the pricing page for details of the costs.

  6. If you're happy with everything, click "Deploy".

You can see the name of the topic (i.e. 'Mytest/MyTopic') that the flow is subscribed to at the top of the editor screen.

Test the CloudLocate flow

You can now test the flow using the first Python script (commenting few lines) from the previous section to publish the measurement data. Remember to:

  • add the credentials of the IP Thing in the script and to set MQTT_MSG to the sample measurement that you wish to send. You can again use the sample measurement above

    • the credentials are available in the Credentials tab of the Thing Details page in the console.

  • Update UBX_File variable with your measurement file name and your measurement time in MEASUREMENT_TIME variable.

  • Put the topic (i.e. Mytest/MyTopic) that you have assigned to the flow in the MQTT_TOPIC variable

You should have already saved and deployed the flow in the steps above. Now you can run the script and see the output both in the debug node and in the email message.

Here below the script to publish the measurement, in which we have commented the code used to receive back the position via MQTT. Remember that the position will be sent by email to the specified address.


import paho.mqtt.client as mqtt

import time

import base64


Hostname = "mqtt.thingstream.io"

DeviceID = ""

Username = ""

Password = ""



UBX_File = "<YOUR_FILE_NAME>" # PATH to your ubx file (e.g. measurement.ubx) if in same directory just update name otherwise provide full path

MEASUREMENT_TIME = "<TIME_OF_YOUR_MEASUREMENT>" #e.g. 2021-05-28T17:19:37

BASE64_ENC_PAYLOAD = ""

with open(UBX_File,'rb') as f:

BASE64_ENC_PAYLOAD = base64.b64encode(f.read()).decode()


#JSON Payload

MQTT_MSG = f"{{\"body\": \"{BASE64_ENC_PAYLOAD}\",\"headers\": {{\"UTCDateTime\": \"{MEASUREMENT_TIME}\" }}}}"

MQTT_PUB_TOPIC = "" #Mytest/MyTopic

MQTT_SUB_TOPIC = ""


def message_handler(client, userdata, message):

print("\n\nReceived message\n" + str(message.payload.decode("utf-8")) + "\n" + message.topic + "\nQoS: " + str(message.qos))

client.disconnect()



client = mqtt.Client(DeviceID)

client.username_pw_set(username = Username, password = Password)

client.connect(Hostname)

client.on_message = message_handler

#if MQTT_SUB_TOPIC:

# client.subscribe(MQTT_SUB_TOPIC)



client.publish(MQTT_PUB_TOPIC, MQTT_MSG)

print("message published")

#client.loop_forever()

Prerequisite to use the Python script

To use the script above you need Python 3.x installed in your PC

  • Download the latest version of Python 3.x from this website and install it.

  • Install paho-mqtt module using command line pip install paho-mqtt

  • save the script as CLoudLocate.py and launch it (when requested in the guide) using the command line python CloudLocate.py (be sure to be in the directory where CloudLocate.py file is located, otherwise add the full path)


Service to Service access

In several scenarios, it can be useful to send the measurement to your application server that will be in charge to send it to Thingstream platform and get back the position. We provide two ways for a Service to Service access

This solutions are an enhancement of what we have just shown to you with the Flow setup. It's important to note that for this solution you will be charged accordingly to the CloudLocate Premium extension price available in the Pricing in the the Premium extension section

Getting real-time measurements

In order to replicate a real use case you need to get real-time measurements from GNSS. The following guides, shows you how to get a MEASX message using u-center (the u-blox evaluatin software for u-blox GNSS) and without u-center replicating a real scenario with a Pyton script ready to use

Supported hardware

To evaluate the service, you can use any of the u-blox GNSS modules that support RXM-MEASX message (i.e. M8, M9 and M10). You have at least two option

  • If you are planning to use your own cellular modem or the RXM-MEASX message is transferred over a non-celllular interface, the simplest way is to purchase one of the following kits: EVK-M8, EVK-M9 or EVK-M10 from the u-blox product selector

  • If you want to use a u-blox cellular modem with intergated GNSS you can purchase an EVK-R510M8S.