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. 

Benefits

The service provides several benefits:

• battery drain minimization: typically the GNSS consumes from 25% to 50% of the device battery. With CloudLocate the GNSS is switched on for few second (1 to 10) and therefore it consumes significantly less power than a standard approach where the GNSS takes at least 30 seconds to fix a position.

• data consumption minimization: the device sends to the cloud only the GNSS raw data sent to cloud  (from 12 bytes to 50 bytes). As explained in the next point there is no need to download form server any additional data.

• no need of assistance: the GNSS does not need any type of assistance data (ephemeris, almanac) therefore it's the best solution for high latency/low bandwidth  networks (i.e. LoRa, Satellite connectivity, NB-IoT) where downloading assistance is definitely not an option.

• latency reduction: the estimated position reaches your cloud application immediately thanks to the Cloud-to Cloud-connection

• fast prototyping: through very few simple configurations you are ready for the field tests

• scalability: once you move to production, you do not need to worry about additional complexity. Device configuration remains the same for all the devices

• secure: CloudLocate use  a per-device authentication; optionally you can decide to protect the transmitted raw data with additional TLS protection

Step by step guide

CloudLocate configuration needs 3 simple steps:

1. Configure the u-blox M10 GNSS

2. Configure the service in u-blox Thingstream service delivery platform

3. Generate the raw measurement in the GNSS and obtain the estimated position in the cloud service

Configure the M10 GNSS

For the complete GNSS configuration you can refer to the guide M10 firmware 5.10 interface description, independently from the form factor (section UBX-CFG-VALSET).  Here below you can find the list of the most relevant configurations:

1. Enable the GPS constellation only and disable the others. 

GPS Enable: b562068a0900000100001f00311001fb80

Galileo Disable: b562068a0900000100002100311000fc89

BDS Disable: b562068a0900000100002200311000fd8e

Glonass Disable: b562068a0900000100002500311000009d

2. Enable the desired raw measurement, (only one) according to your design. If your network support a 50 byte payload, enable the MEAS50 raw measurement that can deliver the best performance. 

UBX-RXM-MEAS50: b562068a09000001000049069120019baa

UBX-RXM-MEAS20: b562068a09000001000044069120019691

UBX-RXM-MEASC12: b562068a0900000100003f069120019178

UBX-RXM-MEASD12: b562068a0900000100003a069120018c5f

UBX-RXM-MEASX: b562068a09000001000005029120015346

By doing this configuration, the GNSS starts sending in output the selected message (2Hz rate) that will be used by the service to estimate the position.

Notes:

•  in case you want to use the 12 bytes raw measurement, you shall enable two messages (UBX-RXM-MEASC12 and UBX-RXM-MEASD12), each of them 12 bytes long

• If you want to further minimize the transmitted data you can use only UBX-RXM-MEASC12 raw measurement under the condition that you can provide a corse position in advance with 100 Km of accuracy. Contact the support for more information.

• To use MEASX raw measurement, you need to implement a filtering logic in the host processor to validate the quality of the satellite signals (this is done internally in the GNSS for the other measurements type). In such case you can refer to the guide for M8/M9 GNSS that only support MEASX measurement type.

In case you need to disable the raw measurement, you can use the following UBX configuration message

UBX-RXM-MEAS50: b562068a09000001000049069120009aa9

UBX-RXM-MEAS20: b562068a09000001000044069120009590

UBX-RXM-MEASX: b562068a09000001000005029120005245

UBX-RXM-MEASC12: b562068a0900000100003f069120009077

UBX-RXM-MEASD12: b562068a0900000100003a069120008b5e

Note: the message configurations will only be saved in RAM. To store it in flash, refer to section UBX-CFG-VALSET 

Configure the Thingstream platform

Thingstream is the u-blox service delivery platform just described above in this guide. 

1. Sign-in/Sign-up in the platform

2. Create a Location Thing for each of your device, that is the logical representation of your device in the platform:

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

   • assign to it a price plan.  To get started, use the Developer plan which offers 100 free requests per month or purchase a plan from the selection available.  You can find more information about the CloudLocate plans on our pricing page.

3. Get the MQTT credentials and the list of topic to configure the MQTT client in the device.  as explained in the following section

Note: when moving to production you can automate steps 2 and 3 using the Zero Touch Provisioning feature.

Test the service

Just need few additional steps to test the service.

1. Configure the MQTT client in the device with the credential and the endpoint that you have retrieved in the previous section. 

2. Configure the MQTT client in the device to publish data in the CloudLocate/GNSS/request topic

3. Send the UBX-CFG-RST  command to simulate a GNSS cold start

UBX-CFG-RST: b56206040400ffff01000d5f 

4. Capture the selected raw measurements (UBX-RXM-MEAS50/MEAS20/MEAS12) sent in output by the GNSS and publish it in the CloudLocate/GNSS/request topic. In normal signal conditions, GNSS takes around 3 seconds to generate the first measurement, and then it generate a new measurement every 500 milliseconds. You can decide to send the first measurement or wait more time and send one of the following message

Note: the just generated raw measurement shall be sent to the service within 60 seconds. If you need to store it and send to service in a later time you can leverage the not-real time option described at the end of this guide.

Note: Before sending the UBX-RXM-MEAS* message to the server, the host must remove the UBX header (8 bytes) from the message leaving just the 12-, 20- or 50-bytes payload. Also the checksum shall be removed

5. To get the the estimated position, the device shall subscribe to the response topic that is reported in the Topic section of the thing detail. As an example:

CloudLocate/device:xyzwe-9999-1234-5678-9abcdefg/GNSS/response 

The estimation takes few tens of milliseconds, without considering the network latency.

6. In most of the use cases you need to get the estimated location on your application in the cloud, rather than on the device. This option is explained in the next section

Note: for more information about the structure of the u-blox GNSS message containing the GNSS raw measurement, you can refer to this guide

Here below a typical response of the CloudLocate server

{

"Lat":47.2852123,

"Lon":8.5652996,

"Alt":549.473,

"Acc":13.393,

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

"Epochs":1

"LocationSource":"CloudLocate"

}

Sample code

To simplify your initial tests you can use the sample code available in the Download area of the Thingstream platform in the section IoT Location-as-a-Service > CloudLocate: Python reference Implementation for M10 in standalone configuration

Next readings

Other interfaces to access to CloudLocate

The just described way to access to CloudLocate is named Device to Service, in which the device sends the GNSS raw measurement to the CloudLocate service endpoint and the estimated position can be retrieved both by cloud application and/or by the client (device) 

There are other two ways, that are more convenient for different architectures:

• Service to Service, that can be used if you need to send the raw measurement to your cloud application and get the estimated position using a REST API

• Premium extension, that is preferred if you are already using one of our Communication-as-a-Service solution, like MQTT Anywhere, MQTT Now, MQTT Flex, MQTT Here. Through the Data Flow Manager you can combine multiple premium extension you can create your own logic to manipulate the data and much more using a simple drag and drop interface.

Zero Touch Provisioning

If using the Device to Service access, when going in production it becomes complex to deal with MQTT credential configuration in the device as well as for  Location Things creation in the Thingstream platform, because these are all manual tasks.

To simplify and automate this activity you can refer to Zero Touch Provisioning solution.

Not real-time measurements

There are some use cases in which the device does not have connectivity all the time. Even in this case you can use CloudLocate service by storing the time and date of the snapshot and send it in the following format:

{

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

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

}

Note: The Base64 encoded measurement consists in the payload of UBX-RXM-MEAS* message to the server, without the UBX frame header (8 bytes). Just take the payload of 12-, 20- or 50-bytes payload (no checksum) and encode in base64.

You can find more information about the structure of UBX-RXM-MEAS/50/20/12 GNSS messages in this guide.

Mixed mode

Mixed mode allows you maximize the power efficiency and the reliability by using CloudLocate for most of the position estimation and addressing the remaining challenging signal conditions by leveraging the device GNSS engine to estimate the position. This Mixed mode guide explains how to set up the client application.

Get the location on your cloud application 

To get the location from your cloud application you need:

1. create an IP Thing in the Thingstream platform. This is a logical object that provides  you the credential to access to the platform with MQTT protocol. Through this Thing you can get the location of all your devices

   • 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

2. configure an MQTT client in your cloud application with the credentials and the endpoint provided in the related section of the new IP Thing

3. Subscribe from the MQTT client in your cloud application to CloudLocate/+/GNSS/response topic to get the position of all the devices using CloudLocate. If you want the position of a single device you can replace the +  with the device ID device:xyzwe-9999-1234-5678-9abcdefg

Note: you can decide to get the estimated position on both side (cloud and device) or only on one side  by simply subscribing to the right topic. When getting the position on the device you cannot use the wildcard  + but only the topic that include the device ID in the path

Payload format summary

This section summarize which are the supported formats accepted by the CloudLocate service according to selected service access mode and the selected raw measurement type.

Regardless the service access mode

• when using UBX-RXM-MEASX, the service requires in input the entire UBX message sent in output by the GNSS, including all the headers and the checksum;

• when using UBX-RXM-MEAS50/MEAS20/MEAS12 the service needs in input only the payload of the UBX message sent in output by the GNSS, removing the headers and the checksum.

More information about the payload structure is available in the Compact raw measurement section

Device to Service access mode

•  Real time location:

  • Option 1:  UBXM-RXM-MEAS* payload, header and checksum excluded; the encoding can be base64  or binary. Base64 ensures a safer transmission over the network nodes between the device and the service endpoint but it increase the packet size.  This option is not applicable to UBX-RXM-MEASX and to UBX-RXM-MEAS12

  •  Option 2: UBXM-RXM-MEAS* payload, header and checksum excluded;  it shall be base64 encoded and inserted in the body attribute of the JSON object while the headers attribute containing the date and time is not required. This option is not applicable to UBX-RXM-MEAS12

• Not real-time location: as Option 2 of real-time location, but the JSON object shall include the Date/time information.

Note: MEAS12 is not supported in Device to Service mode, but only in Service to Service access mode

Service to Service access mode (REST API)

•  Real time location:

  • Option 1:   UBXM-RXM-MEAS* payload, header and checksum excluded, with Base64 encoding . The content type of the API shall be set to plain/text. This option is not applicable to UBX-RXM-MEASX. This option is the best one to minimize the data transmission and so the base64 encoding should be done in the cloud application before issuing the API request

  • Option 2.: UBXM-RXM-MEAS* entire message, including header and checksum. The message shall be encoded in Base64 and added to the payload parameter. In this case the application/JSON content type shall be set in the API and the JSON format shall be used. Since it's a real-time location,  Date/time information is not mandatory

• Not real-time location:  as Option 2 of real-time location, but the JSON object shall include the Date/time information.

Additional info are available in the API documentation

Premium extension (flow)

•  Real time location: refer to Device to Service access mode described above

• Not real-time location: refer to Device to Service access mode described above