src.bluetooth_sig.gatt.characteristics.templates.flag

Flag template for IntFlag encoding/decoding with configurable byte size.

Attributes

Name	Description
F

Classes

Name	Description
FlagTemplate	Template for IntFlag encoding/decoding with configurable byte size.

Module Contents

class src.bluetooth_sig.gatt.characteristics.templates.flag.FlagTemplate(flag_class: type[F], extractor: src.bluetooth_sig.gatt.characteristics.utils.extractors.RawExtractor)

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

Template for IntFlag encoding/decoding with configurable byte size.

Maps raw integer bytes to Python IntFlag instances through extraction and validation. Unlike EnumTemplate (which expects exact enum membership), FlagTemplate accepts any bitwise OR combination of the defined flag members.

Pipeline Integration:

bytes → [extractor] → raw_int → [IDENTITY translator] → int → flag constructor

Examples

>>> class ContactStatus(IntFlag):
...     CONTACT_0 = 0x01
...     CONTACT_1 = 0x02
...     CONTACT_2 = 0x04
>>>
>>> template = FlagTemplate.uint8(ContactStatus)
>>>
>>> # Decode from bytes — any combination is valid
>>> flags = template.decode_value(bytearray([0x05]))
>>> # ContactStatus.CONTACT_0 | ContactStatus.CONTACT_2
>>>
>>> # Encode flags to bytes
>>> data = template.encode_value(ContactStatus.CONTACT_0 | ContactStatus.CONTACT_2)  # bytearray([0x05])

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

Decode bytes to flag instance.

Parameters:

• data – Raw bytes from BLE characteristic.

• offset – Starting offset in data buffer.

• ctx – Optional context for parsing.

• validate – Whether to validate against defined flag bits (default True).

Returns:

Flag instance of type F.

Raises:

• InsufficientDataError – If data too short for required byte size.

• ValueRangeError – If raw value contains undefined bits and validate=True.

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

Encode flag instance or int to bytes.

Parameters:

• value – Flag instance or integer value to encode.

• validate – Whether to validate against defined flag bits (default True).

Returns:

Encoded bytes.

Raises:

ValueError – If value contains undefined bits and validate=True.

classmethod uint16(flag_class: type[F]) → FlagTemplate[F]

Create FlagTemplate for 2-byte unsigned flag field.

Parameters:

flag_class – IntFlag subclass with bit values in 0-65535.

Returns:

Configured FlagTemplate instance.

classmethod uint32(flag_class: type[F]) → FlagTemplate[F]

Create FlagTemplate for 4-byte unsigned flag field.

Parameters:

flag_class – IntFlag subclass with bit values in 0-4294967295.

Returns:

Configured FlagTemplate instance.

classmethod uint8(flag_class: type[F]) → FlagTemplate[F]

Create FlagTemplate for 1-byte unsigned flag field.

Parameters:

flag_class – IntFlag subclass with bit values in 0-255.

Returns:

Configured FlagTemplate instance.

Example::

>>> class Status(IntFlag):
...     BIT_0 = 0x01
...     BIT_1 = 0x02
>>> template = FlagTemplate.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 flags (no scaling needed).

src.bluetooth_sig.gatt.characteristics.templates.flag.F