Device to Service access - Step-by-Step Guide
Introduction
Device-to-Service access allows to access to the service requesting the location estimation directly from your from your devices. This approach is preferred, for example, whenever you do not want to implement additional logic server side to handle the location request.
The Location in the Cloud option offers additional saving of energy and data, by limiting the handshake with the device and thus the on-time of the modem that consumes energy.
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
-
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
-
Select the pricing plan or the developer plan
-
Get the credentials for MQTT access, the service endpoint and the device identity from the Thing details
-
Configure the MQTT client in the device with the above parameters
-
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.
-
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.
-
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 services-support@u-blox.com.
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.
Still need help?
CloudLocate getting started guide
If you need more help or have any questions, please send an email to services-support@u-blox.com