Getting started

Install

sudo apt install muxen-diagnostic-tools

One package carries all five programs and their bash completions. It installs no service, no configuration file and no unit: nothing starts, nothing runs at boot, and installing it changes nothing about how the boat behaves.

The package Depends: muxen-uds (>= 9.8.2). muxen-diag-devices runs muxen-uds as a child process for every bus operation, so that dependency is a hard one — but only that tool uses it.

Verify the install:

muxen-diag-devices --version
muxen-diag-io --version

Each tool prints the version it was built from, which is a git describe string rather than the package version.

What each tool needs to be useful

Tool	Needs
muxen-diag-devices	a CAN interface, and muxen-uds on PATH
muxen-diag-sfsp	a CAN interface, or an MQTT broker
muxen-diag-io	an MQTT broker carrying device/1/… and device/17/…
muxen-diag-voltage	an MQTT broker carrying the power device/… topics
muxen-diag-data-explorer	an MQTT broker carrying anything

The MQTT tools do not decode the CAN bus themselves. They read topics that another service publishes — in a normal installation, muxen-boat. A broker with no device/… topics on it produces an empty table, which is a valid diagnosis in itself.

Running them on the Brain

Every MQTT tool defaults to 127.0.0.1:1883, so on the Brain itself they take no arguments:

muxen-diag-voltage
muxen-diag-io
muxen-diag-data-explorer

muxen-diag-devices and muxen-diag-sfsp take a CAN interface, which defaults to can0:

muxen-diag-devices
muxen-diag-sfsp

Running them from a laptop

The MQTT tools take the broker address, so you can watch a boat from a laptop on the same network without logging in:

muxen-diag-voltage       -h 192.168.1.10
muxen-diag-io            -h 192.168.1.10 -p 1883
muxen-diag-data-explorer -h 192.168.1.10

muxen-diag-sfsp accepts either source. Giving it -h switches it into MQTT mode; without -h it opens the CAN interface directly:

muxen-diag-sfsp -i can0          # read the bus
muxen-diag-sfsp -h 192.168.1.10  # read the same events from the broker

muxen-diag-devices has no remote mode. It needs a CAN interface on the machine it runs on, so it runs on the Brain.

If the broker cannot be reached, the MQTT tools say so and exit rather than sitting on an empty screen:

error: cannot connect to MQTT broker at 192.168.1.10:1883

There is no retry on that first connection. Fix the address or the broker and start the tool again.

The terminal has to be wide enough

The tables are laid out in fixed columns. Below the width a tool needs, the right-hand columns are simply not drawn, and the title bar says so:

[!] need 123 cols

Tool	Minimum columns
muxen-diag-io	123
muxen-diag-devices	105
muxen-diag-voltage	87

muxen-diag-data-explorer adapts instead: it gives the tree pane 40 % of the width, never less than 20 columns and never more than the width minus 20. It gives no warning.

muxen-diag-sfsp prints lines, not a table, and works at any width.

Colours are used throughout but are not required: on a terminal without colour support the tools fall back to reverse video for the selected row.

Keys common to the table views

Key	Effect
arrows, PgUp, PgDn, Home, End	move the selection
Q	quit
?	legend or help overlay

muxen-diag-devices is the exception: it has no ? overlay, and its action keys are listed permanently in its footer.

muxen-diag-io and muxen-diag-voltage add F4 to filter by name and Esc to clear the filter; muxen-diag-voltage adds D to show or hide the extra columns. muxen-diag-data-explorer uses / to search, n and N to step through matches, and p to pause.

The full key list per tool is in Reference.

A first pass on a boat

This is the sequence that answers "where in the chain is the fault", in the order that eliminates the most in the fewest steps.

1. Is the hardware on the bus?

muxen-diag-devices

It scans, then reads each board's configuration, showing a progress bar for both. A board that answers appears with its UID, function, instance, product name and firmware version. A board that does not is not there at all. See Is the device on the bus?.

2. Is its data reaching the broker?

muxen-diag-data-explorer

Expand device, find the function, find the instance. A topic that is present and whose Updated timestamp is advancing means the whole chain from the board to the broker is intact. See What is actually on the wire?.

3. Is the value itself right?

muxen-diag-io          # outputs, digital inputs, analogue inputs
muxen-diag-voltage     # voltage, current, state of charge, state

These two show the same data as the tree, arranged so a whole boat fits on one screen and an outlier is obvious. See Is the output switching? Is the input being seen? and Is the voltage sane? Is anything charging?.

At each step the answer is either "yes, go on" or "no, and the fault is between this step and the last one".

One caution before you use muxen-diag-devices

Four of the five tools cannot change anything. muxen-diag-devices can: it uploads firmware, resets boards, clears their configuration and rewrites their bus address. Two of its keys act on a board without a confirmation prompt or an undo.

Read Acting on a board before pressing anything in it on a boat that is in service.

Where to go next

• Reading a bus scan — Is the device on the bus?
• Acting on a board — Acting on a board
• When something does not work — Troubleshooting
• Every flag and key — Reference