Coverage for src / bluetooth_sig / gatt / characteristics / magnetic_flux_density_3d.py: 97%

1"""Magnetic Flux Density 3D characteristic implementation.""" 

2 

3from __future__ import annotations 

4 

5from ...types.gatt_enums import ValueType 

6from ...types.units import PhysicalUnit 

7from ..context import CharacteristicContext 

8from .base import BaseCharacteristic 

9from .templates import VectorData 

10from .utils import DataParser 

11 

12 

13class MagneticFluxDensity3DCharacteristic(BaseCharacteristic[VectorData]): 

14 """Magnetic Flux Density - 3D characteristic (0x2AA1). 

15 

16 org.bluetooth.characteristic.magnetic_flux_density_3d 

17 

18 Magnetic flux density 3D characteristic. 

19 

20 Represents measurements of magnetic flux density for three 

21 orthogonal axes: X, Y, and Z. Note that 1 x 10^-7 Tesla equals 0.001 

22 Gauss. 

23 

24 Format: 3 x sint16 (6 bytes total) with 1e-7 Tesla resolution. 

25 """ 

26 

27 _characteristic_name: str | None = "Magnetic Flux Density - 3D" 

28 _manual_value_type: ValueType | str | None = ValueType.STRING # Override since decode_value returns dict 

29 _manual_unit: str | None = PhysicalUnit.TESLA.value # Override template's "units" default 

30 

31 _vector_components: list[str] = ["x_axis", "y_axis", "z_axis"] 

32 resolution: float = 1e-7 

33 expected_length: int = 6 # 3 x sint16 

34 

35 def _decode_value(self, data: bytearray, ctx: CharacteristicContext | None = None) -> VectorData: 

36 """Parse 3D magnetic flux density (3 x sint16 with resolution). 

37 

38 Args: 

39 data: Raw bytearray from BLE characteristic. 

40 ctx: Optional CharacteristicContext providing surrounding context (may be None). 

41 

42 Returns: 

43 VectorData with x, y, z axis values in Tesla. 

44 

45 # Parameter `ctx` is part of the public API but unused in this implementation. 

46 # Explicitly delete it to satisfy linters. 

47 del ctx 

48 """ 

49 if len(data) < 6: 

50 raise ValueError("Insufficient data for 3D magnetic flux density (need 6 bytes)") 

51 

52 x_raw = DataParser.parse_int16(data, 0, signed=True) 

53 y_raw = DataParser.parse_int16(data, 2, signed=True) 

54 z_raw = DataParser.parse_int16(data, 4, signed=True) 

55 

56 return VectorData( 

57 x_axis=x_raw * self.resolution, y_axis=y_raw * self.resolution, z_axis=z_raw * self.resolution 

58 ) 

59 

60 def _encode_value(self, data: VectorData) -> bytearray: 

61 """Encode 3D magnetic flux density.""" 

62 x_raw = int(data.x_axis / self.resolution) 

63 y_raw = int(data.y_axis / self.resolution) 

64 z_raw = int(data.z_axis / self.resolution) 

65 

66 result = bytearray() 

67 result.extend(DataParser.encode_int16(x_raw, signed=True)) 

68 result.extend(DataParser.encode_int16(y_raw, signed=True)) 

69 result.extend(DataParser.encode_int16(z_raw, signed=True)) 

70 return result