Loading and updating a firmware

Once a box is on the boat it is updated over the CAN bus, from the Brain, without opening anything and without a probe.

Which image goes in which box

Released images are named after what they are:

010010028-MODBUS-app_blue_airco-firmware.srec      CAN Serial/Modbus
010010028-SERIAL-V2-app_blue_airco-firmware.srec   CAN Serial/Modbus V2

Part	Meaning
010010028	the product ID — the application
-MODBUS / -SERIAL-V2	the board the image was built and signed for
app_blue_airco	the application's short name
-firmware.srec	the update image, loaded over the bus

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

1. The board. Each of the three boards has its own signing key, and each has its own memory map. An image for the wrong board is refused: either the box rejects the transfer request outright, because the image does not start where its own application lives, or the bootloader rejects the signature afterwards. Either way nothing is written over the running firmware. This is also why a 5.x image never installs on a box running 6.x, and the reverse.
2. The transfer itself. Every block carries a checksum, blocks must arrive in order, and the whole image must arrive. Any break and the box aborts — see below.
3. The product ID and the equipment on the channels. Nothing checks this. A box on the same board happily accepts any application built for that board: a Frigomar gateway will run a Blue Airco firmware and then understand nothing of what is on its channels. Read the product ID before you push anything.

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.

Doing the update

muxen-uds -i can0 listfirmware                     # what the Brain has
muxen-uds -i can0 -d <address> firmware --name 010010028-SERIAL-V2-app_blue_airco-firmware.srec

--name picks an image the Brain already holds; --srec <path> loads one from a file instead.

While it runs the box is out of service: it stops translating, and everything on its four channels disappears from the boat's screens. Expect that, and do not do it under way. When the last block has arrived the box confirms, waits half a second so its reply reaches the bus, then restarts and comes up on the new firmware.

Keep the bus quiet during the transfer. The box gives up if more than five seconds pass between two blocks, so a saturated bus or a Brain that goes off doing something else will abort the update. 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 areas: the one it runs from, and a spare. An upload only ever writes the spare. The running firmware is not touched at any point during the transfer.

Before it accepts a single byte, the box checks that the image claims to start exactly where its own application area begins and that it is not larger than that area. An image for another board fails this test immediately.

During the transfer, every block is checked: a bad checksum, a block out of sequence, a block pointing outside the application area, or more than five seconds of silence, and the transfer is abandoned. At the end the box also checks that the number of bytes it received matches the size the Brain announced. If any of that fails, nothing further happens — the box simply carries on running the firmware it already had.

Only a complete image that passes those checks gets as far as the bootloader, and the bootloader verifies its signature before installing it. A cable pulled mid-upload, a Brain that reboots, a bad image: in every case the box ends up either on the new firmware or on the old one, never on nothing.

If an update fails, nothing is damaged and nothing needs opening. Check the box's hardware ID and software version, pick the matching image, and try again.