Appearance
muxen-diagnostic-tools — Overview
muxen-diagnostic-tools is the box of instruments you open when something on the boat is not behaving. A light does not come on, a tank gauge reads nothing, a battery page is blank, a switch stops working. The screens tell you that something is wrong. These five terminal tools tell you where it is wrong: on the wire, at the board, in the data, or only in the display.
They are diagnostic instruments, not a service. Nothing here runs in the background, publishes anything, or changes the boat on its own. You start a tool, look at it, and quit. The one exception is muxen-diag-devices, which can act on a board — update its firmware, reset it, change its address — and every one of those actions is described in Acting on a board.
For an owner or crew member there is nothing to configure and nothing to learn: this package is what an installer or a MUXEN engineer opens on the Brain, or from a laptop on the boat's network, while working out what is wrong.
The problem it solves
A MUXEN installation is a chain, and a fault can be anywhere along it:
device on the CAN bus ──► muxen-boat ──► MQTT broker ──► screens
(a board) (decodes it) (device/… topics)When a screen shows nothing, the useful question is not "is it broken?" but how far along that chain does the truth still hold? Each tool cuts the chain at a different point:
| Tool | Cuts the chain at | Reads from |
|---|---|---|
muxen-diag-devices | the board itself | CAN, through muxen-uds |
muxen-diag-sfsp | the wireless switch layer | CAN, or MQTT |
muxen-diag-io | the decoded outputs and inputs | MQTT |
muxen-diag-voltage | the decoded electrical picture | MQTT |
muxen-diag-data-explorer | everything on the broker, raw | MQTT |
If muxen-diag-devices sees the board but muxen-diag-io shows no row for it, the fault is between the bus and the broker. If both show it and the screen does not, the fault is above the broker. That is the whole method.
Start from the question, not the tool
The chapters of this manual are arranged by what you are trying to find out. The tools are a means to that end.
| What you want to know | Chapter | Tool |
|---|---|---|
| Is the board on the bus at all? What firmware is on it? | 02 | muxen-diag-devices |
| Can I update, reset, park or renumber that board? | 03 | muxen-diag-devices |
| Is the output actually switching? Is the input being seen? | 04 | muxen-diag-io |
| Is the voltage sane? Is anything charging? | 05 | muxen-diag-voltage |
| Did that switch press reach the boat? | 06 | muxen-diag-sfsp |
| What is actually on the wire, byte for byte? | 07 | muxen-diag-data-explorer |
Where it sits
Nothing in this package is installed as a service, and nothing starts at boot. The tools are ordinary interactive programs run from a terminal.
| It reads | From | Which tool |
|---|---|---|
device/…, app/sensor/…, nmea/… topics | the MQTT broker | io, voltage, data-explorer, sfsp in MQTT mode |
| MUXEN broadcast frames | a SocketCAN interface | sfsp in CAN mode |
the CAN bus, through muxen-uds | muxen-uds, run as a child process | devices |
/usr/lib/muxen/firmware | disk | devices |
/etc/muxen/deploy.json | disk | data-explorer |
| It writes | To | Which tool |
|---|---|---|
| firmware, resets, configuration and instance writes | a board, through muxen-uds | devices |
Four of the five tools are strictly read-only observers. They subscribe to the broker and draw what arrives; they publish nothing and they never transmit on the CAN bus. muxen-diag-devices is the only one that can change anything, and only when you press one of its action keys.
The MQTT tools depend on a broker that is already carrying MUXEN data — in practice, muxen-boat decoding the CAN bus onto device/… topics. An empty screen in muxen-diag-io may therefore mean the board is silent, or that nothing is decoding for it.
What is in the package
Five programs, their bash completions, and nothing else. No systemd unit, no configuration file, no state directory, no daemon.
| Program | One line |
|---|---|
muxen-diag-devices | scan the CAN bus, list boards with their firmware version, act on one |
muxen-diag-io | live table of Bloc 8 and Generic I/O outputs, digital inputs and analogue inputs |
muxen-diag-voltage | live table of voltage, current and state for every power device |
muxen-diag-sfsp | a running log of wireless switch presses, receivers and unknown switch ids |
muxen-diag-data-explorer | the whole MQTT topic tree, with pretty-printed payloads |
The package Depends: muxen-uds (>= 9.8.2), which muxen-diag-devices runs for every bus operation. The other four need no MUXEN package to start, only something to talk to.
Document map
| Document | Content |
|---|---|
| Getting started | install, run on the Brain, run from a laptop, first checks |
| Is the device on the bus? | reading a bus scan: boards, addresses, firmware versions |
| Acting on a board | updating, resetting, parking and renumbering a board |
| Is the output switching? Is the input being seen? | is the output switching, is the input being seen |
| Is the voltage sane? Is anything charging? | is the voltage sane, is anything charging |
| Did the switch press reach the boat? | did the switch press reach the boat |
| What is actually on the wire? | reading the raw topic tree |
| Troubleshooting | symptom → cause → check → fix, plus FAQ and tips |
| Reference | every flag, key, topic, colour, path and exit code, per tool |