abawo-bt-app/docs/dfu-v1-operator-guide.md

DFU v1 Operator Guide

This guide explains how to run and support firmware updates for Universal Shifters in abawo_bt_app.

App-Side Flow (Operator)

1. Connect to the target button and open Device Details.
2. In Firmware Update, select a local .bin file with Select Firmware.
3. Confirm file metadata is shown (size, session id, CRC32), then tap Start Update.
4. Monitor progress:
   • Phase text: Sending START, Waiting for ACK, Transferring, Finalizing
   • Progress bar and bytes sent
   • Last ACK sequence (0x..)
5. During Finalizing, expect a brief disconnect while the device reboots.
6. The app attempts reconnect + reachability verification automatically.
7. Success is only shown after reconnect verification passes.

Operational notes:

• Keep the phone near the button for the full transfer.
• Keep this screen open until completion.
• Gear writes and "Connect Button to Bike" are disabled during DFU by design.

Troubleshooting Matrix

Symptom in app	Likely cause	Operator action
Preflight fails with MTU too low	Negotiated MTU below minimum required for 64-byte frames (>=67)	Reconnect BLE, retry update, and reduce RF interference/distance.
Timed out waiting for initial DFU ACK after START	ACK indications not enabled/received, or unstable link	Disconnect/reconnect button, retry update, keep device nearby.
Upload stalled: no ACK progress ...	Packet loss or weak BLE link; missing frame prevents cumulative ACK movement	Move closer, reduce interference, retry update; app will rewind and resend from last ACK while running.
Received malformed ACK indication	Corrupted/unexpected ACK payload from transport path	Reconnect and retry. If repeatable, capture logs and firmware version for investigation.
Device did not perform the expected post-FINISH reset disconnect	Device did not reset after FINISH, or disconnect event was missed	Retry update once. If repeatable, treat as firmware-side finalize/reset issue.
Device did not reconnect after DFU reset	Reboot happened but reconnect window expired	Manually reconnect in app and retry update with strong signal.
post-update verification failed or verification timeout	Device reconnected but status read failed in verification step	Reconnect and verify normal status manually; retry update only if needed.
Transfer reaches end but completion never succeeds; ACK does not advance after FINISH	Likely CRC mismatch (or device rejected FINISH completeness/integrity checks)	Re-export/re-download firmware .bin, reselect file, retry. Do not power cycle mid-transfer.

Escalate with logs when the same firmware + device repeatedly fails after one clean retry.

DFU v1 Limitations and Roadmap

Current v1 limitations:

• The app verifies reachability after reconnect, but cannot strictly compare old/new firmware version yet (no version characteristic exposed by device).
• START.flags supports encrypted/signed modes, but the app currently runs plain .bin updates and does not perform signed/encrypted payload validation.

Roadmap direction:

• Add device firmware version characteristic and enforce strict version progression checks in-app.
• Add signed update manifest verification before upload acceptance.
• Add encrypted payload transport mode and key management flow.

Manual QA Checklist (Release Validation)

Run on at least one known-good button and firmware image.

• Happy path: Select valid .bin -> start -> transfer -> reboot/disconnect -> reconnect -> completed.
• UI state gating: During DFU, gear ratio save and "Connect Button to Bike" controls stay disabled.
• Cancel path: Start update, cancel mid-transfer, confirm terminal canceled state and safe recovery.
• Preflight MTU failure: Force low-MTU environment; confirm clear failure message and no transfer start.
• Stalled ACK handling: In degraded RF conditions, verify retries/rewind behavior and bounded failure messaging.
• Reconnect timeout handling: Simulate slow/no reconnect after FINISH; confirm explicit reconnect timeout error.
• Bad file validation: Confirm non-.bin and empty file selections are rejected with actionable messages.
• Regression check: After update attempt (success/failure), reconnect normally and verify status reads still work.

If a checklist item fails, attach app logs, device identifier, firmware filename/hash, and observed phase/error text.