Getting started

Prerequisites

On the Brain:

• A CAN interface carrying the MUXEN bus, up and running. The default is can0; every command accepts -i/--interface, and the daemon takes it from the MUXEN_INTERFACE environment variable.
• The muxen-systemd package, a hard dependency: it provides the muxen user and group the daemon runs as, and the muxen.target the unit hangs off.
• The muxen-firmware package (Recommends:, version 2026.07.29-2 or later) if you intend to flash anything. It installs the images and the catalog under /usr/lib/muxen/firmware.
• can-utils (Recommends:) is not required by muxen-uds but is what you will reach for when the bus itself is in doubt.

No kernel CAN option beyond a working SocketCAN interface is required: the packaged build carries its own ISO-TP implementation on a raw CAN socket. See CAN transport.

Install

sudo apt install muxen-uds

Check the service

The daemon is a plain always-on service, not socket-activated. It is installed enabled under muxen.target and restarts on failure after 30 s.

systemctl status muxen-uds.service
journalctl -u muxen-uds -f

Its command line is /usr/bin/muxen-udsd --interface ${MUXEN_INTERFACE}, with MUXEN_INTERFACE=can0 set in the unit and overridable with a drop-in:

sudo systemctl edit muxen-uds

[Service]
Environment="MUXEN_INTERFACE=can1"

sudo systemctl restart muxen-uds

The daemon listens for WebSocket connections on TCP port 12345 with the protocol name muxen-ws-uds. The unit sets RestrictNetworkInterfaces=lo, so in the shipped configuration it is reachable through the loopback interface only: a browser reaches it through nginx, which is what the installed snippet /etc/nginx/snippets/muxen-ws-uds.conf proxies at /ws/uds.

Nothing needs enabling by hand after install, and no device is touched at install time.

Your first scan

Start with the passive scan. It listens for the broadcast frames MUXEN devices emit on their own and lists what it heard — it writes nothing to the bus.

$ muxen-uds -i can0 scan --timeout 5
cmd: when=1753960000,	deviceId=0x280 (640),	instance=00,	function=10 (…)
cmd: when=1753960001,	deviceId=0x040 (64),	instance=00,	function=01 (…)
cmd: 2 devices detected

The scan runs for its whole window — 5 s by default — before printing anything. A silent device is simply absent from the list; that is not the same as being offline. To ask every device to answer, use the active scan:

$ muxen-uds -i can0 uid --scan
cmd: scan done, found 2 devices
cmd: UID		DeviceId	Instance	Function
cmd: 2000200007504255	 640		0	… (10)
cmd: 49003A0003503159	  64		0	… (01)

uid --scan broadcasts a UID request, re-broadcasts it every second and collects answers for 4 s. It is the reliable inventory, and the only one that detects an address collision — a contended address is marked with a trailing X. See Devices, addressing and discovery.

Read a device

A device is addressed either by its 12-bit network address or by the function/instance pair that composes it:

muxen-uds -i can0 -d 0x280 readconfig
muxen-uds -i can0 -F 10 -I 0 readconfig      # the same device

read: #000 ProductId                        = 010010004
read: #001 HardwareId                       = 990010061
read: #002 SoftwareVersion                  = 6.2
read: #003 InstanceNum                      = 0
read: #004 VbatMin                          = 2800
…

readconfig walks the table from identifier 0 upwards until the device answers "no such identifier". If the walk stops for any other reason — a timeout, an unparseable answer — the command fails and prints why, rather than hand you a partial table.

To read a single parameter:

muxen-uds -i can0 -d 0x280 readconfig --only-name SoftwareVersion

Change a setting

muxen-uds -i can0 -d 0x040 writeconfig --name VbatMin --value 2800

writeconfig first reads the whole table to learn which identifier carries the name you gave, skips the write if the value is already what you asked for, and writes nothing at all if the read was unreliable. Five parameters are read-only and are never written: ProductId, HardwareId, SoftwareId, SoftwareVersion, FonctionGroup.

Some settings only take effect after a restart:

muxen-uds -i can0 -d 0x040 writeconfig --name VbatMin --value 2800 --reboot

Before writing anything, --check-only tells you whether the device already matches without touching it:

muxen-uds -i can0 -d 0x040 writeconfig --name VbatMin --value 2800 --check-only

Find a box physically

muxen-uds -i can0 -d 0x040 locate

The device plays an LED animation. This is the fastest way to pair a device id with the box behind a panel.

Where to go next

• Addressing, inventory and collisions — Devices, addressing and discovery
• Reading, writing, backing up configuration — Device configuration
• Deploying a whole boat from a project file — Deploying a boat configuration
• Flashing firmware — Firmware
• When something does not work — Troubleshooting