toio.scanner.ble module

BLE scanner (including specific functions for each supported OS)

Scan toio Core Cubes with internal BLE interface.

class toio.scanner.ble.PlatformParam(platform, unsupported_result)[source]

Bases: NamedTuple

platform: str

Alias for field number 0

unsupported_result: Any

Alias for field number 1

toio.scanner.ble.async_platform_specified(param: PlatformParam = ('UNKNOWN', None))[source]
class toio.scanner.ble.UniversalBleScanner[source]

Bases: ScannerInterface

async scan(num: int, sort: Literal['rssi', 'local_name'] | None = 'rssi', timeout: float = 5.0, strategy: Literal['best', 'quick'] = 'best') → List[CubeInfo][source]

Scan the specified number of toio Core Cubes.

With strategy “best”, the scan collects cubes until timeout and returns the top results after sorting. With strategy “quick”, the scan returns as soon as the specified number of cubes are found.

Parameters:

  • num (int) – Number of cubes to be found.

  • sort (SortKey, optional) – Key to sort results. Defaults to “rssi”.

  • timeout (float, optional) – Scan timeout. Defaults to DEFAULT_SCAN_TIMEOUT.

  • strategy (ScanStrategy, optional) – Scan strategy. Defaults to “best”.

Returns:

List of found cubes.

Return type:

List[CubeInfo]

async scan_best(num: int, sort: Literal['rssi', 'local_name'] | None = 'rssi', timeout: float = 5.0) → List[CubeInfo][source]

Scan cubes until timeout and return the best candidates after sorting.

async scan_quick(num: int, sort: Literal['rssi', 'local_name'] | None = 'rssi', timeout: float = 5.0) → List[CubeInfo][source]

Scan cubes and return as soon as the specified number are found.

async scan_with_id(cube_id: Set[str], sort: Literal['rssi', 'local_name'] | None = 'rssi', timeout: float = 5.0) → List[CubeInfo][source]

Scan toio Core Cubes with specified id.

The scan is terminated by a timeout. In the case of a timeout, the number of elements in the returned list is the number of cubes found at the time of the timeout.

Parameters:

  • cube_id (set[str]) – Set of cube id to be found.

  • sort (SortKey, optional) – Key to sort results. Defaults to “rssi”.

  • timeout (float, optional) – Scan timeout. Defaults to DEFAULT_SCAN_TIMEOUT.

Returns:

List of found cubes.

Return type:

List[CubeInfo]

async scan_with_address(address: Set[str], sort: Literal['rssi', 'local_name'] | None = 'rssi', timeout: float = 5.0) → List[CubeInfo][source]

Scan toio Core Cubes with specified BLE address.

The scan is terminated by a timeout. In the case of a timeout, the number of elements in the returned list is the number of cubes found at the time of the timeout.

Parameters:

  • address (set[str]) – Set of BLE address to be found.

  • sort (SortKey, optional) – Key to sort results. Defaults to “rssi”.

  • timeout (float, optional) – Scan timeout. Defaults to DEFAULT_SCAN_TIMEOUT.

Returns:

List of found cubes.

Return type:

List[CubeInfo]

async scan_registered_cubes(num: int, sort: Literal['rssi', 'local_name'] | None = 'rssi', timeout: float = 5.0) → List[CubeInfo][source]

Scan toio Core Cubes registered with Windows

This function only works on Windows platform. On the other platform, this function always returns empty list.

Even if num is greater than the number of registered cubes, the maximum size of the list returned by this function is the number of registered cubes.

Parameters:

  • num (int) – Number of cubes to be found.

  • sort (SortKey, optional) – Key to sort results. Defaults to “rssi”.

  • timeout (float, optional) – Scan timeout. Defaults to DEFAULT_SCAN_TIMEOUT.

Returns:

List of found cubes.

Return type:

List[CubeInfo]

async scan_registered_cubes_with_id(cube_id: Set[str], sort: Literal['rssi', 'local_name'] | None = 'rssi', timeout: float = 5.0) → List[CubeInfo][source]

Scan toio Core Cube specified by the cube_id registered with Windows

This function only works on Windows platform. On the other platform, this function always returns empty list.

Parameters:

  • cube_id (set[str]) – Set of cube id to be found.

  • sort (SortKey, optional) – Key to sort results. Defaults to “rssi”.

  • timeout (float, optional) – Scan timeout. Defaults to DEFAULT_SCAN_TIMEOUT.

Returns:

List of found cubes.

Return type:

List[CubeInfo]