DOCSEARCHbyAlgolia
Submit Docs

u-blox ubxlib

repository·master·Indexed 18 days ago

https://github.com/u-blox/ubxlib

A library providing a consistent interface for interacting with u-blox GNSS and cellular modules across Zephyr-based MCUs (Nordic, STM32, NXP), Linux/Posix, and Windows. It includes a comprehensive Cellular API for lifecycle, connectivity, and security, as well as support for PPP integration on ESP-IDF, Zephyr, and Linux. The library features a common device API, geofencing capabilities for GNSS, Cellular, and Wi-Fi, and a porting layer for cross-platform compatibility.

Tokens
68.5K
Snippets
138
Records
327
Agent score
62%

What's inside ubxlib

  1. Overview of libMga in ubxlib

    master

    The libMga directory contains a modified version of the libMga C library (v22.07). This library is designed to assist u-blox GNSS customers with the integration of AssistNow, primarily on Linux and Windows systems.

    In the ubxlib repository, this library has been modified to be wrapped by u_gnss_mga.c and to ensure compatibility with the ubxlib ecosystem. Key modifications include:

    • Fixed-point arithmetic: Replaced double with int types (using powers of ten) to avoid dependencies on floating-point libraries.
    • Memory Management: malloc() and free() have been replaced with pUPortMalloc() and uPortFree().
    • Time and Synchronization: time() is replaced by uPortGetTickTimeMs(), and timezone is replaced by uPortGetTimezoneOffsetSeconds() (compatible with both Linux and Windows).
    • Concurrency: lock() and unlock() now use the uPortMutexXxx() API instead of native WIN32/Posix.
    • Error Handling: assert() has been replaced with U_ASSERT().
    • Structure Updates: mgaBuildOnlineRequestParams() and mgaBuildOfflineRequestParams() now support NULL buffers and perform length checking. MgaOnlineServerConfig has additional fields, and MgaMsgInfo has been re-ordered for efficient structure packing.
    • Configuration: MgaFlowConfiguration is modified to indicate when UBX-CFG-VAL messages should be used instead of UBX-CFG-NAVX5.

    To identify specific changes within the source code, search for the string MODIFIED.

  2. Overview of the STM32Cube porting layer

    master

    The port/platform/stm32cube directory contains the implementation of the ubxlib porting layer specifically for the STM32Cube platform. This layer allows ubxlib to interface with STM32 hardware and operating systems.

    Key components include:

    • app/: Application code, including examples and unit tests designed to run on the STM32Cube platform.
    • src/: The actual implementation of the porting layers for the STM32Cube platform.
    • mcu/: Configuration and build files specific to the supported MCUs within this platform.
    • u_cfg_os_platform_specific.h: A header file containing hardcoded task priorities and stack sizes for the platform.

  3. Overview of available ubxlib examples

    master

    The example/ directory contains several functional categories of examples:

    • sockets: Bringing up a network (cellular or Wi-Fi) and using UDP or TCP socket connections to a public internet server.
    • security: Utilizing u-blox security features.
    • location: Obtaining a location fix.
    • mqtt_client: Using the MQTT client API to contact an MQTT broker on the public internet.
    • http_client: Using the HTTP client API.
    • cell: Specific to u-blox cellular modules (e.g., SARA-U201, SARA-R4, or SARA-R5).
    • gnss: Specific to u-blox GNSS chips (e.g., M8, M9, M10).
    • utilities/c030_module_fw_update: A utility program required for updating the firmware of the cellular module on C030-R5 or C030-R4xx boards.

  4. Overview of ubxlib platform porting layers

    master

    The port/platform directory contains implementations of the porting layer for various SDKs and MCUs. This layer bridges the platform-independent ubxlib core with specific hardware and operating systems.

    Key components include:

    • platform/common: Contains code shared across all platforms, such as the runner source code used to execute examples and tests.
    • static_size platform: A specialized platform containing stubs for the porting layer and dummy configuration files. It is used to measure the [static] flash and RAM footprint of the platform-independent ubxlib code.

  5. Overview of GNSS-specific examples

    master

    The example/gnss directory contains examples designed specifically for u-blox GNSS chips (e.g., NEO-M8, ZED-F9P) when using GNSS in isolation (without cellular or Wi-Fi/BLE). These examples demonstrate how to configure the device and exchange messages.

    Key functional examples include:

    • Configuration: Using uGnssCfgValXxx() (M9 modules and later only) via u_gnss_cfg.h.
    • Message Exchange: Using uGnssMsg via u_gnss_msg.h to communicate directly with a GNSS chip.
    • Message Decoding: Using uGnssDec via u_gnss_dec.h to decode messages not natively supported by ubxlib.
    • Positioning: Using uGnssPos via u_gnss_pos.h to obtain streamed position fixes.
    • AssistNow: Using uGnssMga via u_gnss_mga.h to achieve faster time to first fix using u-blox AssistNow services.
    • Geofencing: Using the common u_geofence.h API with a GNSS chip.

  6. Overview of the Cellular API groups

    master

    The cell directory provides a control interface for u-blox cellular modules. The API is organized into functional groups:

    • Core/Lifecycle: init/deinit and adding a cellular instance.
    • Configuration & Power: cfg (configuration) and pwr (power management).
    • Connectivity: net (network attachment) and mux (3GPP 27.010 CMUX mode).
    • Information & Security: info (module info), sec (u-blox security), and sec_tls (TLS security).
    • Data & Protocols: sock (sockets), mqtt (MQTT client), and http (HTTP client).
    • Location Services: loc (CellLocate and Assist Now services) and geofence (MCU-based geofencing).
    • Hardware & System: gpio (module GPIOs), file (file storage), fota (FOTA state), time (CellTime timing), and sim (minimal SIM access).

    Note on usage strategy:

    • Use the detailed cell API if you need granular control over the module.
    • Use the common/network, common/sock, common/security, and common/location APIs if you simply want to bring up a bearer and exchange data or establish location. The handles used by the common APIs are generated by the cell API.

  7. Overview of Wi-Fi APIs in ubxlib

    master

    The Wi-Fi directory provides APIs for both control and data exchange. The APIs are organized into functional groups:

    • Core: Initialization/deinitialization and adding Wi-Fi instances.
    • cfg: Configuration of the Wi-Fi module.
    • sock: Sockets for data exchange (Note: using the common/sock component is recommended for best results).
    • mqtt: MQTT client functionality over Wi-Fi (Note: use the generic common/mqtt_client for a more general implementation).
    • http: HTTP client functionality over Wi-Fi (Note: use the generic common/http_client for a more general implementation).
    • loc: Wi-Fi-based location services. This requires an API key for Google Maps, Skyhook, or Here (Note: use the generic common/location component).
    • geofence: MCU-based geofencing using the common/geofence API with Google Maps, Skyhook, or Here. This is only included if U_CFG_GEOFENCE is defined.

    Supported module types are defined in u_wifi_module_type.h.

  8. Overview of the AT client in ubxlib

    master

    The AT client provides helper functions to send commands to an AT interface (such as a V250 modem) over a UART. It handles standard command transmission and parses responses, supporting both synchronous responses and asynchronous unsolicited responses.

    Important Usage Note: This client is an internal utility used by various other ubxlib modules to perform their functions. It is not intended for direct use by customers.

    Compatibility:

    • It sits on top of the port API, making it compatible with any platform supported by that API.
    • It is used by cellular and most short-range modules.
    • Exception: For the NORA-W36 module, do not use this client. Instead, use the ucxclient parser located in common/short-range/src/gen2.

  10. Overview of u-blox security features and module support

    master

    The security API provides interfaces for certificate/key storage, TLS security configuration, and u-blox specific security features including authentication, identification, encryption, and transport services.

    Support for specific features like 'Seal', 'End To End', 'PSK Generation', 'Chip to Chip', and 'Zero Touch Provisioning' varies by module. For example, the SARA-R5 module supports all listed features, while NINA series modules primarily focus on Certificate/Key Storage.

  11. Use cellular-specific examples for SARA modules

    master

    The example/cell directory contains examples specifically designed for u-blox cellular modules, such as the SARA-U201, SARA-R4, and SARA-R5.

    Use these examples when you need to interact with APIs that are specific to cellular behavior via the cell API.

    Note: For general cellular module tasks, refer to the generic examples instead:

  12. Use UBX protocol encode and decode utilities

    master

    The ubx_protocol directory provides utilities for encoding and decoding the UBX protocol, which is used to communicate with u-blox GNSS modules.

    • API: The encoding and decoding functions are located in the api directory.
    • Dependencies: These functions are lightweight and rely only on memcpy() and the common/error/api module for error handling.
    • Testing: You can run the tests located in the test directory on any platform to verify the protocol implementation.