toio.cube package

Subpackages

Submodules

Module contents

class toio.cube.ToioCoreCube(interface: ~toio.device_interface.CubeInterface | None = None, name: str | None = None, scanner: ~typing.Type[~toio.device_interface.ScannerInterface] = <class 'toio.scanner.ble.UniversalBleScanner'>, scanner_args: ~typing.Sequence[~typing.Any] = ())[source]

Bases: CubeInterface

Access to toio Core Cube

Note

  • self.protocol_version is set after connecting to the cube.

  • self.protocol_version and self.max_retry_to_get_protocol_version is supported since v1.1.0.

  • basic scan function is supported since v1.1.0.

When Toio is initialized with no arguments, the scan() function can search for a cubes. scan() can be followed by a call to the connect() function to connect to multiple cubes.

If you initialize ToioCoreCube with a CubeInfo or a CubeInterface, you can connect to specified cube by calling the connect() function. In this case, the scan() function does not work.

ToioCoreCube is an asynchronous context manager. When ‘async with’ is used, ‘__aenter__’ handles the process up to connection, and ‘__aexit__’ handles the disconnection.

interface

control interface (e.g. BleCube)

Type:

CubeInterface

name

cube name (optional)

Type:

str

api

API class

Type:

ToioCoreCubeLowLevelAPI

protocol_version

protocol version of the cube

Type:

Optional[ProtocolVersion]

max_retry_to_get_protocol_version

number of retries to get protocol version

Type:

int

SUPPORTED_MAJOR_VERSION: int = 2
SUPPORTED_MINOR_VERSION: int = 4
static create(initializer: CubeInterface | CubeInfo | Sequence) → ToioCoreCube[source]

Supported toio.py versions: v1.1.0 or later

Create a ToioCoreCube instance from a CubeInterface or CubeInfo

Parameters:

initializer (CubeInitializer) – initializer

Return type:

Optional[ToioCoreCube]

static create_cubes(initializers: Iterable[CubeInterface | CubeInfo]) → List[ToioCoreCube][source]

Supported toio.py versions: v1.1.0 or later

Create a ToioCoreCube instance list from a CubeInterface or CubeInfo list

Parameters:

initializers (Iterable[CubeInitializer]) – initializers

Return type:

List[ToioCoreCube]

__init__(interface: ~toio.device_interface.CubeInterface | None = None, name: str | None = None, scanner: ~typing.Type[~toio.device_interface.ScannerInterface] = <class 'toio.scanner.ble.UniversalBleScanner'>, scanner_args: ~typing.Sequence[~typing.Any] = ())[source]
protocol_version: ProtocolVersion | None
max_retry_to_get_protocol_version: int
async scan()[source]
async connect() → bool[source]
async disconnect() → bool[source]
async read(char_uuid: UUID) → bytearray[source]
async write(char_uuid: UUID, data: bytes | bytearray | memoryview, response: bool = False)[source]
async register_notification_handler(char_uuid: UUID, notification_handler: Callable[[BleakGATTCharacteristic, bytearray], None | Awaitable[None]]) → bool[source]
async unregister_notification_handler(char_uuid: UUID) → bool[source]
is_connect() → bool[source]

Implemented in v1.1.0 or later

get current connection state

class toio.cube.NotificationHandlerInfo(func: Callable[[bytearray], None] | Callable[[bytearray], Awaitable[None]] | Callable[[bytearray, Any], None] | Callable[[bytearray, Any], Awaitable[None]], device: Any, interface: CubeInterface, misc: Any = None)[source]

Bases: object

Information of registered notification handler function.

NotificationHandlerInfo includes several type of information:

  • Unique data given at registration (misc)

  • Information about the device that received the notification (device, interface)

  • Information used for internal use (rest of properties)

__init__(func: Callable[[bytearray], None] | Callable[[bytearray], Awaitable[None]] | Callable[[bytearray, Any], None] | Callable[[bytearray, Any], Awaitable[None]], device: Any, interface: CubeInterface, misc: Any = None)[source]

__init__.

Parameters:

  • func (NotificationHandlerTypes) – notification handler function

  • device (NotificationReceivedDevice) – device to be notified

  • interface (CubeInterface) – interface of device

  • misc (Any) – user data

property misc: Any

User data given when the notification handler function is registered.

property device: Any

The device that received the notification.

property interface: CubeInterface

The interface of the device that received the notification. (equal to device.interface)

property is_async: bool

Whether the notification handler function is async or sync. (for internal use)

property num_of_args: int

Number of arguments received by the registered notification handler function. (for internal use)

get_notified_cube() → ToioCoreCube[source]

Return self.device as ToioCoreCube

class toio.cube.MultipleToioCoreCubes(cubes: int | ~typing.List[~toio.device_interface.CubeInfo], names: ~typing.Sequence[str] | None = None, scanner: ~typing.Type[~toio.device_interface.ScannerInterface] = <class 'toio.scanner.ble.UniversalBleScanner'>, scanner_args: ~typing.Sequence[~typing.Any] = ())[source]

Bases: object

Multiple cube control class

This class is a wrapper to control multiple cubes easier.

When MultipleToioCoreCubes is initialized with an integer, the scan() function can search for a specified number of cubes. scan() can be followed by a call to the connect() function to connect to multiple cubes.

If you initialize MultipleToioCoreCubes with a list of CubeInfo, you can connect to multiple cubes by calling the connect() function. In this case, the scan() function does not work.

MultipleToioCoreCubes is an asynchronous context manager. When ‘async with’ is used, ‘__aenter__’ handles the process up to connection, and ‘__aexit__’ handles the disconnection.

Access to each cubes

Each cube can be accessed by the number.

>>> async with MultipleToioCoreCubes(2) as cubes:
>>>    cubes[0].api....()
>>>    cubes[1].api....()

Each cube can be accessd by ‘for’ also.

>>> async with MultipleToioCoreCubes(2) as cubes:
>>>    for c in cubes:
>>>       c.api....()

When ‘names’ is specified, cubes has each name and can be accessed with specified name.

>>> # accessing by cube name property
>>> async with MultipleToioCoreCubes(2, "alpha", "beta") as cubes:
>>>    cubes.alpha.api....()
>>>    cubes.beta.api....()

>>> # accessing cubes using the cube interface obtained by name
>>> async with MultipleToioCoreCubes(2, "alpha", "beta") as cubes:
>>>     alpha = cubes.named("alpha")
>>>     beta = cubes.named("beta")
>>>     alpha.api....()
>>>     beta.api....()
OPERATION_INTERVAL: float = 0.5
__init__(cubes: int | ~typing.List[~toio.device_interface.CubeInfo], names: ~typing.Sequence[str] | None = None, scanner: ~typing.Type[~toio.device_interface.ScannerInterface] = <class 'toio.scanner.ble.UniversalBleScanner'>, scanner_args: ~typing.Sequence[~typing.Any] = ())[source]

Initialize MultipleCubes

Parameters:

  • cubes (Union[int, List[CubeInfo]]) – number of cubes to be scanned, or list of cubes to be handled

  • names (Optional[Sequence[str]]) – sequence of names of cubes

  • scanner (Type[ScannerInterface]) – scanner interface (default is UniversalBleScanner)

  • scanner_args (Sequence[Any]) – arguments given to the scanner.scan() function

async scan()[source]

scan cubes

If MultipleCubes is initialized with integer number, this function performs to scan the number of cubes.

async connect()[source]

connect to multiple cubes

cubes are connected at MultipleToioCoreCubes.OPERATION_INTERVAL second interval.

async disconnect()[source]

disconnect to multiple cubes

cubes are disconnected at MultipleToioCoreCubes.OPERATION_INTERVAL second interval.

named(name: str) → ToioCoreCube[source]

get the cube specified by the name

Parameters:

name (str) – name

Return type:

ToioCoreCube

Exceptions:

ValueError: the cube specified is not found

class toio.cube.ToioCoreCubeLowLevelAPI(interface: CubeInterface, root_device: Any)[source]

Bases: object

Control APIs This class has control APIs for each characteristic.

battery

Interface to battery characteristic

Type:

api.Battery

button

Interface to button characteristic

Type:

api.Button

configuration

Interface to configuration characteristic

Type:

api.Configuration

id_information

Interface to id information characteristic

Type:

api.IdInformation

indicator

Interface to indicator characteristic

Type:

api.IdInformation

motor

Interface to motor characteristic

Type:

api.Motor

sensor

Interface to sensor characteristic ( Motion Posture Magnet )

Type:

api.Sensor

sound

Interface to sound characteristic

Type:

api.Sound

__init__(interface: CubeInterface, root_device: Any)[source]
property version: str
toio.cube.BatteryResponseType

alias of BatteryInformation

class toio.cube.BatteryInformation(payload: bytearray)[source]

Bases: CubeResponse

Cube remaining battery level response

battery_level

Battery level ( 0 <= battery_level <= 100)

Type:

int

References

https://toio.github.io/toio-spec/en/docs/ble_battery#read-operations

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.Battery(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

Battery characteristic

References

https://toio.github.io/toio-spec/en/docs/ble_battery

static is_my_data(payload: bytearray) → BatteryInformation | None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any)[source]
async read() → BatteryInformation | None[source]

Read the battery level

Returns:

BatteryInformation or None (None returns when read fails)

References

https://toio.github.io/toio-spec/en/docs/ble_battery#read-operations

toio.cube.ButtonResponseType

alias of ButtonInformation

class toio.cube.ButtonState(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Value of the state of cube button

RELEASED = 0
PRESSED = 128
class toio.cube.ButtonInformation(payload: bytearray)[source]

Bases: CubeResponse

Cube button state response

state

State of the cube button

Type:

ButtonState

References

https://toio.github.io/toio-spec/en/docs/ble_button#read-operations

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.Button(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

Button characteristic

References

https://toio.github.io/toio-spec/en/docs/ble_button

static is_my_data(payload: bytearray) → ButtonInformation | None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any)[source]
async read() → ButtonInformation | None[source]

Read the state of button

Returns:

ButtonInformation or None (None returns when read fails)

References

https://toio.github.io/toio-spec/en/docs/ble_button#read-operations

class toio.cube.NotificationCondition(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Notification conditions of ID notification

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#notification-conditions

Always = 0
ChangeDetection = 1
Periodic = 255
class toio.cube.MagneticSensorFunction(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Disable = 0
MagnetState = 1
MagneticForce = 2
class toio.cube.MagneticSensorCondition(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Always = 0
ChangeDetection = 1
class toio.cube.MotorSpeedInformationAcquisitionState(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Disable = 0
Enable = 1
class toio.cube.PostureAngleDetectionType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Euler = 1
Quaternions = 2
HighPrecisionEuler = 3
class toio.cube.PostureAngleDetectionCondition(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Notification condition of posture angle detection

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#notification-conditions-1

Always = 0
ChangeDetection = 1
class toio.cube.ProtocolVersion(payload: bytearray)[source]

Bases: CubeResponse

Protocol version response

version

version (UTF-8)

Type:

str

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#obtaining-the-ble-protocol-version

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.ResponseIdNotificationSettings(payload: bytearray)[source]

Bases: CubeResponse

ID notification setting response

result

Result of the command

Type:

bool

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#responses-to-identification-sensor-id-notification-settings

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.ResponseIdMissedNotificationSettings(payload: bytearray)[source]

Bases: CubeResponse

ID missed notification setting response

result

Result of the command

Type:

bool

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#responses-to-identification-sensor-id-missed-notification-settings

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.ResponseMagneticSensorSettings(payload: bytearray)[source]

Bases: CubeResponse

Magnetic sensor setting response

result

Result of the command

Type:

bool

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#responses-to-magnetic-sensor-settings

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.ResponseMotorSpeedInformationAcquisitionSettings(payload: bytearray)[source]

Bases: CubeResponse

Motor speed information setting response

result

Result of the command

Type:

bool

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#responses-to-motor-speed-information-acquisition-settings

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.ResponsePostureAngleDetectionSettings(payload: bytearray)[source]

Bases: CubeResponse

Posture angle detection setting response

result

Result of the command

Type:

bool

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#responses-to-posture-angle-detection-settings-

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.Configuration(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

Configuration characteristic

References

https://toio.github.io/toio-spec/en/docs/ble_configuration

static is_my_data(payload: bytearray) → ProtocolVersion | ResponseIdNotificationSettings | ResponseIdMissedNotificationSettings | ResponseMagneticSensorSettings | ResponseMotorSpeedInformationAcquisitionSettings | ResponsePostureAngleDetectionSettings | ResponseConnectionIntervalRequest | ResponseGettingRequestedConnectionInterval | ResponseGettingCurrentConnectionInterval | None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any) → None[source]
async request_protocol_version() → None[source]

Send protocol version request command

This function DO NOT return response payload. Receive the result by notification.

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#requesting-the-ble-protocol-version

async set_horizontal_detection_threshold(threshold: int) → None[source]

Send horizontal detection threshold setting command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

threshold (int) – Threshold

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#horizontal-detection-threshold-settings

async set_collision_detection_threshold(threshold: int) → None[source]

Send collision detection threshold setting request command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

threshold (int) – Threshold

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#collision-detection-threshold-settings

async set_double_tap_detection_threshold(threshold: int) → None[source]

Send double-tap detection threshold setting request command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

threshold (int) – Threshold

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#double-tap-detection-time-interval-settings

async set_id_notification(interval_ms: int, condition: NotificationCondition) → None[source]

Send id information notification setting request command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#identification-sensor-id-notification-settings

async set_id_missed_notification(sensitivity_ms: int) → None[source]

Send ID missed notification setting request command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

sensitivity_ms (int) – Sensitivity [ms]

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#identification-sensor-id-missed-notification-settings

async set_magnetic_sensor(function_type: MagneticSensorFunction, interval_ms: int, condition: MagneticSensorCondition) → None[source]

Send magnetic sensor setting request command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#magnetic-sensor-settings-

async set_motor_speed_information_acquisition(state: MotorSpeedInformationAcquisitionState) → None[source]

Send motor speed information acquisition setting request command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

state (MotorSpeedInformationAcquisitionState) – state

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#motor-speed-information-acquisition-settings

async set_posture_angle_detection(detection_type: PostureAngleDetectionType, interval_ms: int, condition: PostureAngleDetectionCondition) → None[source]

Send posture angle setting request command

This function DO NOT return response payload. Receive the result by notification.

Parameters:

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#posture-angle-detection-settings-

async request_to_change_connection_interval(min_interval: int, max_interval: int) → None[source]

Request the connected central device to change the connection interval.

Note

If central device can not accept the requested connection interval value, one of the following occurs: - Bluetooth connection is disconnected. - Another connection interval value is set that can be accepted by the central device.

max_interval must be greater than or equal to min_interval. (except the value is 0xFFFF)

Parameters:

  • min_interval (int) – min_interval, from 6 to 3200, or 0xFFFF (0xFFFF means “to be determined by central”)

  • max_interval (int) – max_interval, from 6 to 3200, or 0xFFFF (0xFFFF means “to be determined by central”)

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#request-to-change-connection-interval-

async get_requested_connection_interval() → None[source]

Get requested connection interval value.

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#obtaining-the-requested-connection-interval-value-

async get_current_connection_interval() → None[source]

Get current connection interval value.

References

https://toio.github.io/toio-spec/en/docs/ble_configuration#obtaining-the-actual-connection-interval-value-

class toio.cube.PositionId(payload: bytearray)[source]

Bases: CubeResponse

Position id information response

References

https://toio.github.io/toio-spec/en/docs/ble_id#position-id

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.StandardId(payload: bytearray)[source]

Bases: CubeResponse

Standard id information response

References

https://toio.github.io/toio-spec/en/docs/ble_id#standard-id

static is_myself(data: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.PositionIdMissed(payload: bytearray)[source]

Bases: CubeResponse

Position id missed response

References

https://toio.github.io/toio-spec/en/docs/ble_id#position-id-missed

static is_myself(data: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.StandardIdMissed(payload: bytearray)[source]

Bases: CubeResponse

Standard id information response

References

https://toio.github.io/toio-spec/en/docs/ble_id#standard-id-missed

static is_myself(data: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.IdInformation(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

ID sensor characteristic

References

https://toio.github.io/toio-spec/en/docs/ble_id

static is_my_data(payload: bytearray) → PositionId | StandardId | PositionIdMissed | StandardIdMissed | None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any)[source]
async read() → PositionId | StandardId | PositionIdMissed | StandardIdMissed | None[source]

Read id information response

Returns:

One of IdInformationData or None (None returns when read fails)

class toio.cube.Color(r: int, g: int, b: int)[source]

Bases: object

Indicator color in RGB

r: int

R value (0 - 255)

g: int

G value (0 - 255)

b: int

B value (0 - 255)

flatten()[source]

Return the tuple representation of this dataclass

__init__(r: int, g: int, b: int) → None
class toio.cube.IndicatorParam(duration_ms: int, color: Color)[source]

Bases: object

Indicator color and lighting period

duration_ms: int
Duration of lighting:
Any fraction less than 10ms will be truncated.
0 - 9: no time limit
10 - 2550: duration [ms]
color: Color
RGB value
static from_int(duration_ms: int, r: int, g: int, b: int) → IndicatorParam[source]
flatten()[source]
__init__(duration_ms: int, color: Color) → None
class toio.cube.Indicator(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

Indicator characteristic

References

https://toio.github.io/toio-spec/en/docs/ble_light

static is_my_data(_payload: bytearray) → None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any)[source]
async turn_on(param: IndicatorParam | Sequence[int]) → None[source]

Send indicator turn on / off command

Parameters:

param (Union[IndicatorParam, Sequence[int]]) – Indicator parameter

References

https://toio.github.io/toio-spec/en/docs/ble_light#repeated-turning-on-and-off-of-indicator

async repeated_turn_on(repeat: int, param_list: Sequence[IndicatorParam] | Sequence[Sequence[int]]) → None[source]

Send repeated indicator turning on / off command

Parameters:

  • repeat (int) – Number of repetitions

  • param_list (Union[Sequence[IndicatorParam], Sequence[Sequence[int]]]) – List of indicator parameters

References

https://toio.github.io/toio-spec/en/docs/ble_light#repeated-turning-on-and-off-of-indicator

async turn_off_all() → None[source]

Send all off command

References

https://toio.github.io/toio-spec/en/docs/ble_light#turn-off-all-indicators

async turn_off(indicator_id: int) → None[source]

Send off command

Parameters:

indicator_id (int) – Indicator ID

References

https://toio.github.io/toio-spec/en/docs/ble_light#turn-off-a-specific-indicator

class toio.cube.MovementType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Movement type

References

https://toio.github.io/toio-spec/en/docs/ble_motor#movement-type

Curve = 0
CurveWithoutReverse = 1
Linear = 2
class toio.cube.RotationOption(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Rotation Option

Angle of the cube at the target point

References

https://toio.github.io/toio-spec/en/docs/ble_motor#%CE%B8-angle-of-the-cube-at-the-target-point

AbsoluteOptimal = 0
AbsolutePositive = 1
AbsoluteNegative = 2
RelativePositive = 3
RelativeNegative = 4
WithoutRotation = 5
SameAsAtWriting = 6
class toio.cube.TargetPosition(cube_location: CubeLocation, rotation_option: RotationOption = RotationOption.AbsoluteOptimal)[source]

Bases: object

Target position parameter

cube_location: CubeLocation

Target position of the cube

rotation_option: RotationOption = 0

Rotation option

static from_int(x: int = 0, y: int = 0, angle: int = 0, rotation_option: int = 0) → TargetPosition[source]
flatten()[source]
__init__(cube_location: CubeLocation, rotation_option: RotationOption = RotationOption.AbsoluteOptimal) → None
class toio.cube.SpeedChangeType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Speed change type

References

https://toio.github.io/toio-spec/en/docs/ble_motor#motor-speed-change-types

Constant = 0
Acceleration = 1
Deceleration = 2
AccelerationAndDeceleration = 3
class toio.cube.Speed(max: int = 0, speed_change_type: SpeedChangeType = SpeedChangeType.Constant)[source]

Bases: object

Speed parameter

max: int = 0

Max speed

speed_change_type: SpeedChangeType = 0

Speed change type

static from_int(max: int = 0, speed_change_type: int = 0) → Speed[source]
flatten()[source]
__init__(max: int = 0, speed_change_type: SpeedChangeType = SpeedChangeType.Constant) → None
class toio.cube.WriteMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Write mode of MotorControlMultipleTargets()

References

https://toio.github.io/toio-spec/en/docs/ble_motor#additional-write-operation-settings

Overwrite = 0
Append = 1
class toio.cube.AccelerationRotation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Rotational direction when the cube is changing orientation

References

https://toio.github.io/toio-spec/en/docs/ble_motor/#rotational-direction-when-cube-changes-orientation

Positive = 0
Negative = 1
class toio.cube.AccelerationDirection(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Direction of cube travel

References

https://toio.github.io/toio-spec/en/docs/ble_motor/#direction-of-cube-travel

Forward = 0
Backward = 1
class toio.cube.AccelerationPriority(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Priority to the translational speed or the rotational velocity

References

https://toio.github.io/toio-spec/en/docs/ble_motor/#priority-designation

TranslationalVelocity = 0
RotationalVelocity = 1
class toio.cube.MotorResponseCode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Response code of motor control APIs

References

https://toio.github.io/toio-spec/en/docs/ble_motor#response-content

SUCCESS = 0
ERROR_TIMEOUT = 1
ERROR_ID_MISSED = 2
ERROR_INVALID_PARAMETER = 3
ERROR_INVALID_CUBE_STATE = 4
SUCCESS_WITH_OVERWRITE = 5
ERROR_NOT_SUPPORTED = 6
ERROR_FAILED_TO_APPEND = 7
class toio.cube.ResponseMotorControlTarget(payload: bytearray)[source]

Bases: CubeResponse

Target specified motor control response

response_code

Response code

Type:

MotorResponseCode

References

https://toio.github.io/toio-spec/en/docs/ble_motor#responses-to-motor-control-with-target-specified

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.ResponseMotorControlMultipleTargets(payload: bytearray)[source]

Bases: CubeResponse

Multiple target specified motor control response

response_code

Response code

Type:

MotorResponseCode

References

https://toio.github.io/toio-spec/en/docs/ble_motor#responses-to-motor-control-with-multiple-targets-specified

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.ResponseMotorSpeed(payload: bytearray)[source]

Bases: CubeResponse

Motor speed response

left

motor speed (left)

Type:

int

right

motor speed (right)

Type:

int

References

https://toio.github.io/toio-spec/en/docs/ble_motor#obtaining-motor-speed-information

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.Motor(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

Motor characteristic

References

https://toio.github.io/toio-spec/en/docs/ble_motor

static is_my_data(payload: bytearray) → ResponseMotorControlTarget | ResponseMotorControlMultipleTargets | ResponseMotorSpeed | None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any)[source]
async motor_control(left: int, right: int, duration_ms: int | None = None) → None[source]

Send motor control command

Parameters:

  • left (int) – Motor speed (left)

  • right (int) – Motor speed (right)

  • duration_ms (Optional[int], optional) – Motor driving period [ms]. Defaults to None.

References

https://toio.github.io/toio-spec/en/docs/ble_motor#motor-control

async motor_control_target(timeout: int, movement_type: MovementType | int, speed: Speed | Sequence[int], target: TargetPosition | Sequence[int]) → None[source]

Send target specified motor control command

Parameters:

  • timeout (int) – Timeout [s] (Note: not [ms])

  • movement_type (MovementType) – Movement type

  • speed (Speed) – Speed parameter

  • target (TargetPosition) – Target parameter

References

https://toio.github.io/toio-spec/en/docs/ble_motor#motor-control-with-target-specified

async motor_control_multiple_targets(timeout: int, movement_type: MovementType | int, speed: Speed | Sequence[int], mode: WriteMode | int, target_list: Sequence[TargetPosition] | Sequence[Sequence[int]]) → None[source]

Send multiple target specified motor control command

Parameters:

  • timeout (int) – Timeout [s] (Note: not [ms])

  • movement_type (Union[MovementType, int]) – Movement type

  • speed (Union[Speed, Sequence[int]]) – Speed parameter

  • mode (Union[WriteMode, int]) – Write mode

  • target_list (List[Union[TargetPosition, Sequence[int]]]) – Target parameter list

References

https://toio.github.io/toio-spec/en/docs/ble_motor#motor-control-with-multiple-targets-specified

async motor_control_acceleration(translation: int, acceleration: int, rotation_velocity: int, rotation_direction: AccelerationRotation | int, cube_direction: AccelerationDirection | int, priority: AccelerationPriority | int, duration_ms: int) → None[source]

Send acceleration specified motor control command

Parameters:

  • translation (int) – Speed at which the cube moves in relation to the direction of travel.

  • acceleration (int) – Specify the increment (or decrement) in speed every 100 milliseconds.

  • rotation_velocity (int) – Rotational velocity when the cube is changing orientation.

  • rotation_direction (Union[AccelerationRotation, int]) – Rotational direction when the cube is changing orientation.

  • cube_direction (Union[AccelerationDirection, int]) – Direction the cube travels.

  • priority (Union[AccelerationPriority, int]) – Priority to the translational speed or the rotational velocity.

  • duration_ms (int) – Motor driving period [ms].

References

https://toio.github.io/toio-spec/en/docs/ble_motor/#motor-control-with-acceleration-specified

class toio.cube.PostureDataType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Euler = 1
Quaternions = 2
HighPrecisionEuler = 3
class toio.cube.Posture(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Orientation of the cube.

Reference:

https://toio.github.io/toio-spec/en/docs/ble_sensor/#posture-detection

Unknown = 0
Top = 1
Bottom = 2
Rear = 3
Front = 4
Right = 5
Left = 6
class toio.cube.MotionDetectionData(payload: bytearray)[source]

Bases: CubeResponse

Information on the cube’s motion detection.

horizontal

Horizontal detection

Type:

bool

collision

Collision detection

Type:

bool

double_tap

Double-tap detection

Type:

bool

posture

Posture detection

Type:

Posture

shake

Shake detection (0:no shake, 1:Level1 - 10:Level10)

Type:

int

Reference:

https://toio.github.io/toio-spec/en/docs/ble_sensor/#obtaining-motion-detection-information

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.PostureAngleEulerData(payload: bytearray)[source]

Bases: CubeResponse

Information of posture angle (Euler angle)

roll

Roll (X axis)

Type:

int

pitch

Pitch (Y axis)

Type:

int

yaw

Yaw (Z axis)

Type:

int

References

https://toio.github.io/toio-spec/en/docs/ble_high_precision_tilt_sensor#obtaining-posture-angle-information-notifications-in-euler-angles

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.PostureAngleQuaternionsData(payload: bytearray)[source]

Bases: CubeResponse

PostureAngleQuaternionData

Information of posture angle (Quaternion)

w
Type:

float

x
Type:

float

y
Type:

float

z
Type:

float

References

https://toio.github.io/toio-spec/en/docs/ble_high_precision_tilt_sensor#obtaining-posture-angle-information-notifications-in-quaternions

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
__str__() → str[source]

Return str(self).

class toio.cube.MagneticSensorData(payload: bytearray)[source]

Bases: CubeResponse

Information of magnetic sensor

state

Magnet state

Type:

int

strength

Magnetic force strength

Type:

int

x

Magnetic force direction (X axis)

Type:

int

y

Magnetic force direction (Y axis)

Type:

int

z

Magnetic force direction (Z axis)

Type:

int

References

https://toio.github.io/toio-spec/en/docs/ble_magnetic_sensor/#obtaining-magnetic-sensor-information-

static is_myself(payload: bytearray) → bool[source]

If argument data is a byte representation of this class, this function converts the byte representation to an object and returns it.

Parameters:

data (GattReadData) – received data from the cube.

__init__(payload: bytearray)[source]
class toio.cube.Sensor(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

Sensor information characteristic

References

Motion detection

Posture angle detection

Magnetic sensor

static is_my_data(payload: bytearray) → MotionDetectionData | PostureAngleEulerData | PostureAngleQuaternionsData | PostureAngleHighPrecisionEulerData | MagneticSensorData | None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any)[source]
async read() → MotionDetectionData | PostureAngleEulerData | PostureAngleQuaternionsData | PostureAngleHighPrecisionEulerData | MagneticSensorData | None[source]

Read sensor information response

Returns:

One of SensorInformationData or None (None returns when read fails)

async request_motion_information() → None[source]

Send motion information request command

async request_posture_angle_information(data_type: PostureDataType) → None[source]

Send posture angle information request command

async request_magnetic_sensor_information() → None[source]

Send magnetic sensor information request

class toio.cube.SoundId(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Sound effect ID

References

https://toio.github.io/toio-spec/en/docs/ble_sound#sound-effect-id

Enter = 0
Selected = 1
Cancel = 2
Cursor = 3
MatIn = 4
MatOut = 5
Get1 = 6
Get2 = 7
Get3 = 8
Effect1 = 9
Effect2 = 10
class toio.cube.Note(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Midi notes

References

https://toio.github.io/toio-spec/en/docs/ble_sound#midi-note-number-and-note-name

C0 = 0
CS0 = 1
D0 = 2
DS0 = 3
E0 = 4
F0 = 5
FS0 = 6
G0 = 7
GS0 = 8
A0 = 9
AS0 = 10
B0 = 11
C1 = 12
CS1 = 13
D1 = 14
DS1 = 15
E1 = 16
F1 = 17
FS1 = 18
G1 = 19
GS1 = 20
A1 = 21
AS1 = 22
B1 = 23
C2 = 24
CS2 = 25
D2 = 26
DS2 = 27
E2 = 28
F2 = 29
FS2 = 30
G2 = 31
GS2 = 32
A2 = 33
AS2 = 34
B2 = 35
C3 = 36
CS3 = 37
D3 = 38
DS3 = 39
E3 = 40
F3 = 41
FS3 = 42
G3 = 43
GS3 = 44
A3 = 45
AS3 = 46
B3 = 47
C4 = 48
CS4 = 49
D4 = 50
DS4 = 51
E4 = 52
F4 = 53
FS4 = 54
G4 = 55
GS4 = 56
A4 = 57
AS4 = 58
B4 = 59
C5 = 60
CS5 = 61
D5 = 62
DS5 = 63
E5 = 64
F5 = 65
FS5 = 66
G5 = 67
GS5 = 68
A5 = 69
AS5 = 70
B5 = 71
C6 = 72
CS6 = 73
D6 = 74
DS6 = 75
E6 = 76
F6 = 77
FS6 = 78
G6 = 79
GS6 = 80
A6 = 81
AS6 = 82
B6 = 83
C7 = 84
CS7 = 85
D7 = 86
DS7 = 87
E7 = 88
F7 = 89
FS7 = 90
G7 = 91
GS7 = 92
A7 = 93
AS7 = 94
B7 = 95
C8 = 96
CS8 = 97
D8 = 98
DS8 = 99
E8 = 100
F8 = 101
FS8 = 102
G8 = 103
GS8 = 104
A8 = 105
AS8 = 106
B8 = 107
C9 = 108
CS9 = 109
D9 = 110
DS9 = 111
E9 = 112
F9 = 113
FS9 = 114
G9 = 115
GS9 = 116
A9 = 117
AS9 = 118
B9 = 119
C10 = 120
CS10 = 121
D10 = 122
DS10 = 123
E10 = 124
F10 = 125
FS10 = 126
G10 = 127
NO_SOUND = 128
class toio.cube.MidiNote(duration_ms: int, note: Note, volume: int)[source]

Bases: object

Midi note

duration_ms: int
Duration of sounding note:
Any fraction less than 10ms will be truncated.
0 - 9: zero
10 - 2550: duration [ms]
note: Note

Midi note

volume: int
Volume:
0: off
1 - 255: max volume
flatten()[source]
__init__(duration_ms: int, note: Note, volume: int) → None
class toio.cube.Sound(interface: CubeInterface, device: Any)[source]

Bases: CubeCharacteristic

Sound characteristic

References

https://toio.github.io/toio-spec/en/docs/ble_sound

static is_my_data(_payload: bytearray) → None[source]

If payload is my characteristic response, this function returns CubeResponse object. Otherwise, it returns None.

Parameters:

payload (GattReadData) – received data from the cube.

__init__(interface: CubeInterface, device: Any)[source]
async play_sound_effect(sound_id: SoundId, volume: int)[source]

Send play sound effect command

Parameters:

  • sound_id (SoundId) – Sound ID

  • volume (int) – Volume

async play_midi(repeat: int, midi_notes: List[MidiNote] | Tuple[MidiNote, ...])[source]

Send play midi note command

Parameters:

  • repeat (int) – Number of repetitions (0: Infinite)

  • midi_notes (Union[List[MidiNote], Tuple[MidiNote, ...]]) – List of midi notes

async stop()[source]

Send sound stop command