Add public GNSS API for obtaining and processing navigation data #61073

bjarki-trackunit · 2023-08-02T12:22:09Z

Introduction

This PR adds a device driver API for GNSS modems.

Navigation data

The first commit adds a header with a proposed data type and a set of utilities to lay the foundation for working with navigation data in a manner abstracted away from the specific source of said data. Navigation data can be obtained from different sources, such as GNSS, WiFi location, cell tower triangulation etc. Processing the data once obtained is identical, which is the reason the navigation data type and utilities are split apart from the GNSS API.

GNSS API

The second commit contains the GNSS API itself. This API provides a function to obtain navigation data as described in the first commit, along with a bunch of GNSS specific features, like setting fix intervals, getting GNSS status etc, which can be used to determine and configure the accuracy of the supplied navigation data for example.

Relevant information before reviewing

The API has been designed to accommodate the common features of the following GNSS modems:

Quectel LC76G
TELIT SE868
Quectel BG96 (internal GNSS)
Quectel L76LL
UBLOX NEO M8

This commit contains a driver for the Quectel LCX6G GNSS modem, along with a collection of libraries for parsing NMEA messages and string formatted integers.

fabiobaltieri · 2023-08-02T15:56:09Z

Thanks for working on this! Love the navigation utils library idea!

For the API, how about:

instead of gnss_get_nav_data(), have an iterable section to register callbacks at build time that would get a pointer of the data structure automatically every time it's updated (thinking like the input one, then it'd be very easy to integrate with zbus down the road)
in struct gnss_driver_api, all the other APIs are set/get pairs, how about just having two generic set_parameter, get_parameter pair? If anything that would keep the API compact and extensible without having to have so many pointers in the structure, thinking you may still do inline wrapper for standard ones so you still have type checking and validation.

fabiobaltieri · 2023-08-02T15:59:01Z

cc @brec-u-blox @jakkra any interest from u-blox folks on this?

jakkra · 2023-08-02T16:30:03Z

cc @brec-u-blox @jakkra any interest from u-blox folks on this?

Yes probably @RobMeades as he is responsible for our ubxlib GNSS library
Maybe also FYI @plerup

rodrigopex · 2023-08-02T17:12:47Z

Great work! Integrating with ZBus (in the future) is an excellent way to go. Some ZBus channels could share the events and nav data. Agree with @fabiobaltieri about iterable sections. However, I imagine the gnss_get_nav_data would still be necessary for some cases.

include/zephyr/data/navigation.h

bjarki-trackunit · 2023-08-02T18:17:56Z

instead of gnss_get_nav_data(), have an iterable section to register callbacks at build time that would get a pointer of the data structure automatically every time it's updated (thinking like the input one, then it'd be very easy to integrate with zbus down the road)

The navigation data provided by an instance of a GNSS device driver is not necessarily completely abstract. An application wanting to share navigation data should do something like the following:

Get GNSS info (number of sats, hdop etc.)
Validate quality of fix (subjective to the application)
Get navigation data from GNSS
Process navigation data (publish on ZBUS for example)

The GNSS API presents the capabilities of the GNSS (getting the data), processing the data is the responsibility of the application.

in struct gnss_driver_api, all the other APIs are set/get pairs, how about just having two generic set_parameter, get_parameter pair? If anything that would keep the API compact and extensible without having to have so many pointers in the structure, thinking you may still do inline wrapper for standard ones so you still have type checking and validation.

The types passed to the functions are not identical, like they are in an API like the sensor API, leading to void * and typecasting on both sides of the API. In this case, having fewer pointers in the API struct will be at the cost of type safety, which I value over saving ROM.

fabiobaltieri · 2023-08-02T18:41:30Z

The navigation data provided by an instance of a GNSS device driver is not necessarily completely abstract. An application wanting to share navigation data should do something like the following:
* Get GNSS info (number of sats, hdop etc.)

* Validate quality of fix (subjective to the application)

* Get navigation data from GNSS

* Process navigation data (publish on ZBUS for example)
The GNSS API presents the capabilities of the GNSS (getting the data), processing the data is the responsibility of the application.

Right but it's an inherently event-driven type of device (new set of data available), thinking that a callback based API would suit it well, in this case it would notify a of new data available (navigation, fix quality etc... guess it makes sense to split them out since they can arrive at different frequency).

The types passed to the functions are not identical, like they are in an API like the sensor API, leading to void * and typecasting on both sides of the API. In this case, having fewer pointers in the API struct will be at the cost of type safety, which I value over saving ROM.

Yeah that's fair, though from what I recall API proposals with an extensive set of functions are usually hard to justify. Anyway, worth trying.

bjarki-trackunit · 2023-08-03T10:52:49Z

Right but it's an inherently event-driven type of device (new set of data available), thinking that a callback based API would suit it well, in this case it would notify a of new data available (navigation, fix quality etc... guess it makes sense to split them out since they can arrive at different frequency).

Do you have an example of an existing event-driven device driver API? I am not entirely sure what an event driven device driver API would look like, it sounds closer to a subsystem to me? Like the navigation header could become a subsystem to which applications and GNSS modem could register as listener/publisher?

fabiobaltieri · 2023-08-03T13:39:47Z

Do you have an example of an existing event-driven device driver API? I am not entirely sure what an event driven device driver API would look like, it sounds closer to a subsystem to me? Like the navigation header could become a subsystem to which applications and GNSS modem could register as listener/publisher?

Yeah, input has that as the only API:

zephyr/include/zephyr/input/input.h

Lines 138 to 143 in 168de28

    
           #define INPUT_LISTENER_CB_DEFINE(_dev, _callback)                              \ 
        
           	static const STRUCT_SECTION_ITERABLE(input_listener,                   \ 
        
           					     _input_listener__##_callback) = { \ 
        
           		.dev = _dev,                                                   \ 
        
           		.callback = _callback,                                         \ 
        
           	}

but there's plenty of those, bluetooth uses a similar pattern for most of the callbacks.

cfriedt · 2023-08-03T16:00:28Z

dev-review: discussed runtime callback registration, vs iterable section callback registration, sensing subsystem comparison (distributing information, events). Maybe make some of those options available via Kconfig?

important: GNSS uses fixed-point math for high-precision calculations (used extensively as well by MISB). Is there a standard library that can be used? Can we implement something for Zephyr? Do we already have something in a module that can be used?

bjarki-trackunit · 2023-08-03T18:00:26Z

Update

After dev-review, I will update the callback mechanism for navigation_data, gnss info and gnss time to work similar to the INPUT_LISTENER_CB_DEFINE, and continue work on the fixed point navigation utilities :)

This commit adds dumping of GNSS data and satellites to the log if CONFIG_GNSS_DUMP_TO_LOG is selected Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

This commit adds parsing utilites for common string representations of values contained in GNSS messages. These utilites both parse and validate the integrity of the data. Unit tests are also added to validate the parsing utilities. Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

This commit adds utilites to parse the RMC and GGA NMEA0183 messages, which contain all data which shall be published using the struct gnss_data. It also adds a test suite for the added utilities. Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

This commit adds generic matches and handlers for the RMC, GGA and GSV messages to be implemented as part of all NMEA0183 based GNSS modems. NMEA0183 based GNSS modems must place the struct gnss_nmea0183_match_data struct as the first struct in their data struct. Their data struct shall then be set as the user_data for the modem_chat instance. Lastly, the gnss_nmea0183_match callbacks must be included in the unsolicited matches for the modem_chat instance. The GNSS modems will initialize the NMEA0183 match instance using gnss_nmea0183_match_init. Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

This commit adds a GNSS driver for the Quectel LCX6G series of GNSS modems (LC26G, LC76G, LC86G). It is based on the modem subsystem, and the GNSS utilities added in the two previous commits. Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

This commit adds a sample which configures a GNSS modem to enable all available systems, registers callbacks to the GNSS data and satellites callbacks, and prints the GNSS data and satellites from the callbacks when invoked using printk. Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

- Added GNSS documentation entry to peripherals - Added GNSS API entry to the API overview as 3.6 experimental Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

fabiobaltieri · 2023-10-30T16:54:21Z

Great job @bjarki-trackunit!

bjarki-trackunit · 2023-10-30T16:57:40Z

@fabiobaltieri Thanks for the help!

kartben · 2023-11-03T17:59:11Z

include/zephyr/data/navigation.h

+int navigation_distance(uint64_t *distance, const struct navigation_data *p1,
+			const struct navigation_data *p2);
+
+/**
+ * @brief Calculate the bearing from one navigation point to another
+ *
+ * @param bearing Destination for calculated bearing angle in millidegrees
+ * @param from First navigation point
+ * @param to Second navigation point
+ *
+ * @return 0 if successful
+ * @return -EINVAL if either navigation point is invalid
+ */
+int navigation_bearing(uint32_t *bearing, const struct navigation_data *from,
+		       const struct navigation_data *to);


@bjarki-trackunit quick Q: was this intentional that these don't seem to have an implementation just yet? Just asking in case this was meant to be included in the PR and was somehow missed :)

I completely forgot about those! They still need an implementation

michael-whg · 2023-11-15T00:18:01Z

drivers/gnss/gnss_parse.c

+	int64_t increment;
+
+	__ASSERT(str != NULL, "str argument must be provided");
+	__ASSERT(str != NULL, "nano argument must be provided");


str is being checked instead of nano

could you send a PR with the fix?

Oleh-Kravchenko · 2023-11-17T15:41:57Z

@bjarki-trackunit,
Where is generic driver for simple NMEA over UART?

bjarki-trackunit · 2023-11-17T16:07:56Z

@bjarki-trackunit,
Where is generic driver for simple NMEA over UART?

All generic NMEA parsing is part of the gnss_nmea0183_match library, a driver will have to implement initialization and power management on top of this. See the quectel one for inspiration :)

fabiobaltieri · 2023-11-17T16:10:37Z

All generic NMEA parsing is part of the gnss_nmea0183_match library, a driver will have to implement initialization and power management on top of this. See the quectel one for inspiration :)

I have one in draft, may send it out over the weekend, did it while this was still in review and never got around to test it again.

Oleh-Kravchenko · 2023-11-17T19:10:12Z

@bjarki-trackunit,
Where is generic driver for simple NMEA over UART?

All generic NMEA parsing is part of the gnss_nmea0183_match library, a driver will have to implement initialization and power management on top of this. See the quectel one for inspiration :)

I've already did, but it doesn't work :)
It is also very hard to debug, no logs :(

bjarki-trackunit · 2023-11-17T19:12:24Z

@bjarki-trackunit,
Where is generic driver for simple NMEA over UART?

All generic NMEA parsing is part of the gnss_nmea0183_match library, a driver will have to implement initialization and power management on top of this. See the quectel one for inspiration :)

I've already did, but it doesn't work :)
It is also very hard to debug, no logs :(

CONFIG_MODEM_MODULES_LOG_LEVEL_DBG=y
CONFIG_LOG=y

Oleh-Kravchenko · 2023-11-17T19:14:05Z

@bjarki-trackunit,
Where is generic driver for simple NMEA over UART?

All generic NMEA parsing is part of the gnss_nmea0183_match library, a driver will have to implement initialization and power management on top of this. See the quectel one for inspiration :)

I've already did, but it doesn't work :)
It is also very hard to debug, no logs :(

CONFIG_MODEM_MODULES_LOG_LEVEL_DBG=y CONFIG_LOG=y

It's generate raw input from UART, but doesn't give any clue why it doesn't accept input:

D: $GNGGA, 151513.00 5020.00000 N 02020.0000 E 1 12 0.68 167.5 M 25.7 M 43

fabiobaltieri · 2023-11-17T19:39:33Z

@bjarki-trackunit @Oleh-Kravchenko #65422

drivers/gnss/gnss_nmea0183.h

bjarki-trackunit force-pushed the feature_add_public_gnss_api branch from cf12c79 to 7111a97 Compare August 2, 2023 12:22

bjarki-trackunit added DNM This PR should not be merged (Do Not Merge) area: API Changes to public APIs labels Aug 2, 2023

bjarki-trackunit self-assigned this Aug 2, 2023

bjarki-trackunit requested a review from fabiobaltieri August 2, 2023 12:25

bjarki-trackunit mentioned this pull request Aug 2, 2023

drivers/location: Add location API #48536

Closed

bjarki-trackunit requested review from ycsin and jukkar August 2, 2023 12:28

bjarki-trackunit force-pushed the feature_add_public_gnss_api branch from 7111a97 to 9acab96 Compare August 2, 2023 12:34

bjarki-trackunit marked this pull request as ready for review August 2, 2023 12:37

bjarki-trackunit requested review from nashif, carlescufi, galak and MaureenHelm as code owners August 2, 2023 12:37

zephyrbot added the area: JSON label Aug 2, 2023

zephyrbot requested review from mrfuchs and Sir-Branch August 2, 2023 12:38

fabiobaltieri reviewed Aug 2, 2023

View reviewed changes

include/zephyr/data/navigation.h Show resolved Hide resolved

henrikbrixandersen self-requested a review August 5, 2023 07:27

nashif added the Architecture Review Discussion in the Architecture WG required label Aug 5, 2023

bjarki-trackunit added 7 commits October 29, 2023 17:11

drivers: gnss: Add GNSS dump to log feature

9e0ae96

This commit adds dumping of GNSS data and satellites to the log if CONFIG_GNSS_DUMP_TO_LOG is selected Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

doc: gnss: Add GNSS documentation

7da47ff

- Added GNSS documentation entry to peripherals - Added GNSS API entry to the API overview as 3.6 experimental Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

bjarki-trackunit dismissed stale reviews from kartben and fabiobaltieri via 7da47ff October 29, 2023 16:12

bjarki-trackunit force-pushed the feature_add_public_gnss_api branch from 3e7bb87 to 7da47ff Compare October 29, 2023 16:12

bjarki-trackunit requested review from cfriedt and rerickson1 October 29, 2023 16:13

rerickson1 approved these changes Oct 30, 2023

View reviewed changes

fabiobaltieri approved these changes Oct 30, 2023

View reviewed changes

cfriedt approved these changes Oct 30, 2023

View reviewed changes

cfriedt merged commit 42676e3 into zephyrproject-rtos:main Oct 30, 2023
20 of 21 checks passed

kartben reviewed Nov 3, 2023

View reviewed changes

michael-whg reviewed Nov 15, 2023

View reviewed changes

michael-whg mentioned this pull request Nov 15, 2023

drivers: gnss: Fix nano parameter not being checked in __ASSERT #65201

Merged

mayankmahajan-nxp reviewed Dec 7, 2023

View reviewed changes

drivers/gnss/gnss_nmea0183.h Show resolved Hide resolved

tomi-font mentioned this pull request Feb 19, 2024

cherry pick modem subsystem nrfconnect/sdk-zephyr#1503

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add public GNSS API for obtaining and processing navigation data #61073

Add public GNSS API for obtaining and processing navigation data #61073

bjarki-trackunit commented Aug 2, 2023 •

edited

fabiobaltieri commented Aug 2, 2023 •

edited

fabiobaltieri commented Aug 2, 2023 •

edited

jakkra commented Aug 2, 2023

rodrigopex commented Aug 2, 2023 •

edited

bjarki-trackunit commented Aug 2, 2023

fabiobaltieri commented Aug 2, 2023

bjarki-trackunit commented Aug 3, 2023

fabiobaltieri commented Aug 3, 2023

cfriedt commented Aug 3, 2023

bjarki-trackunit commented Aug 3, 2023

fabiobaltieri commented Oct 30, 2023

bjarki-trackunit commented Oct 30, 2023

kartben Nov 3, 2023

bjarki-trackunit Nov 3, 2023

michael-whg Nov 15, 2023

fabiobaltieri Nov 15, 2023

Oleh-Kravchenko commented Nov 17, 2023

bjarki-trackunit commented Nov 17, 2023

fabiobaltieri commented Nov 17, 2023 •

edited

Oleh-Kravchenko commented Nov 17, 2023

bjarki-trackunit commented Nov 17, 2023

Oleh-Kravchenko commented Nov 17, 2023

fabiobaltieri commented Nov 17, 2023

Add public GNSS API for obtaining and processing navigation data #61073

Add public GNSS API for obtaining and processing navigation data #61073

Conversation

bjarki-trackunit commented Aug 2, 2023 • edited

Introduction

Navigation data

GNSS API

Relevant information before reviewing

fabiobaltieri commented Aug 2, 2023 • edited

fabiobaltieri commented Aug 2, 2023 • edited

jakkra commented Aug 2, 2023

rodrigopex commented Aug 2, 2023 • edited

bjarki-trackunit commented Aug 2, 2023

fabiobaltieri commented Aug 2, 2023

bjarki-trackunit commented Aug 3, 2023

fabiobaltieri commented Aug 3, 2023

cfriedt commented Aug 3, 2023

bjarki-trackunit commented Aug 3, 2023

Update

fabiobaltieri commented Oct 30, 2023

bjarki-trackunit commented Oct 30, 2023

kartben Nov 3, 2023

Choose a reason for hiding this comment

bjarki-trackunit Nov 3, 2023

Choose a reason for hiding this comment

michael-whg Nov 15, 2023

Choose a reason for hiding this comment

fabiobaltieri Nov 15, 2023

Choose a reason for hiding this comment

Oleh-Kravchenko commented Nov 17, 2023

bjarki-trackunit commented Nov 17, 2023

fabiobaltieri commented Nov 17, 2023 • edited

Oleh-Kravchenko commented Nov 17, 2023

bjarki-trackunit commented Nov 17, 2023

Oleh-Kravchenko commented Nov 17, 2023

fabiobaltieri commented Nov 17, 2023

bjarki-trackunit commented Aug 2, 2023 •

edited

fabiobaltieri commented Aug 2, 2023 •

edited

fabiobaltieri commented Aug 2, 2023 •

edited

rodrigopex commented Aug 2, 2023 •

edited

fabiobaltieri commented Nov 17, 2023 •

edited