src.bluetooth_sig.gatt.characteristics.templates.time_duration

Time-duration template returning timedelta for BLE time characteristics.

Wraps a numeric extractor and converts raw integer counts (seconds, milliseconds, hours, …) into datetime.timedelta instances so that callers receive a proper Python time type instead of a plain int.

Classes

Name

Description

TimeDurationTemplate

Template for time-duration characteristics that return timedelta.

TimeExponentialTemplate

Template for exponentially-encoded time (Time Exponential 8).

Module Contents

class src.bluetooth_sig.gatt.characteristics.templates.time_duration.TimeDurationTemplate(extractor: src.bluetooth_sig.gatt.characteristics.utils.extractors.RawExtractor, *, seconds_per_unit: float = 1.0)

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

Template for time-duration characteristics that return timedelta.

Encodes/decodes a raw integer count in a given time unit (seconds, milliseconds, hours, …) to/from a timedelta.

Pipeline Integration:

bytes -> [extractor] -> raw_int -> x scale -> timedelta(seconds=…)

Examples

>>> template = TimeDurationTemplate.seconds_uint16()
>>> template.decode_value(bytearray([0x2A, 0x00]))
datetime.timedelta(seconds=42)
>>>
>>> template.encode_value(timedelta(seconds=42))
bytearray(b'*\\x00')
classmethod decihours_uint8() → TimeDurationTemplate

1-byte unsigned, 0.1-hour (6-minute) resolution.

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

Decode bytes to timedelta.

Parameters:

  • data – Raw bytes from BLE characteristic.

  • offset – Starting offset in data buffer.

  • ctx – Optional context for parsing.

  • validate – Whether to validate data length (default True).

Returns:

timedelta representing the decoded duration.

Raises:

InsufficientDataError – If data too short for required byte size.

encode_value(value: datetime.timedelta | int | float, *, validate: bool = True) → bytearray

Encode timedelta (or numeric seconds) to bytes.

Parameters:

  • value – timedelta, or a numeric value treated as the raw count.

  • validate – Whether to validate (default True).

Returns:

Encoded bytes.

classmethod hours_uint24() → TimeDurationTemplate

3-byte unsigned, 1-hour resolution.

classmethod milliseconds_uint24() → TimeDurationTemplate

3-byte unsigned, 1-millisecond resolution.

classmethod seconds_uint16() → TimeDurationTemplate

2-byte unsigned, 1-second resolution.

classmethod seconds_uint24() → TimeDurationTemplate

3-byte unsigned, 1-second resolution.

classmethod seconds_uint32() → TimeDurationTemplate

4-byte unsigned, 1-second resolution.

classmethod seconds_uint8() → TimeDurationTemplate

1-byte unsigned, 1-second resolution.

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.

class src.bluetooth_sig.gatt.characteristics.templates.time_duration.TimeExponentialTemplate

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

Template for exponentially-encoded time (Time Exponential 8).

Encoding: value = 1.1^(N - 64) seconds. Special values: 0x00 = 0 s, 0xFE = device lifetime, 0xFF = unknown.

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

Decode exponentially-encoded time to timedelta.

Parameters:

  • data – Raw bytes from BLE characteristic.

  • offset – Starting offset in data buffer.

  • ctx – Optional context for parsing.

  • validate – Whether to validate data length (default True).

Returns:

timedelta representing the decoded duration.

Raises:

InsufficientDataError – If data too short.

encode_value(value: datetime.timedelta | float, *, validate: bool = True) → bytearray

Encode a time duration using exponential encoding.

Parameters:

  • value – timedelta or numeric seconds.

  • validate – Whether to validate (default True).

Returns:

Encoded byte.

property data_size: int

1 byte.

Type:

Size

property extractor: src.bluetooth_sig.gatt.characteristics.utils.extractors.RawExtractor

Return uint8 extractor for pipeline access.