Commander1024
ab6a8010ba
Separate operator guides from development contracts, relocate implementation notes under `docs/devel/`, and update cross-references and hardware tooling paths. Add getting-started, user administration, and firmware update guides while preserving firmware behavior.
87 lines
8.0 KiB
Markdown
87 lines
8.0 KiB
Markdown
# Firmware update
|
|
|
|
The administrator can upload a locally built **application binary** through HTTPS. There is no release server, automatic download, or automatic update service.
|
|
|
|
Related guides: [Web administration](web_administration.md), [account provisioning](user_administration.md), [command reference](command_reference.md), and [security operations](security_operations.md). Implementation details are in the [web development contract](devel/web_administration.md#application-firmware-upload); historical acceptance and regression guidance remain in [roadmap Phase 10](devel/roadmap.md#phase-10--simple-admin-web-firmware-upload).
|
|
|
|
## Before you begin
|
|
|
|
- Keep **USB-to-UART** available for UART0 administration and wired flashing. Native USB CDC is UART1 serial access, not the administration/flashing recovery path described here.
|
|
- Install OTA-enabled firmware **by wire first**. Firmware without the upload route cannot install its own first web updater. The custom OTA partition layout is required. [One-time migration from the old default layout](getting_started.md#partition-migration-and-erasing) is a separate, destructive procedure—not an ordinary update step.
|
|
- Select trusted firmware for **`esp32-s3-devkitc-1-n16r8`**, compatible with this board, partition layout, and existing stored configuration schemas. Check the [legacy downgrade warning](devel/roadmap.md#phase8-legacy-credential-compatibility): older v1-only firmware cannot read the newer TLS-only HTTPS material. An older build is not automatically a safe recovery choice.
|
|
- Save desired RAM-only serial, Wi-Fi, hostname, and display settings. Record nonsecret configuration and verified public HTTPS/SSH fingerprints. Keep passwords separately in a password manager; there is no supported NVS backup/restore facility.
|
|
- Arrange a maintenance window, stable power, and stable network access. Stop work that depends on uninterrupted serial traffic. Use trusted HTTPS and an `admin` account, verifying device identity as described in [security operations](security_operations.md).
|
|
|
|
## Build and upload
|
|
|
|
1. From the trusted project checkout, build:
|
|
|
|
```sh
|
|
pio run
|
|
```
|
|
|
|
2. Select exactly the application output:
|
|
|
|
```text
|
|
.pio/build/esp32-s3-devkitc-1-n16r8/firmware.bin
|
|
```
|
|
|
|
Do not select an ELF, ZIP, merged full-flash binary, bootloader, or partition-table image. Renaming another file to `.bin` does not make it suitable. The browser requires a nonempty `.bin` no larger than **4 MiB**; the device also checks the actual destination capacity and image structure/integrity.
|
|
3. Sign in as `admin` and open **Settings → HTTPS / Reboot → Firmware update**.
|
|
4. Choose the file in **Application .bin**, select **Upload and reboot…**, and confirm. Keep power connected.
|
|
5. Wait for validation and reboot—not just **100%** transmitted bytes. The UI may first report **Upload complete. Validating firmware…**, then **Firmware accepted; rebooting. Reconnect and sign in shortly.**
|
|
6. Restore network reachability, use **Reconnect after reboot** or reload, and explicitly sign in again. Verify the running application, saved configuration, account access, and HTTPS/SSH identities before another upload. Check UART0 if the result is unclear.
|
|
|
|
Upload handling is synchronous and can stall or drop browser serial/admin connections and other web work. UART0 and native USB are independent recovery/data paths, not guarantees of uninterrupted timing during flash operations. Reboot interrupts **all** transports.
|
|
|
|
## What is preserved—and what is not guaranteed
|
|
|
|
The updater writes only the inactive application slot and OTA selection metadata. It does not rewrite the partition table/bootloader or erase NVS, PHY, storage, or other data partitions. Saved users, credentials, settings, and device identities remain stored. This preserves stored bytes, not compatibility with arbitrary firmware: the uploaded application must understand existing schemas and must not itself erase or incompatibly migrate them.
|
|
|
|
The server checks target/header, completeness, exact image length, and SDK image integrity, including the appended SHA-256 digest, before selecting the image. **A digest is not publisher authentication.** Neither validation nor a `.bin` filename proves that the firmware is trusted, fully board-compatible, or able to boot and operate correctly.
|
|
|
|
There is **no image-signature/signing-key policy, secure-boot guarantee, anti-rollback/version-downgrade enforcement, automatic rollback, or post-boot health-confirmation mechanism** in this update workflow. There is no partition migration or NVS backup/restore. A valid but broken application can require wired recovery.
|
|
|
|
## Lost response, timeout, or failed upload
|
|
|
|
**Do not blindly retry or power-cycle an uncertain update.** A lost response, page close, sign-out, timeout, or browser abort proves neither cancellation nor failure. The image may already be selected, and any later reset can boot it.
|
|
|
|
- Before boot selection, rejected/incomplete images and receive/write/validation failures abort the upload without selecting the candidate. The inactive slot may already be erased or partially written.
|
|
- `firmware_commit_failed` means boot-metadata selection failed with SDK transactional uncertainty. Inspect the device before any reset or retry; do not infer that selection definitely stayed unchanged.
|
|
- A successful response means validation and boot selection succeeded. Successful server send schedules reboot after about 500 ms, but does not prove browser receipt or successful boot.
|
|
- If sending the response fails **after selection**, the device schedules no automatic reboot and rejects further admissible uploads with **409 `firmware_selected_reboot_required`** until device reset. HTTPS stop/start does not clear this latch. Inspect via UART0 and deliberately reboot when appropriate.
|
|
- Reloading clears browser-side uncertainty locks only; it does not undo committed work or clear the device's selected-image latch.
|
|
|
|
The device's ten-second receive-stall and 120-second receive-loop checks are not hard flash-operation deadlines. Synchronous erase/write/validation can extend elapsed time. The browser's 180-second timeout cannot cancel committed work. Software reboot/lifecycle exclusions cannot prevent physical reset, power loss, or panic.
|
|
|
|
### Interpreting errors
|
|
|
|
| Response | Meaning / next step |
|
|
|---|---|
|
|
| 400 | Malformed, incompatible, or incomplete image/request. Check the build artifact before a deliberate new attempt. |
|
|
| 401 / 403 | Authentication, Origin/CSRF, or administrator access failure. Restore a valid admin login; if upload had begun, inspect state first. |
|
|
| 408 `firmware_timeout` | Device receive deadline exceeded. Inspect state and network conditions. |
|
|
| 409 `firmware_selected_reboot_required` | Image already selected; inspect and deliberately reboot, rather than upload again. |
|
|
| 413 / 415 | Image exceeds destination capacity or wrong content type. Use the supported application binary/browser workflow. |
|
|
| 500 `firmware_write_failed` / `firmware_commit_failed` | Flash/selection failure. Use UART0 to inspect; commit failure carries selection uncertainty. |
|
|
| 503 | Busy, unavailable partition/service, or insufficient resources. Resolve the condition before a deliberate retry. |
|
|
|
|
A disconnected browser may never receive the error. Competing web requests may wait during upload rather than promptly report busy.
|
|
|
|
## Wired recovery
|
|
|
|
If the new application does not boot or no longer serves HTTPS:
|
|
|
|
1. Connect the USB-to-UART path and select a known-good **schema- and layout-compatible** project checkout.
|
|
2. Run the documented wired workflow:
|
|
|
|
```sh
|
|
pio run --target upload
|
|
pio device monitor -b 115200
|
|
```
|
|
|
|
3. Inspect startup, restore connectivity, verify saved settings and identities, and test normal operation before returning to web updates.
|
|
|
|
**Do not erase for ordinary updates or recovery.** Erasing destroys persisted configuration and credentials. There is no automatic recovery flashing or rollback. If the partition layout itself needs migration, use the separate migration procedure knowingly rather than treating erase as generic troubleshooting.
|
|
|