canboat server

canboat server is the whole device → analyzer → n2kd pipeline in one process: it reads a gateway (see gateways.md), decodes every message, applies the device quirks you switch on, and serves the result over TCP. It replaces actisense-serial | analyzer | n2kd and its siblings.

canboat server --kind actisense --device /dev/ttyUSB0

Ports

Every port is a TCP port, listening on all interfaces unless --bind 127.0.0.1 keeps it to this host. The first five are the C n2kd's (-p and the ports after it), so its clients work unchanged. 0 turns a port off.

The JSON on the snapshot, analyzer and AIS ports takes convert's --id, --units and --wrap. Unlike convert, it writes a lookup field as its value and its name, {"value":381,"name":"B & G"}, as the C n2kd does (it runs analyzer -nv); --no-nv writes the name alone, "B & G", and --nv says the default, as convert takes both too. A value the lookup has no name for is {"value":N} by default and the bare number N with --no-nv. A key field whose name the lookup gives to more than one code is written as its code, 28, so records of B&G's three "Outside Temperature" keys stay apart. The snapshot and analyzer ports start with the header convert writes, whose showLookupValues says which; the AIS port has no header. The filter and override ports always write both, as canboat tui reads the codes.

The state the filter and override ports set is kept in --config-dir: /etc/default/canboat if it is writable (the systemd/root case), otherwise ~/.local/canboat. canboat server --help has the rest of the options.

Discovery

canboat server advertises itself over mDNS / DNS-SD as _canboat._tcp, so a client on the LAN can find it, see which ports it serves and what it runs, without being told a host and port. The instance is called canboat on <hostname>, with DNS-SD's (2) added when two servers share a host. --no-mdns turns it off, for a network where multicast is unwanted.

The SRV record names the analyzer port, or the first open port when that one is off. The TXT record:

With --bind <address> the advert is only on that interface, as the ports are; otherwise it is on every interface that is up. It is withdrawn when the server stops on SIGINT or SIGTERM. canboat answers mDNS itself, so it needs neither Avahi nor Bonjour, and works alongside either. It is the mdns cargo feature, on by default; cargo build --no-default-features --features cli leaves it out of the binary.

dns-sd -B _canboat._tcp                      # macOS
avahi-browse -r _canboat._tcp                # Linux

Running it as a service

canboat server is one process with nothing else to supervise, so any init system with a restart policy will do. With systemd, as a system service in /etc/systemd/system/canboat.service:

[Unit]
Description=CANboat server
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/canboat server --kind actisense --device /dev/serial/by-id/usb-Actisense_NGT-1_XXXX-if00-port0
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

then sudo systemctl enable --now canboat, and journalctl -u canboat -f for its log. Or as a user service, in ~/.config/systemd/user/canboat.service, with ExecStart=%h/.cargo/bin/canboat … and WantedBy=default.target:

systemctl --user enable --now canboat
sudo loginctl enable-linger $USER    # start at boot, and keep running after you log out
journalctl --user -u canboat -f

• The device name. Use the stable name under /dev/serial/by-id/, not /dev/ttyUSB0, which can change between boots; see gateways.md. A user service needs the user in the dialout group.
• A network gateway. A user service can't wait for network-online.target; Restart=on-failure brings it back once the gateway can be reached.
• SocketCAN. --bitrate needs root or CAP_NET_ADMIN. For a user service, set the bit rate when the interface comes up instead (with systemd-networkd, a .network file with [CAN] BitRate=250K), and leave --bitrate out.
• Its state. The NMEA 0183 filter and the rate overrides are kept in --config-dir: /etc/default/canboat for a system service, ~/.local/canboat for a user's.

From n2kd_monitor

n2kd_monitor, the perl script that restarted the C n2kd and its gateway driver, was removed in v8. What its /etc/default/n2kd set is now given to canboat server:

Device quirks

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.

A capture as a live bus (--replay)

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

Performance

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 ×.