boatkit-io/n2k comprises packages (and associated tools) supporting the exchange of NMEA 2000 messages across a range of transports. Client go code can send and receive strongly typed go data structures, with the library translating to/from a stream of NMEA 2000 messages. (The current implementation reads but doesn't write.)
NMEA 2000 is a proprietary industry standard for inter-connecting marine electronic devices. This project leverages the great work of the canboat open-source project that has "reverse engineered the NMEA 2000 database by network observation and assembling data from public sources."
The canboat project includes and references valuable documentation for potential users of this package. This project's documentation assumes readers are familiar with and can reference that documentation as needed.
The pgngen command processes the current canboat.json file (accessed at https://raw.githubusercontent.com/canboat/canboat/master/docs/canboat.json) and generates the file pgninfo_generated.go (github.com/boatkit-io/n2k/pkg/pgn/pgn_generated.go). The generated file provides constants, data types, and decoder functions used to create strongly typed golang data structures for interacting with NMEA 2000 devices.
The command takes no arguments. It caches the canboat.json file in the local file system for an hour to avoid generating unnecessary load on the server and network.
The convertcandumps command converts between a number of NMEA 2000 message representations produced (and sometimes consumed) by NMEA gateways. It reads these formats:
.ydr files, described in Appendix E of https://www.yachtd.com/downloads/ydwg02.pdf. .raw files, formats are described at https://github.com/canboat/canboat/wiki/analyzer. .CAN files, format described in https://www.yachtd.com/downloads/CANVIEW.zip/CANView.pdf. .n2k files, output of linux candump with delta timestamps
It writes .n2k and plain .raw files.
The replay command consumes *.n2k files generated by the convertcandumps command and outputs a textual representation of the resulting golang data structures. It's useful for testing the n2k packages and to understand the NMEA 2000 device interactions.
See the source to replay as an example of the intended use model.
Responsible for managing the interaction with the nmea gateway (or to replay a recording of message frames received from a gateway or other source). To support a new gateway create a new implementation that supports this interface definition.
The endpoint passes new message frames to the adapter through its input function. The data format is determined by the gateway or other source.
Responsible for generating a "packet" from frames received through its input function, and passes complete packets on through its output function. The packet is an intermediate format used by subsequent processors.
This adapter can access a number of helper functions:
- is the PGN known (defined in canboat)?
- is it Proprietary?
- is it Fast or Single?
Receives packet through its input function, decodes it, and passes the resulting Go struct (or an UnknownPGN if it fails to decode the packet) on through its output function.
Subscribe is a separate package that manages subscribers and distributes go structs (in this case n2k-related) to them.
To be provided
See changelog
- canboat An open source collection of command line tools and data relevant to NMEA 2000 boat networks
- tbd