muxen-uds — Overview

muxen-uds is how the MUXEN Brain talks to the electronic boxes on the boat's own CAN bus. Every MUXEN device — a battery monitor, a power distribution box, a tank sensor interface, an NMEA 2000 gateway — carries a small configuration table and a firmware image. muxen-uds reads that table, writes it, restarts the device, makes it blink for identification, and uploads a new firmware into it.

For the owner or the crew this is the machinery behind "the installer changed a setting" and "the yard updated the boxes". Nothing here runs by itself: no command in this manual is issued unless somebody, or an HMI screen, asks for it.

For an installer or an integrator it is the diagnostic tool of the MUXEN bus: a command-line program on the Brain, and a WebSocket daemon that gives the same commands to a web interface.

The problem it solves

A MUXEN device has no screen and no keyboard. Its settings — battery voltage thresholds, tank calibration, its own address on the bus — live in a table inside the device, and the only way in is the CAN bus it is wired to.

muxen-uds speaks UDS (Unified Diagnostic Services, ISO 14229) over that bus. UDS is the automotive diagnostic protocol; MUXEN uses three of its services plus a few vendor routines:

UDS service	Code	Used for
ECU Reset	0x11	reset — cold start a device
Read Data By Identifier	0x22	readconfig — walk the parameter table
Write Data By Identifier	0x2E	writeconfig — change one parameter
Routine Control	0x31	locate, factory, routine
Request Download / Transfer Data / Transfer Exit	0x34 / 0x36 / 0x37	firmware — upload an image

Background on the protocol itself: https://en.wikipedia.org/wiki/Unified_Diagnostic_Services.

What ships in the package

One Debian package, muxen-uds, installs five programs:

Program	What it is
muxen-uds	the command-line tool — every command lives here
muxen-udsd	the WebSocket daemon, run by systemd as muxen-uds.service
muxen-scan	wrapper, execs muxen-uds scan
muxen-uid	wrapper, execs muxen-uds uid
muxen-deploy	wrapper, execs muxen-uds deploy

Plus a bash completion file, two nginx snippets and the systemd unit. See Reference for the exact paths.

The CLI and the daemon are built from the same command implementations, so a command behaves identically whether it was typed in a shell or sent as JSON over the WebSocket. The only differences are how parameters arrive and how results are printed.

Where it sits on the boat

   HMI / web interface            shell on the Brain
        (@muxen/uds)                  (muxen-uds)
             |                              |
      ws://…/ws/uds                         |
             |                              |
      muxen-udsd  ────────────┬─────────────┘
                              |
                        ISO-TP / UDS
                              |
                        can0 (MUXEN bus)
                              |
        ┌─────────────┬───────┴───────┬──────────────┐
     device 64     device 320     device 640      device …

muxen-uds is the single owner of diagnostic traffic on the MUXEN bus. Other MUXEN components do not write UDS frames themselves; they drive muxen-uds. muxen-portal, for instance, uses the muxen-uds WebSocket for its scans, readconfig calls, firmware uploads and resets.

What it talks to:

Peer	How
MUXEN devices	UDS over ISO-TP on can0 (the interface is configurable)
Web interfaces	WebSocket JSON on port 12345, usually reverse-proxied at /ws/uds
muxen-firmware	reads the firmware images and their products.json catalog from /usr/lib/muxen/firmware
The boat configuration	reads /etc/muxen/deploy.json or /etc/muxen/configuration/<project>.json, writes /var/lib/muxen/deployed.json
systemd	muxen-uds.service, PartOf=muxen.target

It does not publish to MQTT and holds no state of its own beyond the deployed-device cache.

What it does not do

• It does not monitor. muxen-uds acts when asked and is otherwise idle; live boat data is the business of the other MUXEN daemons.
• It does not manage addresses automatically. A device that shares its address with another has to be fixed by hand — see Devices, addressing and discovery.

Document map

Document	Content
Getting started	install, verify the service, first scan, first read
Devices, addressing and discovery	addressing, scan, uid, locate, address collisions
Device configuration	readconfig, writeconfig, backup, factory
Deploying a boat configuration	deploy, checkconfig, project files
Firmware	listfirmware, firmware upload, what can go wrong
Web clients — @muxen/uds	the @muxen/uds TypeScript client and a Vue 3 sample
Troubleshooting	symptom → cause → action, FAQ, tips
Reference	CLI, options, files, units, defaults, exit status
WebSocket protocol	the WebSocket JSON wire format
CAN transport	CAN identifiers, ISO-TP framing, timeouts and retries