SimpleCube API

API for easy access to the toio Core Cube

Simple
No asynchronous processing
No cube scanning required
Functions with almost the same functionality as Visual Programming blocks

Example

Motor control

import sys

from toio.simple import SimpleCube


def test():
    with SimpleCube() as cube:
        cube.move(30, 3)
        cube.spin(60, 2)
        cube.run_motor(70, 10, 1)
        cube.run_motor(10, 70, 1)
        cube.run_motor(-20, -20, 0)
        cube.sleep(0.5)
        cube.stop_motor()

if __name__ == "__main__":
    sys.exit(test())

Motor control (Move to the specified position)

import sys

from toio.simple import SimpleCube


def test():
    targets = ((30, 30), (30, -30), (-30, -30), (-30, 30), (30, 30))
    with SimpleCube() as cube:
        for target in targets:
            target_pos_x, target_pos_y = target
            print(f"move to ({target_pos_x}, {target_pos_y})")
            success = cube.move_to(speed=70, x=target_pos_x, y=target_pos_y)
            print(f"arrival: {success}")
            if not success:
                print("Position ID missed")
                break
            cube.sleep(0.5)


if __name__ == "__main__":
    sys.exit(test())

Location reading

import signal
import sys

from toio.simple import SimpleCube

LOOP = True


def ctrl_c_handler(_signum, _frame):
    global LOOP
    print("Ctrl-C")
    LOOP = False


signal.signal(signal.SIGINT, ctrl_c_handler)


def test():
    with SimpleCube() as cube:
        while LOOP:
            pos = cube.get_current_position()
            orientation = cube.get_orientation()
            print("POSITION:", pos, orientation)
            cube.sleep(0.5)


if __name__ == "__main__":
    sys.exit(test())

Other sample code

Additional sample code can be found in the examples-simple directory.

API List

    # connect and disconnect
    SimpleCube(name: Optional[str] = None, timeout:int = 5, log_level: int = NOTSET) -> None:
    disconnect():

    # Motor control and movement
    move(speed: int, duration: float) -> None:
    spin(speed: int, duration: float) -> None:
    run_motor(left_speed: int, right_speed: int, duration: float,) -> None:
    stop_motor() -> None:
    move_steps(direction: Direction, speed: int, step: int) -> bool:
    turn(speed: int, degree: int) -> bool:
    move_to(speed: int, x: int, y: int) -> bool:
    set_orientation(speed: int, degree: int) -> bool:
    move_to_the_grid_cell(speed: int, cell_x: int, cell_y: int) -> bool:

    # Get position information
    get_current_position() -> Optional[tuple[int, int]]:
    get_x() -> Optional[int]:
    get_y() -> Optional[int]:
    get_orientation() -> Optional[int]:
    get_grid() -> Optional[tuple[int, int]]:
    get_grid_x() -> Optional[int]:
    get_grid_y() -> Optional[int]:
    is_on_the_gird_cell(cell_x: int, cell_y: int) -> bool:

    # Get card information
    is_touched(item: StandardIdType) -> bool:
    get_touched_card() -> Optional[StandardId]:

    # Get other information
    get_cube_name() -> Optional[str]:
    get_battery_level() -> Optional[int]:
    get_3d_angle() -> Optional[tuple[int, int, int]]:
    get_posture() -> Optional[int]:
    is_button_pressed() -> Optional[int]:

    # Lamp control
    turn_on_cube_lamp(r: int, g: int, b: int, duration: float) -> None:
    turn_off_cube_lamp() -> None:

    # sound control
    play_sound(note: int, duration: float) -> bool:
    stop_sound() -> None:

    # detect a magnet
    is_magnet_in_contact() -> Optional[int]:

    # wait for time
    sleep(sleep_second: float):

API description

Connect and disconnect

`SimpleCube(name: Optional[str] = None, timeout:int = 5, log_level: int = NOTSET) -> None:`

Create a SimpleCube object. When you create a SimpleCube instance, the cube is searched for and connected.

Arguments	Description
name	unique 3-digit ID of the cube to connect
timeout	scan timeout in seconds
log_level	log level

Examples of use

This sample code performs the following actions.

Connect to a nearby cube
Advance the Cube at speed 50 for 1 second
Disconnect

cube = SimpleCube()
cube.move(50, 1)
cube.disconnect()

SimpleCube() can use with statements because it is a context manager. When exiting the with block, disconnect() is automatically called. The preceding code can be written as follows by using the with statement.

with SimpleCube() as cube:
  cube.move(50, 1)

If disconnect() is not called and the program exits while still connected to the Cube, it may not be possible to connect in subsequent program executions. To ensure a reliable disconnect, it is recommended to use SimpleCube() with the with statement.

Cubes to be connected

If SimpleCube() does not have the argument name, SimpleCube() looks for a surrounding cube and tries to connect to the cube with the best signal reach. If no cube is found in the vicinity, a ValueError exception is thrown.

If the argument name is a string with a unique 3-digit ID, it tries to connect to the specified cube. If the given cube is not found, a ValueError exception is thrown.

Special note on Windows

Windows can register cubes with the OS as Bluetooth devices.
The registered cube has priority as the connection target.

When running on Windows, the target cube for connection is determined in the following order.

Connection order in Window: with name specified.

a cube registered in the OS with a matching name
if not found, the cube that was actually scanned and the name matches

Connection order in Window: without name specified.

the cube registered in the OS that has the best radio reception
if not found, actually scan the cube with the best radio reception

`disconnect()`

Disconnect from the cube.

If disconnect() is not called and the program exits while still connected to the Cube, it may not be possible to connect in subsequent program executions. Make sure to disconnect at the end of the program.

Motor control and movement

`move(speed: int, duration: float) -> None:`

Move the cube.

Arguments	Description	Possible values
speed	motor speed	-100 <= speed <= 100
duration	running time (sec)	0 <= duration <= 2.55

A positive value for speed will move forward. Negative values cause backward motion.

If duration is set to a value greater than 2.55, it is treated as 2.55. If duration is set to 0, it is "no time limit". In this case, move() does not wait for completion, but returns immediately after communicating with the cube.

`spin(speed: int, duration: float) -> None:`

Rotate the cube in place.

Arguments	Description	Possible values
speed	motor speed	-100 <= speed <= 100
duration	running time (sec)	0 <= duration <= 2.55

A positive value for speed causes counterclockwise rotation, a negative value causes clockwise rotation.

If duration is set to a value greater than 2.55, it is treated as 2.55. If duration is set to 0, it is "no time limit". In this case, move() does not wait for completion, but returns immediately after communicating with the cube.

`run_motor(left_speed: int, right_speed: int, duration: float,) -> None:`

The cube's motors run at separate speeds for the left and right side of the cube.

Arguments	Description	Possible values
left_speed	motor speed (left)	100 <= left_speed <= 100
right_speed	motor speed (right)	100 <= right_speed <= 100
duration	running time (sec)	0 <= duration <= 2.55

Positive values for left_speed and right_speed will rotate forward, and negative values will rotate backward, respectively.

If duration is set to a value greater than 2.55, it is treated as 2.55. If duration is set to 0, it is "no time limit". In this case, move() does not wait for completion, but returns immediately after communicating with the cube.