SolarOS 4.13.4 manual · app

Flash another ESP board

flash downloads complete SolarOS factory images to SD and programs another supported ESP board through a named UART bus. The target must share ground with the SolarOS device. Connect the SolarOS UART TX pin to target RX and SolarOS RX to target TX. Both sides use 3.3 V logic; do not connect a 5 V UART signal.

Open the catalog browser:

flash

The browser reads only the verified catalog saved on SD. It does not access the network when it opens. Its Catalog tab presents the available board, flavor, and version entries as a foldable tree. All groups are initially folded. Use Up and Down to select an entry, Left and Right to fold or unfold a group, and Enter to act on a version. The browser retains the selected entry, scroll position, and folded groups after catalog refreshes and artifact operations. An asterisk marks an artifact that is cached on SD. Enter offers to download a remote artifact or program a cached artifact. d always offers a download, f always offers programming, and r refreshes the signed catalog. Delete or x asks for confirmation before it removes the selected cached artifact from SD. The verified catalog entry stays available, so the artifact can be downloaded again.

Press Tab to open Settings. Select the UART port with Left and Right. Select BOOT pin or RESET pin and press Enter to enter a GPIO number from 0 to 63. An empty value disables automatic control; Delete also clears the selected pin. These settings apply to the current Flash app session. The control pins refer to GPIOs on the SolarOS device, not pins on the target.

Before programming starts, a popup stays visible with the instructions for the current control-pin setup. With no control pins, put the target into ROM download mode manually while the popup is open. During refresh, download, verification, and programming, the popup shows the current stage and progress. The final success or failure remains visible until it is dismissed.

Catalog refresh uses the same repository as ota url. For example, an OTA URL of http://server/solaros/latest reads the flash catalog and signature from http://server/solaros/flash/. Artifact URLs then come from the verified catalog.

The same operations are available from the shell:

flash refresh
flash list
flash download BOARD FLAVOR [VERSION]
flash BOARD FLAVOR [version=VERSION] [port=uart0] [boot=PIN] [reset=PIN] [baud=RATE]

Shell completion for flash BOARD FLAVOR reads the verified SD catalog and offers only boards and flavors whose factory artifact is already cached.

When version is omitted, SolarOS selects the first matching catalog entry; the release catalog orders newer versions first. The program command refuses to use an artifact that is not already cached. port, boot, and reset refer to resources on the SolarOS device, not pins on the target.

If both boot and reset are present, SolarOS drives the target into ROM download mode automatically. With only boot, SolarOS holds that signal low while it starts the connection; reset the target manually. With only reset, hold the target's boot strap active while SolarOS toggles reset. With neither, put the target in download mode before you run the command.

Storage and verification

All data is stored on removable media:

/sdcard/.flash/catalog.json
/sdcard/.flash/catalog.sig
/sdcard/.flash/BOARD/FLAVOR/VERSION/flash-manifest.json
/sdcard/.flash/BOARD/FLAVOR/VERSION/factory.bin

The catalog signature uses the SolarOS OTA public key. Downloads are streamed to a staging file, checked against the catalog size and SHA-256, extracted, and checked again against flash-manifest.json before activation. A failed update keeps the previous cached artifact.

Before erasing the target, SolarOS verifies the cached factory image, opens the requested UART exclusively, identifies the target chip, and compares it with the manifest. It rejects an unsupported or different chip, an undersized flash device, secure-download mode, flash encryption, or secure boot. A successful write ends with the target bootloader's MD5 verification.

The board ID is explicit because the ESP ROM reports the chip family, not the physical board or its pin/display/storage layout. A matching chip is therefore necessary but is not enough to choose a board artifact safely.

Resource use

The flasher has no boot-time task and keeps no catalog or transfer buffers in memory while unused. It allocates its app state, catalog model, worker stack, HTTP buffers, UART loader context, and transfer buffer only after flash is opened, and releases them when the app exits. UART and optional GPIO resources are also claimed only for the active programming operation.

Quick reference

Run flash refresh to cache the signed catalog, flash list to show artifacts, and flash download BOARD FLAVOR [VERSION] to store one verified factory image under /sdcard/.flash. Program it with flash BOARD FLAVOR plus optional version=, port=, boot=, reset=, and baud= values. The target chip must match the selected board artifact. Connect crossed 3.3 V UART signals and a common ground; use both optional control pins for automatic download mode.