Awesome

Learning by examples

This repo is intended to be a starting point on learning how to use the u-blox open source library ubxlib. The intended target system here is the XPLR-IOT-1 device but most of the examples are also applicable to any u-blox module or EVK supported by ubxlib.

The main focus here is to make everything as uncomplicated as possible. The host mcu in an XPLR-IOT-1 device is the Nora-B1 with Nordic nRF5340. Unless you are familiar with the nRFConnect SDK and the Zephyr RTOS, the learning curve for mastering the development environment for this chip is quite steep. This repo tries to raise the abstraction layer and let you focus on the actual programming using ubxlib. Once started you can then dig into the more intricate parts of both ubxlib and Zephyr in your own pace.

The interface to building, running and debug software for ubxlib can be either the command line or Microsoft Visual Studio Code.

Both Windows (Windows 10, 11 tested) and Debian Linux (Ubuntu 20.04, 22.04 tested) are supported.

In order to get the required development environment and tools an installation script must first be run. This will use the Nordic standard installation for the nRF connect environment (currently version 2.2.0). If you already have this installed in the standard location it will be used and not reinstalled. Some additional tools like Visual Studio Code will also be installed unless already present.

Goto this page for more information about the installation process.

Requirements

To use this repo you need at least an XPLR-IOT-1 device. Please note though that this device doesn't contain any debug chip so in order to be able to do debugging you need to have some kind of debugger/programmer device. This would typically be a JLink debugger.

You also need a 10 pin programmer cable to connect the XPLR-IOT-1 and the programmer. Example shown below:

However it is still possible to build and flash the examples into an XPLR-IOT-1 without a programmer. This is then made through a usb cable connected to the unit. No debugging is however possible in this case. Please note that this type of flashing requires the "newtmgr" program. This is installed automatically by the installation scripts of this repo, but if you have done a manual installation you have to add this manually as well and make sure it is in your path. It is available for download from here

Please note that the usb cable should also be inserted if you want to see printouts from the example programs.

The actual flash process is different if you have a debuger unit or are just using the serial cable. In the first case everything is done automatically if the debug is connected to the XPLR-IOT-1. In the latter case manual interaction is needed. You must first turn off the XPLR-IOT-1 with its on/off button. Then press down button 1 on the top side of the unit and keep it pressed while turning on the device again. The unit is now in bootloader mode and the flashing process can begin. Flashing performed by this repository tools will prompt you for confirmation of that the unit is in bootloader mode before starting.

Also please note that by flashing these examples you will overwrite the "Sensor Aggregation" firmware which is installed in a fresh XPLR-IOT-1. Should you later want to restore that firmware, this page will show you how.

The WiFi captive portal example requires ubxlib version 1.3 or later, to be released July 2023.

Getting started

Once you have everything installed and have connected your XPLR-IOT-1, you can start exploring the functionality of this repository.

Begin by starting a new command window. Then change working directory to where the repository was cloned. If you have used the installation script this will be in a directory underneath your home directory named ubxlib_examples_xplr_iot.

Then issue the following command:

Windows:

do vscode

Linux:

./do vscode

This will execute a complete build of the simple blink example and then start Visual Studio Code.

Once Visual Studio Code has started you will find the "main.c" source code in a window.

From within Visual Studio Code you can then build, rebuild, flash and run the examples. This is done via selecting the menus Terminal -> Run Build Task or by pressing the shortcut ctrl-shift-b. Choose Build and run "blink" to flash and start the blink example and the red led of your XPLR-IOT-1 should start blinking.

You can then select any of the other examples by choosing Select Example in the Build Task menu as above. After that you can select Build and run again.

If you have a debug unit you can then also start a debugging session by first selecting the Run and debug icon in the left side pane.

Then select the green arrow in the top section and a debugging session will start.

The program will stop at the first line in the program. Experiment with the different debug functions in Visual Studio Code such as stepping, checking variables etc.

You can then start modifying the examples to you liking or add your own, more about that further down.

Using the nRFConnect Visual Studio Code extension

If you are used to using the nRFConnect Visual Studio Code extension and prefer to use it instead of the Visual Studio environment created by the do command, then that is of course also possible.

In this case just open Visual Studio Code and then select Add an existing application in the nRF Connect extension. Browse to one of the example directory and choose open. Then do a Add build configuration in the normal way using the nrf5340dk_nrf5340_cpuapp as board. After that you can use the different operations available from the nRF Connect extension for building and debugging etc. You find all the used overlay and configuration files in the config directory of this repo. Please note that builds created this way will not use the bootloader.

Creating your own examples

There are three ways you can experiment and create new example applications.

• Edit the existing examples and rebuild.
• Copy one existing example to the playground directory and edit and build from there. Everything added here will be excluded from git operations.
• Create a directory outside of this repo and add a corresponding directory structure and source files there. If you then set the application directory as you default and start the do command from there it will pick up your example application instead of the ones in the repo.

Advanced usage

All the operations performed in this repo are controlled by one central command named do. This command is executed as described above in a command window with the default directory set to the root of the repo.

Below is the help information for the command as shown when issuing "do --help". More thorough description below.

usage: do [-h] [-e EXAMPLE] [-p] [--no-bootloader] [--when-changed] [-d BUILD_DIR]
        [-n NCS_DIR] [-t GCC_DIR] [-u UBXLIB_DIR]
        operation [operation ...]

positional arguments:
operation             Operation to be performed: vscode, build, flash, run, monitor, debug, terminal

optional arguments:
-h, --help            show this help message and exit
-e EXAMPLE, --example EXAMPLE
                        Name of the example
-p, --pristine        Pristine build (rebuild)
--no-bootloader       Don't use the bootloader
--when-changed        Only flash when build was triggered
-d BUILD_DIR, --build-dir BUILD_DIR
                        Root directory for the build output
-n NCS_DIR, --ncs-dir NCS_DIR
                        Nrf connect sdk installation directory
-t GCC_DIR, --gcc-dir GCC_DIR
                        GCC toolchain installation directory
-u UBXLIB_DIR, --ubxlib-dir UBXLIB_DIR
                        Ubxlib directory

The most typical operations are:

These operations can also be started from within Visual Studio Code as described above.

There are some options for the operations which can be specified. These can be temporary for the actual command or be saved as new defaults. In the latter case the operation "save" is used.

The --example option is used to specify which example to build. If not specified the example used in latest previous run will be used. See the directory structure underneath the examples subdirectory for the names available. Example:

do build -e socket

There will be a automatic search for examples among the directories so if you add your own that will be included as well in the list of choosables.

Directory specification

There are some directories which are needed to be defined for the build process. These have default values depending on how the installation is made but can always be overridden by the options below:

Other options

The config directory

This directory contains the specifics for handling the XPLR-IOT-1 in Zephyr.

The files here are mainly overlay files used to override the specific settings for XPLR-IOT-1 when using the nrf5340dk board files.

Here is also a c-file for defining the default gpio pins etc and setting them to enable the different u-blox modules automatically from ubxlib.

There are some cmake variables you can define for controlling these files.

Bootloader

By default the mcuboot bootloader which is available in a fresh XPLR-IOT-1 will be kept. If you don't want that then use the option:

--no-bootloader

Should you later want to change this you can use the operation "flash_bootloader"

Network cpu

The network cpu of the host nrf5340 is not used in most of the examples. However if the Bluetooth functionality is to be used in the host (and not in the Nina module), a firmware for the network cpu has to be built and flashed. The build is done automatically whenever the KConfig setting CONFIG_BT is set.

To flash the built network cpu firmware the following command must be used after a successful build of the example:

do flash_net

This is only required to be done once.

Please note that this command will only work for examples that has defined CONFIG_BT. The current examples doing that are: ble_ibeacon_z, ble_scan_z and aoa_tag. In this case the command will be for ibeacon_z:

do flash_net -e ble_ibeacon_z

Visual Studio Code workspace

Once VS Code has been opened via the do vscode command and you want to save your setup of windows etc you can save it as a workspace. The next time you then run this command it will detect the workspace and open it.