src.bluetooth_sig.gatt.characteristics.base¶

Base class for GATT characteristics.

Implements the core parsing and encoding system for Bluetooth GATT characteristics following official Bluetooth SIG specifications.

See characteristic_meta for infrastructure classes (SIGCharacteristicResolver, CharacteristicMeta, ValidationConfig). See pipeline for the multi-stage parse/encode pipeline. See role_classifier for characteristic role inference.

Attributes¶

Name	Description
`T`
`logger`

Classes¶

Name	Description
`BaseCharacteristic`	Base class for all GATT characteristics.

Module Contents¶

class src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic(info: src.bluetooth_sig.types.CharacteristicInfo | None = None, validation: src.bluetooth_sig.gatt.characteristics.characteristic_meta.ValidationConfig | None = None)¶

Bases: src.bluetooth_sig.gatt.characteristics.context_lookup.ContextLookupMixin, src.bluetooth_sig.gatt.characteristics.descriptor_mixin.DescriptorMixin, abc.ABC, Generic[T]

Base class for all GATT characteristics.

Generic over T, the return type of _decode_value().

Automatically resolves UUID, unit, and python_type from Bluetooth SIG YAML specifications. Supports manual overrides via _manual_unit and _python_type attributes.

Validation Attributes (optional class-level declarations):: min_value / max_value: Allowed numeric range. expected_length / min_length / max_length: Byte-length constraints. allow_variable_length: Accept variable length data. expected_type: Expected Python type for parsed values.

build_value(data: T | src.bluetooth_sig.types.SpecialValueResult, validate: bool = True) → bytearray¶

Encode value or special value to characteristic bytes.

Delegates to EncodePipeline for the multi-stage pipeline (type validation → range validation → encode → length validation).

Parameters:

data – Value to encode (type T) or SpecialValueResult.
validate – Enable validation (type, range, length checks).

Returns:

Encoded bytes ready for BLE write.

Raises:

CharacteristicEncodeError – If encoding or validation fails.

encode_special(value_type: src.bluetooth_sig.types.SpecialValueType) → bytearray¶

Encode a special value type to bytes (reverse lookup).

Raises ValueError if no raw value of that type is defined for this characteristic.

encode_special_by_meaning(meaning: str) → bytearray¶

Encode a special value by a partial meaning string match.

Raises ValueError if no matching special value is found.

classmethod get_allows_sig_override() → bool¶

Check if this characteristic class allows overriding SIG characteristics.

Custom characteristics that need to override official Bluetooth SIG characteristics must set _allows_sig_override = True as a class attribute.

Returns:: True if SIG override is allowed, False otherwise.

get_byte_order_hint() → str¶: Get byte order hint (Bluetooth SIG uses little-endian by convention).

classmethod get_class_uuid() → src.bluetooth_sig.types.uuid.BluetoothUUID | None¶

Get the characteristic UUID for this class without creating an instance.

This is the public API for registry and other modules to resolve UUIDs.

Returns:: BluetoothUUID if the class has a resolvable UUID, None otherwise.

classmethod get_configured_info() → src.bluetooth_sig.types.CharacteristicInfo | None¶

Get the class-level configured CharacteristicInfo.

This provides public access to the _configured_info attribute that is set by __init_subclass__ for custom characteristics.

Returns:: CharacteristicInfo if configured, None otherwise

get_field_unit(field_name: str) → str¶

Get the resolved unit symbol for a specific struct field.

For struct-valued characteristics with per-field units (e.g. Heart Rate Measurement: bpm for heart rate, J for energy expended), this resolves the unit for a single field via FieldSpec.unit_id → UnitsRegistry → .symbol.

Parameters:: field_name – The Python-style field name (e.g. 'heart_rate') or raw GSS field name (e.g. 'Heart Rate Measurement Value').
Returns:: Resolved unit symbol, or empty string if not found.

get_special_value_meaning(raw_value: int) → str | None¶

Get the human-readable meaning of a special value.

Parameters:: raw_value – The raw integer value to look up.
Returns:: The meaning string (e.g., “value is not known”), or None if not special.

get_special_value_type(raw_value: int) → src.bluetooth_sig.types.SpecialValueType | None¶

Get the category of a special value.

Parameters:: raw_value – The raw integer value to classify.
Returns:: The SpecialValueType category, or None if not a special value.

get_yaml_data_type() → str | None¶: Get the data type from YAML automation (e.g., ‘sint16’, ‘uint8’).

get_yaml_field_size() → int | None¶: Get the field size in bytes from YAML automation.

get_yaml_resolution_text() → str | None¶: Get the resolution description text from YAML automation.

get_yaml_unit_id() → str | None¶: Get the Bluetooth SIG unit identifier from YAML automation.

is_signed_from_yaml() → bool¶: Determine if the data type is signed based on YAML automation.

is_special_value(raw_value: int) → bool¶

Check if a raw value is a special sentinel value.

Checks both manual overrides (_special_values class variable) and GSS-derived special values, with manual taking precedence.

Parameters:: raw_value – The raw integer value to check.
Returns:: True if this is a special sentinel value, False otherwise.

classmethod matches_uuid(uuid: str | src.bluetooth_sig.types.uuid.BluetoothUUID) → bool¶: Check if this characteristic matches the given UUID.

parse_value(data: bytes | bytearray, ctx: src.bluetooth_sig.gatt.context.CharacteristicContext | None = None, validate: bool = True) → T¶

Parse characteristic data.

Delegates to ParsePipeline for the multi-stage pipeline (length validation → raw int extraction → special value detection → decode → range/type validation).

Returns:

Parsed value of type T.

Raises:

SpecialValueDetectedError – Special sentinel (0x8000=”unknown”, 0x7FFFFFFF=”NaN”)
CharacteristicParseError – Parse/validation failure

allow_variable_length: bool = False¶

property description: str¶: Get the characteristic description from GSS specification.

property display_name: str¶

Get the display name for this characteristic.

Uses explicit _characteristic_name if set, otherwise falls back to class name.

expected_length: int | None = None¶

expected_type: type | None = None¶

property gss_special_values: dict[int, str]¶

Get special values from GSS specification.

Extracts all special value definitions (e.g., 0x8000=”value is not known”) from the GSS YAML specification for this characteristic.

GSS stores values as unsigned hex (e.g., 0x8000). For signed types, this method also includes the signed interpretation so lookups work with both parsed signed values and raw unsigned values.

Returns:: Dictionary mapping raw integer values to their human-readable meanings. Includes both unsigned and signed interpretations for applicable values.

property info: src.bluetooth_sig.types.CharacteristicInfo¶: Characteristic information.

property is_bitfield: bool¶: Whether this characteristic’s value is a bitfield.

last_parsed: T | None = None¶

max_length: int | None = None¶

max_value: int | float | None = None¶

min_length: int | None = None¶

min_value: int | float | None = None¶

property name: str¶: Get the characteristic name from _info.

property optional_dependencies: list[str]¶

Get resolved optional dependency UUID strings.

Performance: Returns list[str] for efficient comparison with dict keys.

property python_type: type | str | None¶: Get the resolved Python type for this characteristic’s values.

property required_dependencies: list[str]¶

Get resolved required dependency UUID strings.

Performance: Returns list[str] for efficient comparison with dict keys.

property role: src.bluetooth_sig.types.gatt_enums.CharacteristicRole¶

Classify the characteristic’s purpose from SIG spec metadata.

Override via _manual_role class variable, or the heuristic in role_classifier.classify_role() is used. Result is cached per concrete subclass.

property size: int | None¶

Get the size in bytes for this characteristic from YAML specifications.

Returns the field size from YAML automation if available, otherwise None. This is useful for determining the expected data length for parsing and encoding.

property spec: src.bluetooth_sig.types.registry.CharacteristicSpec | None¶: Get the full GSS specification with description and detailed metadata.

property unit: str¶

Get the unit of measurement from _info.

Returns empty string for characteristics without units (e.g., bitfields).

property unit_symbol: str¶

Get the canonical SIG unit symbol for this characteristic.

Resolves via the UnitsRegistry using the YAML unit_id (e.g. org.bluetooth.unit.thermodynamic_temperature.degree_celsius → °C). Falls back to unit when no symbol is available.

Returns:: SI symbol string (e.g. '°C', '%', 'bpm'), or empty string if the characteristic has no unit.

property uuid: src.bluetooth_sig.types.uuid.BluetoothUUID¶: Get the characteristic UUID from _info.

src.bluetooth_sig.gatt.characteristics.base.T¶

src.bluetooth_sig.gatt.characteristics.base.logger¶