SimpleCube API

簡単に toio コアキューブにアクセスするための API

シンプル
非同期処理なし
キューブのスキャンが不要
Visual Programming のブロックとほぼ同じ機能を持った関数

例

モーター制御

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())

モーター制御（指定位置まで移動）

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())

位置情報の読み取り

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())

その他のサンプルコード

その他のサンプルコードは、examples-simple ディレクトリにあります。

API 一覧

    # 接続と切断
    SimpleCube(name: Optional[str] = None, timeout:int = 5, log_level: int = NOTSET) -> None:
    disconnect():

    # モーター制御と移動
    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_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:

    # カード情報の取得
    is_touched(item: StandardIdType) -> bool:
    get_touched_card() -> Optional[StandardId]:

    # その他の情報の取得
    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]:

    # ランプ制御
    turn_on_cube_lamp(r: int, g: int, b: int, duration: float) -> None:
    turn_off_cube_lamp() -> None:

    # 音制御
    play_sound(note: int, duration: float) -> bool:
    stop_sound() -> None:

    # 磁石の検出
    is_magnet_in_contact() -> Optional[int]:

    # 時間待ち
    sleep(sleep_second: float):

API 説明

接続と切断

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

SimpleCubeオブジェクトを生成します。生成時にキューブを検索して接続します。

引数	説明
name	接続するキューブの固有 3 桁 ID
timeout	スキャンのタイムアウト時間（秒）
log_level	ログレベル

使用例

下記のコードは

近くのキューブに接続
キューブを１秒間、速度 50 で前進
切断

を行います。

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

SimpleCube() はコンテキストマネージャなので、with 文を使うことができます。 with ブロックを抜ける際には自動的にdisconnect()が呼ばれます。さきほどのコードは、with文を使うことにより下記のように書けます。

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

disconnect()が呼ばれず、Cube と接続したままの状態でプログラムが終了した場合には後のプログラム実行でキューブと接続できないことがあります。確実に切断するため、SimpleCube()はwith文での使用を推奨します。

接続対象となるキューブについて

SimpleCube() が引数 name を持たない場合、SimpleCube() は周囲のキューブを探し、電波が一番届きやすいキューブへ接続を試みます。周囲にキューブが見つからない場合はValueError例外が発生します。

引数 name に固有 3 桁 ID の文字列が指定されている場合、指定されたキューブへの接続を試みます。指定されたキューブが見つからない場合はValueError例外が発生します。

Windows に関する特記事項

Windows は Bluetooth 機器として OS にキューブを登録できます。
登録されているキューブが接続対象として優先されます。

Windows で動作している場合、接続対象キューブは下記の順番で決まります。

Window での接続順番：name指定ありの場合

OS に登録されているキューブでnameが一致しているもの
見つからなかった場合は、実際にスキャンを行いnameが一致したもの

Window での接続順番：name指定なしの場合

OS に登録されているキューブのうち電波が一番届きやすいもの
見つからなかった場合は、実際にスキャンを行い電波が一番届きやすいもの

`disconnect()`

キューブとの接続を解除します。

disconnect()が呼ばれず、Cube と接続したままの状態でプログラムが終了した場合には次の実行で接続に失敗することがあります。プログラム終了時には確実に切断してください。

モーター制御と移動

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

キューブを動かします。

引数	説明	指定可能な値
speed	モーターの速度	-100 <= speed <= 100
duration	動作時間（秒）	0 <= duration <= 2.55

speed に正の値を指定すると前進します。負の値を指定すると後進します。

duration に 2.55 より大きい値を設定した場合は 2.55 として扱われます。
duration に 0 を指定した場合は「制限時間なし」となります。このとき move()は完了を待たず、キューブと通信を行ったあとすぐにリターンします。

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

キューブをその場で回転させます。

引数	説明	指定可能な値
speed	モーターの速度	-100 <= speed <= 100
duration	動作時間（秒）	0 <= duration <= 2.55

speed に正の値を指定すると反時計回りに、負の値を指定すると時計回りに回転します。

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

キューブのモーターを左右別々の速度で動かします。

引数	説明	指定可能な値
left_speed	モーターの速度（左）	100 <= left_speed <= 100
right_speed	モーターの速度（右）	100 <= right_speed <= 100
duration	動作時間（秒）	0 <= duration <= 2.55

left_speed, right_speed はそれぞれ正の値を指定すると前進方向に、負の値を指定すると後進方向に回転します。