actor: Yandrik

event_type: claimed

assignee: Yandrik

title: Add DFU protocol constants and domain models

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

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

status: open

issue_type: task

created_by: Yandrik


event_type: closed

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


title: Implement DFU packet codec and CRC32 utilities with tests

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)

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


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


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

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

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


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


title: Implement BLE DFU transfer engine with cumulative ACK retransmit

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

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

issue_type: feature


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


title: Add firmware file selection and binary validation flow

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

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


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

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

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


new_value: Added post-FINISH reset disconnect, reconnect, and reachability verification before marking update complete


title: Integrate firmware update UI into device details page

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

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


new_value: Integrated firmware file selection, update controls, progress display, and DFU state handling into device details page


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

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

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


new_value: Expanded DFU tests to cover bounded retry timeout failure and deterministic sequence wrap-around behavior


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

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

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

issue_type: chore


new_value: Added DFU v1 operator guide with troubleshooting matrix, limitations, and QA checklist; linked from README


title: UI overhaul from mockups

description: App-wide UI reskin based on the provided mockups. Scope: shared theme tokens, shell navigation with Devices and Settings, Devices tab redesign, Settings redesign with theme selection, Connect Device page restyle, Device Details reskin, gear ratio preset additions and restyle, trainer popup restyle, and per-phase verification/commits.

issue_type: epic


title: Phase 1: theme and shell navigation

description: Implement shared app theme tokens, support system/light/dark theme selection, replace top-level navigation with Devices and Settings shell, retire Home as a destination, and keep Connect Device / Device Details as pushed routes.


title: Phase 2: devices and settings reskin

description: Redesign Devices tab and Settings tab using the new design system. Devices becomes the default tab and shows saved devices and add-device entry; Settings includes theme mode controls.


title: Phase 3: connect flow and popup restyle

description: Restyle the Connect Device page and trainer assignment popup to match the new visual language while preserving the existing BLE behavior.