README
¶
Golang NMEA 2000 Library
boatkit-io/n2k
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.
Commands
pgngen
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.
convertdumps
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.
replay
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.
Processing Overview
See the source to replay as an example of the intended use model.
Endpoint
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.
Frame to Packet Adapter
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?
Packet to Struct Adapter
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
Subscribe is a separate package that manages subscribers and distributes go structs (in this case n2k-related) to them.
Build instructions
To be provided
Version History
See changelog
Related Projects
- canboat An open source collection of command line tools and data relevant to NMEA 2000 boat networks
- tbd
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
convertcandumps
Convertcandumps reads, converts, and writes NMEA 2000 dump files.
|
Convertcandumps reads, converts, and writes NMEA 2000 dump files. |
|
pgngen
Command pgngen generates the file pgninfo_generated.go.
|
Command pgngen generates the file pgninfo_generated.go. |
|
pkg
|
|
|
adapter
Package adapter defines an interface to read NMEA 2000 messages and output Packets, an intermediate representation.
|
Package adapter defines an interface to read NMEA 2000 messages and output Packets, an intermediate representation. |
|
adapter/canadapter
Package canadapter implements the adapter interface for n2k endpoints.
|
Package canadapter implements the adapter interface for n2k endpoints. |
|
endpoint
Package endpoint declares an interface.
|
Package endpoint declares an interface. |
|
endpoint/n2kfileendpoint
Package n2kfileendpoint provides reads n2k log files and sends canbus frames to a channel.
|
Package n2kfileendpoint provides reads n2k log files and sends canbus frames to a channel. |
|
endpoint/socketcanendpoint
Package socketcanendpoint contains the SocketCANEndpoint struct described below
|
Package socketcanendpoint contains the SocketCANEndpoint struct described below |
|
endpoint/usbcanendpoint
Package usbcanendpoint contains the USBCANEndpoint struct described below
|
Package usbcanendpoint contains the USBCANEndpoint struct described below |
|
pgn
Package pgn uses data from canboat.json to convert NMEA 2000 messages to strongly-typed golang data.
|
Package pgn uses data from canboat.json to convert NMEA 2000 messages to strongly-typed golang data. |
|
pkt
Package pkt converts input messages to an intermediate (Packet) form, and outputs equivalent golang structs.
|
Package pkt converts input messages to an intermediate (Packet) form, and outputs equivalent golang structs. |
|
subscribe
Package subscribe manages subscriptions to all or specific go structs.
|
Package subscribe manages subscriptions to all or specific go structs. |