muxen-datalogger-tools — Overview

muxen-datalogger-tools writes the boat's CAN traffic to disk so that it can be read later. Nothing on a boat is watched all the time: an alarm fires at three in the morning, a motor derates for ninety seconds, a battery module drops off the bus and comes back. By the time anyone looks, the evidence is gone.

This package keeps the evidence. Once started it records every frame it sees and leaves compressed files on the Brain that a support engineer can read weeks later — on the boat over SSH, or copied off and opened on a laptop.

This is legacy recording, switched on for an investigation and switched off again. Installing the package starts nothing: both units are systemd templates, nothing enables them, and the package ships no maintainer script that would. Someone has to run systemctl enable --now muxen-can-datalogger@can0.service for an interface, deliberately.

Nothing in this package ever deletes a capture. There is no retention policy, no rotation out, no pruning — files accumulate for as long as the recorder runs, and a datalogger left running on a boat will eventually fill the filesystem and take the Brain down with it. Turn it off when the investigation is over, and read Disk budget before you leave it running.

It has no screen page, no button and no configuration file. For the crew it is invisible. For an installer it is two services to start when they are needed, a disk budget to respect, and a stop afterwards.

The two recorders

One package, two binaries, two systemd template units. They read the same bus and write into the same folder, and they answer different questions.

	muxen-can-datalogger	muxen-csv-datalogger
Question	what was on the wire?	what was this device reporting?
Output	one capture file at a time	one file per device and frame kind
Format	BUSMASTER text log	CSV with a header row
Content	every frame, raw hex	decoded named fields
Coverage	everything except error frames	the frame kinds it knows how to decode
Extra mode	replay a capture back onto a bus	—

Use the CAN logger when the question is about the bus: a device that stopped talking, a flood of frames, a timing problem, an identifier nobody recognises. Its output opens in BUSMASTER and replays onto a bench bus.

Use the CSV logger when the question is about a value: a battery voltage over an afternoon, a motor current during a manoeuvre, a tank level that jumped. Its output opens in a spreadsheet with no decoding step.

Running both at once is supported and doubles the disk cost. See Disk budget.

The problem it solves

The rest of the MUXEN stack is live. muxen-boat turns CAN frames into MQTT topics, screens display them, muxen-energy reduces them into a summary — and then the frame is gone. MQTT retains one payload per topic; a screen shows the present. There is no history anywhere.

Nothing else in the stack answers "show me the fifteen minutes before the fault". This package does, and it does it by being as close to a tape recorder as possible:

• It never transmits while recording. It opens the CAN socket for reception and writes what arrives.
• It reads no configuration. No deployment file, no MQTT broker, no other service. A Brain that is half-commissioned still records.
• It keeps no state beyond the files themselves. Restart it and it picks the next unused file index and carries on.
• It decides nothing. It does not judge a frame interesting, does not summarise, does not sample. Every frame is a line.

The cost of that simplicity is that it will happily fill a disk. That is the one thing the installer owns; Disk budget is about nothing else.

Where it sits

                       ┌─► muxen-can-datalogger@can0 ─► can0.N.log(.gz)
CAN bus (can0) ────────┤
                       └─► muxen-csv-datalogger@can0 ─► can0_device_T_I_B.N.log(.gz)

                              both under /var/lib/muxen/datalogger

It reads	From	Purpose
CAN frames	the SocketCAN interface named by the unit instance	everything it records
the log folder	disk, once at startup	pick the next unused file index

It writes	To	Purpose
capture files	/var/lib/muxen/datalogger	the recording
a configuration summary and file-index lines	stdout, so the journal	what it decided at startup

It talks to nothing else. No MQTT broker, no /etc/muxen/deploy.json, no other muxen-* daemon, no socket, no port. The only external program it runs is /usr/bin/gzip, once per closed file, which is why gzip (>= 1.9) is a hard package dependency.

Instantiated per interface

Both units are systemd templates, and the part after the @ is the name of the CAN interface to record:

sudo systemctl enable --now muxen-can-datalogger@can0.service

That is the whole configuration surface of a normal installation. A Brain with two buses runs two instances; each one records its own interface into its own set of files, because the interface name is the first part of every filename.

Each unit refuses to start if /sys/class/net/<instance> does not exist, so an instance naming an interface this Brain does not have stays inactive rather than failing in a loop.

Getting started shows the real invocations, including the one thing about the second unit that is not what its name suggests.

What it does not do

Stated plainly, because each of these is a question installers ask:

• It does not delete anything. There is no retention setting, no maximum number of files and no maximum total size. Old captures accumulate until something else removes them.
• It does not upload anything. Files stay on the Brain.
• It does not publish anything on MQTT, so a boat's screens and alarm logic cannot tell whether recording is working.
• It does not record error frames (CAN logger), so a bus error storm looks like silence in the capture.
• It does not know the bus bitrate. The capture header always claims 500 kbit/s, whatever the interface is really running at.

Document map

Document	Content
Getting started	install, enable per interface, verify, read a first capture
Log files	file naming, rotation, compression, and the lifecycle of one file
Disk budget	how fast this fills a disk, and how to bound it
Replay	replaying a capture onto a bus, and what it does not reproduce
Troubleshooting	symptom → cause → check → fix, plus FAQ and tips
Reference	CLI, defaults, units, files, packaging
File formats	the exact bytes of both formats, for parser authors