src.bluetooth_sig.gatt.characteristics.role_classifier

Role classification for GATT characteristics.

Classifies a characteristic’s purpose (MEASUREMENT, FEATURE, CONTROL, etc.) from SIG spec metadata using a tiered heuristic based on GSS YAML signals, name conventions, and type inference.

Validated against a hand-verified ground truth map of all 294 registered characteristics — see scripts/test_classifier.py. Characteristics that cannot be classified from the available YAML metadata alone should use _manual_role on their class.

Functions

Name

Description

classify_role(...)

Classify a characteristic's purpose from SIG spec metadata.

Module Contents

src.bluetooth_sig.gatt.characteristics.role_classifier.classify_role(char_name: str, python_type: type | str | None, is_bitfield: bool, unit: str, spec: src.bluetooth_sig.types.registry.CharacteristicSpec | None) → src.bluetooth_sig.types.gatt_enums.CharacteristicRole

Classify a characteristic’s purpose from SIG spec metadata.

Role definitions: - MEASUREMENT: value represents something measured or observed from

the device or environment (physical quantity, sampled reading, derived sensor metric).

  • STATUS: discrete operational/device state (mode, flag, trend,

    categorical state snapshot).

  • FEATURE: capability declaration (supported options/bitmasks), not a

    live measured value.

  • CONTROL: command/control endpoint (typically control point writes).

  • INFO: contextual metadata, identifiers, or descriptive/static data

    that does not represent a measurement.

Uses a tiered priority system — strongest YAML signals first, then name conventions, type inference, and struct name patterns.

Tier 1 — YAML-data-driven (highest confidence):

  1. Name contains Control Point → CONTROL

  2. Physical (non-unitless) unit_id → MEASUREMENT

  3. Field-level physical units in structure → MEASUREMENT

Tier 2 — Name + type signals:

  1. Name contains Status → STATUS

  2. is_bitfield is True → FEATURE

  3. python_type is IntFlag subclass → FEATURE

Tier 3 — SIG naming conventions:

  1. Name contains Measurement or ends with Data → MEASUREMENT

  2. Name ends with Feature(s) → FEATURE

Tier 4 — Type-driven inference:

  1. Non-empty unit string → MEASUREMENT

  1. python_type is str → INFO

  2. python_type is a string subtype name → INFO

  3. python_type is an Enum subclass → STATUS

  4. Unitless unit_id + numeric type → MEASUREMENT

  5. python_type is float → MEASUREMENT

  6. python_type is bool → STATUS

Tier 5 — Struct name patterns (for structs with no YAML signal):

  1. Measurement struct keyword → MEASUREMENT

  2. Status struct keyword → STATUS

Tier 6 — Fallback:

  1. Otherwise → UNKNOWN

Parameters:

  • char_name – Display name of the characteristic.

  • python_type – Resolved Python type (int, float, str, etc.) or None.

  • is_bitfield – Whether the characteristic is a bitfield.

  • unit – Unit string (empty string if not applicable).

  • spec – Resolved YAML spec (may be None).

Returns:

The classified CharacteristicRole.