2.3.5

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.3.5
+
+* added FOTA capabilities for wearables to support capability-based firmware updates
+* added support for aborting an in-progress FOTA update
+* expanded FOTA documentation and API doc comments, including abort flow examples
+
 ## 2.3.4
 
 * fixed a bug where the stream of sensor values would not be properly closed when the device is disconnected, which could lead to memory leaks and other issues

CONTRIBUTING.md

@@ -0,0 +1,127 @@
+# Contributing to OpenEarable Flutter
+
+Thank you for contributing to `open_earable_flutter`.
+
+This package is published publicly and supports multiple wearable integrations, so contribution quality matters. Keep changes small, reviewable, and well documented.
+
+## Core Expectations
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/) for every commit.
+- Rebase your branch on top of the target branch. Do not merge the target branch into your feature branch.
+- Run `dart format .` and ensure `flutter analyze` passes before pushing.
+- Document classes, public APIs, and non-obvious functions.
+- Update package documentation when public behavior, setup, or capabilities change.
+- Keep pull requests focused. Do not mix refactors, formatting-only edits, and feature work unless they are directly related.
+- Never commit secrets, local environment files, build artifacts, or unrelated generated output.
+
+## Development Setup
+
+The repository uses the Flutter version pinned in [`.flutter_version`](https://github.com/OpenEarable/open_earable_flutter/blob/main/.flutter_version).
+
+1. Install the required Flutter SDK version.
+2. Fetch dependencies:
+
+```bash
+flutter pub get
+```
+
+3. If you work on the example app as well, fetch its dependencies too:
+
+```bash
+cd example
+flutter pub get
+```
+
+## Branching Workflow
+
+1. Create a feature branch from the current target branch.
+2. Make focused commits with conventional commit messages.
+3. Rebase onto the latest target branch before opening or updating your pull request.
+4. Resolve conflicts locally and rerun the verification steps.
+
+Example commit messages:
+
+```text
+feat(sensor): add open ring calibration support
+fix(fota): avoid duplicate update state emission
+docs(readme): clarify bluetooth permission setup
+refactor(device): simplify wearable factory registration
+test(pairing): cover stereo reconnection flow
+```
+
+## Code Quality Standards
+
+### Architecture
+
+- Prefer small, composable abstractions over large multi-purpose classes.
+- Keep responsibilities clearly separated across managers, models, capabilities, and utilities.
+- Avoid introducing tight coupling between device-specific implementations and shared infrastructure.
+- Preserve backward compatibility for public APIs unless the change is intentional and clearly documented.
+
+### Documentation
+
+- Add Dart documentation comments for every public class, enum, extension, mixin, typedef, constructor, method, and top-level function you introduce or materially change.
+- Add documentation for internal functions and classes when the behavior is not immediately obvious.
+- Explain why something exists or how it should be used, not just what the code literally does.
+- Update the relevant files in [`doc/`](https://github.com/OpenEarable/open_earable_flutter/tree/main/doc) and [README.md](https://github.com/OpenEarable/open_earable_flutter/blob/main/README.md) when contributors change user-facing functionality.
+
+### Style
+
+- Follow the repository lint rules in [analysis_options.yaml](https://github.com/OpenEarable/open_earable_flutter/blob/main/analysis_options.yaml).
+- Use trailing commas where appropriate and keep return types explicit.
+- Prefer clear naming over clever shorthand.
+- Avoid unrelated drive-by changes in files touched for another purpose.
+
+## Verification Before Pushing
+
+Run these commands from the repository root:
+
+```bash
+dart format .
+flutter analyze
+flutter test
+```
+
+Also validate the example app when your change can affect it:
+
+```bash
+cd example
+flutter test
+flutter build web --dart-define=BUILD_COMMIT=$(git rev-parse --short HEAD) --dart-define=BUILD_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+```
+
+Notes:
+
+- CI currently enforces `flutter analyze` and builds the example web app for pull requests.
+- If `flutter test` does not cover your change sufficiently, add targeted tests instead of relying on manual verification only.
+- If a command is not applicable to your change, mention what you ran and why in the pull request description.
+
+## Pull Requests
+
+Before opening a pull request, make sure:
+
+- the branch is rebased on the latest target branch;
+- commits use conventional commit messages;
+- formatting, analysis, tests, and relevant example validation pass;
+- documentation is updated for API or behavior changes;
+- the pull request description explains the problem, the solution, and any migration or validation notes.
+
+If your change affects public APIs, protocol behavior, permissions, supported devices, or firmware update flows, call that out explicitly in the pull request.
+
+## Commit and History Hygiene
+
+- Prefer multiple clean commits over one noisy commit history during development, then squash if the maintainers request it.
+- Do not rewrite shared branch history after others have based work on it unless you have coordinated the change.
+- Do not use merge commits to sync your branch with the target branch. Use `git fetch` followed by `git rebase`.
+
+## What To Update When You Change Behavior
+
+Depending on the change, update one or more of the following:
+
+- [README.md](https://github.com/OpenEarable/open_earable_flutter/blob/main/README.md)
+- files in [`doc/`](https://github.com/OpenEarable/open_earable_flutter/tree/main/doc)
+- [CHANGELOG.md](https://github.com/OpenEarable/open_earable_flutter/blob/main/CHANGELOG.md)
+- example code in [`example/lib/`](https://github.com/OpenEarable/open_earable_flutter/tree/main/example/lib)
+- tests in [`example/test/`](https://github.com/OpenEarable/open_earable_flutter/tree/main/example/test)
+
+High-quality contributions are easier to review, safer to release, and faster to maintain. Optimize for clarity, correctness, and a clean project history.

README.md

@@ -15,6 +15,9 @@ This Dart package provides functionality for interacting with OpenEarable device
 
 [![Button](https://raw.githubusercontent.com/OpenEarable/open_earable_flutter/main/.github/assets/show_on_pub_dev_button.svg)](https://pub.dev/packages/open_earable_flutter)
 
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/OpenEarable/open_earable_flutter/CONTRIBUTING.md) for the contribution workflow, code quality expectations, rebasing policy, and required verification steps.
 
 ## Permissions
 For your app to be able to use [UniversalBLE](https://pub.dev/packages/universal_ble) in this package, you need to grant the following permissions:
@@ -116,3 +119,6 @@ To get started with the OpenEarable Flutter package, follow these steps:
 
 ## Add custom Wearable Support
 Learn more about how to add support for your own wearable devices in the [Adding Custom Wearable Support](https://github.com/OpenEarable/open_earable_flutter/blob/main/doc/ADD_CUSTOM_WEARABLE.md) documentation.
+
+## Firmware Updates
+Learn more about firmware-over-the-air updates in the [FOTA documentation](https://github.com/OpenEarable/open_earable_flutter/blob/main/doc/FOTA.md).

doc/CAPABILITIES.md

@@ -178,6 +178,31 @@ if (deviceIdentifierService != null) {
 }
 ```
 
+#### FotaCapability
+
+Provides the device-level abstraction for firmware update operations.
+
+```dart
+final fota = wearable.getCapability<FotaCapability>();
+if (fota != null) {
+  final request = fota.createFirmwareUpdateRequest(selectedFirmware);
+}
+```
+
+Use `createFirmwareUpdateRequest(...)` to build a wearable-specific update
+request without depending on the underlying FOTA backend.
+
+#### FotaSlotInfoCapability
+
+Provides firmware slot or image-table state for FOTA backends that expose it.
+
+```dart
+final slotInfo = wearable.getCapability<FotaSlotInfoCapability>();
+if (slotInfo != null) {
+  final slots = await slotInfo.readFirmwareSlots();
+}
+```
+
 ---
 
 ## Summary