Re: ✘example

[Gary E. Miller]

Yo Joshua!

On Sun, 7 Mar 2021 19:15:16 -0500
Joshua Judson Rosen <rozzin@hackerposse.com> wrote:

> I don't know about the general audience, but I can speak for
> FoxtrotGPS, which was called out in that but report.
> 
> The same person also field a bug in our tracker:
> 
>       https://bugs.launchpad.net/foxtrotgps/+bug/1917998

Good, that is how things get fices.

> Maybe it's not _exactly_ the same issue on both ends, because
> on your end he's pointing to the absence of a value in the _protocol
> stream_, and on our end he's pointing to our use of a member in the
> gps_fix_t structure in the API..., but:

Same item, just different stages of the pipeline.

> I think our `misunderstanding' in FoxtrotGPS came from the comments
> in gps.h, which we were looking at because it felt like the only
> practical documentation that we had since there wasn't any description
> of the data library structures in the libgps man page;

Because it is described in gpsd_json man page.

> these lines in particular:
> 
>           /* GPS status -- always valid */
>           int    status;              /* Do we have a fix? */
>       #define STATUS_NO_FIX   0       /* no */

Sure, it is always valid, just not saying what you think it says.
You conveniently snipped the next lines:

#define STATUS_FIX     1       /* yes, GPS, without DGPS */
#define STATUS_DGPS_FIX        2       /* yes, with DGPS */
#define STATUS_RTK_FIX 3       /* yes, with RTK Fixed */
#define STATUS_RTK_FLT 4       /* yes, with RTK Float */
#define STATUS_DR      5       /* yes, with dead reckoning */
#define STATUS_GNSSDR  6       /* yes, with GNSS + dead reckoning */
#define STATUS_TIME    7       /* yes, time only (surveyed in) */

I'll have to make clear that is orthonal to a 2D or 3D fix.  As defined
by the receiver vendors, those can be set when there is no valid fix.

And lsat week I adeed:

    /* GPS status, aka fix type, is a modifier (adjective) to
     * gps_data.mode.  It is not a replacement for, or superset of, mode.
     * It is almost, but not quite, the same as the NMEA 4.x xxGGA GPS
     * Quality Indicator Values.  Many GNSS receivers do not supply it.
     */
    int    status;              /* What kind of fix? */
#define STATUS_NO_FIX   0       // Unknown status, maybe no fix.

Is that clear now?  It it now obvious that "unknown" is also valid?

A lot of the confusion is that NMEA keeps changing what that means.

Anything else I need to do to make that clearer?

> You say:
> 
>       "no status field" is perfectly normal in many configurations.
>       [...]
> 
>       This statement was never, ever, true:
> 
>       "they assume that gpsdata.fix.status == 0 means no fix."
> 
> OK. I guess I have to read that as "the comments in gps.h have been
> actively misleading us for the last decade" (that "always valid"
> remark in particular directly contradicts everything that you just
> wrote in that ticket that diego filed).

It was "valid", it just did not mean what you thought it did.  It is
about DGPS, RTK P(y), etc., not whether you have a 2D or 3D fix.

> Thank you for for fixing it :)

Is it fixed?  Does not really feel done to me.

> As far as this remark goes:
> 
>       The man page shows "mode" is the proper way to check for a
> fix.
> 
> There isn't even a reference to that man page from the libgps man
> page, and I could be wrong but I don't _think_ there even ever was.

Good point.  I just added it.  I'm pretty sure gpsd_json does not belong
in man1.  So much to fix...

> If you want users of the library to go read the protocol docs,
> at least point to the protocol docs from the API docs.

Anything else, more than adding See Also gpsd_jons to libgps?

> I think what you're trying to do right now with providing examples
> is better, though; but really, just fixing the misleading remarks
> in the header would have been enough for us.

Does it need anything beyond the current state?  Currently it is:

----
    /* GPS status, aka fix type, is a modifier (adjective) to
     * gps_data.mode.  It is not a replacement for, or superset of, mode.
     * It is almost, but not quite, the same as the NMEA 4.x xxGGA GPS
     * Quality Indicator Values.  Many GNSS receivers do not supply it.
     */
    int    status;              /* What kind of fix? */
#define STATUS_NO_FIX   0       // Unknown status, maybe no fix.
/* yes, plain GPS (SPS Mode), without DGPS, PPS, RTK, DR, etc. */
#define STATUS_FIX      1
#define STATUS_DGPS_FIX 2       /* yes, with DGPS */
#define STATUS_RTK_FIX  3       /* yes, with RTK Fixed */
#define STATUS_RTK_FLT  4       /* yes, with RTK Float */
#define STATUS_DR       5       /* yes, with dead reckoning */
#define STATUS_GNSSDR   6       /* yes, with GNSS + dead reckoning */
#define STATUS_TIME     7       /* yes, time only (surveyed in, manual) */
// Note that STATUS_SIM and MODE_NO_FIX can go together.
#define STATUS_SIM      8       /* yes, simulated */
/* yes, Precise Positioning Service (PPS)
 * Not to be confused with Pulse per Second (PPS)
 * PPS is the encrypted military P(Y)-code */
#define STATUS_PPS_FIX  9
----



> Thanks again.

And thanks for the feed back.

RGDS
GARY
---------------------------------------------------------------------------
Gary E. Miller Rellim 109 NW Wilmington Ave., Suite E, Bend, OR 97703
        gem@rellim.com  Tel:+1 541 382 8588

            Veritas liberabit vos. -- Quid est veritas?
    "If you can't measure it, you can't improve it." - Lord Kelvin

pgpTPQnU3YtmF.pgp
Description: OpenPGP digital signature