Bootloader OTA Operator Guide

This guide explains the Universal Shifters single-slot bootloader update flow in abawo_bt_app.

App-Side Flow

Connect to the target button and open Device Details.
In Firmware Update, select a local raw application .bin with Select Firmware.
The app validates size and vector table before enabling the update.
Review file metadata: size, session id, CRC32, app start, image version, and reset vector.
Tap Start Update and keep the phone close to the button.
The app sends EnterDfu to the running application, waits for reset, and connects to US-DFU.
The app sends bootloader START; this erases the active app slot.
The app transfers offset-based frames and tracks bootloader expected_offset.
The app sends FINISH, waits for final OK, then waits for the bootloader reset.
Success is shown only after the updated app reconnects and status verification passes.

File extension must be .bin.
Image must be at least 8 bytes and no larger than 0x42000 bytes.
Image bytes must start at application address 0x00030000.
Initial stack pointer must be aligned and within 0x20000000..=0x20010000.
Reset vector must have the Thumb bit set and point inside the image after the first two vector words.
Flags are always 0; encrypted/signed update flags are not supported by the current bootloader.
Image version is currently sent as 0 unless a later packaging flow provides it.

Single-slot update is destructive after bootloader START; the previous app is erased before image transfer.
If transfer fails after START, recovery is through bootloader DFU or external reflash.
Gear writes and Connect Button to Bike stay disabled while OTA is running.
If BLE drops during transfer, retry promptly while the bootloader is still advertising US-DFU.
Cancel after START sends bootloader ABORT and leaves the device in bootloader/recovery flow.

Symptom in app	Likely cause	Operator action
Invalid stack pointer or reset vector	`.bin` is not a raw app image for `0x00030000`	Rebuild/export the application image from the correct linker layout.
Could not connect to bootloader DFU mode	Phone did not find `US-DFU` after app reset	Move closer, retry, and verify the device is advertising `US-DFU`.
Timed out waiting for bootloader DFU status	Status indication/read did not arrive	Reconnect to `US-DFU` and retry.
Bootloader status `bounds error`	Image length or app start rejected	Use a valid app image no larger than `0x42000` bytes.
Bootloader status `CRC error`	Full-image CRC did not match flash contents	Re-export or re-download the `.bin`, then retry.
Bootloader status `vector table error`	Bootloader rejected the written vector table	Rebuild firmware for app start `0x00030000`.
Bootloader status `flash error`	Flash erase/write/read failed	Retry once; if repeated, service or externally reflash the device.
Bootloader status `boot metadata error`	Bootloader could not persist boot metadata	Treat as service risk; retry reflash, then return device if repeated.
Updated app did not reconnect	New app did not boot/confirm or reconnect window expired	Scan for `US-DFU`; if present, retry OTA with a known-good image.
Updated app reconnected but verification failed	Normal app status read failed	Reconnect manually and verify status; retry only if the device is still in bootloader or unusable.

Escalate with app logs, device identifier, firmware filename/hash, and observed bootloader status when a known-good image repeatedly fails.

Happy path: select valid .bin, enter bootloader, transfer, finish, reboot, reconnect, completed.
Image validation: invalid extension, empty file, too-small file, too-large file, invalid SP, invalid reset vector.
UI state gating: gear ratio save and trainer assignment remain disabled during OTA.
Queue-full/status recovery: app sends GET_STATUS and resumes from returned offset.
Cancel path: cancel after START sends [ABORT, session] and shows canceled state.
Bootloader status errors: CRC/vector/flash/metadata statuses show actionable messages.
Reconnect timeout: no updated app reconnect produces a clear failure message.
Regression check: after successful update, status and firmware telemetry still load normally.