Rethink Capabilities to allow different versions of the same Wearable with different capabilities

[DennisMoschina]

Problem: Firmware-dependent capabilities are not represented

Background

Currently, all wearables of a given type expose all capabilities that are supported by any firmware version of that wearable. This implicitly assumes that all connected devices run the latest firmware.

However, for some wearables, new capabilities were introduced in later firmware releases. When a device runs an older firmware version, these capabilities may be:

• partially implemented,
• unavailable, or
• behave differently.

Problem Statement

Because capabilities are assigned solely based on the wearable type and not on the firmware version, the system cannot reliably determine which features are actually supported by a connected device. This leads to ambiguous behavior and increases the risk of runtime errors or unsupported operations when working with older firmware versions.

Desired Behavior

Capabilities should be conditionally enabled based on the firmware version of the connected wearable. A device should only expose the capabilities that are guaranteed to be supported by its currently installed firmware.

Proposed Direction (high-level)

Introduce a mechanism to:

• associate capabilities with minimum (and optionally maximum) firmware versions, and
• resolve the effective set of capabilities for a wearable at runtime based on its reported firmware version.

Motivation

• Avoid ambiguous or undefined behavior when interacting with older firmware
• Improve robustness of feature detection
• Make firmware evolution explicit and easier to reason about
• Enable backward compatibility without special-case logic in app code

[DennisMoschina]

Proposed Solution: Runtime Capability Registry

To address firmware-dependent capability availability, we propose introducing a runtime capability registry on the Wearable base class.

Core Idea

Rather than assigning capabilities solely via the wearable type (inheritance / implements), each wearable maintains a set of capabilities that can be queried at runtime. These capabilities can be:

• implicitly provided by the wearable itself (for backward compatibility), and
• explicitly registered after the firmware version has been read.

This allows the effective set of supported capabilities to be resolved dynamically based on the device’s firmware version.

---

Reference Implementation (simplified)

abstract class Wearable {
  final String name;
  final List<dynamic> _capabilities = [];

  Wearable({
    required this.name,
    required WearableDisconnectNotifier disconnectNotifier,
  }) {
    disconnectNotifier.addListener(_notifyDisconnectListeners);
    _capabilities.add(this); // exposes existing capabilities
  }

  bool hasCapability<T>() {
    for (final capability in _capabilities) {
      if (capability is T) return true;
    }
    return false;
  }

  T? getCapability<T>() {
    for (final capability in _capabilities) {
      if (capability is T) return capability;
    }
    return null;
  }

  T requireCapability<T>() {
    final capability = getCapability<T>();
    if (capability != null) return capability;
    throw StateError('Wearable does not have required capability: $T');
  }

  void registerCapability<T>(T capability) {
    if (hasCapability<T>()) {
      throw StateError('Wearable already has capability: $T');
    }
    _capabilities.add(capability);
  }
}

---

How this solves the original problem

Firmware-dependent capabilities

After connecting to a device and reading its firmware version, capabilities can be conditionally registered:

final version = await wearable.readDeviceFirmwareVersion();

if (version >= Version.parse('2.3.0')) {
  wearable.registerCapability<TimeSynchronizable>(
    TimeSyncCapability(wearable),
  );
}

A device will only expose capabilities that are guaranteed to be supported by its installed firmware.

---

Backward compatibility

• Existing wearables already implement many capability interfaces.
• By registering this in the constructor, all previously available functionality remains accessible.
• No immediate refactor of existing devices is required.

This avoids breaking existing code while enabling gradual adoption of firmware-gated capabilities.

---

Benefits relative to the issue goals

• Eliminates ambiguous behavior. Capabilities are only exposed when explicitly registered for a firmware version.
• Improves robustness of feature detection. Callers can reliably check support via:

if (wearable.hasCapability<TimeSynchronizable>()) { ... }

• Makes firmware evolution explicit. Capability registration logic clearly documents when a feature was introduced.
• Avoids class / decorator explosion. No need for 2^N subclasses or stacked decorators.
• Supports incremental migration. Existing is Capability checks can coexist during transition.

---

Trade-offs

• Capability checks move from device is Capability to hasCapability<T>() / getCapability<T>().
• Capability lookup is O(n), but the list is small and can be optimized later if needed.