examples

XPLR-HPG-Software Examples

The folder contains multiple code examples, showcasing key features of the modules and services available on the XPLR-HPG-1 and XPLR-HPG-2 kits. They can be used as quick-start guides to help you kick-off your next u-blox powered project.

Examples Summary

Name	Description	Features
Hpg Base	Template project to get you started.	board manager
Hpg Kit Info	Diagnostic application reporting hardware info to console.	board manager hpglib/common hpglib/location_services/xplr_gnss_service hpglib/location_services/xplr_lband_service hpglib/communication service
Thingstream ZTP (Wi-Fi)	Demonstration of Thingstream's ZTP service for location things using Wi-Fi.	board manager hpglib/common xplr_wifi_starter xplr_ztp hpglib/thingstream_service
Thingstream Correction Data using Certs (Wi-Fi)	Demonstration of Thingstream's PointPerfect data correction via MQTT using WiFi. Correction data is fed to a GNSS module. Authentication using certificates.	board manager hpglib/common xplr_wifi_starter xplr_mqtt hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers
Thingstream Correction Data using ZTP (Wi-Fi)	Demonstration of Thingstream's PointPerfect data correction via MQTT using WiFi. Correction data is fed to a GNSS module. Authentication using Zero Touch Provisioning (ZTP).	board manager hpglib/common xplr_wifi_starter xplr_ztp hpglib/thingstream_service xplr_mqtt hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers
Thingstream Correction Data using Captive Portal (Wi-Fi)	Demonstration of Thingstream's PointPerfect correction data via MQTT using WiFi. Credentials provisioning and live map tracking are featured through a self-hosted web interface.	board manager hpglib/common xplr_wifi_starter (DNS + Webserver) xplr_ztp hpglib/thingstream_service xplr_mqtt hpglib/location_services/xplr_gnss_service hpglib/location_services/xplr_lband_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
NTRIP Correction data (Wi-Fi)	Example of how to get correction data from a 3rd party NTRIP Caster using Wi-Fi	board manager hpglib/common hpglib/location_services/xplr_gnss_service hpglib/ntripWiFiClient_service hpglib/log_service hpglib/sd_service
Thingstream Correction Data using Configuration file in SD card	Demonstration of Thingstream's PointPerfect data correction via MQTT using WiFi. Correction data is fed to a GNSS module. Authentication using configuration file in SD card.	board manager hpglib/common xplr_wifi_starter xplr_mqtt hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
Bluetooth echo server	Example of how to use the HPGLib bluetooth client. In this case the XPLR-HPG board acts as an echo server for a Bluetooth connected device.	board manager hpglib/common hpglib/bluetooth_service hpglib/log_service hpglib/sd_service
Correction data via Wi-Fi MQTT with SW Maps via Bluetooth	Demonstration of Thingstream's PointPerfect data correction via MQTT using WiFi while integrating bluetooth connectivity with SW Maps application. Correction data is fed to a GNSS module. Authentication using certificates.	board manager hpglib/common hpglib/bluetooth_service xplr_wifi_starter xplr_mqtt hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers
Network Registration (cellular)	Demo project for configuring a cellular module and registering to a cellular provider.	board manager hpglib/common hpglib/communication service hpglib/log_service hpglib/sd_service
Thingstream Correction Data using Certs (cellular)	Example of how to access Thingstream's Location Service data, providing required certificates manually, over cellular and forward them to a GNSS module.	board manager hpglib/common hpglib/communication service hpglib/mqttClient_service hpglib/thingstream_service hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
Thingstream Correction Data using ZTP (cellular)	Example of how to access Thingstream's Location Service data, using ZTP, over cellular and forward them to a GNSS module.	board manager hpglib/common hpglib/communication service hpglib/httpClient_service hpglib/mqttClient_service hpglib/thingstream_service hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
NTRIP Correction data (Cellular)	Example of how to get correction data from a 3rd party NTRIP Caster using cellular network	board manager hpglib/common hpglib/location_services/xplr_gnss_service hpglib/ntripCellClient_service hpglib/log_service hpglib/sd_service
Correction data via Cellular MQTT with SW Maps via Bluetooth	Example of how to access Thingstream's Location Service data, providing required certificates manually, over cellular and forward them to a GNSS module while integrating bluetooth connectivity with SW Maps application.	board manager hpglib/common hpglib/communication service hpglib/mqttClient_service hpglib/bluetooth_service hpglib/thingstream_service hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
GNSS/LBAND Module Configuration	Example of how to configure your GNSS or LBAND module.	board manager hpglib/common hpglib/location_services/xplr_gnss_service hpglib/location_services/xplr_lband_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
GNSS Save on Shutdown	Example of how to use the functionality of ZED module to store its current configuration to the backup flash and fetch it in the next boot.	board manager hpglib/common xplr_wifi_starter xplr_mqtt hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
Thingstream Correction Data over cellular interface using Configuration file in SD card	Demonstration of Thingstream's PointPerfect data correction via MQTT using cellular. Application settings provided by configuration files in SD card.	board manager hpglib/common hpglib/communication service hpglib/mqttClient_service hpglib/thingstream_service hpglib/location_services/xplr_gnss_service hpglib/location_services/location_service_helpers hpglib/log_service hpglib/sd_service
HPG as an AT peripheral	Example of how to use your HPG kit as a peripheral using AT commands or the included python API application.	board manager hpglib/at_parser_service hpglib/at_server_service hpglib/com_service hpglib/common hpglib/location_service hpglib/log_service hpglib/mqttCell_service hpglib/ntripCellClient_service hpglib/log_service hpglib/ntripWiFiClient_service hpglib/nvs_service hpglib/thingstream_service hpglib/sd_service xplr_mqtt xplr_wifi_starter

Building Instructions

Working with any of the examples provided requires editing a single line in CMakeLists.txt to select a project to build.

Individual build instructions are provided under all example folders.
In general, building any of the provided projects, involves the following steps:

1. Clone the XPLR-HPG repository and update included submodules.
2. Navigate to XPLR-HPG-SW folder and Open with Code (or open the ```VS code `` app and open the folder from the app menu).
3. Open the CMakeLists.txt located in the root of the workspace.
4. Select the example you wish to build by activating the corresponding set(ENV{XPLR_HPG_PROJECT} <example_name>) command.
5. Run MenuConfig using either the "cog" symbol present in the Status bar or by opening the command palette (Ctrl+Shift+P) and typing ESP-IDF:SDK Configuration editor (menuconfig).
6. Check / Edit the current configuration according to your needs.
7. Click Save and then Build, Flash and Monitor the project to the MCU using the "flame" icon.

NOTE: Remember, only one project(<example_name>) and its corresponding include path "$ENV{XPLR_HPG_SW_PATH}/examples/<module>/<example>" can be active at a time!

Configuring application via the SD card

Several examples offer the option to be configured via a json file in the SD card.

When the board boots and the main application starts a check is performed for the presence of the xplr_config.json file in the SD card.
If the check fails for any reason (SD not present, file not found, etc) the board keeps the values of the Kconfig configuration.
Otherwise, the configuration options are parsed and applied, overriding the Kconfig values.

NOTES:

1. If the xplr_config.json exists in the SD card and a fail occurs during the parsing of the configuration options then the application reaches an error state (does not fall back to Kconfig values). So it advised to have the xplr_config.json file in the SD card only if the configuration via the SD is the preferred method of configuration (and not the Kconfig via the menuconfig).
2. The configuration options are applied in the beginning of the application and there is no update during the runtime (if for example an SD is inserted containing a xplr_config.json file with different configuration). So if an update to configuration options is needed a system reboot is necessary.
3. No configuration options are saved between different boots of the board. If the board is set up via the SD, the SD is then removed and a reboot event occurs, all configuration options are lost and the board must be reconfigured (either via Kconfig or via the SD card).

The examples/applications that support this functionality are:

• Short Range :
  • hpg_wifi_http_ztp
  • hpg_wifi_mqtt_correction_certs
  • hpg_wifi_mqtt_correction_ztp
  • hpg_wifi_ntrip_correction
  • hpg_wifi_correction_sd_config_file
• Positioning :
  • hpg_gnss_save_on_shutdown
• Cellular :
  • hpg_cell_register
  • hpg_cell_mqtt_correction_certs
  • hpg_cell_mqtt_correction_ztp
  • hpg_cell_ntrip_correction
  • hpg_cell_mqtt_correction_certs_sd_autonomous