App Documentation

open_wearable/README.md

@@ -1,16 +1,28 @@
-# open_wearable
+# OpenWearable App Module
 
-A new Flutter project.
+Flutter application module for the OpenEarable app.
 
-## Getting Started
+## Documentation
 
-This project is a starting point for a Flutter application.
+High-level architecture and state-management docs live in [`docs/`](./docs/README.md).
 
-A few resources to get you started if this is your first Flutter project:
+- [App Setup and Architecture](./docs/app-setup.md)
+- [State and Providers](./docs/state-and-providers.md)
 
-- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+## Development Quick Start
 
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+1. Install Flutter (stable channel).
+2. From this folder (`open_wearable/`), fetch dependencies:
+   ```bash
+   flutter pub get
+   ```
+3. Run on a connected device/emulator:
+   ```bash
+   flutter run
+   ```
+
+## Notes
+
+- Core app bootstrap is in `lib/main.dart`.
+- Route definitions are in `lib/router.dart`.
+- High-level feature state is primarily under `lib/view_models/`.

open_wearable/docs/README.md

@@ -0,0 +1,21 @@
+# OpenWearable App Documentation
+
+This folder contains high-level documentation for the Flutter app in `open_wearable/`.
+
+## Documents
+
+- [App Setup and Architecture](./app-setup.md)
+  - Startup flow, dependency initialization, routing, UI shell, and lifecycle handling.
+- [State and Providers](./state-and-providers.md)
+  - How top-level providers are wired, how per-device providers are created, and how data flows from wearables to UI.
+- [Page Documentation](./pages/README.md)
+  - Detailed page-by-page contracts: needs, behavior, and outputs.
+
+## Suggested Reading Order
+
+1. [App Setup and Architecture](./app-setup.md)
+2. [State and Providers](./state-and-providers.md)
+
+## Scope
+
+These docs are intentionally focused on app-level behavior and state handling. They are not API references for `open_earable_flutter`.

open_wearable/docs/app-setup.md

@@ -0,0 +1,125 @@
+# App Setup and Architecture
+
+This document describes the high-level setup of the OpenWearable Flutter app (`open_wearable/`), including startup, routing, shell layout, and lifecycle behavior.
+
+## 1. Runtime Entry Point
+
+Main entry point: `lib/main.dart`
+
+Startup sequence:
+
+1. `WidgetsFlutterBinding.ensureInitialized()`
+2. Create `LogFileManager` and initialize both app and library loggers.
+3. Initialize persisted settings:
+   - `AutoConnectPreferences.initialize()`
+   - `AppShutdownSettings.initialize()`
+4. Start app with `MultiProvider`.
+
+The app wraps all screens in a single provider tree so global services/state are available everywhere.
+
+## 2. Top-Level Provider Tree
+
+Created in `main.dart`:
+
+- `WearablesProvider` (`ChangeNotifierProvider`)
+- `FirmwareUpdateRequestProvider` (`ChangeNotifierProvider`)
+- `SensorRecorderProvider` (`ChangeNotifierProvider`)
+- `WearableConnector` (`Provider.value`)
+- `AppBannerController` (`ChangeNotifierProvider`)
+- `LogFileManager` (`ChangeNotifierProvider.value`)
+
+`MyApp` is stateful and subscribes to provider streams once, then orchestrates global side effects (dialogs, toasts, banners, lifecycle reactions).
+
+## 3. App Shell and Navigation
+
+Router config: `lib/router.dart`
+
+- Router uses `GoRouter` with a global `rootNavigatorKey`.
+- `HomePage` is mounted at `/` and receives optional section query parameter (`?tab=`).
+- Primary routes:
+  - `/` home shell
+  - `/connect-devices`
+  - `/device-detail`
+  - `/log-files`
+  - `/recordings`
+  - `/settings/general`
+  - `/fota` and `/fota/update`
+
+### FOTA route guard
+
+`/fota` redirects back to `/?tab=devices` on unsupported platforms and shows a platform dialog explaining the restriction.
+
+## 4. Home Layout Structure
+
+Main shell: `lib/widgets/home_page.dart`
+
+Top-level sections:
+
+1. Overview
+2. Devices
+3. Sensors
+4. Apps
+5. Settings
+
+Behavior:
+
+- Compact screens use `PlatformTabScaffold` with bottom navigation.
+- Large screens use a `NavigationRail` + `IndexedStack` layout.
+- `SensorPageController` lets other sections deep-link into specific tabs inside the Sensors page.
+
+## 5. Lifecycle and Background Behavior
+
+Handled centrally in `_MyAppState` (`main.dart`) via `WidgetsBindingObserver`.
+
+Key behaviors:
+
+- Auto-connect is stopped on pause and resumed on app resume depending on user setting.
+- If "shut off all sensors on app close" is enabled, a grace-period timer is started when app goes inactive/paused.
+- Background execution window is managed via `AppBackgroundExecutionBridge` while shutdown or recording protection is needed.
+- If sensor shutdown completed while app was backgrounded, open app-flow screens are popped back to root on resume.
+
+## 6. Connection and Event Handling
+
+Two layers are used:
+
+- `WearableConnector` (`lib/models/wearable_connector.dart`)
+  - Direct connection API and event stream for connect/disconnect events.
+- `BluetoothAutoConnector` (`lib/models/bluetooth_auto_connector.dart`)
+  - Reconnect workflow based on remembered device names and user preference.
+
+`MyApp` subscribes to connector/provider event streams to:
+
+- Add wearables to global providers.
+- Show firmware dialogs.
+- Show app banners/toasts for important runtime events.
+
+## 7. Feature Module Layout
+
+High-level code organization under `lib/`:
+
+- `widgets/`: shared UI and top-level pages.
+- `view_models/`: provider-backed state and orchestration logic.
+- `models/`: persistence, app-level settings, connection helpers, logging helpers.
+- `apps/`: feature mini-apps (e.g., posture tracker, heart tracker).
+- `theme/`: theming.
+- `router.dart`: route table.
+- `main.dart`: bootstrap and global lifecycle/event orchestration.
+
+## 8. Persistence and Local State
+
+Persisted settings/data include:
+
+- Auto-connect preference and remembered names (`AutoConnectPreferences` + `SharedPreferences`).
+- Shutdown/graph settings (`AppShutdownSettings` + `SharedPreferences`).
+- Sensor profiles/configuration JSON files (`SensorConfigurationStorage`).
+- Log files (`LogFileManager`).
+
+## 9. Typical Runtime Flow
+
+1. App starts and initializes settings/logging.
+2. Providers are created.
+3. Router builds Home shell.
+4. User connects devices manually or auto-connect restores previous devices.
+5. `WearablesProvider` initializes per-device sensor configuration state.
+6. Sensors/config pages consume provider state and update UI.
+7. Lifecycle transitions trigger shutdown/auto-connect policies.

open_wearable/docs/pages/README.md

@@ -0,0 +1,16 @@
+# Page Documentation
+
+This section documents the app pages in a consistent format:
+
+- `Needs`: what must be available for the page to work correctly.
+- `Does`: core behavior and responsibilities.
+- `Provides`: what the page exposes to users/other flows (navigation outcomes, side effects, state updates).
+
+## Coverage
+
+- [Shell and Navigation Pages](./shell-and-navigation-pages.md)
+- [Device Pages](./device-pages.md)
+- [Sensor Pages](./sensor-pages.md)
+- [Settings and Logging Pages](./settings-and-logging-pages.md)
+- [Apps Pages](./apps-pages.md)
+- [Firmware Update (FOTA) Pages](./fota-pages.md)

open_wearable/docs/pages/apps-pages.md

@@ -0,0 +1,57 @@
+# Apps Pages
+
+## `AppsPage` (`lib/apps/widgets/apps_page.dart`)
+- Needs:
+  - `WearablesProvider` for connected wearable names.
+  - App catalog entries (`_apps`) with compatibility metadata.
+- Does:
+  - Computes enabled/disabled app tiles based on compatible connected devices.
+  - Renders app catalog and app-level status summary.
+- Provides:
+  - Launch entry point for mini-app experiences.
+
+## `SelectEarableView` (`lib/apps/widgets/select_earable_view.dart`)
+- Needs:
+  - Constructor inputs:
+    - `startApp(Wearable, SensorConfigurationProvider)` callback
+    - `supportedDevicePrefixes`
+  - `WearablesProvider` with sensor config providers for candidate devices.
+- Does:
+  - Filters connected wearables by app compatibility.
+  - Lets user select one wearable and launches app with scoped provider context.
+- Provides:
+  - Compatibility-safe wearable picker for app flows.
+
+## `HeartTrackerPage` (`lib/apps/heart_tracker/widgets/heart_tracker_page.dart`)
+- Needs:
+  - Constructor inputs:
+    - `wearable`
+    - `ppgSensor` (required)
+    - optional accelerometer and optical temperature sensors
+  - `SensorConfigurationProvider` in scope.
+- Does:
+  - Configures required sensor streaming settings on enter.
+  - Builds OpenRing-specific or generic PPG processing pipeline.
+  - Produces heart-rate/HRV/signal-quality streams for UI charts.
+  - Restores/turns off configured streaming settings on dispose (best effort).
+- Provides:
+  - Heart metrics visualization and quality feedback workflow.
+
+## `PostureTrackerView` (`lib/apps/posture_tracker/view/posture_tracker_view.dart`)
+- Needs:
+  - Constructor input: `AttitudeTracker` implementation.
+- Does:
+  - Creates and owns `PostureTrackerViewModel`.
+  - Displays live posture state, thresholds, and tracking controls.
+  - Opens app-specific settings page.
+- Provides:
+  - Posture tracking runtime view and control surface.
+
+## `SettingsView` (Posture) (`lib/apps/posture_tracker/view/settings_view.dart`)
+- Needs:
+  - Constructor input: existing `PostureTrackerViewModel`.
+- Does:
+  - Edits posture reminder thresholds and tracking behavior.
+  - Supports calibration action and tracking start.
+- Provides:
+  - App-specific posture tuning and calibration settings.

open_wearable/docs/pages/device-pages.md

@@ -0,0 +1,40 @@
+# Device Pages
+
+## `DevicesPage` (`lib/widgets/devices/devices_page.dart`)
+- Needs:
+  - `WearablesProvider` with current `wearables` list.
+  - `WearableDisplayGroup` helpers for pair/single grouping and ordering.
+- Does:
+  - Shows connected wearables as list (small screens) or grid (large screens).
+  - Supports pull-to-refresh by attempting `connectToSystemDevices()`.
+  - Allows pair combine/split UI mode through `WearablesProvider` stereo pair state.
+- Provides:
+  - Main device inventory view.
+  - Entry into `DeviceDetailPage` and connect flow.
+
+## `ConnectDevicesPage` (`lib/widgets/devices/connect_devices_page.dart`)
+- Needs:
+  - `WearablesProvider` (to display connected devices and add new connections).
+  - `WearableConnector` provider for explicit connect actions.
+  - `WearableManager` scan/connect capabilities and runtime BLE permissions.
+- Does:
+  - Starts BLE scanning on page open and allows manual refresh/rescan.
+  - Displays connected and available devices separately.
+  - Connects selected devices and updates global wearable state.
+- Provides:
+  - Device discovery and connection workflow.
+  - Scan status and actionable connection UI.
+
+## `DeviceDetailPage` (`lib/widgets/devices/device_detail/device_detail_page.dart`)
+- Needs:
+  - Constructor input: `Wearable device`.
+  - `WearablesProvider` (for sensor shutdown/disconnect helper flow).
+  - `FirmwareUpdateRequestProvider` (for preselecting FOTA target).
+  - Device capabilities to unlock sections (`AudioModeManager`, `RgbLed`, `StatusLed`, `Battery*`, etc.).
+- Does:
+  - Shows detailed per-device controls and metadata.
+  - Handles disconnect flow and "forget" helper (system settings handoff).
+  - Prepares firmware update target and navigates to FOTA flow.
+- Provides:
+  - Capability-aware control surface for one wearable.
+  - Path from device details to firmware update workflow.

open_wearable/docs/pages/fota-pages.md

@@ -0,0 +1,45 @@
+# Firmware Update (FOTA) Pages
+
+## `FotaWarningPage` (`lib/widgets/fota/fota_warning_page.dart`)
+- Needs:
+  - `FirmwareUpdateRequestProvider` with selected wearable.
+  - Battery capability on selected device for pre-check (`BatteryLevelStatus`) if available.
+- Does:
+  - Presents update risk checklist and recovery guidance link.
+  - Reads battery level and enforces warning/confirmation gates below threshold.
+  - Routes to `/fota/update` when user proceeds.
+- Provides:
+  - Safety gate before update execution.
+
+## `FirmwareUpdateWidget` (`lib/widgets/fota/firmware_update.dart`)
+- Needs:
+  - `FirmwareUpdateRequestProvider` in scope.
+  - Valid selected firmware for step 0 -> step 1 transition.
+- Does:
+  - Hosts two-step flow (select firmware, install firmware).
+  - Prevents back navigation while update is active.
+  - Creates `UpdateBloc` for install step.
+  - Caches wearable metadata (name/side label) for post-update verification UX.
+- Provides:
+  - Main firmware update execution page.
+
+## `UpdateStepView` (`lib/widgets/fota/stepper_view/update_view.dart`)
+- Needs:
+  - `UpdateBloc` and `FirmwareUpdateRequestProvider` in context.
+  - Optional callbacks for update running-state reporting.
+- Does:
+  - Starts update automatically when configured (`autoStart`).
+  - Renders update timeline/history and current stage.
+  - Arms and displays post-update verification banner on successful completion.
+  - Provides link to update logger view when available.
+- Provides:
+  - Detailed progress and outcome UI for the update process.
+
+## `LoggerScreen` (`lib/widgets/fota/logger_screen/logger_screen.dart`)
+- Needs:
+  - Constructor input: `FirmwareUpdateLogger logger`.
+- Does:
+  - Reads device-side MCU logs and filters by severity.
+  - Renders log list with color-coded levels.
+- Provides:
+  - Post-update diagnostic log visibility.