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

Table of contents

Other ST Microcontroller manuals

ST ST25DV-I2C User manual

ST STM32W-SK User manual

ST STM32G4 Series User manual

ST STM32F7 Series Supplement

ST STM32 Nucleo Installation and operating instructions

ST STM32L562E-DK User manual

ST ST7LITE1 B Series User manual

ST Flash ST7 Service manual

ST STM32F100 Series Installation and operating instructions

ST STM32 Nucleo User manual

ST STEVAL-MKSBOX1V1 User manual

ST ST624 B-EMU2 Series User manual

ST STM32F7508-DK Manual

ST STM8AF Series User manual

ST SimpleMAC STM32W108 Series User manual

ST STM32F20 Series Installation and operating instructions

ST AN3155 Installation and operating instructions

ST STM8S User manual

ST ST7260 Series User manual

ST STM32H745I-DISCO User manual

ST STM32MP135F-DK User manual

ST STM8L Installation and operating instructions

ST STM8L-DISCOVERY User manual

ST STM32F105 series Installation and operating instructions

Popular Microcontroller manuals by other brands

AMS

AMS AS7261 Demo Kit user guide

Novatek

Novatek NT6861 manual

Espressif Systems

Espressif Systems ESP8266 SDK AT Instruction Set

Nuvoton

Nuvoton ISD61S00 ChipCorder Design guide

STMicrolectronics

STMicrolectronics ST7 Assembler Linker user manual

Texas Instruments

Texas Instruments Chipcon CC2420DK user manual

Lantronix

Lantronix Intrinsyc Open-Q 865XR SOM user guide

NEC

NEC 78GK0S/K 1+ Series Application note

Mikroe

Mikroe SEMITECH N-PLC Click Application note

Intel

Intel Agilex user guide

Cypress

Cypress CY4607 HX2VL quick start guide

DIGITAL-LOGIC

DIGITAL-LOGIC MICROSPACE manual

Texas Instruments

Texas Instruments TMS320F2837 D Series Workshop Guide and Lab Manual

CYPRES

CYPRES CY14NVSRAMKIT-001 user guide

Texas Instruments

Texas Instruments INA-DUAL-2AMP-EVM user guide

Espressif Systems

Espressif Systems ESP8266EX Programming guide

Abov

Abov AC33M8128L user manual

Laird

Laird BL654PA user guide