Device configuration

Every MUXEN device holds a table of named parameters: thresholds, calibration factors, its own instance number, plus a few read-only identity fields. Changing a setting on the boat — a low-battery alarm level, a tank's full-scale value — means writing one row of that table.

This chapter covers reading it, writing it, saving it and resetting it, one device at a time. Applying a whole boat's configuration at once is Deploying a boat configuration.

The parameter table

A row has four fields:

Field	Meaning
id	the identifier the device stores it under, 0…65534
name	the parameter name, e.g. VbatMin
type	int8_t…int64_t, uint8_t…uint64_t, or string
value	the value

The table is dense from identifier 0: readconfig reads id 0, then 1, and so on until the device answers "I hold no such identifier", which is what marks the end. There is no length field.

Five names are treated as read-only and are never written, whatever the source of the write:

ProductId, HardwareId, SoftwareId, SoftwareVersion, FonctionGroup

They identify the product and the image running on it. They are also the fields a client uses to match a firmware image against a device — see Firmware.

Identifiers are not stable across firmware versions. A parameter can move from one id to another when a device is updated. Everything in muxen-uds that restores a saved configuration therefore matches on the name and re-resolves the id against the device it is talking to. Prefer --name over --id for the same reason.

Reading

muxen-uds -i can0 -d 0x280 readconfig

read: #000 ProductId                        = 010010004
read: #003 InstanceNum                      = 0
read: #004 VbatMin                          = 2800

An empty string prints as (empty).

Option	Effect
--only-id 123	read that one identifier and stop
--only-name xyz	walk the table, keep only these names (repeatable)
--save-as-json <file>	also write the table as JSON
--save-as-csv <file>	also write the table as CSV

--only-id and --only-name are mutually exclusive.

--only-id is a single exchange and is the cheap way to poll one value. --only-name still walks the whole table, because the name→id mapping is only known once the row has been read.

The command fails rather than return a partial table. It stops successfully only on a negative response; a timeout, an unparseable answer or an answer echoing another identifier is reported on stderr and no file is written:

cmd: read stopped at id 12: no answer, ensure device is online
cmd: device answered but holds no parameter
cmd: none of the requested parameters exist on this device

That behaviour matters: an offline device answers nothing at id 0, and a "successful" empty read would be indistinguishable from a device with no parameters — and would then be saved as a backup, or fed to a deploy.

Saved formats

--save-as-json writes the format writeconfig --from-json reads back:

{
  "version": 1,
  "parameters": [
    { "id": 4, "name": "VbatMin", "type": "uint16_t", "value": 2800 }
  ]
}

--save-as-csv writes a header line then one row per parameter:

id,name,type,value
4,VbatMin,uint16_t,2800

CSV is for reading; only the JSON form can be restored.

Writing

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

Select the parameter by --name or --id, never both, and give --value (or --clear, which writes 0 / the empty string).

What happens on every write, in order:

1. The whole table is read first. That is the name→id map, and it is also how the tool knows the parameter's type and current value. If that read is unreliable the write is abandoned — writing to a wrongly-mapped id is worse than not writing.
2. The value is converted to the device's type. You always pass a string on the command line; it is cast to the width and signedness the device declared. A value that does not fit is skipped, not truncated.
3. A no-op write is skipped. If the device already holds that value, nothing is sent.
4. The write is sent, retried up to three times on a 2-second timeout.
5. Optionally the device is rebooted, and only after a successful write.

Option	Effect
--name xyz	select by name
--id 0	select by identifier
--value 0	the new value
--clear	write 0 / the empty string
--from-json <file>	restore a whole table from a JSON dump
--reboot / --no-reboot	reboot after a successful write; default is no reboot
--check-only	dry run: report whether the device is already in sync, write nothing

--check-only returns success when every requested parameter already matches and failure on the first one that does not. It is the safe way to answer "does this device need touching?".

Restoring a saved configuration

muxen-uds -i can0 -d 0x040 writeconfig --from-json device-0x040.json

--from-json cannot be combined with --name or --id. Each entry is matched by name against the live table and its id re-resolved, so a dump taken before a firmware update still applies afterwards. Entries whose name the device does not carry are skipped silently; read-only names are dropped as the file is parsed.

Backing up every device

cd /var/tmp && muxen-uds -i can0 backup

backup runs a passive scan, then a readconfig on each device it found, writing one JSON file per device into the current working directory:

device-0x280-function-10-instance-00.json
device-0x040-function-01-instance-00.json

Two consequences of it being built on the passive scan: a device that stayed quiet during the 5-second window is not backed up, and the result is only as complete as the scan was. For a full-inventory backup, check uid --scan first and read the missing devices by hand.

A device whose read failed is reported (at -vv) and simply has no file. backup itself still exits 0.

Factory operations

muxen-uds -i can0 -d 0x280 factory --reset-device-configuration

Option	Effect
--reset-device-id	reset the device's CAN address; the device is rebooted afterwards
--reset-device-configuration	reset every configuration section except the CAN address
--allocate-device-configuration <device-id>	allocate a configuration section for a dynamic device (0–0xFFF)
--port 0-255	the port to allocate it on

At least one of the three must be given, otherwise the command prints its help.

--reset-device-id sends the device back to its parking address, so plan for the unit to reappear at instance 63 of its function and to need a new instance — see Devices, addressing and discovery. --reset-device-configuration leaves the address alone, which is what you want before re-deploying a project onto a unit.

deploy performs a --reset-device-configuration on each device before writing it, which is why a deploy is a full replacement of a device's settings rather than a merge.

Restarting a device

muxen-uds -i can0 -d 0x280 reset --delay 500

--delay is the delay in milliseconds the device waits before restarting, 0–65535, default 500. The delay exists so the device can acknowledge the request before it disappears.

Raw routines

muxen-uds -i can0 -d 0x040 routine --action 1 --routine 2

routine sends a UDS RoutineControl request as-is. --action is the routine control type (1 = start, 2 = stop, 3 = request results), --routine the 16-bit routine identifier, and --payload an optional hexadecimal string appended as the binary payload. On success it prints the device's answer on stdout as hexadecimal bytes, starting with 71, the positive RoutineControl response; a refusal or a timeout is reported on stderr instead.

It is an escape hatch for routines that have no dedicated command; the example above is exactly what locate sends. Use it when you know what the device expects — nothing here validates the routine against the target.

Compatibility with 4.x firmware

--firmware-4x is a global option, given before the command:

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

It changes three things on the write path: the identifier is sent with bit 15 set, InstanceNum is never written from a JSON restore, and a multi-parameter write stops after InstanceNum. Leave it off for current firmware.