XPLR-IOT-1 CloudLocate Demo

This guide is intended to provide all the information  and tools on how to setup the CloudLocate demo with XPLR-IOT-1.  The demo aims to demonstrate to the customer the significant GNSS energy saving using CloudLocate by comparing it with a standard GNSS working mode, without A-GNSS.

The expected way to run the demo (once completed the set-up) is to go in the field with the customer, for example around the customer office, and get 3-20 positions and finally demonstrate and discuss the results in the customer office.

The expected outcome is to engage the customer in a testing activity in short period. The customer can use the same demo tool, or set up its own test scenario.

With this demo you can demonstrate two main scenarios:

• Scenario 1 - real-time position: the device is always in the position to transmit the position to the service because it has always the connectivity available.

• Scenario 2 - post processing: the device does not need to transmit immediately the position to the server. It stores multiple CloudLocate snapshot and send all data at once when connectivity is available or when it's more appropriate to implement an energy saving strategy considering also the connectivity.

The next section explain how to setup and run the demo. Once the first setup is done, for the subsequent demos only minor or no changes are requested.

This guide does not provide information about how CloudLocate service works. If you want to know more about CloudLocate service, read the Getting Started Guide.

Demo Set-up

Prerequisites and tools

Herew below the list of the tools that you need to run the demo. You will be guided step-by-step for download and  installation in the following sections.

• your laptop

• XPLR-IOT-1 rev D - we explain how to verify the revision of your XPLR-IOT-1 in a section at the end of this guide.

• Node.js installed in your laptop.

• The demo code for the laptop to show the demo result and the demo code for the XPLR-IOT-1.

• a domain/account in u-blox Thingstream portal.

• A country with an LTE-M network or as an alternative the access to Wi-Fi connectivity. If you plan to use LTE-M connectivity, you can leverage the embedded SIM already present in the XPLR-IOT-1. Verify that it is already active. 

  • if it is the first time that you approach the XPLR-KIT-1, you can use the redemption code to activate the SIM as explained in the leaflet added to the box. The SIM takes around 30 mins to be active, once you have completed the procedure.

The time to set-up the demo the first time is around 30-40 minutes. After the initial setup you can run the demo again without or with minor additional configurations .

Demo workflow and architecture

Workflow

The demo is composed by two steps:

• data (position) collection.

• data publishing to the map.

If the customer country has LTE-M connectivity, you can publish position after the collection. Otherwise you can collect multiple positions and publish the data once you are back in the office through the Wi-Fi network

Architecture

The picture shows the demo architecture

Once you have collected one or more position (more info will be provided in next sections) to publish the collected data you need to push the button 2 for 1 second . This action triggers an MQTT connection to the Thingstream platform over a pre-defined topic. The published data will be retrieved by the application running on the laptop that automatically connects  to CloudLocate service for the cloud position estimation and shows in the map the comparison between that position and the one estimated by the M10 GNSS in the XPLR-IOT-1 kit.

Note: on the  top right corner of the map you can find a a comparison in regards of estimated energy consumption and receiver on-time. This summary includes all the collected positions.

Credential Generation

To run the demo you need to generate 3 set of credentials on the Thingstream platform:

• IP Thing 1 for XPLR-IOT -1 connection

• IP Thing 2 for laptop  connection

• REST API credentials for CloudLocate service 

IP Thing credentials

Sign-in in the Thingstream portal and repeat this step twice, one for each IP thing.

• In the Communication Service section  select Communication Thing and then click the button to add a Thing

• Select New IP Thing and give it a name. and follow the wizard

• In  the Credential tab you can find the information for XPLR-IOT-1 and laptop software configuration (Clien ID, Username and password)

Note: the wizard forces you to assign a price plan to the IP Thing.  You can start using the Developer plan, but remind that this is limited to  5K messages per month.

CloudLocate  REST API Credentials

• In the Thingstream platform, select Location services and then  Location Thing and then click on Add Location Thing

• Select the CloudLocate Tab and add a CloudLocate  S2S Thing and follow the wizard.

• In  the Credential tab you can find the information for the rest API (Endpoint, Username and password)

Note: the wizard forces you to assign a price plan to the IP Thing.  You can start using the Developer plan, but remind that this is limited to  5K messages per month.

Laptop demo software

Download and install

As the first step you shall install the node.js free software that can be downloaded from this link https://nodejs.org/en/download. The installation does NOT require admin privileges, and can be installed in any laptop.

As second step you can download the demo Software. Once downloaded, unzip it and put in your preferred folder.

Note: this link is accessible only to u-blox personnel. 

Demo software configuration

Browse into the folder of the demo Software , open the app folder and open the index.js file with a text editor.

Modify the credentials at thee top of the file with the one generated above:

• IPThing-CloudLocate demo -->  use  credential and Client ID of IP Thing 2.

• S2S-CloudLocate --> use the REST API credentials.

Save and close the file.

Run the Laptop demo software

To run the demo software:

• open a command prompt and navigate till the folder where the software is located as shown in the picture below

• launch the software with the command  npm run start

After few seconds, the software opens a map in your default browser.  Depending on the version of the laptop demo software, it might be required to click on the Connect button, that trigger the subscription to the CloudLocateDemo topic. If the button is not present, the subscription happens automatically. Do not change the subscription topic.

The software is properly subscribing to the CloudLocateDemo topic when in the command prompt you can read:

 watching for file changes...Message from client

{"topic":"CloudLocateDemo"}

MQTT CLIENT SUBSCRIBED FOR EVENTS ON TOPIC:CloudLocateDemo

Note: when using the LAN network the MQTT protocol might be blocked. You are suggested to us the Wi-Fi network of  the office for your laptop internet connection

XPLR-IOT-1 demo code

Download and install

To  install the  demo code you need the following software:

• The CloudLocate XPLR-IOT demo code (app_update.bin, pick the latest version)

• network manager

• Update_XPLR-IOT-1-Location

• Putty

If you have never done this before for other XPLR-IOT-1 examples, look at this short guide, where you can find also the link to download all the tools.

If you are already aware of the procedure, download the CloudLocate XPLR-IOT demo code and flash it into the XPLR-IOT-1.

Demo configuration

Connect to XPLR-IOT-1 using putty and type help to see all the possible configurations

Configure the MQTT client

Location data are transmitted from the device to the laptop application using MQTT protocol. To configure the MQTT Client type

uart:~$ config mqtt set username password DeviceID

replacing username, password and DeviceID with the credentials of IP Thing 1 mentioned above.

Check the configuration with 

uart:~$ config mqtt get

Configure the connectivity

You can publish (send) data  to the laptop application by using the WiFi or LTE-M if the country support this Radio Acceess Technoogy.  In case of Wi-Fi be sure that the device is in the covered area of the Wi-Fi network.

To configure Wi-Fi connection:

uart:~$ config wifi set SSID password

replacing SSID and password with the corresponding value. If using your mobile phone as hotspot, be sure that it's always active.

Check the configuration with:

uart:~$ config wifi get

If using LTE-M and the Thingstream embedded SIM (assuming that it is already active), you only need to set the APN

uart:~$ config cell set CellRegistrationTimeout APN

Replace the apn with tsiot and set a different CellRegistrationTimout if needed (default is 180 seconds).

As always check the configuration with:

uart:~$ config cell get

Finally, set the desired connectivity (cell or wifi) with:

uart:~$ config network set cell

or 

uart:~$ config network set wifi

depending on which connectivity you plan to use.

Collect and publish the location data

A location data set is composed by:

•  a position calculated by the M10 GNSS in the XPLR-Kit 

• and a Raw data message that is used by CloudLocate service to estimate a position in the cloud

A location data set can be collected by pressing the button 1 of the XPLR-IOT-1.

Because of space constraints, you can collect a maximum of 20 data set without publishing. There are two main ways to proceed:

• Mode 1: collect one data set, publish it and then repeat again the operation as many times as you want. This is possible only if you have access to LTE-M connectivity or you use your mobile phone as hotspot.

• Mode 2: collect up to 20 data sets and publish  all data  via Wi-Fi at once when you go back to the office.

Collecting a data-set

Collecting location data can be done using the XPLR-IOT -1 button. According to how long you press the button 1 you can test different types of CloudLocate Raw measurements (MEAS50 and MEAS20), while the standard GNSS fix is independent.

• short press for 1 seconds (and less than 5 seconds)--> MEAS50 (this is the suggested option)

• long press for 5 seconds --> MEAS20

• long press for 10 seconds (and less than 3 seconds)--> a dummy location is generated, that is useful just to test that demo is working end to end without collecting real field data

The LED helps you to understand what is happening

• after a short press of 1 second the LED blinks blue until the collection of one data set has been completed or the timeout has been reached

• after a long press of 5 seconds the LED blinks yellow until the collection of one data set has been completed or the timeout has been reached

• In both cases, If the data have been collected successfully, a green LED blinks for few seconds, otherwise a RED led blinks for few seconds

Note: consider that in good sky visibility, collecting one location data set takes at least 50 seconds.

Note: between two position you can keep the XPLR-IOT-1 switched on or off, at your  preference, since the data are saved persistently.

Publishing a data set

With data set publishing you transfer all the data-set stored in the XPLR-IOT-1 to the laptop application for the visualization. 

Note: before doing that, be sure that the laptop software is running and it has subscribed to the CloudLocateDemo topic as explained above.

To publish data sets press the button 2 of the XPLR-IOT-1 for 1 second. A white LED start blinking. 

• If the operation is successful, a green LED blinks for few seconds and the positions will appear in the map in the  laptop.

• If the operation is not successful, a red LED blinks for few seconds. The reasons are mainly due to connectivity issue:

  • If using LTE-M consider that the modem might take some time to register to the network.

  • if using Wi-Fi and the hotspot of your mobile phone make sure it is active.

  • the Troubleshooting section at the end of the guide gives you additional help

Note: after publishing, the location data are removed from the device.

Initial test 

When running the demo for the first time, you might want to test the end -to-end communication, but you might not have already captured a location.

In such case you can load a dummy location saved in the software. You have two ways to do that:

• if you are connected to the XPLR-IOT-1 through the USB cable, just type location dummy.  If you then type  location, you can verify that a location have been loaded in the device

• if you are not connected, just press button 10 for one second. The LED will blink yellow and then green.

You can now publish the location as explained in the previous section and verify that the demo is running properly.

Other useful configuration

Other useful settings to consider are:

• set  a delay for the CloudLocate Raw measurement. With the purpose to get a more reliable Raw measurement, you might want to delay the time by when the raw measurement is captured.  This can be done with the command

uart:~$ config set IndexOfMessageToPick CompactMessageTimeout

uart:~$ config set 8 120

and replacing the IndexOfMessageToPick with a value greater than the default one (4).  Every unit is equal to 500ms, therefore if you specify 8, the demo application waits 4 additional seconds after the first raw measurement is available and pick and save the first Raw measurement available  after 4 seconds.

Note: you  have always to specify both parameters (IndexOfMessageToPick, CompactMessageTimeout).  If you want to change only one parameter, you need to first read the value already set with config get and then set the desired parameters as explained above.

• Set a timeout: in adverse signal condition the GNSS receiver might not be able to generate a RAW measurement. By setting a timeout, the demo application stop the measurement search after the given period (in seconds)

uart:~$ config set IndexOfMessageToPick CompactMessageTimeout

uart:~$ config set 8 180

• use config clear to clear all the settings and restore the default ones. This command restore also the connectivity settings

• use version to check the version of the demo firmware uploaded in the kit.

Troubleshooting

Some typical problems that you might find are:

• the laptop application does not show the position collected by the XPLR-IOT-1:

  • the laptop application has not subscribed to CloudLocateDemo Topic.  Refer to the Collect and publish location data for more information.

  • you are using the hotspot of your mobile phone and although it seems to be active, it is not. 

  • if using LTE-M connectivity, check that your SIM is active.  If using the Thingstream  embedded SIM you should have activated it by using the redemption code in the XPLR-KIT box.

  • if using LTE-M connectivity, check that you have set the TSIOT apn as explained in the previous section

  • the network to which the device or the laptop is connected might not allow the usage of MQTT protocol. 

• be sure to assign a valid plan to the IP Things created above,. The developer plan is capped and works only for few publishing. You can change plan in the IP Thing details section.

Checking  XPLR-IOT-1 version

To verify the revision of your XPLR-IOT-1, open it and check the printed version in the top right corner as indicated by the red box in the following picture.

Still need help?

Demo Software download

CloudLocate getting started guide

If you need more help or have any questions, please contact services-support@u-blox.com.