bwolf/gpsd_proto

The `gpsd_proto` module contains types and functions to connect to gpsd to get GPS coordinates and satellite information.

gpsd_proto  

The gpsd_proto module contains types and functions to connect to gpsd to get GPS coordinates and satellite information.

gpsd_proto uses a plain TCP socket to connect to gpsd, reads and writes JSON messages. The main motivation to create this crate was independence from C libraries, like libgps (provided by gpsd) to ease cross compiling.

A example demo application is provided in the example sub directory. Check the repository for up to date sample code.

Testing

gpsd_proto has been tested against gpsd version 3.17 on macOS and Linux with these devices:

• Adafruit Ultimate GPS Breakout - PA1616S
• Quectel EC25 Mini PCIe 4G/LTE Module
• u-blox MAX-M8Q
• GPS mice (Adopt SkyTraQ Venus 8)
• iOS app GPS2IP.

Feel free to report any other supported GPS by opening a GitHub issue.

Reference documentation

Important reference documentation of gpsd are the JSON protocol and the client HOWTO.

Development notes

Start gpsd with a real GPS device:

/usr/local/sbin/gpsd -N -D4 /dev/tty.SLAB_USBtoUART

Or start gpsd with a TCP stream to a remote GPS:

/usr/local/sbin/gpsd -N -D2 tcp://<IP>:<PORT>

Test the connection to gpsd with telnet localhost 2947 and send the string:

?WATCH={"enable":true,"json":true};

gpsd_proto's Issues

Satellite azimuth, elevation, & signal strength coming as floats from gpsd?

Hi; when I use your library with gpsd, Satellite data appears to come across as floating point data, and it was causing Gpsd to not be able to read Satellite / Sky data. I turned up logging, and that captured the JSON data that gpsd_proto sees:

[2020-08-23T04:14:02Z TRACE gpsd_proto] {"class":"SKY","device":"/dev/ttyACM0","xdop":0.44,"ydop":0.57,"vdop":1.12,"tdop":0.70,"hdop":0.72,"gdop":1.50,"pdop":1.33,"satellites":[{"PRN":3,"el":35.0,"az":267.0,"ss":36.0,"used":true,"gnssid":0,"svid":3},{"PRN":4,"el":29.0,"az":311.0,"ss":30.0,"used":true,"gnssid":0,"svid":4},{"PRN":16,"el":41.0,"az":212.0,"ss":36.0,"used":true,"gnssid":0,"svid":16},{"PRN":22,"el":29.0,"az":242.0,"ss":39.0,"used":true,"gnssid":0,"svid":22},{"PRN":25,"el":4.0,"az":46.0,"ss":0.0,"used":false,"gnssid":0,"svid":25},{"PRN":26,"el":82.0,"az":177.0,"ss":40.0,"used":true,"gnssid":0,"svid":26},{"PRN":27,"el":0.0,"az":178.0,"ss":0.0,"used":false,"gnssid":0,"svid":27},{"PRN":29,"el":24.0,"az":58.0,"ss":17.0,"used":true,"gnssid":0,"svid":29},{"PRN":31,"el":56.0,"az":63.0,"ss":36.0,"used":true,"gnssid":0,"svid":31},{"PRN":32,"el":22.0,"az":139.0,"ss":34.0,"used":true,"gnssid":0,"svid":32},{"PRN":46,"el":15.0,"az":247.0,"ss":38.0,"used":true,"gnssid":1,"svid":133},{"PRN":51,"el":29.0,"az":227.0,"ss":0.0,"used":false,"gnssid":1,"svid":138},{"PRN":65,"el":59.0,"az":206.0,"ss":31.0,"used":true,"gnssid":6,"svid":1},{"PRN":66,"el":38.0,"az":321.0,"ss":34.0,"used":true,"gnssid":6,"svid":2},{"PRN":72,"el":22.0,"az":172.0,"ss":35.0,"used":true,"gnssid":6,"svid":8},{"PRN":74,"el":22.0,"az":49.0,"ss":0.0,"used":false,"gnssid":6,"svid":10},{"PRN":75,"el":68.0,"az":346.0,"ss":34.0,"used":true,"gnssid":6,"svid":11},{"PRN":76,"el":37.0,"az":261.0,"ss":34.0,"used":true,"gnssid":6,"svid":12},{"PRN":83,"el":4.0,"az":6.0,"ss":18.0,"used":false,"gnssid":6,"svid":19},{"PRN":84,"el":15.0,"az":59.0,"ss":0.0,"used":false,"gnssid":6,"svid":20},{"PRN":85,"el":6.0,"az":113.0,"ss":27.0,"used":true,"gnssid":6,"svid":21}]}

[2020-08-23T04:14:02Z ERROR offline_maps::gpsd] gpsd thread died with error: Gpsd(JsonError(Error("invalid type: floating point `35`, expected i16", line: 0, column: 0)))

As you can see, the values look like floats, like 35.0 for the el member of the first satellite in that packet. The weird thing is, I've definitely used gpsd, gpsd_proto, and this GPS hardware together before, and it has worked just fine. I know neither the hardware nor the version of gpsd_proto has changed, which makes me think this is a change in gpsd, and how it encodes data.

While I get what look like floats, they always seem to end in .0.

It was pretty easy to change gpsd_proto to be floats; I'll send a PR too, shortly.

In case it matters,
I'm using gpsd: 3.21 (revision 3.21) (I'm not sure what the version was when everything was working.)
gpsd_proto 0.6.0
My device identifies itself just as a "G-MOUSE"; it looks exactly like this;

Bus 001 Device 007: ID 1546:01a8 U-Blox AG [u-blox 8]

Lastly, thank you for gpsd_proto; it's been very easy & nice to use.

Update Tokio, Futures versions

This project currently assumes version 0.1 for tokio and futures, but they are now on version 0.3. Trying to upgrade them causes the async.rs example to break. I'm still learning Rust, so it might be a while before I'm comfortable tackling this myself.

`Device.activated` fails on zeros

I've noticed lately that due to something flaky with my hardware or with gpsd, it tends to emits these JSON messages:

{"class":"DEVICE","path":"/dev/ttyAMA0","activated":0}

Serde fails to parse this. The error I get from gpd_proto::get_data() is:

JsonError(Error("invalid type: integer `0`, expected a string", line: 0, column: 0))

Since Device.activated is an Option<String>, this appears to be why it fails on 0, an integer.

According to the gpsd documentation, the "activated" field is only a string, so at first I thought this is a bug in gpsd, since it's not writing the correct output. But apparently this is intentional, since later on in the documentation is this example output:

{"class":"DEVICE","path":"/dev/pts1","activated":0}

So my interpretation is that that the Device.activated should still be an Option<String>, but that a value of 0 should parse as None. Is this possible to do?

(Alternately, it could be an Option<StringOrInt> with an enum for StringOrInt, but that seems excessive and would be an API change.)

Supports Adafruit GPS

It also supports the Adafruit Ultimate GPS Breakout v3 running on Debian Bookworm, gpsd version 3.22 (revision 3.22).

PPS responses not handled

It seems that PPS responses from gpsd are not handled, so gpsd_proto panics.

Here's a log at trace level:

[2019-06-22T08:43:38Z TRACE gpsd_proto] {"class":"VERSION","release":"3.16","rev":"3.16-4","proto_major":3,"proto_minor":11}

[2019-06-22T08:43:38Z TRACE gpsd_proto] {"class":"DEVICES","devices":[{"class":"DEVICE","path":"/dev/ttyAMA0","driver":"u-blox","subtype":"SW ROM CORE 3.01 (107888),HW 00080000,FWVER=SPG 3.01,PROTVER=18","activated":"2019-06-22T08:43:38.163Z","flags":1,"native":1,"bps":9600,"parity":"N","stopbits":1,"cycle":1.00,"mincycle":0.25},{"class":"DEVICE","path":"/dev/pps0","driver":"PPS","activated":"2019-06-22T08:43:38.001Z"}]}

[2019-06-22T08:43:38Z TRACE gpsd_proto] {"class":"WATCH","enable":true,"json":true,"nmea":false,"raw":0,"scaled":false,"timing":false,"split24":false,"pps":false}

[2019-06-22T08:43:39Z TRACE gpsd_proto] {"class":"PPS","device":"/dev/pps0","real_sec":1561193019, "real_nsec":0,"clock_sec":1561193019,"clock_nsec":286,"precision":-20}

thread 'main' panicked at 'gpsd error: JsonError(Error("unknown variant `PPS`, expected one of `DEVICE`, `TPV`, `SKY`", line: 1, column: 14))', src/libcore/result.rs:997:5
note: Run with `RUST_BACKTRACE=1` environment variable to display a backtrace.

GST responses not parsed

Similar to #1, GST responses are not parsed. I'll submit a pull request shortly.

[2019-07-14T00:16:41Z TRACE gpsd_proto] {"class":"GST","device":"/dev/ttyAMA0","time":"2019-07-14T00:44:02.000Z","rms":5947882.000,"lat":16.000,"lon":11.000,"alt":18.000}

thread '<unnamed>' panicked at 'Unexpected gpsd data: JsonError(Error("unknown variant `GST`, expected one of `DEVICE`, `TPV`, `SKY`, `PPS`", line: 1, column: 14))', src/libcore/result.rs:997:5

These started getting emitted after I updated gpsd from 3.16 to 3.17.