GNSS: API ambiguities

[JordanYates]

Is your enhancement proposal related to a problem? Please describe.

There are several aspects of the GNSS API which appear under-defined to me. Time and location are two concepts where the devil is in the details.

1. What is the default state of a GNSS modem in PM_DEVICE_STATE_ACTIVE?

It appears as though the default state is "whatever the modem decides to do". Presumably most receivers default to a 1Hz NMEA output when they first boot up, but is an updated rate through gnss_set_fix_rate preserved after a suspend?

2. struct navigation_data has no reference frame

What is the reference frame of the geolocation data?

• WGS-84
• PZ-90
• GTRF

3. altitude has no reference point

What is the reference height of the altitude parameter?

• Mean Sea Level
• Reference frames (e.g. Height above the WGS-84 ellipsoid)

4. When can the values in struct gnss_time be trusted?

It is documented as being in UTC time format, but for GPS at least leap second information is only broadcast once every 12.5 minutes.

5. Which UTC time base is struct gnss_time?

This is a small problem relative to the others, but which UTC time base is the data in struct gnss_time? Each GNSS constellation uses a difference UTC reference, which can differ slightly from each other.

• GPS -> United States Naval Observatory
• BeiDou -> National Time Service Center
• etc

Describe the solution you'd like

Consistent definitions for the various states and terms so that users of the API can expect the same behaviour/outputs regardless of the modem.

Failing that, a way to determine which output form the data is in.

[bjarki-andreasen]

For now, all of these are the "default" the GNSS is configured with. The idea is to provide generic Kconfigs to set the references to use by the GNSS. This is with the presumption that all GNSS modems and other navigation subsystems in an application will use the same references, and not switch references at runtime. For this reason, they are not exposed in any of the runtime APIs, the values there are the "final" post processed values.

There is no GNSS implementing configuring the references/datums, hence they Kconfigs have not been introduced yet :)

[bjarki-andreasen]

Regarding PM, the configurations survive resume/suspend cycles, this includes set_fix_rate(). I'm going to create a PR to remove the set_periodic_config() API since it is conflicting with using PM to manage the state of the GNSS.

[JordanYates]

For now, all of these are the "default" the GNSS is configured with. The idea is to provide generic Kconfigs to set the references to use by the GNSS. This is with the presumption that all GNSS modems and other navigation subsystems in an application will use the same references, and not switch references at runtime. For this reason, they are not exposed in any of the runtime APIs, the values there are the "final" post processed values.

There is no GNSS implementing configuring the references/datums, hence they Kconfigs have not been introduced yet :)

There are two separate issues here. Switching between references at runtime is not really what I am concerned about.

The question I am interested in is "What format is my data in?" As far as I can tell, the current answer is "Look up the exact part number of your GNSS modem, then read through its datasheet/application notes".

[JordanYates]

6. Positive leap seconds not represent-able by struct gnss_time

The following valid UTC times are not representable within the documented /** Millisecond [0, 59999] */ range:

TAI=2009-01-01T00:00:33.0; UTC=2008-12-31T23:59:60.0; UT1≅2008-12-31T23:59:59.407
TAI=2009-01-01T00:00:33.5; UTC=2008-12-31T23:59:60.5; UT1≅2008-12-31T23:59:59.907

http://www.madore.org/~david/computers/unix-leap-seconds.html

[bjarki-andreasen]

6. Positive leap seconds not represent-able by struct gnss_time

The following valid UTC times are not representable within the documented /** Millisecond [0, 59999] */ range:

TAI=2009-01-01T00:00:33.0; UTC=2008-12-31T23:59:60.0; UT1≅2008-12-31T23:59:59.407
TAI=2009-01-01T00:00:33.5; UTC=2008-12-31T23:59:60.5; UT1≅2008-12-31T23:59:59.907

http://www.madore.org/~david/computers/unix-leap-seconds.html

Right, we can extend it to 60999 :)

[bjarki-andreasen]

For now, all of these are the "default" the GNSS is configured with. The idea is to provide generic Kconfigs to set the references to use by the GNSS. This is with the presumption that all GNSS modems and other navigation subsystems in an application will use the same references, and not switch references at runtime. For this reason, they are not exposed in any of the runtime APIs, the values there are the "final" post processed values.

There is no GNSS implementing configuring the references/datums, hence they Kconfigs have not been introduced yet :)

There are two separate issues here. Switching between references at runtime is not really what I am concerned about.

The question I am interested in is "What format is my data in?" As far as I can tell, the current answer is "Look up the exact part number of your GNSS modem, then read through its datasheet/application notes".

~I will extend the Quectel lcx76 driver~ to illustrate how to configure/respect references at build time using Kconfig, it will look something like:

choice GNSS_REFERENCE_FRAME
        bool "reference frame"

config GNSS_REFERENCE_FRAME_WGS84
        ...

endchoice

where either a gnss device driver will configure it to use said reference on boot, or depend on the one it uses if it can't be configured. The application can use the choice to know what format the data is in :)