src.bluetooth_sig.gatt.characteristics.utils.translators¶

Value translators for the BLE encoding/decoding pipeline.

This module provides the translation layer that converts raw integers to domain values (and back). Translators have a single responsibility: value interpretation and scaling.

The translation layer is the second stage of the decode pipeline:: bytes → [Extractor] → raw_int → [Translator] → typed_value

Translators do NOT handle: - Byte extraction (that’s the extractor’s job) - Special value detection (that’s a pipeline interception point) - Validation (that’s a separate validation layer)

Attributes¶

Name	Description
`FLOAT32_IEEE11073`
`FLOAT32_IEEE754`
`IDENTITY`
`PERCENTAGE`
`SFLOAT`
`T`

Classes¶

Name	Description
`Float32IEEE754Translator`	Translator for standard IEEE-754 32-bit float (not IEEE 11073).
`Float32IEEETranslator`	Translator for IEEE 11073 32-bit FLOAT format (medfloat32).
`IdentityTranslator`	Pass-through translator for values needing no conversion.
`LinearTranslator`	Linear scaling translator: value = (raw + offset) * scale_factor.
`PercentageTranslator`	Translator for percentage values (0-100).
`SfloatTranslator`	Translator for IEEE 11073 16-bit SFLOAT format.
`ValueTranslator`	Protocol for raw-to-value translation.

Functions¶

Name	Description
`create_linear_translator`(→ LinearTranslator)	Factory for creating LinearTranslator instances.

Module Contents¶

class src.bluetooth_sig.gatt.characteristics.utils.translators.Float32IEEE754Translator¶

Bases: ValueTranslator[float]

Translator for standard IEEE-754 32-bit float (not IEEE 11073).

For characteristics using standard single-precision floats rather than the medical device FLOAT32 format.

translate(raw: int) → float¶: Convert raw bits to IEEE-754 float.

untranslate(value: float) → int¶: Encode IEEE-754 float to raw bits.

class src.bluetooth_sig.gatt.characteristics.utils.translators.Float32IEEETranslator¶

Bases: ValueTranslator[float]

Translator for IEEE 11073 32-bit FLOAT format (medfloat32).

Used by medical device profiles for higher precision measurements.

translate(raw: int) → float¶: Convert raw FLOAT32 bits to float value.

untranslate(value: float) → int¶: Encode float to FLOAT32 raw bits.

NAN = 8388607¶

NEGATIVE_INFINITY = 8388610¶

NRES = 8388608¶

POSITIVE_INFINITY = 8388606¶

RFU = 8388609¶

class src.bluetooth_sig.gatt.characteristics.utils.translators.IdentityTranslator¶

Bases: ValueTranslator[int]

Pass-through translator for values needing no conversion.

Used for simple integer types where raw == domain value.

translate(raw: int) → int¶: Return raw value unchanged.

untranslate(value: int) → int¶: Return value unchanged.

class src.bluetooth_sig.gatt.characteristics.utils.translators.LinearTranslator(scale_factor: float = 1.0, offset: int = 0)¶

Bases: ValueTranslator[float]

Linear scaling translator: value = (raw + offset) * scale_factor.

This implements the Bluetooth SIG M, d, b formula:: actual_value = M * 10^d * (raw + b)
Where:: scale_factor = M * 10^d offset = b

Examples

Temperature 0.01°C resolution: LinearTranslator(scale_factor=0.01, offset=0) Humidity 0.01% resolution: LinearTranslator(scale_factor=0.01, offset=0)

classmethod from_mdb(m: int, d: int, b: int) → LinearTranslator¶

Create from Bluetooth SIG M, d, b parameters.

Parameters:

m – Multiplier factor.
d – Decimal exponent (10^d).
b – Offset added to raw value.

Returns:

Configured LinearTranslator instance.

Examples

Temperature 0.01°C: from_mdb(1, -2, 0) Percentage 0.5%: from_mdb(5, -1, 0)

translate(raw: int) → float¶: Apply linear scaling: (raw + offset) * scale_factor.

untranslate(value: float) → int¶: Reverse linear scaling: (value / scale_factor) - offset.

property offset: int¶: Return the offset value (b parameter).

property scale_factor: float¶: Get the scale factor (M * 10^d).

class src.bluetooth_sig.gatt.characteristics.utils.translators.PercentageTranslator¶

Bases: ValueTranslator[int]

Translator for percentage values (0-100).

Simple pass-through since percentage is typically stored as uint8 0-100. Provides semantic clarity in the pipeline.

translate(raw: int) → int¶: Return percentage value.

untranslate(value: int) → int¶: Return percentage as raw.

class src.bluetooth_sig.gatt.characteristics.utils.translators.SfloatTranslator¶

Bases: ValueTranslator[float]

Translator for IEEE 11073 16-bit SFLOAT format.

SFLOAT is used by many Bluetooth Health profiles (blood pressure, glucose, weight scale, etc.). It provides a compact representation with ~3 significant digits.

Special value handling: - 0x07FF: NaN - 0x0800: NRes (Not at this resolution) - 0x07FE: +INFINITY - 0x0802: -INFINITY

translate(raw: int) → float¶

Convert raw SFLOAT bits to float value.

Parameters:: raw – Raw 16-bit integer from extractor.
Returns:: Decoded float value, or NaN/Inf for special values.

untranslate(value: float) → int¶

Encode float to SFLOAT raw bits.

Parameters:: value – Float value to encode.
Returns:: Raw 16-bit integer for extractor.

NAN = 2047¶

NEGATIVE_INFINITY = 2050¶

NRES = 2048¶

POSITIVE_INFINITY = 2046¶

class src.bluetooth_sig.gatt.characteristics.utils.translators.ValueTranslator¶

Bases: abc.ABC, Generic[T]

Protocol for raw-to-value translation.

Translators convert raw integer values to typed domain values and back. They handle scaling, offset, and type conversion but NOT: - Byte extraction (use RawExtractor) - Special value handling (pipeline intercepts before translation) - Validation (separate validation layer)

Type parameter T is the output type (int, float, etc.).

abstractmethod translate(raw: int) → T¶

Convert raw integer to domain value.

Parameters:: raw – Raw integer from extractor.
Returns:: Typed domain value.

abstractmethod untranslate(value: T) → int¶

Convert domain value back to raw integer.

Parameters:: value – Typed domain value.
Returns:: Raw integer for encoder.
Raises:: ValueError – If value cannot be converted to raw integer.

src.bluetooth_sig.gatt.characteristics.utils.translators.create_linear_translator(scale_factor: float | None = None, offset: int = 0, m: int | None = None, d: int | None = None, b: int | None = None) → LinearTranslator¶

Factory for creating LinearTranslator instances.

Can be configured either with scale_factor/offset or M/d/b parameters.

Parameters:

scale_factor – Direct scale factor (takes precedence over M/d).
offset – Direct offset (takes precedence over b).
m – Bluetooth SIG multiplier.
d – Bluetooth SIG decimal exponent.
b – Bluetooth SIG offset.

Returns:

Configured LinearTranslator.

Examples

>>> temp_translator = create_linear_translator(scale_factor=0.01)
>>> temp_translator = create_linear_translator(m=1, d=-2, b=0)

src.bluetooth_sig.gatt.characteristics.utils.translators.FLOAT32_IEEE11073¶

src.bluetooth_sig.gatt.characteristics.utils.translators.FLOAT32_IEEE754¶

src.bluetooth_sig.gatt.characteristics.utils.translators.IDENTITY¶

src.bluetooth_sig.gatt.characteristics.utils.translators.PERCENTAGE¶

src.bluetooth_sig.gatt.characteristics.utils.translators.SFLOAT¶

src.bluetooth_sig.gatt.characteristics.utils.translators.T¶