Loading and updating a firmware

A can-mdv in service is updated over the boat's CAN bus, from the Brain, without opening anything and without touching the battery switch it is wired to.

Which image goes in which box

Released images are named after what they are:

010010029-V2-app_mdv-firmware.srec

Part	Meaning
010010029	the product ID — which firmware this is
-V2	the board, can-mdv v2 — the one in service
app_mdv	the program the product ID stands for
-firmware	the update image, loaded over the bus

Three things must line up, and only the first two are checked for you:

1. The signature. The image is signed with the board's key. A box whose bootloader does not recognise the signature never installs the image; it restarts on the firmware it already had. An image without -V2 in its name is for the earlier board and will be refused.
2. The product ID. Both the box and the image carry one. They must be the same, or you are changing what the box does.
3. What is wired to the box must match the firmware. Nothing checks this. The hardware-test firmware will happily install itself on an installed box and stop driving the battery switch.

Read what a box currently is before touching it:

muxen-uds -i can0 -d <address> readconfig --only-name ProductId \
                                          --only-name HardwareId \
                                          --only-name SoftwareVersion

<address> is the device address on the bus — see Reference for how it is formed. A can-mdv answers on two addresses; the battery-switch one is the one to use.

TIP

A box that has never been given an instance number does not answer on its battery-switch address at all. Find it with muxen-uds -i can0 uid --scan and address it by UID, or talk to its battery device, which is reachable from the first power-up.

Doing the update

muxen-uds -i can0 listfirmware                    # what the Brain has
muxen-uds -i can0 -d <address> firmware --name 010010029-V2-app_mdv-firmware.srec
muxen-uds -i can0 -d <address> reset

The transfer itself does not interrupt the box: it keeps running its current firmware, keeps the switch under control and keeps publishing while the image is being written to its spare slot. The new firmware is only installed at the reset, and it is the reset that takes the box out of service for a few seconds — the switch is not commanded and the battery disappears from the boat's screens while it restarts.

Do not do it under way, and not while anyone is relying on being able to open or close the battery switch from a screen.

The full command reference lives in the muxen-uds manual, chapter Firmware.

Why a failed update cannot brick a box

The box holds two firmware slots. An upload writes the spare slot, never the running one — see the flash layout in The hardware. Nothing about the running firmware is touched while the transfer is in progress.

At the next reset the bootloader looks at the spare slot and checks the image against the signing key built into it. Only an image that is complete and correctly signed is installed. Anything else is ignored and the box starts on the firmware it already had:

What went wrong	What the box does
the transfer was cut — cable pulled, Brain rebooted, bus lost	the spare slot holds a partial image, which fails the check; the old firmware starts
the image was for the earlier board — no -V2 in its name	the signature does not match the key in this box's bootloader; the old firmware starts
the image file is corrupt	same — it fails the check; the old firmware starts

A can-mdv also gives up on a transfer by itself: if more than five seconds pass between two chunks, it abandons the upload rather than sit waiting. The command reports the failure; nothing is installed.

In every case the box ends up either on the new firmware or on the old one, never on nothing. Check the image, then run the command again.