85async def discover_ftms_devices(
 86    discover_time: float = 10,
 87    **kwargs: Any,
 88) -> AsyncIterator[tuple[BLEDevice, MachineType]]:
 89    """
 90    Discover FTMS devices.
 91
 92    Parameters:
 93    - `discover_time` - Discover time. Defaults to 10s.
 94    - `**kwargs` - Additional keyword arguments for backwards compatibility.
 95
 96    Return:
 97    - `AsyncIterator[tuple[BLEDevice, MachineType]]` async generator of `BLEDevice` and `MachineType` tuples.
 98    """
 99
100    devices: set[str] = set()
101
102    async with BleakScanner(
103        service_uuids=[normalize_uuid_str(FTMS_UUID)],
104        kwargs=kwargs,
105    ) as scanner:
106        try:
107            async with asyncio.timeout(discover_time):
108                async for dev, adv in scanner.advertisement_data():
109                    if dev.address in devices:
110                        continue
111
112                    try:
113                        machine_type = get_machine_type_from_service_data(adv)
114
115                    except NotFitnessMachineError:
116                        continue
117
118                    devices.add(dev.address)
119
120                    _LOGGER.debug(
121                        " #%d - %s: address='%s', name='%s'",
122                        len(devices),
123                        machine_type.name,
124                        dev.address,
125                        dev.name,
126                    )
127
128                    yield dev, machine_type
129
130        except asyncio.TimeoutError:
131            pass

42def get_client(
43    ble_device: BLEDevice,
44    adv_or_type: AdvertisementData | MachineType,
45    *,
46    timeout: float = 2,
47    on_ftms_event: FtmsCallback | None = None,
48    on_disconnect: DisconnectCallback | None = None,
49    **kwargs: Any,
50) -> FitnessMachine:
51    """
52    Creates an `FitnessMachine` instance from [Bleak](https://bleak.readthedocs.io/) discovered
53    information: device and advertisement data. Instead of advertisement data, the `MachineType` can be used.
54
55    Parameters:
56    - `ble_device` - [BLE device](https://bleak.readthedocs.io/en/latest/api/index.html#bleak.backends.device.BLEDevice).
57    - `adv_or_type` - Service [advertisement data](https://bleak.readthedocs.io/en/latest/backends/index.html#bleak.backends.scanner.AdvertisementData) or `MachineType`.
58    - `timeout` - Control operation timeout. Defaults to 2.0s.
59    - `on_ftms_event` - Callback for receiving fitness machine events.
60    - `on_disconnect` - Disconnection callback.
61    - `**kwargs` - Additional keyword arguments for backwards compatibility.
62
63    Return:
64    - `FitnessMachine` instance.
65    """
66
67    adv_data = None
68
69    if isinstance(adv_or_type, AdvertisementData):
70        adv_data = adv_or_type
71        adv_or_type = get_machine_type_from_service_data(adv_or_type)
72
73    cls = get_machine(adv_or_type)
74
75    return cls(
76        ble_device,
77        adv_data,
78        timeout=timeout,
79        on_ftms_event=on_ftms_event,
80        on_disconnect=on_disconnect,
81        kwargs=kwargs,
82    )

134async def get_client_from_address(
135    address: str,
136    *,
137    scan_timeout: float = 10,
138    timeout: float = 2,
139    on_ftms_event: FtmsCallback | None = None,
140    on_disconnect: DisconnectCallback | None = None,
141    **kwargs: Any,
142) -> FitnessMachine:
143    """
144    Scans for fitness machine with specified BLE address. On success creates and return an `FitnessMachine` instance.
145
146    Parameters:
147    - `address` - The Bluetooth address of the device on this machine (UUID on macOS).
148    - `scan_timeout` - Scanning timeout. Defaults to 10.0s.
149    - `timeout` - Control operation timeout. Defaults to 2.0s.
150    - `on_ftms_event` - Callback for receiving fitness machine events.
151    - `on_disconnect` - Disconnection callback.
152    - `**kwargs` - Additional keyword arguments for backwards compatibility.
153
154    Return:
155    - `FitnessMachine` instance if device found successfully.
156    """
157
158    async for dev, machine_type in discover_ftms_devices(
159        scan_timeout, kwargs=kwargs
160    ):
161        if dev.address.lower() == address.lower():
162            return get_client(
163                dev,
164                machine_type,
165                timeout=timeout,
166                on_ftms_event=on_ftms_event,
167                on_disconnect=on_disconnect,
168                kwargs=kwargs,
169            )
170
171    raise BleakDeviceNotFoundError(address)

52def get_machine_type_from_service_data(
53    adv_data: AdvertisementData,
54) -> MachineType:
55    """Returns fitness machine type from Bluetooth advertisement data.
56
57    Parameters:
58        adv_data: Bluetooth [advertisement data](https://bleak.readthedocs.io/en/latest/backends/index.html#bleak.backends.scanner.AdvertisementData).
59
60    Returns:
61        Fitness machine type.
62    """
63
64    data = adv_data.service_data.get(normalize_uuid_str(FTMS_UUID))
65
66    if data is None or not (2 <= len(data) <= 3):
67        raise NotFitnessMachineError(data)
68
69    # Reading mandatory `Flags` and `Machine Type`.
70    # `Machine Type` bytes may be reversed on some machines or be a just one
71    # byte (it's bug), so I logically ORed them.
72    try:
73        mt = functools.reduce(operator.or_, data[1:])
74        mf, mt = MachineFlags(data[0]), MachineType(mt)
75
76    except ValueError:
77        raise NotFitnessMachineError(data)
78
79    if mf and mt:
80        return mt
81
82    raise NotFitnessMachineError(data)

 46class FitnessMachine(ABC, PropertiesManager):
 47    """
 48    Base FTMS client.
 49
 50    Supports `async with ...` context manager.
 51    """
 52
 53    _machine_type: ClassVar[MachineType]
 54    """Machine type."""
 55
 56    _data_model: ClassVar[type[RealtimeData]]
 57    """Model of real-time training data."""
 58
 59    _data_uuid: ClassVar[str]
 60    """Notify UUID of real-time training data."""
 61
 62    _cli: BleakClient
 63
 64    _updater: DataUpdater
 65
 66    _device: BLEDevice
 67    _need_connect: bool
 68
 69    # Static device info
 70
 71    _device_info: DeviceInfo = {}
 72    _m_features: MachineFeatures = MachineFeatures(0)
 73    _m_settings: MachineSettings = MachineSettings(0)
 74    _settings_ranges: MappingProxyType[str, SettingRange] = MappingProxyType({})
 75
 76    def __init__(
 77        self,
 78        ble_device: BLEDevice,
 79        adv_data: AdvertisementData | None = None,
 80        *,
 81        timeout: float = 2.0,
 82        on_ftms_event: FtmsCallback | None = None,
 83        on_disconnect: DisconnectCallback | None = None,
 84        **kwargs: Any,
 85    ) -> None:
 86        super().__init__(on_ftms_event)
 87
 88        self._need_connect = False
 89        self._timeout = timeout
 90        self._disconnect_cb = on_disconnect
 91        self._kwargs = kwargs
 92
 93        self.set_ble_device_and_advertisement_data(ble_device, adv_data)
 94
 95        # Updaters
 96        self._updater = DataUpdater(self._data_model, self._on_event)
 97        self._controller = MachineController(self._on_event)
 98
 99    @classmethod
100    def _get_supported_properties(
101        cls, features: MachineFeatures = MachineFeatures(~0)
102    ) -> list[str]:
103        return cls._data_model._get_features(features)
104
105    async def __aenter__(self):
106        await self.connect()
107        return self
108
109    async def __aexit__(self, exc_type, exc, tb):
110        await self.disconnect()
111
112    # BLE SPECIFIC PROPERTIES
113
114    def set_ble_device_and_advertisement_data(
115        self, ble_device: BLEDevice, adv_data: AdvertisementData | None
116    ):
117        self._device = ble_device
118
119        if adv_data:
120            self._properties["rssi"] = adv_data.rssi
121
122            if self._cb:
123                self._cb(UpdateEvent("update", {"rssi": adv_data.rssi}))
124
125    @property
126    def unique_id(self) -> str:
127        """Unique ID"""
128
129        return self.device_info.get(
130            "serial_number", self.address.replace(":", "").lower()
131        )
132
133    @property
134    def need_connect(self) -> bool:
135        """Connection state latch. `True` if connection is needed."""
136        return self._need_connect
137
138    @need_connect.setter
139    def need_connect(self, value: bool) -> None:
140        """Connection state latch. `True` if connection is needed."""
141        self._need_connect = value
142
143    @property
144    def rssi(self) -> int | None:
145        """RSSI."""
146        return self.get_property("rssi")
147
148    @property
149    def name(self) -> str:
150        """Device name or BLE address"""
151
152        return self._device.name or self._device.address
153
154    def set_disconnect_callback(self, cb: DisconnectCallback):
155        """Set disconnect callback."""
156        self._disconnect_cb = cb
157
158    async def connect(self) -> None:
159        """
160        Opens a connection to the device. Reads necessary static information:
161        * Device Information (manufacturer, model, serial number, hardware and software versions);
162        * Supported features;
163        * Supported settings;
164        * Ranges of parameters settings.
165        """
166
167        self._need_connect = True
168
169        await self._connect()
170
171    async def disconnect(self) -> None:
172        """Disconnects from device."""
173
174        self._need_connect = False
175
176        if self.is_connected:
177            await self._cli.disconnect()
178
179    @property
180    def address(self) -> str:
181        """Bluetooth address."""
182
183        return self._device.address
184
185    @property
186    def is_connected(self) -> bool:
187        """Current connection status."""
188
189        return hasattr(self, "_cli") and self._cli.is_connected
190
191    # COMMON BASE PROPERTIES
192
193    @property
194    def device_info(self) -> DeviceInfo:
195        """Device Information."""
196
197        return self._device_info
198
199    @property
200    def machine_type(self) -> MachineType:
201        """Machine type."""
202
203        return self._machine_type
204
205    @cached_property
206    def supported_properties(self) -> list[str]:
207        """
208        Properties that supported by this machine.
209        Based on **Machine Features** report.
210
211        *May contain both meaningless properties and may not contain
212        some properties that are supported by the machine.*
213        """
214
215        x = self._get_supported_properties(self._m_features)
216
217        if self.training_status is not None:
218            x.append(c.TRAINING_STATUS)
219
220        return x
221
222    @cached_property
223    def available_properties(self) -> list[str]:
224        """All properties that *MAY BE* supported by this machine type."""
225
226        x = self._get_supported_properties()
227        x.append(c.TRAINING_STATUS)
228
229        return x
230
231    @cached_property
232    def supported_settings(self) -> list[str]:
233        """Supported settings."""
234
235        return ControlModel._get_features(self._m_settings)
236
237    @property
238    def supported_ranges(self) -> MappingProxyType[str, SettingRange]:
239        """Ranges of supported settings."""
240
241        return self._settings_ranges
242
243    def _on_disconnect(self, cli: BleakClient) -> None:
244        _LOGGER.debug("Client disconnected. Reset updaters states.")
245
246        del self._cli
247        self._updater.reset()
248        self._controller.reset()
249
250        if self._disconnect_cb:
251            self._disconnect_cb(self)
252
253    async def _connect(self) -> None:
254        if not self._need_connect or self.is_connected:
255            return
256
257        await close_stale_connections(self._device)
258
259        _LOGGER.debug("Initialization. Trying to establish connection.")
260
261        self._cli = await establish_connection(
262            client_class=BleakClient,
263            device=self._device,
264            name=self.name,
265            disconnected_callback=self._on_disconnect,
266            # we needed only two services: `Fitness Machine Service` and `Device Information Service`
267            services=[c.FTMS_UUID, DIS_UUID],
268            kwargs=self._kwargs,
269        )
270
271        _LOGGER.debug("Connection success.")
272
273        # Reading necessary static fitness machine information
274
275        if not self._device_info:
276            self._device_info = await read_device_info(self._cli)
277
278        if not self._m_features:
279            (
280                self._m_features,
281                self._m_settings,
282                self._settings_ranges,
283            ) = await read_features(self._cli, self._machine_type)
284
285        await self._controller.subscribe(self._cli)
286        await self._updater.subscribe(self._cli, self._data_uuid)
287
288    # COMMANDS
289
290    async def _write_command(
291        self, code: ControlCode | None = None, *args, **kwargs
292    ):
293        if self._need_connect:
294            await self._connect()
295            return await self._controller.write_command(
296                self._cli, code, timeout=self._timeout, **kwargs
297            )
298
299        return ResultCode.FAILED
300
301    async def reset(self) -> ResultCode:
302        """Initiates the procedure to reset the controllable settings of a fitness machine."""
303        return await self._write_command(ControlCode.RESET)
304
305    async def start_resume(self) -> ResultCode:
306        """Initiate the procedure to start or resume a training session."""
307        return await self._write_command(ControlCode.START_RESUME)
308
309    async def stop(self) -> ResultCode:
310        """Initiate the procedure to stop a training session."""
311        return await self._write_command(stop_pause=StopPauseCode.STOP)
312
313    async def pause(self) -> ResultCode:
314        """Initiate the procedure to pause a training session."""
315        return await self._write_command(stop_pause=StopPauseCode.PAUSE)
316
317    async def set_setting(self, setting_id: str, *args: Any) -> ResultCode:
318        """
319        Generic method of settings by ID.
320
321        **Methods for setting specific parameters.**
322        """
323
324        if setting_id not in self.supported_settings:
325            return ResultCode.NOT_SUPPORTED
326
327        if not args:
328            raise ValueError("No data to pass.")
329
330        if len(args) == 1:
331            args = args[0]
332
333        return await self._write_command(code=None, **{setting_id: args})
334
335    async def set_target_speed(self, value: float) -> ResultCode:
336        """
337        Sets target speed.
338
339        Units: `km/h`.
340        """
341        return await self.set_setting(c.TARGET_SPEED, value)
342
343    async def set_target_inclination(self, value: float) -> ResultCode:
344        """
345        Sets target inclination.
346
347        Units: `%`.
348        """
349        return await self.set_setting(c.TARGET_INCLINATION, value)
350
351    async def set_target_resistance(self, value: float) -> ResultCode:
352        """
353        Sets target resistance level.
354
355        Units: `unitless`.
356        """
357        return await self.set_setting(c.TARGET_RESISTANCE, value)
358
359    async def set_target_power(self, value: int) -> ResultCode:
360        """
361        Sets target power.
362
363        Units: `Watt`.
364        """
365        return await self.set_setting(c.TARGET_POWER, value)
366
367    async def set_target_heart_rate(self, value: int) -> ResultCode:
368        """
369        Sets target heart rate.
370
371        Units: `bpm`.
372        """
373        return await self.set_setting(c.TARGET_HEART_RATE, value)
374
375    async def set_target_energy(self, value: int) -> ResultCode:
376        """
377        Sets target expended energy.
378
379        Units: `kcal`.
380        """
381        return await self.set_setting(c.TARGET_ENERGY, value)
382
383    async def set_target_steps(self, value: int) -> ResultCode:
384        """
385        Sets targeted number of steps.
386
387        Units: `step`.
388        """
389        return await self.set_setting(c.TARGET_STEPS, value)
390
391    async def set_target_strides(self, value: int) -> ResultCode:
392        """
393        Sets targeted number of strides.
394
395        Units: `stride`.
396        """
397        return await self.set_setting(c.TARGET_STRIDES, value)
398
399    async def set_target_distance(self, value: int) -> ResultCode:
400        """
401        Sets targeted distance.
402
403        Units: `m`.
404        """
405        return await self.set_setting(c.TARGET_DISTANCE, value)
406
407    async def set_target_time(self, *value: int) -> ResultCode:
408        """
409        Set targeted training time.
410
411        Units: `s`.
412        """
413        return await self.set_setting(c.TARGET_TIME, *value)
414
415    async def set_indoor_bike_simulation(
416        self,
417        value: IndoorBikeSimulationParameters,
418    ) -> ResultCode:
419        """Set indoor bike simulation parameters."""
420        return await self.set_setting(c.INDOOR_BIKE_SIMULATION, value)
421
422    async def set_wheel_circumference(self, value: float) -> ResultCode:
423        """
424        Set wheel circumference.
425
426        Units: `mm`.
427        """
428        return await self.set_setting(c.WHEEL_CIRCUMFERENCE, value)
429
430    async def spin_down_start(self) -> ResultCode:
431        """
432        Start Spin-Down.
433
434        It can be sent either in response to a request to start Spin-Down, or separately.
435        """
436        return await self.set_setting(c.SPIN_DOWN, SpinDownControlCode.START)
437
438    async def spin_down_ignore(self) -> ResultCode:
439        """
440        Ignore Spin-Down.
441
442        It can be sent in response to a request to start Spin-Down.
443        """
444        return await self.set_setting(c.SPIN_DOWN, SpinDownControlCode.IGNORE)
445
446    async def set_target_cadence(self, value: float) -> ResultCode:
447        """
448        Set targeted cadence.
449
450        Units: `rpm`.
451        """
452        return await self.set_setting(c.TARGET_CADENCE, value)

13class CrossTrainer(FitnessMachine):
14    """
15    Cross Trainer (Elliptical Trainer).
16
17    Specific class of `FitnessMachine`.
18    """
19
20    _machine_type: ClassVar[MachineType] = MachineType.CROSS_TRAINER
21
22    _data_model: ClassVar[type[RealtimeData]] = CrossTrainerData
23
24    _data_uuid: ClassVar[str] = CROSS_TRAINER_DATA_UUID

13class IndoorBike(FitnessMachine):
14    """
15    Indoor Bike (Spin Bike).
16
17    Specific class of `FitnessMachine`.
18    """
19
20    _machine_type: ClassVar[MachineType] = MachineType.INDOOR_BIKE
21
22    _data_model: ClassVar[type[RealtimeData]] = IndoorBikeData
23
24    _data_uuid: ClassVar[str] = INDOOR_BIKE_DATA_UUID

13class Treadmill(FitnessMachine):
14    """
15    Treadmill.
16
17    Specific class of `FitnessMachine`.
18    """
19
20    _machine_type: ClassVar[MachineType] = MachineType.TREADMILL
21
22    _data_model: ClassVar[type[RealtimeData]] = TreadmillData
23
24    _data_uuid: ClassVar[str] = TREADMILL_DATA_UUID

13class Rower(FitnessMachine):
14    """
15    Rower (Rowing Machine).
16
17    Specific class of `FitnessMachine`.
18    """
19
20    _machine_type: ClassVar[MachineType] = MachineType.ROWER
21
22    _data_model: ClassVar[type[RealtimeData]] = RowerData
23
24    _data_uuid: ClassVar[str] = ROWER_DATA_UUID

29class MachineType(Flag):
30    """
31    Fitness Machine Type.
32
33    Included in the Advertisement Service Data.
34
35    Described in section **3.1.2: Fitness Machine Type Field**.
36    """
37
38    TREADMILL = auto()
39    """Treadmill Machine."""
40    CROSS_TRAINER = auto()
41    """Cross Trainer Machine."""
42    STEP_CLIMBER = auto()
43    """Step Climber Machine."""
44    STAIR_CLIMBER = auto()
45    """Stair Climber Machine."""
46    ROWER = auto()
47    """Rower Machine."""
48    INDOOR_BIKE = auto()
49    """Indoor Bike Machine."""

323class UpdateEvent(NamedTuple):
324    """Update Event."""
325
326    event_id: Literal["update"]
327    """Always `update`."""
328    event_data: UpdateEventData
329    """`UpdateEvent` data."""

341class SetupEvent(NamedTuple):
342    """Setting Event."""
343
344    event_id: Literal["setup"]
345    """Always `setup`."""
346    event_data: SetupEventData
347    """`SetupEvent` data."""
348    event_source: ControlSource
349    """Reason of event."""