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

Figure 10. X-NUCLEO-GNSS1A1 expansion board
3.2 Hardware setup
The following hardware components are needed:
1. One STM32 Nucleo development platform (suggested order code: NUCLEO-F401RE, NUCLEO-L476RG,
NUCLEO-L073RZ or NUCLEO-U575ZI-Q)
2. One Discovery kit for IoT node (order code: B-L475E-IOT01A)
3. One GNSS expansion board (order code: X-NUCLEO-GNSS1A1)
4. One GPS/GLONASS/Beidou antenna to be connected to the X-NUCLEO-GNSS1A1 (bundled with the
GNSS expansion board)
5. One USB type A to Mini-B USB cable to connect the STM32 Nucleo to the PC
3.2.1 X-NUCLEO-GNSS1A1 setup
For the X-NUCLEO-GNSS1A1 proper operations, the following jumper settings must be used:
•J2 open
• J3 closed
• J4 closed
• J5 open
• J6 closed
• J7 closed
• J8 open
• J9 closed
• J10 open
• J11 closed
• J12 closed
• J13 closed
• J14 closed
• J15 closed
UM2334
Hardware setup
UM2334 - Rev 7 page 11/19

3.2.2 Startup sequence
Step 1. Connect the X-NUCLEO-GNSS1A1 to the STM32 Nucleo development board.
Step 2. Power the STM32 Nucleo using the type A mini-B USB cable
Step 3. Program the STM32 Nucleo using the firmware example provided.
Step 4. Reset the MCU via the STM32 Nucleo reset button.
The evaluation kit is ready-to-use.
3.3 Software setup
The following software components are required to set up a suitable development environment for creating
applications for the STM32 Nucleo equipped with the X-NUCLEO-GNSS1A1 expansion board:
•X-CUBE-GNSS1: an expansion for STM32Cube dedicated to GNSS applications development. The X-
CUBE-GNSS1 firmware and related documentation is available on www.st.com.
• Development tool-chain and Compiler: the STM32Cube expansion software supports the three following
environments:
– IAR Embedded Workbench for Arm (IAR-EWARM) toolchain + ST-LINK
– RealView Microcontroller Development Kit (MDK-ARM-STM32) toolchain + ST-LINK
–STM32CubeIDE + ST-LINK
3.4 System setup guide
This section describes how to setup different hardware parts before developing and executing an application on
the STM32 Nucleo board with the GNSS expansion board.
3.4.1 STM32 Nucleo and GNSS expansion board setup
The STM32 Nucleo board integrates the ST-LINK/V2-1 debugger/programmer.
You can download the appropriate ST-LINK/V2-1 USB driver (STSW-LINK009) from www.st.com.
The GNSS expansion board X-NUCLEO-GNSS1A1 is easily connected to the STM32 Nucleo development
through the Arduino UNO R3 extension connector and can interface with the external STM32 microcontroller on
the STM32 Nucleo board either via UART or Inter-Integrated Circuit (I²C) channels.
UM2334
Software setup
UM2334 - Rev 7 page 12/19

Figure 11. X-NUCLEO-GNSS1A1 expansion board connected to an STM32 Nucleo board
The GPS/GLONASS/Beidou antenna included with the X-NUCLEO-GNSS1A1 expansion board must be
connected to the antenna connector on the expansion board.
Figure 12. GPS/GLONASS/Beidou antenna
3.4.2 GNSS Firmware Upgrader utility setup
The GNSS FW Upgrader Java utility included in the software package is a graphical user interface that can be
used to upgrade the Teseo-LIV3F on the X-NUCLEO-GNSS1A1 to the latest firmware version.
It has no particular minimum requirements, you can use any Linux, Microsoft or OSX PC with:
• Java Runtime Environment (JRE) 6+
• 1 x USB port
UM2334
System setup guide
UM2334 - Rev 7 page 13/19

To use the Firmware Updater Java utility, make sure you have correctly set up your hardware and software.
The utility can be launched by simply clicking twice on the FWUPG.jar file, located in the
“Utilities\PC_Software\FirmwareUpdaterTool” folder.
UM2334
System setup guide
UM2334 - Rev 7 page 14/19

Revision history
Table 2. Document revision history
Date Version Changes
06-Dec-2017 1 Initial release.
25-Jan-2018 2 Updated Figure 5 GetPos: menu.
Added Section 3.6 Virtual_COM_Port sample application.
11-May-2018 3
Updated Introduction, Section 3.1 Overview, Section 3.2 Architecture, Section 3.3 Folder structure,
Section 3.5 GetPos sample application.
Added Section 3.5.2 SimOSGetPos.
15-Oct-2018 4
Updated Introduction, Table 1. List of acronyms, Section 3.1 Overview, Figure 2. X-CUBE-GNSS1
software architecture, Section 3.3 Folder structure, Figure 8. GNSS FW Upgrader: Open button,
Figure 9. GNSS FW Upgrader: upgrade process, Figure 11. X-NUCLEO-GNSS1A1 expansion board
and Figure 12. X-NUCLEO-GNSS1A1 expansion board connected to an STM32 Nucleo board.
Added Section 3.5.3 A_GetPos.
23-Apr-2019 5
Updated Figure 2. X-CUBE-GNSS1 software architecture, Figure 3. X-CUBE-GNSS1 package
folder structure, Section 3.5 GetPos sample application, Section 3.5.2 SimOSGetPos, Section 3.5.3
A_GetPos, Section 3.6 Virtual_COM_Port sample application and Section 3.7 GNSS FW Upgrader
utility.
14-Apr-2022 6
Minor text changes.
Removed Section 2 What is STM32Cube? and Section 2.1 STM32Cube architecture, and replaced
them with a link in the introduction.
21-Jun-2022 7
Updated introduction, Section 1 Acronyms and abbreviations, Section 2.1 Overview,
Section 2.2 Architecture, Section 2.3 Folder structure, Section 2.5 GetPos sample
application, Section 2.5.2 SimOSGetPos, Section 2.6 Virtual_COM_Port sample application,
Section 3.3 Software setup, Section 3.2 Hardware setup, and Section 3.4.1 STM32 Nucleo and
GNSS expansion board setup.
Added references to NUCLEO-U575ZI-Q development board.
UM2334
UM2334 - Rev 7 page 15/19

Contents
1Acronyms and abbreviations ......................................................2
2X-CUBE-GNSS1 software expansion for STM32Cube ...............................3
2.1 Overview .....................................................................3
2.2 Architecture ...................................................................3
2.3 Folder structure ................................................................4
2.4 APIs .........................................................................5
2.5 GetPos sample application ......................................................5
2.5.1 GetPos usage procedure ..................................................5
2.5.2 SimOSGetPos...........................................................7
2.5.3 A_GetPos ..............................................................7
2.6 Virtual_COM_Port sample application .............................................8
2.7 GNSS FW Upgrader utility .......................................................8
3System setup guide...............................................................10
3.1 Hardware description ..........................................................10
3.1.1 STM32 Nucleo .........................................................10
3.1.2 X-NUCLEO-GNSS1A1 expansion board......................................10
3.2 Hardware setup ...............................................................11
3.2.1 X-NUCLEO-GNSS1A1 setup ..............................................11
3.2.2 Startup sequence .......................................................12
3.3 Software setup................................................................12
3.4 System setup guide ...........................................................12
3.4.1 STM32 Nucleo and GNSS expansion board setup ..............................12
3.4.2 GNSS Firmware Upgrader utility setup .......................................13
Revision history .......................................................................15
UM2334
Contents
UM2334 - Rev 7 page 16/19

List of tables
Table 1. List of acronyms ....................................................................2
Table 2. Document revision history ............................................................. 15
UM2334
List of tables
UM2334 - Rev 7 page 17/19

List of figures
Figure 1. X-CUBE-GNSS1 software architecture ...................................................4
Figure 2. X-CUBE-GNSS1 package folder structure .................................................4
Figure 3. GetPos: TeraTerm serial COM port setup ..................................................6
Figure 4. GetPos: menu ....................................................................6
Figure 5. GetPos: menu option 1 ..............................................................7
Figure 6. A_GetPos menu option 0 and related sub-options ............................................8
Figure 7. GNSS FW Upgrader: Open button ......................................................9
Figure 8. GNSS FW Upgrader: upgrade process ...................................................9
Figure 9. STM32 Nucleo board .............................................................. 10
Figure 10. X-NUCLEO-GNSS1A1 expansion board ................................................. 11
Figure 11. X-NUCLEO-GNSS1A1 expansion board connected to an STM32 Nucleo board ...................... 13
Figure 12. GPS/GLONASS/Beidou antenna ...................................................... 13
UM2334
List of figures
UM2334 - Rev 7 page 18/19

IMPORTANT NOTICE – READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST
products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST
products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgment.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of
purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, refer to www.st.com/trademarks. All other product or service names
are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2022 STMicroelectronics – All rights reserved
UM2334
UM2334 - Rev 7 page 19/19