CANBOAT

A small but effective set of command-line utilities to work with CAN networks on BOATs. The most common version of CAN networks on board, and in fact at the moment the only ones that this suite can analyse, is NMEA 2000.

The NMEA 2000 database and implementation is copyrighted by the NMEA (National Marine Electronics Association). Access is restricted to members and parties that pay for it. If they do so they are not able to divulge the content of the database, thus making it impossible for open source developers to get access to it.

For this reason we have reverse engineered the NMEA 2000 database by network observation and assembling data from public sources.

If you just want to know how the NMEA 2000 protocol works, with an explanation of all reverse engineered data, please go to the documentation page.

To use the programs included in this project you may need a supported CAN interface. This can be a marketed-as-such NMEA 2000 Gateway or a non NMEA specific CAN interface.

For more information go to the CANBoat Wiki.

CANboat ships two implementations. Both are tier 1 — supported, tested and released together — and they are interchangeable for the jobs they both do.

C tools. analyzer and the *-serial gateway drivers are the originals and stay tier 1. They are small, dependency-light and build with nothing but make and a C compiler.

canboat, the Rust binary. One executable with subcommands. convert and the gateway support are tier 1 alongside their C counterparts; everything with no C equivalent is tier 1 as the only implementation.

canboat install-shims drops symlinks so the subcommands answer to the old names (analyzer, n2kd, actisense-serial, …). It never takes a name that another program already holds, so it is safe to run in a directory that has the C tools installed — it reports what it left alone.

The remaining C converters, the helper scripts in util/ (PHP, perl and ksh) and the Python tooling will most likely move to Rust in time; the C n2kd and n2kd_monitor already have, and were removed in v8.

Some devices misbehave in ways CANboat can cover for. Each workaround is a named quirk, and every one of them is off by default — they all rewrite or invent data, so you switch on the ones you need:

gps-rollover is the odd one out: it corrects a decoded value rather than putting a frame on the bus, which is why it is available when decoding a capture file too. Do not use it on a capture made before April 2019 — it cannot tell a rolled-over date from a genuinely old one, and will move the whole log forward twenty years.

Without a device list it only touches the dates a GNSS receiver produced, because those are the only ones whose origin the PGN itself tells us. Any other device that takes its clock from the bus repeats the wrong date, and nothing in its PGNs says so; that is what the device list is for. Naming a device by manufacturer and unique number, or by NAME, needs its PGN 60928 Address Claim to have gone by — canboat server asks for those at startup, a capture has to contain one. The AIS reports (129793, 129794) relay another station's clock and 127258 carries the variation model's date, so those are never corrected.

None of that helps a display that reads the broken GPS directly. gps-relay is the nearest thing to a fix short of replacing the receiver: canboat server re-sends every broadcast PGN from the listed devices — position, COG/SOG, satellites, not just the dated ones, or no display would accept it as a GPS — from its own address, byte for byte except for the corrected dates. The other devices then see a second GPS source, canboat, and you select it in each of them. That needs devices with real source selection, which not every brand gets right, and it leaves the old receiver on the bus, since it is where the data comes from.

The decoder is also a Rust crate, canboat, so you can embed NMEA 2000 handling instead of parsing another program's output. One crate, a small public API, and features that gate the weight you pay for:

The crate's own README has the quick start and is what crates.io shows; the API reference is on docs.rs and its design in crates/doc/library-api-plan.md.

Same decode work — -json -nv over 1.26 M PGN frames (canboat's dirona-actisense-serial.raw × 50) on an M4 Pro, release build:

canboat server goes one step further and collapses the canboat convert | canboat n2kd pipeline into a single process with no JSON text serialisation between stages:

That's 46 % less wall time than the piped setup while doing strictly more work (it's a long-running service with TCP fan-out); on CPU time the ratio is closer to 3.4 ×.

canboat server --replay <capture> plays a capture as if it were a gateway, so you can test a consumer such as Signal K without a boat. It reads any format canboat reads, keeps the capture's pacing but stamps every frame with the current time, and starts over at the end. The TCP ports are the same as for a real gateway, the input port included: frames written to it go to --replay-sent <file> as PLAIN/FAST lines, or are dropped, and are not echoed back.

canboat server --replay samples/dirona-actisense-serial.raw --replay-sent sent.raw

Other devices ask a node which PGNs it sends and reads (PGN 126464). canboat server --tx-pgn <pgn>[,…] --rx-pgn <pgn>[,…] (or BridgeConfig::pgn_lists in the library) names the PGNs your application sends and reads, so the gateway can answer truthfully. What happens with them depends on the gateway:

analyzer reads NMEA 2000 data from a number of text formats on stdin and turns each message into human readable text or JSON. Some formats it understands directly; capture formats from specific gateways or CAN tools are first turned into the analyzer's PLAIN format by a small helper program that you pipe into analyzer:

• Directly by analyzer — text logs that already contain decoded CAN identifiers. The format is auto-detected, or can be forced with -format <NAME>.
• Via actisense-serial — Actisense NGT-1 binary streams and log files. actisense-serial -r <file> | analyzer
• Via candump2analyzer — Linux can-utils dumps and other raw CAN captures. candump2analyzer <file> | analyzer

The full list of understood formats:

pcap2candump can additionally turn a raw .pcap capture into the candump log format for candump2analyzer. Example captures for many of these formats live in the samples/ directory.

make builds the C tools into rel/<platform>/; make rust builds canboat and keel into target/release/. Neither needs the other — you can build just the side you care about.

Use make rust rather than a bare cargo build if you have edited database/: the Rust PGN tables are generated by keel and committed, so cargo alone will compile against the previous ones.

Full instructions are in BUILDING.md, and the Wiki covers per-platform detail and how to start extending the PGN database.

PGN definitions live as YAML under database/ (one file per PGN variant in pgns/, one per enumeration in lookups/). The easiest way to add a new message or correct an existing one is the built-in, evidence-first editor:

./keel/keel edit

Paste one or more real captures, and the local web editor stacks the bytes, decodes them live as you define fields, suggests an existing definition to clone when your frame nearly matches one, and lets you save your captures as regression tests — all rule-checked before it will write. See AGENTS.md §9 for the full workflow (editor and by-hand) and CONTRIBUTING.md for the evidence and commit rules.

Pull requests are welcome! See CONTRIBUTING.md for how to write your PR title (it becomes the release changelog entry), the source/generated lockstep rule, and what evidence a database change needs.

If you just want to use the definitions in XML or JSON format, use the versions in the docs directory, e.g. (./docs/canboat.xml) or (./docs/canboat.json). We recommend that you pin your retrieval to a particular release. Semantic versioning is used to warn you of major (x.0.0) or minor (0.x.0) changes to the definitions.

See Changelog.

• canboatjs — pure JavaScript NMEA 2000 decoder and encoder

(The Rust library used to live separately as canboat-rs; it was merged into this repository in v8 and is the canboat-* crates described above.)

Snapshot of early October 2026. The CANboat version each project uses and when it was last updated were taken from GitHub on 7 October 2026 and will drift. The current CANboat release is v8.3.0. The survey behind this table, with more projects, is in research/downstream-survey-2026-10.md. Maintain one of these, or another project built on CANboat? Open an issue to correct your entry or to be notified of new major and minor releases.

CANboat and its sibling canboatjs are command-line tools. If you just want to use your NMEA 2000 network, these projects build on them and provide a friendlier experience:

• OpenPlotter
• Signal K

If you find CANboat useful, please consider supporting its development via GitHub Sponsors.

(C) 2009-2026, Kees Verruijt, Harlingen, The Netherlands.

This file is part of CANboat.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.