src.bluetooth_sig.gatt.characteristics.templates.enum¶

Enum template for IntEnum encoding/decoding with configurable byte size.

Attributes¶

Name	Description
`T`

Classes¶

Name	Description
`EnumTemplate`	Template for IntEnum encoding/decoding with configurable byte size.

Module Contents¶

class src.bluetooth_sig.gatt.characteristics.templates.enum.EnumTemplate(enum_class: type[T], extractor: src.bluetooth_sig.gatt.characteristics.utils.extractors.RawExtractor)¶

Bases: src.bluetooth_sig.gatt.characteristics.templates.base.CodingTemplate[T]

Template for IntEnum encoding/decoding with configurable byte size.

Maps raw integer bytes to Python IntEnum instances through extraction and validation. Supports any integer-based enum with any extractor (UINT8, UINT16, SINT8, etc.).

This template validates enum membership explicitly, supporting non-contiguous enum ranges (e.g., values 0, 2, 5, 10).

Pipeline Integration:: bytes → [extractor] → raw_int → [IDENTITY translator] → int → enum constructor

Examples

>>> class Status(IntEnum):
...     IDLE = 0
...     ACTIVE = 1
...     ERROR = 2
>>>
>>> # Create template with factory method
>>> template = EnumTemplate.uint8(Status)
>>>
>>> # Or with explicit extractor
>>> template = EnumTemplate(Status, UINT8)
>>>
>>> # Decode from bytes
>>> status = template.decode_value(bytearray([0x01]))  # Status.ACTIVE
>>>
>>> # Encode enum to bytes
>>> data = template.encode_value(Status.ERROR)  # bytearray([0x02])
>>>
>>> # Encode int to bytes (also supported)
>>> data = template.encode_value(2)  # bytearray([0x02])

decode_value(data: bytearray, offset: int = 0, ctx: src.bluetooth_sig.gatt.context.CharacteristicContext | None = None, *, validate: bool = True) → T¶

Decode bytes to enum instance.

Parameters:

data – Raw bytes from BLE characteristic
offset – Starting offset in data buffer
ctx – Optional context for parsing
validate – Whether to validate enum membership (default True)

Returns:

Enum instance of type T

Raises:

InsufficientDataError – If data too short for required byte size
ValueRangeError – If raw value not a valid enum member and validate=True

encode_value(value: T | int, *, validate: bool = True) → bytearray¶

Encode enum instance or int to bytes.

Parameters:

value – Enum instance or integer value to encode
validate – Whether to validate enum membership (default True)

Returns:

Encoded bytes

Raises:

ValueError – If value not a valid enum member and validate=True

classmethod sint16(enum_class: type[T]) → EnumTemplate[T]¶

Create EnumTemplate for 2-byte signed enum.

Parameters:: enum_class – IntEnum subclass with values -32768 to 32767
Returns:: Configured EnumTemplate instance

classmethod sint32(enum_class: type[T]) → EnumTemplate[T]¶

Create EnumTemplate for 4-byte signed enum.

Parameters:: enum_class – IntEnum subclass with values -2147483648 to 2147483647
Returns:: Configured EnumTemplate instance

classmethod sint8(enum_class: type[T]) → EnumTemplate[T]¶

Create EnumTemplate for 1-byte signed enum.

Parameters:: enum_class – IntEnum subclass with values -128 to 127
Returns:: Configured EnumTemplate instance

Example::

>>> class Temperature(IntEnum):
...     FREEZING = -10
...     NORMAL = 0
...     HOT = 10
>>> template = EnumTemplate.sint8(Temperature)

classmethod uint16(enum_class: type[T]) → EnumTemplate[T]¶

Create EnumTemplate for 2-byte unsigned enum.

Parameters:: enum_class – IntEnum subclass with values 0-65535
Returns:: Configured EnumTemplate instance

Example::

>>> class ExtendedStatus(IntEnum):
...     STATE_1 = 0x0100
...     STATE_2 = 0x0200
>>> template = EnumTemplate.uint16(ExtendedStatus)

classmethod uint32(enum_class: type[T]) → EnumTemplate[T]¶

Create EnumTemplate for 4-byte unsigned enum.

Parameters:: enum_class – IntEnum subclass with values 0-4294967295
Returns:: Configured EnumTemplate instance

classmethod uint8(enum_class: type[T]) → EnumTemplate[T]¶

Create EnumTemplate for 1-byte unsigned enum.

Parameters:: enum_class – IntEnum subclass with values 0-255
Returns:: Configured EnumTemplate instance

Example::

>>> class Status(IntEnum):
...     IDLE = 0
...     ACTIVE = 1
>>> template = EnumTemplate.uint8(Status)

property data_size: int¶: Return byte size required for encoding.

property extractor: src.bluetooth_sig.gatt.characteristics.utils.extractors.RawExtractor¶: Return extractor for pipeline access.

property translator: src.bluetooth_sig.gatt.characteristics.utils.translators.ValueTranslator[int]¶: Get IDENTITY translator for enums (no scaling needed).

src.bluetooth_sig.gatt.characteristics.templates.enum.T¶