ST UM2334 User manual

Introduction
The X-CUBE-GNSS1 is an expansion software package for STM32Cube.
The software runs on the STM32 and includes drivers for the Teseo-LIV3F global navigation satellite system (GNSS) device,
middleware for the NMEA protocol support, and RTOS (Azure® RTOS ThreadX or FreeRTOS™) for task scheduling to ensure a
better asynchronous message parsing.
It is built on top of the STM32Cube software technology for easy portability across different STM32 microcontrollers.
The software comes with sample implementations for the drivers running on the X-NUCLEO-GNSS1A1 expansion board, when
connected to a NUCLEO-F401RE, NUCLEO-L476RG, NUCLEO-L073RZ, or NUCLEO-U575ZI-Q development board.
The software also includes a sample application for assisted GNSS provided by the Teseo-LIV3F GNSS device. The application
is tailored for the B-L475E-IOT01A discovery kit for IoT nodes.
Related links
Visit the STM32Cube ecosystem web page on www.st.com for further information
Getting started with the X-CUBE-GNSS1 global navigation satellite system
software expansion for STM32Cube
UM2334
User manual
UM2334 - Rev 7 - June 2022
For further information contact your local STMicroelectronics sales office.
www.st.com

1Acronyms and abbreviations
Table 1. List of acronyms
Acronym Description
A-GNSS Assisted global navigation satellite system
BSP Board support package
BeiDou China regional navigation satellite system
DRAW Dead reckoning automotive way
Galileo Europe global navigation satellite system
GLONASS Global navigation satellite system
GNSS Global navigation satellite system
GPS Global positioning system
HAL Hardware abstraction layer
I2C Inter integrated circuit
IC Integrated circuit
IP Internet protocol
NMEA National Marine Electronics Association - United States standards organization for marine equipment
QZSS Quasi-zenith satellite system (used in the Asia-Oceania regions)
RTOS Real-time operating system
TCP Transmission control protocol
UART Universal asynchronous receiver-transmitter
USB Universal serial bus
UM2334
Acronyms and abbreviations
UM2334 - Rev 7 page 2/19

2X-CUBE-GNSS1 software expansion for STM32Cube
2.1 Overview
X-CUBE-GNSS1 is a software package that expands the functionality provided by STM32Cube .
The key features of the package are:
•Complete software to build applications using the Teseo-LIV3F GNSS device
• Middleware for the NMEA protocol and for assisted GNSS (A-GNSS) support
• RTOS (Azure® RTOS ThreadX or FreeRTOS™) task scheduling to ensure a better asynchronous message
parsing
• Easy portability across different MCU families, thanks to STM32Cube
• Sample application to transmit GNSS data to a PC and for A-GNSS support
• Free, user-friendly license terms
The package includes sample applications that the developer can use to start experimenting with the code. A
Java application to update the Teseo-LIV3F and the STM32 Nucleo board firmware is included in the package.
2.2 Architecture
This software is a fully compliant expansion of STM32Cube architecture for the development of applications using
the ST Teseo-LIV3F GNSS module.
The software is based on the STM32CubeHAL hardware abstraction layer for the STM32 microcontroller. The
package extends STM32Cube by providing a board support package (BSP) for the GNSS expansion board and
some middleware components for NMEA protocol and A-GNSS support. The package is also based on the
FreeRTOS library to exploit the benefits of task scheduling for a better asynchronous message parsing.
The software layers used by the application software to access and use the GNSS expansion board are:
•STM32Cube HAL layer: consists of simple, generic, and multi-instance APIs (application programming
interfaces) which interact with the upper layer applications, libraries, and stacks. These generic and
extension APIs are based on a common framework so that overlying layers like middleware can function
without requiring specific microcontroller unit (MCU) hardware information. This structure improves library
code reusability and guarantees easy portability across other devices.
•Board support package (BSP) layer: provides software support for the STM32 Nucleo board peripherals,
excluding the MCU. These specific APIs provide a programming interface for certain board-specific
peripherals like LEDs, user buttons, etc., and can also be used to fetch individual board version information.
It also provides support for initializing, configuring, and reading data.
UM2334
X-CUBE-GNSS1 software expansion for STM32Cube
UM2334 - Rev 7 page 3/19

Figure 1. X-CUBE-GNSS1 software architecture
Sample Applications
Application
NMEA
Middleware
STM32Cube Hardware Abstraction Layer (HAL)
Hardware
Abstraction
Hardware
STM32 Nucleo development board
STM32 Nucleo expansion boards
A-GNSS RTOS mbedTLS
X-NUCLEO-GNSS1A1 (Sense)
cJSON
2.3 Folder structure
Figure 2. X-CUBE-GNSS1 package folder structure
The following folders are included in the software package:
•CubeMX: includes configuration files for STM32CubeMX tool.
•Documentation: contains a compiled HTML file generated from the source code, detailing the software
components and APIs.
•Drivers: contains the HAL drivers, the board-specific drivers for each supported board or hardware platform
(including the on-board components) and the CMSIS vendor-independent hardware abstraction layer for the
Arm Cortex®-M processor series.
UM2334
Folder structure
UM2334 - Rev 7 page 4/19

•Middlewares: contains a library for the NMEA protocol support (for example, for NMEA message parsing),
a FreeRTOS library for task scheduling management, an A-GNSS library for assisted GNSS support, and a
cJSON library for JSON message parsing.
•Projects: contains the sample applications used to access the GNSS data provided for the NUCLEO-
F401RE, NUCLEO-L476RG, NUCLEO-L073RZ, and NUCLEO-U575ZI-Q platforms and a sample
application for A-GNSS provided for the B-L475E-IOT01A discovery kit for IoT nodes. All the applications
are available under three development environments: IAR Embedded Workbench for Arm (IAR-EWARM),
RealView Microcontroller Development Kit (MDK-ARM), and STM32CubeIDE.
•Utilities: contains a “PC_Software” folder with a Java utility to update the Teseo-LIV3F device firmware.
2.4 APIs
Detailed technical information about the APIs available to the user can be found in a compiled HTML file located
inside the “Documentation” folder of the software package where all the functions and parameters are fully
described.
2.5 GetPos sample application
An example application using the X-NUCLEO-GNSS1A1 expansion board with a NUCLEO-L476RG board is
included in the package (in the folder ROOT_DIR\Projects\STM32L476RG-Nucleo\Applications\GetPos). Ready
to be built projects are available for multiple IDEs.
In this application, real-time GNSS data received by the Teseo-LIV3F device can be displayed through a serial
connection and a serial terminal on a PC.
The GetPos application is built on top of the FreeRTOS support introducing a task (consumer), to parse the
messages (enqueued in a shared queue) coming from the Teseo-LIV3F device, and a task (listener) to parse
commands coming from the serial terminal.
The sample application also shows three advanced features supported by the Teseo-LIV3F device:
•Geofencing: allows the Teseo-LIV3F receiver to raise an NMEA message when the resolved GNSS position
is close to enter or exit from a specific circle.
•Odometer: provides information on the traveled distance using only the resolved GNSS position.
•Data Logging: allows the Teseo-LIV3F receiver to save the resolved GNSS position on the local flash
memory to be retrieved on demand from the host.
The Teseo-LIV3F device sends the received GNSS data via UART (or I²C) to the STM32 microcontroller on the
STM32 Nucleo board according to the NMEA 0183 version 4.0 protocol. At compile time, the user can choose
the interface to receive data (setting the macro USE_I2C in the file gnss1a1_conf.h) and also enable a specific
feature (setting the corresponding macro in the file teseo_liv3f_conf.h).
2.5.1 GetPos usage procedure
The following instructions show how to use the GetPos sample application to return information relating to a
GNSS position.
UM2334
APIs
UM2334 - Rev 7 page 5/19

Step 1. Open a serial connection between the STM32 Nucleo and the X-NUCLEO-GNSS1A1 expansion board
and your PC with the correct COM port for your PC and the following remaining parameters:
Figure 3. GetPos: TeraTerm serial COM port setup
Step 2. Push the Reset button to show the menu options in the terminal window.
Figure 4. GetPos: menu
UM2334
GetPos sample application
UM2334 - Rev 7 page 6/19

Step 3. Select from the different options to obtain human readable information related to the acquired GNSS
position, the satellites in view, the active satellites and so on.
The figure below relates to menu selection option 1
Figure 5. GetPos: menu option 1
2.5.2 SimOSGetPos
SimOsGetPos is a particular case of the GetPos application described in this section, included in the package
folder ROOT_DIR\Projects\STM32L073RZ-Nucleo\Applications\SimOSGetPos.
It shows how real-time GNSS data ($GPGGA) received by the Teseo-LIV3F device can be displayed, through a
serial connection and a serial terminal, on a PC.
This application is tailored for STM32 Nucleo L0 family and excludes the FreeRTOS support.
2.5.3 A_GetPos
A_GetPos is an extension of the GetPos application including the Assisted GNSS feature (both predictive and
real-time) supported by the Teseo-LIV3F GNSS device.
The application has to access the Internet and is customized for B-L475E-IOT01A Discovery kit for IoT node
providing the Wi-Fi connectivity (for further details on Assisted GNSS, refer to AN5160 and Section 3 of UM2399
freely available at www.st.com).
This application can be found in the package folder ROOT_DIR\Projects\B-L475-IOT01\Applications\A_GetPos.
UM2334
GetPos sample application
UM2334 - Rev 7 page 7/19

Figure 6. A_GetPos menu option 0 and related sub-options
2.6 Virtual_COM_Port sample application
Virtual_COM_Port is the application to be loaded in order to use the ST TESEO-SUITE PC software tool
(available at https://www.st.com, together with a Quick Training Guide on how to use it) for managing,
configuring and evaluating the Teseo GNSS device.
It is included in the package folder ROOT_DIR\Projects\STM32F401RE-Nucleo\Applications\Virtual_COM_Port.
Ready-to-build projects are available for multiple IDEs.
Using this application, the real-time GNSS data received by the Teseo-LIV3F device are displayed through a
serial connection and a serial terminal on a PC.
2.7 GNSS FW Upgrader utility
The X-CUBE-GNSS1 software expansion for STM32Cube contains a Java utility to upgrade the
Teseo-LIV3F GNSS device firmware to the latest available version. This utility is available in the
ROOT_DIR\Utilities\PC_Software folder.
Step 1. Connect the X-NUCLEO-GNSS1A1 expansion board to the STM32 Nucleo development board.
Step 2. Copy the FW_Updater firmware to the Nucleo drive.
You will find the firmware in the ROOT_DIR\Projects\STM32F401RE-Nucleo\Applications\FW_Updater
folder on your PC.
Step 3. Run the GNSS Upgrader utility
UM2334
Virtual_COM_Port sample application
UM2334 - Rev 7 page 8/19

Step 4. Establish connection with the STM32 Nucleo board by selecting the serial port and clicking the Open
button.
Note: Keep the [Reset] button on the STM32 Nucleo board pressed until the updating procedure starts.
Figure 7. GNSS FW Upgrader: Open button
After a few seconds, the Teseo-LIV3F current firmware version is displayed in the GUI
A pop-up window indicates whether the firmware is the latest available version.
Step 5. If the current firmware is not the latest version, click on the Update FW >>> button to start the upgrade
process.
Figure 8. GNSS FW Upgrader: upgrade process
Step 6. Wait for the upgrade to complete
A new pop-up should now confirm that the firmware is up to date.
The GUI will show the new firmware version.
UM2334
GNSS FW Upgrader utility
UM2334 - Rev 7 page 9/19

3System setup guide
3.1 Hardware description
3.1.1 STM32 Nucleo
STM32 Nucleo development boards provide an affordable and flexible way for users to test solutions and build
prototypes with any STM32 microcontroller line.
The Arduino connectivity support and ST morpho connectors make it easy to expand the functionality of the
STM32 Nucleo open development platform with a wide range of specialized expansion boards to choose from.
The STM32 Nucleo board does not require separate probes as it integrates the ST-LINK/V2-1 debugger/
programmer.
The STM32 Nucleo board comes with the comprehensive STM32 software HAL library together with various
packaged software examples for different IDEs (IAR EWARM, Keil MDK-ARM, STM32CubeIDE, mbed and GCC/
LLVM).
All STM32 Nucleo users have free access to the mbed online resources (compiler, C/C++ SDK and developer
community) at www.mbed.org to easily build complete applications.
Figure 9. STM32 Nucleo board
3.1.2 X-NUCLEO-GNSS1A1 expansion board
The X-NUCLEO-GNSS1A1 expansion board is based on the Teseo-LIV3F tiny GNSS module.
It represents an affordable, easy-to-use, global navigation satellite system (GNSS) module, embedding a TeseoIII
single die standalone positioning receiver IC, usable in different configurations in your STM32 Nucleo project.
The Teseo-LIV3F is a compact (9.7x10.1 mm) module that provides superior accuracy thanks to the on-board
26 MHz temperature compensated crystal oscillator (TCXO) and a reduced time-to-first fix (TTFF) with its
dedicated 32 KHz real-time clock (RTC) oscillator.
The Teseo-LIV3F module runs the GNSS firmware (X-CUBE-GNSS1) to perform all GNSS operations including
acquisition, tracking, navigation and data output without external memory support.
The X-NUCLEO-GNSS1A1 expansion board is compatible with the Arduino™ UNO R3 connector and the ST
morpho connector, so it can be plugged to the STM32 Nucleo development board and stacked with additional
STM32 Nucleo expansion boards.
UM2334
System setup guide
UM2334 - Rev 7 page 10/19