When an update does not go through

Before anything else: a failed update never leaves the Brain without a working system. The new version is written to the copy that is not running, the running copy is never touched, and a new copy that fails to boot is abandoned by the bootloader in favour of the previous one. Nothing on this page is made worse by trying again.

The update page says the Brain is not provisioned

The Brain has never been introduced to the update server, or it lost its credential when its data partition was rebuilt. It is not broken and it runs perfectly well — it simply cannot be updated over the air until somebody with server credentials registers it. That is a yard operation.

A USB-key update works regardless and is the way to update a Brain in this state.

The page says no update is available, but I was told there is one

Most often one of these, all of them deliberate:

• It is already installed. Check the installed version shown on the page. If it is the new one, the update is done.
• It has just been installed and the Brain is confirming the result. Between the reboot and the confirmation, the version is deliberately not offered again so it cannot be installed twice. Give it a minute and check again.
• The assignment is for another Brain. Boats with more than one Brain have one entry per board on the server.

The check never comes back

A check is a real round-trip to the update server. On a satellite or a weak cellular link it can genuinely take the best part of a minute, and it will fail outright if the boat has no route to the internet at all.

Two things to look at before anything else: whether the boat is actually online, and whether the Brain's clock is right. A clock that is far off breaks the security check on the connection to the server, and the symptom is an unhelpful connection error rather than anything mentioning the time.

The install stops partway through

The page shows failed with the reason. The Brain is not at risk — the transfer was writing into the copy it is not running from, and the bootloader was not switched.

The usual causes:

• The link dropped. Try again on a better connection.
• The file could not be trusted. The update was not signed by MUXEN, or was altered in transit. Nothing is written when that happens.
• The update is not for this hardware. Same outcome, nothing written.

The failed update stays on offer and can be applied again.

The install finished but the Brain did not reboot

The install itself is complete and the new copy is already selected in the bootloader, so rebooting the Brain by hand finishes the job with nothing lost.

After the reboot, it says the update failed

Two different things produce that.

The Brain came back on the old version. The bootloader tried the new copy, it did not come up, and the bootloader put the previous one back. That is the safety mechanism doing its job. The boat is running exactly what it was running before. Why the new version did not come up is a question for MUXEN — report the version and the action number.

The Brain is running the new version but did not certify itself healthy. The update is on the Brain and working; something in the start-up checks reported a problem. Also one to report.

Either way the update is not marked as applied, so it will be offered again at the next check.

The installed version shows as unknown

Normal on a Brain whose software was written at the factory rather than by an update. It clears after the first update, it is not a fault, and it does not prevent updating.

Nothing happens when I plug the USB key in

Work through this in order:

• Give it time. The install takes several minutes and there is no progress bar on the screen for it. "Nothing happening" for two minutes is normal.
• Check the stick is readable by the Brain — FAT32 or exFAT, not a Mac-only or Linux-only format.
• Check the file name still ends in .raucb and that the file was not renamed, unzipped or repackaged.
• Check the version is actually newer than what the Brain is running. A file at or below the running version is ignored on purpose — that is not a fault, and it is why plugging the same stick in twice does nothing the second time.
• Check it is the file for a Brain. A file built for other hardware is refused.
• Try the stick on a computer first. A stick the Brain cannot mount is by far the most common cause.

If the version still does not change after a reboot, the install did not run and the reason is in the Brain's system log — that is where MUXEN will look; see internal/troubleshooting.md.

FAQ

Is it safe to update while we are under way? The download and the install are: they write into the copy of the system software the Brain is not running, and nothing on the boat changes. The reboot is the part to plan for — the screens and every MUXEN service go down for a boot cycle, and for a second one if the new version has to be rolled back. Do it at anchor or alongside if you can.

What happens if the power goes out during an update? Nothing is lost. The Brain was still running its old system software, and the half-written copy is simply incomplete — it is not the one the bootloader starts. Run the update again.

What happens if the new version does not work? The bootloader tries the new copy, and if it does not come up it starts the old one instead. The Brain ends up back where it was, and reports the failure to the update server the next time it has a link.

Will an update wipe my settings? No. Configuration and data live on a separate partition that updates never touch. Only the system software is replaced.

Does the Brain update itself overnight? No. It contacts the update server only when somebody opens the update page and asks, and it installs only after an explicit confirmation. Nothing happens on its own.

How long does an update take? Long enough that it is not worth promising a number: it depends on the size of the release and on the link. Over the air, watch the percentage — while it moves, it is working. From a USB key, expect several minutes.

Can I go back to the previous version? Not from the update page, and not from a USB key: a key is only installed when it is newer than what is running. Going backwards is a yard operation.

Can I update two Brains from the same stick? Yes. Nothing is written to the stick and the file is not consumed.

Tips

Run a check before you need one. Checking is free and changes nothing. Knowing on Friday that a release is waiting is better than discovering it when the yard is closed.

Do the reboot on your terms. Applying an update from the page reboots the Brain about five seconds after the install finishes.

Note the action number. It is the one identifier that ties what you did on the boat to what the update server recorded, and it is what MUXEN will ask for.

Check the installed version after a reboot. It is the fastest way to see whether the update actually took.

Do not run two updates at once. A second install is refused, but two people — one on the screen, one with a USB key — will confuse each other.

Keep the clock right. It is the cause of update failures that looks least like itself.

For MUXEN engineers

Log locations, service states, HTTP status codes and the failure modes of the update client itself are in internal/troubleshooting.md.