Is the device on the bus?

This is the first question of every diagnosis, and it has a definite answer. muxen-diag-devices asks the CAN bus which boards are present, then asks each of them what it is and what firmware it runs. A board that answers is on the bus. A board that does not is not — no matter what the screens show.

For an owner: this is the list of the electronic boards installed on the boat, and whether each one is talking. Nothing on this page changes anything; the keys that do are covered in the next chapter.

Running a scan

muxen-diag-devices          # can0
muxen-diag-devices -i can1

The tool works in two phases, each with a progress bar, before the table appears:

1. Scanning CAN bus… — a UID scan of the whole bus.
2. Reading device configuration… — one configuration read per board, naming the board it is currently reading.

Both phases go through muxen-uds, which is run as a child process. The second phase is the slow one: it is one round trip per board, so a well-populated boat takes a while. The progress bar counts boards, not device rows.

If the first phase fails outright the tool refuses to start:

Error: bus scan failed (is muxen-uds installed?)

Reading the table

UID               Function                  Inst  Product              Version  Latest
2000200007504255  Power output (1)          0     Bloc 8               5.7      5.7 =
49003A0003503159  Battery (5)               2     Battery module       5.1      5.7 ^
                  Generic IO (17)           0     (same hw)
0034002F30511234  Battery (5)               P     read failed

Column	What it is
UID	the board's unique hardware identity, 16 hex characters
Function	what this row does on the bus, with its function code
Inst	the instance number, or P for a parked board
Product	the product name, resolved from the product code
Version	the firmware version the board reports
Latest	the newest compatible firmware present on this Brain

The title bar counts both: N devices, M boards.

One UID is one board; a board can be several devices

This is the single thing that confuses people about this table.

The bus is addressed by device, not by board. Every device on the bus has an address built from its function and its instance, and one physical board may present several of them at once — a board acting as a battery, a Generic I/O and a concentrator occupies three addresses. All three answer, all three are listed, and all three share one UID.

The table makes that visible by grouping rows that share a UID and showing the UID, product name and firmware only on the first row of the group. The rest read (same hw), dimmed, because the firmware belongs to the board and not to any one of its functions.

Rows are ordered so a group stays together: boards are sorted by the lowest function code they present, then by UID, then by function and instance within the group. A multi-function board therefore appears among the devices of its lowest function.

Anything you do to one row of a group is done to that board. Updating firmware from the third row of a group updates the board, and the tool redirects the action to the group's first row before running it.

The address: function and instance

A device address on the MUXEN bus is one number, and the tool splits it the way the bus does:

function = deviceId / 64
instance = deviceId % 64

so there are 64 instances per function, numbered 0 to 63.

Instance 63 is the parking address. A board that has never been given an instance, or one that was deliberately parked, sits there. The table shows it as P rather than 63, because it is a state and not a position. A parked board is on the bus and answers a scan, but it is not doing its job: nothing addresses it, and no other tool will show its data.

Two boards presenting the same function and the same instance answer at the same address. Neither can then be read individually, and both turn up as read failed. That is covered in Troubleshooting.

The firmware columns

Version is what the board reports for itself. Latest is the newest firmware file this Brain has on disk for that product, and the sign after it is the comparison:

Shown	Colour	Meaning
5.7 =	green	the board runs the newest firmware available here
5.7 ^	red	a newer firmware is available; [U] will offer it
6.1 = (Not released firmware, it's CE !)	yellow	the board runs a firmware newer than anything on disk — a pre-release build
-	none	no firmware for this product on this Brain

Only firmware sharing the running major version is ever offered. A board on 5.1 is offered 5.7 and never 6.0, because the 5.x and 6.x series are not interchangeable. If the only firmware on disk for a product is 6.x and the board runs 5.x, Latest reads - — not because nothing is there, but because nothing compatible is there.

Firmware lives under /usr/lib/muxen/firmware, one directory per product code, with files named <productId>-v<version>-<name>.srec:

/usr/lib/muxen/firmware/
├── products.json
└── MUX-B8/
    └── MUX-B8-v5.7-release.srec

products.json maps product codes to readable names and is the only reason the Product column says "Bloc 8" rather than "MUX-B8". Without it the code is shown as-is; nothing else depends on it.

Neither the firmware directory nor products.json is shipped by this package.

read failed

The board answered the UID scan — it is on the bus — but the configuration read did not come back. The row shows read failed in red, with no product and no version.

The scan and the read are different operations: the scan is a broadcast every board answers, the read is addressed to one device id. So read failed means the board is present and something about addressing it individually is wrong. In decreasing order of likelihood:

1. An address collision. Two devices at the same function and instance, so neither can be read.
2. A parked board that has not been activated for individual addressing.
3. A firmware too old to answer the configuration read.

A failed read is not sticky. Pressing [E] to rescan clears the flag and tries that board again — a board that has just answered a UID broadcast deserves another go, possibly at a new address.

Refreshing what you are looking at

Key	Effect
S	re-read the selected board's configuration
E	rescan the bus, then read only the boards no configuration is held for

[E] is the cheap one and the one to use after physically changing something: it keeps everything it already knows, picks up boards that appeared or moved, and only pays the round-trip cost for the ones it cannot account for.

[S] is for a single board you have just changed. It always re-reads the board's first row, then copies the result onto the rest of the group.

Neither key transmits anything to a board beyond the read itself.

The table has a limit

muxen-diag-devices holds 128 device rows. On a bus with more, the title bar says so in red:

[!] table full (128 max) — some devices not shown

It says it rather than silently truncating, because a diagnostic tool that quietly hides a device is worse than useless. If you see it, the list you are looking at is incomplete.

What a clean scan tells you, and what it does not

A board that appears with its product name and version is:

• powered,
• physically connected to the bus you scanned,
• terminated and wired well enough to complete a UDS exchange,
• running a firmware recent enough to answer.

It does not tell you that the board's own inputs and outputs work, that it is publishing anything, or that its data reaches a screen. That is the next link in the chain — see Is the output switching? Is the input being seen?, Is the voltage sane? Is anything charging? and What is actually on the wire?.