muxen-blocswap — Overview

muxen-blocswap answers one question, every thirty seconds, for every MUXEN module the boat's configuration declares: is this still the same physical unit as last time?

When it is not — because a module was swapped out for a spare — the daemon pushes the boat's configuration back onto the replacement and restarts it. Nobody connects a laptop, nobody opens a configuration tool, nobody has to remember what the old module was set to. The boat comes back on its own, typically inside a minute.

That is the whole product. The daemon has no user interface, no command line, no MQTT topic and no status command.

The problem it solves

A MUXEN bloc — a power-output module, a battery monitor, a sensor interface — carries two things: an address on the MUXEN bus, and a configuration that says what that particular boat wants it to do. A replacement bloc off the shelf has neither of the second.

Historically, replacing a failed bloc at sea or at the quay meant a service call: bring a laptop, find the boat's project file, push the configuration onto the new unit, reset it, check. On a boat whose crew is mid-passage that is not a realistic answer.

muxen-blocswap makes the swap the only manual step. Fit the spare, and the Brain notices and finishes the job.

How a bloc is recognised

Every MUXEN device carries a UID: an 8-byte serial number burned into the microcontroller, written as 16 hexadecimal characters. It is unique to the physical unit and survives everything — configuration, firmware, factory reset.

The deviceId is the opposite: it is an address, not an identity. It is 12 bits, (function << 6) | instance, so device 65 is function 1 instance 1. Two blocs of the same product, on the same boat, differ only by their instance.

The daemon holds one pairing per monitored bloc:

	Meaning	Where it comes from
deviceId	the address the boat expects a bloc at	devices[] in /etc/muxen/deploy.json
UID	the physical unit that was there last time	/var/lib/muxen/deployed.json at startup, then the running scan

A swap is exactly this: the same deviceId, answered by a different UID. Nothing else counts as one.

That has a consequence worth knowing before any field visit: the replacement has to answer at the same deviceId as the unit it replaces. The daemon matches on the address. A spare that comes up on a different instance is simply a device the boat's configuration never asked for, and nothing happens.

What it does when it sees one

every 30 s
  │
  ├─ muxen-uds uid --scan-to-json   ──►  { deviceId → UID }, duplicate flag
  │
  ├─ for each monitored device: has the UID at this address changed?
  │
  └─ if it has:
       muxen-uds --device-id <id> deploy    ──►  write the configuration
       muxen-uds --device-id <id> reset     ──►  restart the bloc

Two shell commands, in that order, then the daemon records the new UID as the one it now expects and goes back to watching. Everything the replacement receives comes from muxen-uds, which owns the boat's diagnostic traffic; muxen-blocswap never opens the CAN bus itself and never transmits a frame.

Hot swap and cold swap

A swap is detected whether or not the Brain was awake while it happened. Both cases run the same test, at different moments:

• Hot swap — the bus stays live. The old bloc disappears from a scan, the new one appears at the same address with a different UID, and the daemon acts on the next tick.
• Cold swap — the boat is dead while the work happens, so the Brain never sees the transition. The UID it expects was written to /var/lib/muxen/deployed.json before the blackout; on the way back up the daemon reads it from there and compares against what is actually on the bus now.

The second case is why the daemon reads a file at startup rather than just watching. See Swapping a bloc.

The safety interlock

The scan reports whether two devices are answering at the same address. While that is true, the daemon does nothing at all — no deploy, no reset, no state change, for any device.

That interlock is deliberately paranoid. If the scan result does not carry the flag at all, the daemon assumes the worst and locks. A boat where an address is contended is a boat where "the unit at deviceId 65" is not a well-defined thing, and writing a configuration to it would be a guess.

The interlock is also silent: nothing is logged while it holds. A daemon that appears to be ignoring an obvious swap is the symptom to look for — see Troubleshooting.

What it does not do

Assign an instance to a new bloc	Not implemented. The replacement must already answer at the right deviceId
Upload firmware	muxen-uds does that, on request. muxen-blocswap never asks
Publish anything	No MQTT topic, no CAN frame, no status socket
Re-read its configuration	The device list is built once, at startup
Watch virtual devices	Anything carrying VirtualDevice is skipped

Where it sits

/etc/muxen/deploy.json      ──►┐
                               ├──►  muxen-blocswap  ──►  muxen-uds  ──►  can0
/var/lib/muxen/deployed.json ─►┘         (30 s)             (CLI)

It reads	When	Purpose
/etc/muxen/deploy.json	once, at startup	is the feature on, and which deviceIds to watch
/var/lib/muxen/deployed.json	once, at startup	the UID last known at each deviceId

It runs	When	Purpose
muxen-uds uid --scan-to-json <file>	every 30 s	who is on the bus, and at which address
muxen-uds --device-id <id> deploy	on a detected swap	write the boat's configuration to the bloc
muxen-uds --device-id <id> reset	immediately after	restart the bloc so it runs it

It writes nothing except a temporary scan file, which it deletes.

Off by default

The daemon is installed and running on every Brain that carries the package, but it acts only when the boat's configuration turns it on: a setting named FeatureBlocSwap whose value is the string "1". Without it the daemon logs one line and monitors nothing.

That is the switch an installer flips at commissioning, and it is on the features page of the boat's configuration tool rather than in a file on the Brain. See Getting started.

Document map

Document	Content
Getting started	install, turn the feature on, verify it is watching the right blocs
Swapping a bloc	the field procedure, the detection rules, and the timings
Troubleshooting	symptom → cause → check → fix, plus FAQ and tips
Reference	configuration keys, files, journal messages, systemd, packaging