acceptance_criteria:
- User can select a firmware .bin and complete upload end-to-end
- Upload follows protocol and handles packet loss via retransmit
- App shows clear progress and failure states
- Device reconnects after reboot and is reachable

created_by: Yandrik

description:
Implement the firmware update flow defined in universal-shifters/update-process.md for the Flutter app.

Scope:
- Manual local .bin selection and upload over BLE GATT
- START/DATA/FINISH/ABORT protocol support
- Cumulative ACK handling with retransmit
- Expected reboot/disconnect handling and reconnect check

Out of scope for v1:
- Hosted firmware distribution/backend
- Cryptographic signature verification in app
- Encrypted payload transport mode

issue_type: epic

status: open

title: Implement Universal Shifters BLE DFU v1 in app (manual .bin upload)


acceptance_criteria:
- All protocol constants match spec exactly
- No duplicated literal DFU UUID/opcode values across services/UI
- Domain models compile and are ready for transfer engine integration

assignee: Yandrik

close_reason: Implemented DFU constants, flags, opcodes, and typed progress models in shifter_types.dart

description:
Add protocol surface in app code for DFU support.

Work:
- Add UUID constants for dfu_control (...40008), dfu_data (...40009), dfu_ack (...4000a)
- Add opcode/frame constants (START=0x01, FINISH=0x02, ABORT=0x03, frame size 64, payload size 63)
- Add flags constants and typed update-state/progress models used by service/UI
- Remove future magic numbers by centralizing constants

issue_type: task

status: closed

title: Add DFU protocol constants and domain models


acceptance_criteria:
- CRC test vector passes: "123456789" => 0xCBF43926
- START/FINISH/ABORT encoders produce exact lengths/byte layout
- Frame segmentation handles final partial payload correctly
- Seq wrap and ack+1 rewind helpers covered by tests

close_reason: Added DFU protocol codec/CRC utilities with unit tests for payloads, frames, and sequence helpers

description:
Implement pure protocol helpers.

Work:
- Build START payload (11 bytes, LE fields)
- Build FINISH/ABORT payloads
- Build/segment DATA frames (seq + 63-byte payload)
- Implement ACK/sequence helpers including wrapping behavior
- Implement CRC32 (ISO-HDLC reflected polynomial 0xEDB88320, init/final xor FFFFFFFF)

title: Implement DFU packet codec and CRC32 utilities with tests


acceptance_criteria:
- UI can run full update flow start-to-finish
- Progress/state transitions are visible and consistent
- Conflicting controls are disabled during active transfer
- Failures and cancellations are clearly shown

description:
Add user-facing update controls and status presentation.

Work:
- Add update card with Select Firmware, Start Update, Cancel
- Show phase text, progress %, bytes sent/acked, and retry status
- Disable conflicting actions (gear writes / connect button-to-bike) during DFU
- Show explicit reboot expectation after FINISH
- Persist/clear transient state correctly on page lifecycle changes

issue_type: feature

title: Integrate firmware update UI into device details page


acceptance_criteria:
- User can select .bin and app obtains byte payload
- Validation errors are explicit and user-facing
- Metadata (size/crc/session) is available to transfer engine

close_reason: Completed

description:
Implement local firmware artifact input for v1.

Work:
- Integrate file picker for local firmware .bin
- Read bytes safely and validate non-empty payload
- Guard against malformed selections and unsupported files
- Compute total_len and crc32 from selected bytes
- Generate per-session session_id and set flags=0x00 for v1

title: Add firmware file selection and binary validation flow


acceptance_criteria:
- Tests cover success and critical failure/retry paths
- Wrap-around and ack rewind behavior is validated
- Regressions in sequencing/CRC are caught automatically

description:
Add targeted tests for protocol and engine behavior.

Work:
- Unit tests for codec + CRC + sequence helpers
- Engine tests with mocked BLE ack stream for:
  - happy path
  - dropped frame / stalled ACK and rewind
  - timeout and bounded retry fail
  - cancel/abort cleanup
- Ensure deterministic tests for wrap-around sequence scenarios

title: Add DFU test suite for happy path, loss, stalls, and cancel


acceptance_criteria:
- Team can execute update and triage failures from docs
- v1 limitations are explicit and not ambiguous
- QA checklist is actionable and complete

description:
Document how to use and support the new updater.

Work:
- Add app-side DFU flow docs (select/start/progress/reboot/reconnect)
- Add troubleshooting matrix for common failures (MTU, stalled ACK, reconnect timeout, CRC mismatch)
- Record explicit v1 limitations and future security/version-verification roadmap
- Add manual QA checklist for release validation

issue_type: chore

title: Document DFU v1 operator flow, troubleshooting, and constraints


acceptance_criteria:
- Happy path reaches done with full ACKed transfer
- Loss/stall path retransmits and recovers correctly
- Cancel triggers ABORT and returns to idle cleanly
- Engine surfaces explicit error reasons for UI

close_reason: Implemented firmware transfer engine with preflight, cumulative ACK handling, retries, cancel ABORT, and unit tests

description:
Build the runtime transfer engine used by UI.

Work:
- Subscribe to dfu_ack indications before START
- Send START and require initial ACK 0xFF
- Stream dfu_data using write without response in windows (configurable, default 8)
- Track cumulative ACK; on stall/timeout rewind to ack+1 (wrapping aware)
- Handle invalid/no-progress scenarios with bounded retries
- Send FINISH after full acked upload
- Support ABORT for cancellation and terminal error cleanup
- Emit state/progress stream for UI

title: Implement BLE DFU transfer engine with cumulative ACK retransmit


acceptance_criteria:
- Upload start is blocked when MTU/connection preconditions fail
- Error messages explain what failed and next step
- Preflight result is exposed for transfer start path

close_reason: Implemented DFU preflight checks for connection state and negotiated MTU with typed results and tests

description:
Add runtime guards required for protocol correctness.

Work:
- Ensure active connection to target button before DFU start
- Request elevated MTU (e.g. 128/247) before upload
- Validate negotiated MTU supports 64-byte data writes (ATT payload requirement)
- Fail early with actionable message when transport preconditions are not met

title: Add BLE DFU preflight checks (MTU and connection readiness)


acceptance_criteria:
- Expected reset does not appear as generic failure
- Reconnect path is attempted and result is surfaced
- Completion criteria are consistent with v1 definition

description:
Implement robust completion handling around expected device reset.

Work:
- Treat disconnect after successful FINISH as expected behavior
- Reconnect with update-specific timeout strategy
- Verify device is reachable/readable after reconnect
- Surface success only after reconnect verification path
- Document limitation: no strict firmware version compare until firmware exposes version characteristic

title: Handle post-FINISH disconnect/reboot and reconnect verification