Getting started

Prerequisites

On the Brain:

• muxen-uds ≥ 10.0.0, running and reachable. The portal daemon never writes UDS traffic to can0 itself; it drives muxen-uds over its WebSocket API for scanning, readconfig, firmware upload and reset. This keeps a single owner for diagnostic traffic on the bus.
• can0 up as the MUXEN bus (classic CAN, 500 k).
• The can_isotp kernel module, which carries the tunnel's ISO-TP endpoints, and vxcan for the CAN and LIN mirrors. Both are present on a standard Brain image; the daemon falls back to vcan with echo filtering if vxcan is unavailable.
• can-utils and a serial terminal (picocom, minicom, tio or screen) to actually drive the mirrors. They are Recommends: of the package.

On the gateway: a product firmware recent enough to answer readconfig with its HardwareId. That is the only key open resolves on. A unit whose firmware does not expose it is refused — bring it onto a current product firmware first.

Install

sudo apt install muxen-portal

One package carries everything: the muxen-portal daemon and ctl (a single binary), the muxen-detect audit tool, the systemd units, bash completion, and all seven signed portal firmware images.

The images are installed straight into the muxen-uds firmware store directory /usr/lib/muxen/firmware/portal/, which is the registration step — the store is a plain directory both the daemon and muxen-uds read directly. There are no maintainer scripts pushing anything anywhere, and no gateway is touched at install time. A gateway only ever receives firmware during a muxen-portal open.

An apt upgrade muxen-portal therefore refreshes the binaries and the images together, and "the upgrade updated the firmware" means the next session uses the new image.

The daemon is socket-activated

muxen-portal.socket owns the ctl socket /run/muxen-portal/ctl.sock and is enabled under muxen.target. The service itself is not auto-started: the first ctl command starts the daemon, and there is no resident process while the portal is unused.

systemctl status muxen-portal.socket    # enabled, active
muxen-portal list-targets               # this starts the daemon

Nothing needs enabling by hand after install.

A first session on a CAN gateway

1. Find the gateway.

$ muxen-portal list-targets
deviceId  uid               board             type
     321  2000200007504255  muxen_cancan_v2   can
     640  49003A0003503159  muxen_can-serial_v2  serial

list-targets is a UID scan plus a readconfig per device, so it takes a few seconds. Gateways whose HardwareId the daemon does not recognise are not listed.

A target can also be given by its 16-hex-character muxen UID, which is the stable identity and works even when the device is parked or its deviceId is contended.

2. Open the session.

$ muxen-portal open 321 --rate 250000
opening 2000200007504255 (muxen_cancan_v2) — image: portal-muxen_cancan_v2-1.1.0.srec — mirror: portal0
warning: 1 product identity will be offline during the session

The one-liner names the image that was resolved, so you can confirm from the CLI which srec went to the device. The warning goes to stderr; on a bus-extender gateway it says instead that the entire segment behind the gateway will be offline, because those devices cannot be enumerated.

open performs the identification synchronously — target lookup, HardwareId → image selection, offline warning — so a refusal is immediate. It then returns while the upload, the swap and the handshake continue in the daemon. Add --wait to block until the session is active or failed, which is what a script wants.

Bring-up takes roughly 30–60 s in total; the firmware upload alone is about 16 s.

3. Watch it come up.

$ muxen-portal status
state: active
transport: isotp
target:
  uid              2000200007504255
  deviceId         321
  board            muxen_cancan_v2
  firmware         portal-muxen_cancan_v2-1.1.0.srec
  uploadPercent    100
mirror: portal0
remote CAN:
  busState         0 (error-active)
  baudrate         250000
  rxFrames         4192
  txFrames         0

--json returns the raw object for scripting. The states you will see are opening, active, recovering, closing, closed, lost and failed.

4. Use the mirror. It is an ordinary SocketCAN interface.

candump portal0
cansend portal0 18EEFF00#0011223344556677
candump portal0,0:0,#FFFFFFFF     # data frames AND error frames

The error-frame mask matters: a bare candump portal0 does not deliver CAN_ERR_FLAG frames, so remote bus errors and LIN error records look like silence. See The mirrors.

5. Close it.

$ muxen-portal close --wait
closing … revert verified (product identity 2000200007504255 back)

close destroys the mirrors, tells the gateway to reboot — which makes MCUboot revert — and verifies by scan that the product identity has returned. It is honoured in any phase, including mid-upload.

If you forget, nothing is stranded: the gateway self-reverts when the Brain stops pinging it.

A first session on a serial gateway

$ muxen-portal open 640 --rate 19200 --channel 2
$ picocom -b 19200 /dev/tty-portal0-ch2

Notes specific to serial gateways:

• Each open channel gets its own PTY, /dev/tty-portal0-chN, and /dev/tty-portal0 points at the first one opened.
• stty and picocom -b work. Baudrate and framing changes on the PTY are detected and forwarded to the gateway as a hot re-OPEN; the remote port really does change rate.
• Open more channels without re-uploading:muxen-portal open-channel 3 --rate 9600.
• Every other channel is monitor-opened by default — counted by the gateway, not streamed — so muxen-portal stats can answer "is anything talking on port 3?" without a terminal attached to it.

$ muxen-portal stats
port  state    rate     RX bytes    RX B/s   TX bytes    TX B/s   errors  err/s
   1  monitor  19200         9600      96.0          0       0.0        1    0.0
   2  in use   19200       184320    1920.0        512       4.0        0    0.0
   3  monitor  19200            0       0.0          0       0.0        0    0.0
   4  monitor  19200        40000     400.0          0       0.0    31940  310.0

note: a port is receiving but with a high error rate — the configured baud is probably wrong.

A first session on a LIN gateway

$ muxen-portal open 322 --rate 19200
$ candump portal0ch1,0:0,#FFFFFFFF
$ cansend portal0ch1 002#R          # send header 0x02, publish the answer

LIN buses are mirrored as SocketCAN interfaces under the sllin mapping — CAN ID = LIN ID, RTR = header-only request — so candump reads the bus and cansend drives the schedule as master, with no LIN-specific tooling. --listen-only makes the channel a monitor instead, for a bus some other master owns.

Where to go next

• Driving each mirror, and their fidelity limits — The mirrors
• Reading the counters and the wire-timing histogram — Monitoring a session
• Auditing what is actually on a port — muxen-detect — remote port audit and identity extraction
• When something does not work — Troubleshooting