CloudLocate Service-to-Service access using REST API

Introduction

Service-to-Service access enables you to leverage the power of CloudLocate sending the GNSS measurements from your application platform, instead of directly using your IoT device.

This documentation will guide you through the process of setting up your Thingstream account for service-to-service access using the Thingstream Customer API to publish data to the platform.

As an alternative option, you can publish the data using an MQTT client as described in this guide.

Prerequisites

The prerequisites to complete the procedure are:

  1. you have access to the u-blox Thingstream portal and you have already created a domain

  2. you have registered a credit card in the portal or you have a credit line active.

  3. You have a basic knowledge of the Data Flow Manager. More information is available in our Flows guide.

Procedure overview

The mains steps of this procedure are

  1. Create an IP Thing

  2. Import the desired flow from the templates list

  3. Modify the flow (only if any customization is required)

  4. Deploy the flow

  5. Send the measurement and get the location back

Create an IP Thing

The first step is to create an IP thing; this is used to inject data in the platform

  1. Click on "Things" on the left side panel, which will open up Things page

  2. Click on "Add Thing" button at the top right of the page, which will open a dialog where you can add a thing

  3. On the dialog that pops up, click "Add IP Thing"

When you click "Add IP Thing" button, a new screen (in the same dialog) will appear where you will have to enter a name for the thing, and click "Add Thing".


4. Give your "Internet Thing" a name

5. Click "Add Thing"

Once you've created a thing, you will be asked to select a plan. You need to select an MQTT Now plan in order to use service-to-service access. All pricing plans are available in the pricing section under the MQTT now panel. You can start with the developer plan or select the plan that suits your needs best, and click "Activate".

6. Select a plan that suits your needs

7. Click "Activate"

8. Once you've activated the device, click "View details" to see details of the thing you just created.

9. Copy the "DeviceID" using the icon on the right side. You need this for what is to come next.

Still need help?

CloudLocate getting started guide

Service to Service access using MQTT

API Documentation

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

Import a Flow from the template list

The next step is to create a Flow to call the CloudLocate service. We've created a template to help you get started

  1. Click "Flows" on the sidebar

  2. Click "Create Flow", and then select "From Flow Library"

3. Click on "IoT Location-as-a-Service"

4. Click "CloudLocate Position"

5. Click "Copy" dropdown and select "Copy to domain & edit" which will take you to the flow editor.

Flow Explanation

Let's look at what's happening in the flow, in detail, before we take it for a test drive (for that you need to "Deploy" the flow first, which we will cover in next section).

Summary of the flow

Once the flow is deployed, it will subscribe to a topic (via thingstream subscribe node), convert the incoming payload to json (via json node), save the identity in the payload (SaveIdentity node) before passing the measurement data to the CloudLoate node. The calculated position is passed to the AppendIdentity node, which will add back the identity saved earlier, and will then do two things: [1] output the response as a debug message (via the msg.payload (debug) node), and [2] send the payload in the body of an HTTP POST request (via the HTTP request node).

Now let's look at each node in detail:

thingstream subscribe node

This node acts as an input to the flow. When we deploy the flow, we associate a topic with it, and whenever something is published on that topic (via the Publish API or an MQTT publish), it gets injected into the flow using this node.

This node does not need any configuration.

json node

This node converts the incoming payload from a JSON string to a JSON object representation

SaveIdentity (function) node

This is a JavaScript function node, which has been renamed to "SaveIdentity". The job of this node is to extract the "identity" header from the incoming payload and save it as a flow variable (to be used later). This is necessary as the CloudLocate node requires only the base64 encoded measurement as an input.

The "Identity" header is used to identify the device sending the measurement data. If you do not need this identification, you don't have to set this header.

If you "double-click" this node, it will open up function code, which will look like:

flow.set(`identity:${msg.messageId}`, msg.payload.headers.identity);

return msg;

CloudLocate node

This node calls the CloudLocate service and returns a calculated location.

AppendIdentity (function) node

The job of this function node is to put back identity header's value as part of payload. Once that is done, the flow variable is reset. The output from this node is used by the two following nodes

msg.payload (debug) node

This node outputs debug data to the "debug" tab on the right-hand side of the editor.

http request node

This node is responsible for making an HTTP(s) request which could be used to POST the calculated location together with the identity value (if provided). Details of how to use this, and all nodes, can be found in the "info" tab on the right-hand side of the editor

thingstream publish node

The thingstream publish node can be used to publish the result of the flow to another Thingstream MQTT topic.

email node

The email node can be used to send the flow results by email. Simply connect and configure email node (by looking at its info tab), and link it with the AppendIdentity function node. If you plan to use it, double-click on the node and:

  • set the To field with your email address

  • set a subject for the email

  • replace the body field with below code

Lat: {{payload.Lat}}

Lon: {{payload.Lon}}

Alt: {{payload.Alt}}

Acc: {{payload.Acc}}

Time: {{payload.MeasxTime}}

Epochs: {{payload.Epochs}}

Identity: {{payload.identity}}

  • Save the flow

sms node

You may also wish to send an SMS with the location result. Just connect the output of the AppendIdentity node to the sms node, and configure it as required.

Flow Deployment

Before you can start using the flow, it needs to be deployed.

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

2. You need to setup subscription before flow can be deployed. Click "Edit" against "Subscription" to configure it.

3. In the search box, start searching for the topic that you want the flow to subscribe to. Although you are using a REST API to publish the device measurement you shall do this step

4. If the topic already exists (eventually previously created in the Topic section of the left side menù) you can pick it from the list, otherwise click Add.

5. Click "Done"

6. Click "Deploy" to deploy the flow.

7. This flow contains premium extension nodes. The popup that shows up warns you of this, and has a link to pricing page for details. If you're OK with the cost, click "Deploy".

Once the flow is deployed, the top part of the page changes to show you which topic the flow is subscribed to

NOTE: Do not close this tab or navigate away from it. Later when you call Publish API, you can view the position generated in "debug" tab.

Send Measurement and Get Position

Now that you've deployed the flow, it's time to send an http request with measurement data, and get a position out of it. For that, you need your domain credentials to call Publish API.

You can get domain credentials by following below said steps

Getting Domain Credentials

  1. Move your mouse over to "Settings" on the left side-menu

  2. Click "Domain Settings" from the sub-menu that opens up

  3. On the right side of the page that is shown, click "SHOW ACCESS KEYS" and it will reveal your domain's access keys in a dialog box

4. Copy the value next to "Domain Key".

5. Copy the value next to "Domain Secret".

Calling Publish API using Swagger

Now that you have your access key and secret, go to Publish API swagger playground

https://api.thingstream.io/swagger

  1. Copy your domain key in the text box that has "domain_key" written in it.

  2. Copy your domain secret in the text box that has "domain_secret" written in it.

  3. Click "Explore".

  4. Click "Publish API Webservice" to expand the section.

5. Once you've expanded the section, click "/publish/topic/string" - using this API, you will publish the measurement data, using HTTP, to theflow.

6. You need to set request body to following JSON

{

"deviceId": "",

// this is the deviceId of the IP thing we created earlier

"qos": 0,

// this will remain 0

"topic": "",

// this is the topic we created before during the flow deployment

"content": ""

// this is the measurement data that you need to send

// please see below sample measurement data

// one with identity, and one without

// you need to place sample measurement data as an escaped string

}

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

{

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

"headers":{"UTCDateTime": "yyyy-mm-ddThh:mm:ss" , "identity": "my_device"}

}

where identity field is optional and is your preferred device identifier and should be different for every device. See the two sample measurement below for a real example.

The measurement in the body field shall be a Base64 encoded string:

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

  • If you are getting the measurement (UBX-RXM-MEASX) directly from the receiver, without using u-center, be sure to make the conversion into Base64 in your own code

Note: remember that you can avoid to add the "UTCDateTime" parameter if you can send the measurements within 1 min from when it has been generated in the GNSS. If you are not in this use case you need always to add that time field.

Finally, before adding the payload to the content field you have to escape it.

{\"body\": \"Base64 encoded measurement (String)\",\"headers\":{\"identity\":\"my_device\",\"UTCDateTime\": \"yyyy-mm-ddThh:mm:ss\" }}

For testing purpose you can use this tool

Sample measurement (unescaped) without identity

{

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

}


Sample measurement (unescaped) with identity

{

"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" , "identity": "my_device" }

}

Sample request body for Publish API - (content escaped)

{

"deviceId": "device:1234567-a1b2-471a-9eb4-f89dc162b255",

"qos": 0,

"topic": "s2s/cloudlocate/position",

"content": "{\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\", \"identity\": \"my_device\" }\r\n}"

}


7. Once you've set the request body as mentioned above, click "Try it out!" to send the data to flow.

8. Once you click "Try it out!", if everything is setup correctly, you will see 200 response code.

You don't have to use swagger to send the request. If you look at "Curl" section, it gives you cURL request you can make from your server.

Now that you've sent the measurement data, it is now time to see what position was calculated in the flow.

9. If you go back to your flow window, and click "debug" tab on the right, you will see the position payload that was generated by given measurement data.

NOTE:

  • If you've closed the flow tab after deploying it, open it again, and then send the request mentioned above in order to get debug info.

  • Remember to configure the http request node or link the append Identity node to the email node if you need a quick check

  • After every change, remember to save the flow

If you gave measurement data as mentioned above, it should correspond to this location:

{"Lat":47.2852123,"Lon":8.5652996,"Alt":549.473,"Acc":13.393,"MeasxTime":"2021-05-28T17:19:37","Epochs":1}


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.