CloudLocate Device-to-Service access using MQTT

Prerequisites

To use the service you need

•  at least one of the  following  hardware: 

  • a u-blox GNSS receiver (generation M8 or M9 or M10) and/or

  • a Wi-Fi  module and/or (u-blox or third-party)  and/or

  • a Cellular module  (u-blox or third-party)

• the access to Thingstream service delivery platform

• the knowledge and tools on how to use an MQTT client

Procedure overview

The mains steps of this procedure are

1. Create a CloudLocate Thing, that is the logical representation of your device in the Thingstream platform; you need one Thing for each device, but for production purpose this step can be automatized by using Zero Touch Provisioning

2. Select the pricing plan or the developer plan

3. Get the credentials for MQTT access, the service endpoint and the device identity from the Thing details

4. Configure the  MQTT client in the device with the above parameters

5. Send the service JSON payload, generated as described in the Getting Started guide by publishing the payload in the request topic and get the location estimation by subscribing to the response topic

Here below an extensive explanation for each step.

Create a CloudLocate Thing

The first step is to create a CloudLocate Thing that provides you all the required parameters for the API:

• username and password and device ID

• service endpoint

The Thing let also you to:

• modify the pricing plan

• deactivate/ reactivate the access

• monitor the usage of the service

• and look at the the events

Sign-in into the Thingstream portal and select the Location Things item from the Location Services section. Click the button to create a new Location Thing and browse to the CloudLocate section from where you can select the wizard to create CloudLocate Thing.  

During the creation steps you are suggested to assign a price plan. If you skip this step the Thing will not be automatically activated and cannot be used. When you are ready to assign a plan, open the Thing panel and assign the preferred one. A free developer plan is available.

Configure the MQTT client

RAW data shall be sent to the service using the MQTT protocol. 

• username, password, clientID and service endpoint data are available in the Credential tab, when opening the Thing details

• Request and response topic are available in the Topic tab. 

CloudLocate/GNSS/request  (request topic)

CloudLocate/<deviceID>/GNSS/response  (response topic)

• MQTT protocol version 3.1.1 shall be used.  You can use port 1883 for unencrypted TCP or port 8883 for TLSv1.2. MQTT over WebSockets is not supported.  

Send a measurement and get a position

The service supports multiple format:

• the JSON formatted request containing information of GNSS raw data, and/or cellular tower scan and/or Wi-Fi measurements. as described in the Getting Started guide.

• a binary payload containing only the GNSS raw data, useful for low bandwidth connectivity. To know more, you are suggested to read the Compact raw message guide.

In both cases to get a location you need to publish the RAW data in the request topic and subscribe to the response topic to get the estimated location.

Sample API response

A succesfull location response provides the position estimation as long as the date and time of the request, a copy of the RequestId if provided in input, and a LocationSource that indicates which source (Cellular, Wi-Fi or GNSS) have been used for the provided estimation.

{

    "Location": {

        "Lat": 51.496268,

        "Lon": -0.0949408,

        "Unc68": 27.0

    },

    "DateTime": "2023-09-14T13:02:01",

    "RequestId": "82cb34c9-88c9",

    "LocationSource": "WiFi"

}

Location in the Cloud

The Location in the Cloud option allows you to save additional device energy and deliver faster the device location to the end user that might be your cloud application or another system/device using this information according to your business needs. 

As shown in the picture at the beginning of this slide, the RAW data can be sent by the IoT device to the service endpoint exactly in the same way just explained above. 

To send the estimated position directly to your cloud application, few additional step are required. 

1. Create a IP Thing in the portal, in the Communication Service section as shown in the following picture. The IP things is an interface that allows you to connect from your server to Thingstream platform (where CloudLocate service is hosted) using MQTT protocol. The new created Thing provides the MQTT credentials, the device ID and the URL.

2. Using the MQTT client in the server, subscribe to the topic CloudLocate/<deviceID>/GNSS/response  to get the location of a single device or use the + wildcard to get the location for all your devices CloudLocate/+/GNSS/response. In this case it's suggested to use the RequestID parameter in the service payload sent  by the device to the service so that you can identify to which device this position belongs.

There are many free MQTT client that you can use to do an initial tests. If you need support please contact suppport@thingstream.io. 

There are also several other options to retrieve the position server side  by using the http(s), sms, email, ftp, amqp functions embedded in Thingstream Data Flow Manager that allows also to manipulate and transform data in the most convenient way before delivering to your cloud application.

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.