The canboat binary

canboat is one executable with subcommands: it does what CANboat's C programs do, plus canboat server, canboat tui and the gateways the C drivers never had. Both are tier 1: supported, tested and released together, and where both do a job they are interchangeable. The C programs are in c/programs.md.

The PGN database is compiled into it: there is nothing to load at runtime, and every subcommand decodes the same way.

Every subcommand takes --help. using.md puts them together into pipelines.

Warning

The PGN database is reverse engineered. Most definitions have been confirmed against several devices, but some fields are educated guesses. Do not build something safety-critical on a decoded value without checking it against what the instrument itself shows.

canboat convert

Decodes a capture, or converts it to another capture format. The input format is detected from the first line, or set with --from; .pcap, .pcap.gz and .nif containers are unwrapped. file-formats.md lists the formats.

canboat convert capture.log                 # JSON
canboat convert --to text capture.log       # human-readable
canboat convert --to plain capture.candump  # canboat PLAIN, for analyzer
canboat convert --pgn 129025 --src 3 capture.log

$ canboat convert small.log
{"version":"8.3.0","commit":"7ac57fdb","units":"si","protocol":"nmea2000","showLookupValues":false}
{"timestamp":"2011-11-24T22:42:04.388Z","prio":2,"src":36,"dst":255,"pgn":127251,"description":"Rate of Turn","fields":{"sid":125,"rate":0.0050963438}}
{"timestamp":"2011-11-24T22:42:04.390Z","prio":2,"src":36,"dst":255,"pgn":127250,"description":"Vessel Heading","fields":{"sid":0,"heading":3.1834,"deviation":0.0000,"variation":0.0000,"reference":"Magnetic"}}

The first line is a header, not a message: the version, the units, the protocol, and whether lookups are written as value and name (--no-banner leaves it out). Its JSON is not quite the C analyzer's: field keys are lowerCamelCase and values are in SI units (radians, kelvin, pascal). --id spaces --units metric gives analyzer's keys and units. --nv, --empty and --debug match analyzer's -nv, -empty and -debug (--no-nv says the default, as server takes both too); --protocol j1939 or quick decodes those buses. --quirk gps-rollover corrects dates, as in server.md.

canboat interface

Bridges a live gateway to stdin and stdout, in canboat's FAST format: what it receives goes to stdout, what it reads on stdin goes onto the bus.

canboat interface --kind actisense /dev/ttyUSB0
canboat interface --kind yachtd tcp://ydwg
canboat interface --kind socketcan can0

-r only reads, -w only writes, and -b sets the baud rate. The gateways, their options and their PGN lists are in gateways.md.

canboat server

The whole gateway → decode → serve chain in one process; see server.md.

canboat n2kd

Reads decoded JSON on stdin, from analyzer -json or canboat convert, and serves it to TCP clients on the same ports as canboat server, from base port 2597 (-p): the snapshot, the JSON stream, NMEA 0183, the raw input port and the AIS snapshot. It listens on 127.0.0.1 unless given --public.

actisense-serial -r /dev/ttyUSB0 | analyzer -json -nv | canboat n2kd

It replaces the C n2kd, which was removed in v8. For a new setup, canboat server is usually the better choice: being one process, it can also answer ISO Requests and Group Functions, track the devices on the bus, and request what has gone stale. Use canboat n2kd when you want the pipeline, for instance to decode elsewhere or to tee a stage with iptee.

canboat tui

An interactive terminal browser: the PGNs on the bus, the devices sending them, and the decoded fields of the one you select.

canboat tui --host pi.local       # a canboat server or n2kd
canboat tui --log capture.log     # a capture

It reads the snapshot (2597) and JSON stream (2598) ports. There is no default host: with neither option it starts idle, with a dialog to load a capture or connect.

canboat format-message

Builds one message from field values, for any PGN, in canboat PLAIN or another format (--to). A number is in the field's unit; raw:N writes the wire bits.

canboat format-message --list               # every PGN
canboat format-message 126996 --help        # a PGN's fields
canboat format-message isoRequest --dst 0 PGN=126996

canboat replay

Writes a PLAIN or FAST capture from stdin to stdout at the pace it was recorded, as the C replay does. canboat server --replay serves a capture as a live bus instead; see server.md.

canboat install-shims

Makes the subcommands answer to the old names (analyzer, n2kd, actisense-serial, …), with symlinks in the binary's own directory or in --dir. It never takes a name that another program already holds, so it is safe in a directory with the C programs installed, and it says which names it left alone:

/usr/local/bin/analyzer: left alone, a file is already there
/usr/local/bin/n2kd -> /usr/local/bin/canboat