Location example

.gitignore

@@ -0,0 +1,54 @@
+# Prerequisites
+*.d
+
+# Object files
+*.o
+*.ko
+*.obj
+*.elf
+
+# Linker output
+*.ilk
+*.map
+*.exp
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Libraries
+*.lib
+*.a
+*.la
+*.lo
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+!newtmgr.exe
+*.out
+*.app
+*.i*86
+*.x86_64
+*.hex
+
+# Debug files
+*.dSYM/
+*.su
+*.idb
+*.pdb
+
+# Kernel Module Compile Results
+*.mod*
+*.cmd
+.tmp_versions/
+/.vscode
+modules.order
+Module.symvers
+Mkfile.old
+dkms.conf

README.md

@@ -0,0 +1,39 @@
+# XPLR-IOT-1-location-example
+
+This project is intended to be used with XPLR-IOT-1 from u-blox to get a location using both CellLocate and CloudLocate technologies. This repository contains two examples containing source codes for each approach to get a location using XPLR-IOT-1. Any future updates of this application will be uploaded here. 
+
+The main function of this project is to calculate location based on cellular, Wi-Fi or GNSS information, whichever is required by the user. The user is required to set some configurable parameters in the example as per the requirements and the example will bring back the location based on those parameters. 
+
+The two example projects are configured to build assuming that XPLR-IOT-1 comes with a Bootloader that allows firmware on the device to be updated without the need of a debugger/programmer. One of the major aspects of the firmware is that it uses ubxlib library as much as possible to implement its functionality.
+
+It is to specify that this is an example project and any example code will not be a part of the end product.
+
+More information about XPLR-IOT-1 hardware etc. can be found in the following link: [XPLR-IOT-1 quick start](https://developer.thingstream.io/guides/iot-communication-as-a-service/hardware/xplr-iot-1-quick-start-guide)
+
+All examples requires to setup the cellular connection usign the SARA-R5 cellular module in the XPLR-IOT-1 kit. Although the sample code includes the connection setup, you might experience a long connection time the very first time that the connection is set up or after a SARA R5 firmware upgrade, and this can result in a failure of location example. It is  suggested to read the section "SARA-R5 connection troubleshooting guide" of the [Module connection set up guide](https://developer.thingstream.io/guides/location-services/celllocate-getting-started/module-connection-setup) to optimize the connection set up. 
+
+Additional repositories associated with XPLR-IOT-1 are available for firmware flash, application firmware, Node-RED dashboard and the hardware design:
+
+- Firmware flash on XPLR-IOT-1
+https://github.com/u-blox/XPLR-IOT-1
+
+- Firmware running on NORA-B106:
+https://github.com/u-blox/XPLR-IOT-1-software
+
+- Node-RED dashboard:
+https://github.com/u-blox/XPLR-IOT-1-Node-RED-dashboard
+
+- Hardware design:
+https://github.com/u-blox/XPLR-IOT-1-hardware
+
+
+## Disclaimer
+Copyright © u-blox
+
+u-blox reserves all rights in this deliverable (documentation, software, etc., hereafter “Deliverable”).
+
+u-blox grants you the right to use, copy, modify and distribute the Deliverable provided hereunder for any purpose without fee.
+
+THIS DELIVERABLE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR U-BLOX MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS DELIVERABLE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
+
+In case you provide us a feedback or make a contribution in the form of a further development of the Deliverable (“Contribution”), u-blox will have the same rights as granted to you, namely to use, copy, modify and distribute the Contribution provided to us for any purpose without fee.

celllocate-wifi-example/CMakeLists.txt

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+list(APPEND ZEPHYR_EXTRA_MODULES ${CMAKE_CURRENT_SOURCE_DIR}/../ubxlib_priv)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(celllocate_wifi_example)
+
+FILE(GLOB app_sources src/*.c)
+FILE(GLOB head_sources src/*.h)
+
+target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+target_sources(app PRIVATE ${app_sources})
+target_sources(app PRIVATE ${head_sources})

celllocate-wifi-example/README.md

@@ -0,0 +1,121 @@
+# XPLR-IOT-1-location-example
+
+This project is intended to be used with XPLR-IOT-1 from u-blox to get a location using both Cell ID and Wi-Fi sniffing technology using the u-blox CellLocate service. The project contains the location example for XPLR-IOT-1 and future updates of this application will be uploaded here. It is assumed that XPLR-IOT-1 has a Serial Bootloader that allows firmware on the device to be updated without the need of a debugger/programmer.
+
+The main function of the code is to collect Cellular or Wi-Fi information and send it to CellLocate service to get back a location in response. The Wi-Fi module can be enabled/disabled in the configuration parameters in the code for the location calculation. The code uses ubxlib library as much as possible to implement the functionality.
+
+The code is compatible with:
+- NINA firmware version 5.0.0. 
+- SARA-R510S-01B release 03.15_ENG1301. Please contact [email protected] to get the firmware.
+- Firmware upgrade procedure is available in this guide: https://www.u-blox.com/docs/UBX-21035674
+
+Prerequisite and notes:
+- to access to CellLocate service you need a valid token, that is the alphanumeric string generated by u-blox Thingstream service delivery platform; it is used by the device for service authentication. This guide explains how to generate it
+https://developer.thingstream.io/guides/location-services/tokens
+- CellLocate service provide by default the estimated location back the XPLR-IOT kit; in addition you can get the estimated position directly to your cloud application using a Cloud to Cloud connection;
+https://developer.thingstream.io/guides/location-services/celllocate-getting-started/location-in-the-cloud
+
+
+
+## Setup
+
+1. Clone the XPLR-IOT-1-location-example.
+
+2. Set your CellLocate token in the code, save it and build. You can also tweek the configuration parameters in the code. For the details, see [Description](#description).   
+
+3. Building the code will generate a binary file named as **app_update.bin** at the following location:
+
+*XPLR1-IOT-location-example/celllocate-wifi-example/build/zephyr*
+
+4. Copy the **app_update.bin** file and paste it at the given location: 
+
+*XPLR1-IOT-location-example/image_flashing*
+
+5. Go to *XPLR1-IOT-location-example/image_flashing* folder. 
+
+6. Connect your XPLR-IOT-1 kit to your system and determine the COM port number for NORA-B1 on Interface 0 of the USB-UART interface. 
+
+7. Run *Update_XPLR-IOT-1-Location.bat* file and a pop-up window will appear input your comport as following: 
+
+![Bat file pop-up](../imgs/bat.PNG?raw=true)
+
+8. Input your comport and press enter. The process will start flashing **app_update.bin** image file into your kit.
+
+9. More details about the XPLR-IOT-1 bootloader can be found in the following link: [XPLR-IOT-1](https://github.com/u-blox/XPLR-IOT-1-software/tree/main/tools_and_compiled_images)
+
+
+## Description
+
+The user is required to set some configurable parameters as per the requirements and the example will bring back the location based on those parameters. The configurable parameters are: 
+
+1. **MIN_WIFI_SIGNALSTRENGTH**:
+The user needs to set the signal strength for Wi-Fi scan in dBm with -30 dBm being the maximum signal strength and -90 dBm being the minimum:
+
+`#define MIN_WIFI_SIGNALSTRENGTH <your_desired_signal_strength>`
+
+A list of Wi-Fi signal strength is given below for reference:  
+
+* -30 dBm	: Maximum signal strength.
+* -50 dBm	: Excellent signal strength.
+* -60 dBm	: Still good, reliable signal strength.
+* -67 dBm	: Minimum value for all services that require smooth and reliable data traffic.
+* -70 dBm	: Signal is not very strong
+* -80 dBm	: Minimum value required to make a connection.
+* -90 dBm	: Unlikely able to connect or make use of any services 
+
+2. **NUM_WIFI_ACCESSPOINT**: 
+The minimum number of Wi-Fi access points accepted by the service to calculate the location is 5. So, the user needs to set the maximum limit of access point provided that the value is not less than 5:
+
+`#define NUM_WIFI_ACCESSPOINT <your_desired_num_access_points>`
+
+3. **CELL_LOCATE_TOKEN**:
+The user needs to enter the CellLocate service token against which the device is registered on Thingstream:
+
+`#define CELL_LOCATE_TOKEN "<your_celllocate_token>"`
+
+4. **APN**:
+The user needs to set the APN name for the network being used to run the example
+
+`#define APN <network_apn>`
+
+5. **USE_WIFI**:
+As discussed earlier, there are two operating modes in this example: 
+  - Cell based location calculation
+  - Wi-Fi based location calculation
+
+To calculate the location based on cellular information, set this flag to 0. It will return the position based on cellular information only:
+
+`#define USE_WIFI 0`
+
+In the other case where user needs information using Wi-Fi scan, set this flag to 1 and the service will return the location based on Wi-Fi access points:
+
+`#define USE_WIFI 1`
+
+When using Wi-Fi location, the service automatically use Cell Id as backup in case a position cannot be estimated using Wi-Fi scan.
+
+Once the configurations are done, build the code and flash it in the kit. For further information of firmware flash, refer to [XPLR-IOT-1](https://github.com/u-blox/XPLR-IOT-1) and [XPLR-IOT-1-software](https://github.com/u-blox/XPLR-IOT-1-software#programmingbuilding-the-firmware)   
+
+
+## Note
+
+After the firmware upgrade on SARA R5, the module stops responding to NORA-B1 Comport. To enable the communication, the user needs to send the following AT commands to NORA: 
+
+  - AT+USIO=2
+  - AT+CFUN=16
+
+In case you are not getting the position information or you are getting unexpected results, it's suggested to look at the following guides:
+- [Module connection setup](https://developer.thingstream.io/guides/location-services/celllocate-getting-started/module-connection-setup) to verify that the cellular connection have been properly estabilished and that the module can access to Internet and reach the CellLocate server
+- [Troubleshooying guide](https://developer.thingstream.io/guides/location-services/celllocate-getting-started/celllocate-troubleshooting-guide) to verify if you are in any of the listed edge cases
+
+
+
+## Disclaimer
+Copyright © u-blox
+
+u-blox reserves all rights in this deliverable (documentation, software, etc., hereafter “Deliverable”).
+
+u-blox grants you the right to use, copy, modify and distribute the Deliverable provided hereunder for any purpose without fee.
+
+THIS DELIVERABLE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR U-BLOX MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS DELIVERABLE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
+
+In case you provide us a feedback or make a contribution in the form of a further development of the Deliverable (“Contribution”), u-blox will have the same rights as granted to you, namely to use, copy, modify and distribute the Contribution provided to us for any purpose without fee.