Acting on a board

muxen-diag-devices is the only tool in this package that changes anything. From the table described in Is the device on the bus?, six keys act on the selected board: update its firmware, clear its configuration, reset it, park it, renumber it, or re-read it.

For an owner: these are the commissioning and maintenance operations an installer performs on the boat's electronic boards. They are not something to try out. A board whose address has been changed stops appearing where the rest of the system expects it, and the screens that depended on it go blank until it is put back.

Every action runs muxen-uds as a child process. Nothing is done through a shell, so a space or a semicolon in a UID or a firmware path cannot be misread as a command.

The keys

Key	Action	Confirmation	Board reboots
U	update firmware	yes, with the version change	yes
C	clear configuration	yes	no
R	reset	none	yes
P	park — set the instance to 63	yes	yes
I	set the instance number	yes, twice	yes
S	re-read the selected board	not an action	no
E	rescan the bus	not an action	no

[R] is the one to be careful with: it acts the moment you press it, with no prompt.

Actions that need to see the board's own output run with the table suspended: the terminal returns to normal, the full muxen-uds command is echoed, its output scrolls past, and the tool waits for ENTER before redrawing.

--- Running: muxen-uds -i can0 -d 321 firmware --srec /usr/lib/muxen/firmware/MUX-B8/MUX-B8-v5.7-release.srec ---

…

--- Done (exit 0) --- Press ENTER to continue ---

The result of every action is reported in the bottom-right corner of the table for ten seconds.

[U] — update firmware

The tool refuses before touching the board in two cases:

Message	Meaning
No firmware available for <product>	nothing compatible on disk for that product
Already at latest version (<v>)	the board is at or ahead of the newest file

Otherwise it asks, naming the product and the version change:

        Update firmware?
──────────────────────────────
 Bloc 8
 Version: 5.1 -> 5.7
        [Y] Yes    [N] No

On confirmation it runs the upload with the table suspended, then waits five seconds for the board to reboot — with a countdown on screen — and re-reads its configuration, so the Version column reflects what is actually running rather than what was sent.

If the upload fails the status line says so and nothing further is done:

Firmware update FAILED on device 0x141

Two constraints are worth knowing before you press it:

• Only the same major series is ever offered. See Is the device on the bus?. A cross-major update is not reachable from this tool.
• The action belongs to the board, not the row. Pressing [U] on the second row of a multi-function board updates the board; the tool redirects to the group's first row before running anything.

[C] — clear configuration

   Clear device configuration?
──────────────────────────────
 Device 0x141 - Battery(5) inst 2
 This will reset all config (except address)

The board's parameters go back to their defaults. Its address is not touched, so it stays where it was on the bus and keeps answering. The tool re-reads the board immediately afterwards.

Everything an installer configured on that board — names, capacities, bindings, thresholds — is gone, and there is no undo in this tool. On a boat in service, know what was configured before you press it.

[R] — reset

Sends a reset and reports it:

Reset sent to device 0x141

There is no confirmation prompt. This is the only destructive-adjacent key that acts immediately, and the only one whose command runs silently in the background rather than with the table suspended, so there is no muxen-uds output to read.

Resetting a board reboots it. Whatever it was driving stops for the duration, and the tool's own table is not refreshed automatically afterwards — press [E] if you want to see the board come back.

[P] — park

  Park device (instance -> 63)?
──────────────────────────────
 Device 0x141 - Battery(5) inst 2
 This will reset the device CAN address

Parking moves the board to instance 63, the parking address. It is how you take a board out of the addressed installation without unplugging it — for a swap, a re-addressing, or to break an address collision.

A parked board is still on the bus and still answers a scan, but nothing addresses it and no other tool in this package will show its data. From the boat's point of view it has gone.

Because parking reboots the board onto its new address, everything the table held about it is stale the moment the command returns. The tool therefore waits five seconds, rescans the bus and selects the parked row:

Parked device 0x141 — now 0x17F (P)

If the board does not turn up parked after the rescan, it says that instead:

Parked device 0x141 — not seen parked after rescan

which means the park went through but the board has not come back yet, or has come back somewhere unexpected. Press [E] again before concluding anything.

[I] — set the instance number

This is the commissioning action: giving a board its place in the installation.

     Set instance number
──────────────────────────────
 Device 0x141 - Battery(5) inst 2
 UID: 49003A0003503159

 New instance (0-63): _
   [ENTER] Confirm    [ESC] Cancel

Only digits are accepted, at most two, and the value must be 0 to 63 — anything else is rejected in the popup with Value must be 0-63!. A value equal to the current instance is refused as Instance unchanged. A second popup then asks to confirm the change explicitly.

The sequence that follows runs with the table suspended, one command at a time, each echoed:

1. If the board is parked (instance 63), it is first activated for individual addressing by its UID. Without this step a parked board does not accept the write.
2. The instance is written to the board's InstanceNum parameter.
3. The board is reset, which is what makes the new instance take effect.
4. The bus is rescanned, so the table shows the board at its new address.

Each step reports its own failure, and the tool stops at the first one:

Message	Where it stopped
UDS activation FAILED for UID <uid>	step 1 — the parked board could not be activated
Instance change FAILED on device 0x…	step 2 — the write did not go through
Instance written but reset FAILED — power-cycle the device	step 3
Instance changed to N — X devices, Y boards	all four steps completed

The third one matters: the new instance is stored on the board, but the board is still running at its old address. Power-cycling it applies the change. Do not write the instance a second time.

Collisions

Two boards presenting the same function at the same instance answer at the same address, and neither can be read or written individually. [I] cannot repair that, because it needs to address one of them.

The way out is to remove one from the bus, address the other, and put the first back — or to park one of the pair, which does not need individual addressing in the same way. See Troubleshooting.

What none of these keys do

• Nothing here is undone by quitting the tool. Every action is a change on the board.
• Nothing here backs anything up. There is no export of a board's configuration before [C].
• Nothing here touches /etc/muxen/deploy.json. The boat's deployment file still describes the board at its old address after [P] or [I], and has to be brought back in step with it separately.
• Nothing here restarts a MUXEN service. A daemon that read the board's address at startup keeps using the old one until it is restarted.

A safe order for commissioning a board

1. [E] — confirm the board is on the bus and note its UID.
2. [U] — bring it to the firmware the rest of the fleet runs, if Latest shows ^.
3. [I] — give it its instance.
4. [E] — confirm it came back at the new address, with its product and version still readable.
5. Leave muxen-diag-devices, and check with muxen-diag-io or muxen-diag-voltage that the board's data now reaches the broker at the instance you gave it.

Step 5 is the one people skip. A board can be perfectly addressed on the bus and still be missing from the broker, and that is a different fault with a different fix.