Update

Update

A player is flashed once over USB. After that, new firmware reaches it three ways: it finds releases by itself and installs them at two taps; its web page takes a file from your computer; a file in the card's root is applied at the next power-on. Every image is signed, the new firmware runs on trial before it is kept, and there is a way back to the factory copy without a computer.

The first flash

Each release carries two images. ….factory.bin is the whole flash for a board over USB: the first time, to start over, or to move a player to firmware signed with another key. ….ota.bin is the same firmware for a player that already runs evo-esp32, through any of the three ways below.

With esptool 5 and the board on its USB-C port (it appears as a serial port; no driver):

esptool --chip esp32c5 --port PORT write-flash 0x0 evo-esp32-waveshare-esp32-c5-touch-lcd-28-<version>.factory.bin

esptool verifies the write. If it cannot connect, hold the board's BOOT button while plugging it in and run the command again. The flash clears the device's stored network hint (the access point's channel, so the first join after it takes a few seconds longer); your settings are on the card, which stays in. A player on 0.1.6 or earlier takes this flash once; from 0.1.7 it updates itself.

Releases the player finds

With the network up, the player reads the project's release manifest a minute and a half after the network joins and once a day after that, and says where it stands in the Update › row of Settings and on its web page:

The row says	Meaning
up to date	The release it runs is the latest.
0.2.0 available	A newer release is published. Two taps on the row within twelve seconds install it; the first tap arms, the second confirms.
waiting for a quiet moment	The look is put off while a heavy track plays (a 96 kHz FLAC leaves little working memory for the connection); it is taken ten minutes later, or the moment nothing plays.
check failed: …	The manifest could not be read; the player tries again in an hour.
off	update = off on the card.

update = auto installs a release by itself once nothing has played for a minute; update = check (the default) only tells you; update = off never looks. update_url points the player at a manifest of your own, for a fleet held on a release of your choosing; empty, it is the project's. The keys are in Configuration.

An install is the same as any other update: the image is fetched over HTTPS into the free slot, its signature is checked, and the player restarts into it on trial.

From the web page

The player's page is at http://<name>.local/ (the name is name in evoconfig.txt, evo-player when not set; the address is in Settings). With web_user and web_password set on the card, the browser asks for them once.

Firmware on this player lists the three slots — the factory copy and two update slots — with each one's version, its id (the first bytes of the build's fingerprint), which is running, which boots next, and its state. Update takes an .ota.bin from your computer. Releases is the row above, on the page: the standing, Install when one is available, Check now. Factory copy has Keep this firmware as the factory copy, offered when the player runs from an update slot and the firmware is past its trial, which copies it into the factory slot; and Restart into the factory copy, when the player is not running from it.

http://<name>.local/status is the same in plain text, for a script.

From the card

One <anything>.ota.bin in the card's root is applied at power-on, before anything plays. The file is renamed <anything>.ota.applied once written, so it is applied once. A file that is the firmware already running is marked applied without a write, and the panel says Done. A file that is not whole, is not a firmware image, or is not signed with the player's key is renamed <anything>.ota.refused, the panel says Update failed with the reason (also in evostatus.txt), and the music plays after a tap. With more than one .ota.bin in the root none is touched and the panel says so the same way. An earlier .ota.applied or .ota.refused of the same name is replaced.

What the panel shows

While firmware is written the face is a message in the middle of a cleared screen: Updating — Writing the new firmware. Do not switch off: the player restarts by itself when it is done — then Restarting. Nothing else is shown and taps do nothing; the write takes under a minute. An outcome that is not a restart stays up until a tap: Update failed with the reason (the firmware you had keeps running), or Done — a copy kept as factory, or a file on the card that is the firmware already running.

The trial minute

New firmware starts on trial. It is confirmed once the panel has lit, the audio output has opened, the network has joined (where the card names one; a router that is off is given three minutes, then forgiven) and the main loop has turned for a healthy minute — about seventy seconds after power-on in practice. A firmware that has not met that within five minutes, or that crashes before it does, is rolled back: the bootloader returns to the firmware the player had.

That is also what happens if the power is cut during the trial. Wait for the face to come back and the music to start before touching anything; the Update › row and the page say up to date once the new firmware is confirmed.

Signed firmware

Every image carries a signature (ECDSA P-256, in the Secure Boot v2 format) and the running firmware accepts a new image only when it was signed with the key of its own. A file that is unsigned, signed with another key or altered in transit is refused after it is written and the slot is cleared. Releases are signed with the project's release key held in the build service; nothing is burned into the chip, so a board can always be flashed over USB, and a USB flash is how a player moves to firmware signed with another key.

The way back

Firmware that runs but is wrong — it starts and confirms, yet something you need is broken — is left by returning to the factory copy, which the trial cannot do for you. Two ways:

• On the panel, with no computer: at power-on, hold a finger on the panel from the moment it lights and keep it there for five seconds. The face says Returning and the player restarts from the factory copy. The window for this is the first fifteen seconds after the panel lights.
• On the page: Restart into the factory copy.

The update slots keep their firmware through the return: the next update goes on as before, and the factory copy is what you kept there last (Keep this firmware as the factory copy) or the release you flashed over USB.

The board's own BOOT button is not this: it is the chip's download strap for esptool.