技術ドキュメント - 使い方 - Cubeクラス

目次

1. 概説

Cube クラスは、toio™コア キューブ (以降、キューブ) を操作するための機能が実装されています。
このクラスは、異なる環境向けの実装切り替えが出来るマルチプラットフォーム対応クラスとなっており、 Unity システム上で動くキューブ(以下シミュレータ) と 現実のキューブ の 2 つの実行環境に対応しています。

シミュレータについてはコチラのページをご参照下さい。

現実のキューブでは、toio™コア キューブ技術仕様(通信仕様)に沿って Unity プログラムから Bluetooth 通信を行う事で、現実のキューブを操作します。

Real/Sim 機能表

現在(2024/05/20)、キューブのBLE プロトコルバージョンは 5 つです。

2.0.0　2.1.0　2.2.0　2.3.0　2.4.0

toio SDK for Unity では、現実に動作するキューブクラス(Real 対応)、シミュレータで動作するキューブクラス(Sim 対応)の 2 つの内部実装が用意されています。それぞれ内部実装が異なっているため、対応状況に違いがあります。
以下に実装対応表を示します。

BLE プロトコルバージョン 2.0.0

機能タイプ 機能 Real 対応状況 Sim 対応状況
読み取りセンサー Position ID o o
  Standard ID o o
モーションセンサー 水平検出 o o
  衝突検出 o ※
ボタン ボタンの状態 o o
バッテリー バッテリー残量 o x
モーター モーター制御 x x
  時間指定付きモーター制御 o o
ランプ 点灯・消灯 o o
  連続的な点灯・消灯 o o
  全てのランプを消灯 x x
  特定のランプを消灯 x x
サウンド 効果音の再生 o o
  MIDI note number の再生 o o
  再生の停止 o o
設定 BLE プロトコルバージョンの要求 o x
  水平検出のしきい値設定 o o
  衝突検出のしきい値設定 o x
  BLE プロトコルバージョンの取得 o x

※ … シミュレータ側に検出機能は実装されていませんが、インスペクター上から手動で判定の有無を切り替えることが出来ます。 詳細は【コチラ】をご確認ください。

BLE プロトコルバージョン 2.1.0

機能タイプ 機能 Real 対応状況 Sim 対応状況
モーションセンサー ダブルタップ検出 o ※
  姿勢検出 o o
モーター モーター制御（指示値範囲変更） o o
  目標指定付きモーター制御 o o
  複数目標指定付きモーター制御 x x
  加速度指定付きモーター制御 o o
  目標指定付きモーター制御の応答 o o
  複数目標指定付きモーター制御の応答 x x
設定 ダブルタップ検出の時間間隔の設定 o x

BLE プロトコルバージョン 2.2.0

機能タイプ 機能 Real 対応状況 Sim 対応状況
モーションセンサー モーションセンサー情報の要求 o o
  シェイク検出 o o
磁気センサー 磁気センサー情報の要求 o o
  磁石の状態 o o
モーター モーターの速度情報の取得 o o
設定 読み取りセンサーの ID 通知設定 o o
  読み取りセンサーの ID missed 通知設定 o o
  読み取りセンサーの ID 通知設定の応答 o o
  読み取りセンサーの ID missed 通知設定の応答 o o
  磁気センサーの設定 o o
  磁気センサーの設定の応答 o o
  モーターの速度情報の取得の設定 o o
  モーターの速度情報の取得の設定の応答 o o

BLE プロトコルバージョン 2.3.0

機能タイプ 機能 Real 対応状況 Sim 対応状況
磁気センサー 磁力の検出 o o
姿勢角検出 姿勢角検出の要求 o o
  姿勢角情報の取得（オイラー角での通知） o o
シリアライズ情報 シリアライズ情報 x x
設定 磁気センサーの設定 (updated) o o
  姿勢角検出の設定 o o
  姿勢角検出の設定の応答 o o

BLE プロトコルバージョン 2.4.0

機能タイプ 機能 Real 対応状況 Sim 対応状況
姿勢角検出 姿勢角検出の要求 (updated) o o
  姿勢角情報の取得（クォータニオンでの通知） o o
  姿勢角情報の取得（高精度オイラー角での通知） o o
設定 姿勢角検出の設定 (updated) o o
  コネクションインターバル変更要求 o x
  コネクションインターバル要求値の取得 o x
  現在のコネクションインターバル値の取得 o x
  コネクションインターバル変更要求の応 o x
  コネクションインターバル要求値の取得の応答 o x
  現在のコネクションインターバル値の取得の応答 o x


2. 既存 toio™ ライブラリ(toio.js)との比較

toio.jsは、javascript で書かれた既存の toio ライブラリです。
このライブラリは node.js で作られており、PC 環境で動作します。
scanner、cube の 2 つをクラスを利用してキューブを操作します。

以下に toio.js のサンプルコードを示します。

const { NearestScanner } = require("@toio/scanner");

async function main() {
  // start a scanner to find the nearest cube
  const cube = await new NearestScanner().start();

  // connect to the cube
  await cube.connect();

  // move cube
  cube.move(100, 100, 1000);
  //         |    |     `--- duration [ms]
  //         |    `--------- right motor speed
  //          `------------- left motor speed
}

main();

toio SDK for Unity は toio.js ユーザーでも使いやすいプログラムを目指し、 scanner、cube の 2 つのクラスを使用してキューブを操作する仕組みにしました。

以下に、同じ挙動をする本プログラムのサンプルコードを示します。

public class SimpleScene : MonoBehaviour
{
    async void Start()
    {
        // start a scanner to find the nearest cube
        var peripheral = await new CubeScanner().NearestScan();

        // connect to the cube
        var cube = await new CubeConnecter().Connect(peripheral);

        // move cube
        cube.Move(100, 100, 1000);
        //         |    |     `-- duration [ms]
        //         |    `-------- right motor speed
        //          `------------ left motor speed
    }
}


3. Cube クラス API

3.1. 変数

// 接続したキューブのBLE プロトコルバージョン
public string version { get; }

// キューブの固有識別ID
// シミュレータ環境では Cube ゲームオブジェクトの InstanceID が ID になります
public string id { get; protected set; }

// キューブのアドレス
public string addr { get; }

// Complete Local Name
public string localName { get; }

// キューブの接続状態
public bool isConnected { get; }

// キューブのバッテリー状態
public int battery { get; protected set; }

// マット上のキューブのX座標
// キューブの中心位置を基準とした座標となっています。
// マットの上にいる間、自動更新されます。
// コールバック機能：standardIdCallback
public int x { get; protected set; }

// マット上のキューブのY座標
// キューブの中心位置を基準とした座標となっています。
// マットの上にいる間、自動更新されます。
// コールバック機能：standardIdCallback
public int y { get; protected set; }

// マット上のキューブのXY座標
// キューブの中心位置を基準とした座標となっています。
// マットの上にいる間、自動更新されます。
// コールバック機能：standardIdCallback
public Vector2 pos { get; }

// マット上のキューブの角度
// キューブの中心位置を基準とした角度になっています。
// マットの上にいる間、自動更新されます。
// コールバック機能：standardIdCallback
public int angle { get; protected set; }

// マット上のキューブのXY座標
// キューブの光学センサー位置を基準とした座標になっています。
// マットの上にいる間、自動更新されます。
// コールバック機能：standardIdCallback
public Vector2 sensorPos { get; }

// マット上のキューブの角度
// キューブの光学センサー位置を基準とした角度になっています。
// マットの上にいる間、自動更新されます。
// コールバック機能：standardIdCallback
public int sensorAngle { get; protected set; }

// 読み取り可能な特殊ステッカーのID
// キューブの光学センサーから取得したIDとなっています。
// コールバック機能：standardIdCallback
public uint standardId { get; protected set; }

// キューブのボタン押下状態の変数
// コールバック機能：buttonCallback
public bool isPressed { get; protected set; }

// キューブの傾き状態の変数
// コールバック機能：slopeCallback
public bool isSloped { get; protected set; }

// キューブの衝突状態の変数
// 内部実装は継承クラスによって大きく異なる可能性があります。
// コールバック機能：collisionCallback
public bool isCollisionDetected { get; protected set; }

// キューブがマット上にいるか判定する変数
public bool isGrounded { get; protected set; }

// キューブの最高速度を表す変数
// BLE プロトコルバージョン毎に異なるため用意されています。
public int maxSpd { get; }

// キューブの最低速度を表す変数
// BLE プロトコルバージョン毎に異なるため用意されています。
public int deadzone { get; }

// ver2.1.0
// キューブのダブルタップ状態
// 一度タップされてから一定時間内に再度タップされます。
// コールバック機能：doubleTapCallback
public bool isDoubleTap { get; protected set; }

// キューブの姿勢
// キューブの水平面に対する姿勢が変化したときに値が変わります。
// コールバック機能：poseCallback
public PoseType pose { get; protected set; }

// ver2.2.0
// キューブのシェイク状態
// キューブを振ると振った強さに応じて値が変わります。
// コールバック機能：shakeCallback
public int shakeLevel { get; protected set; }

// キューブのモーター ID 1（左）の速度
// コールバック機能：motorSpeedCallback
public int leftSpeed { get; protected set; }

// キューブのモーター ID 2（右）の速度
// コールバック機能：motorSpeedCallback
public int rightSpeed { get; protected set; }

// コアキューブの磁石状態
// コールバック機能：magnetStateCallback
public MagnetState magnetState { get; protected set; }

// ver2.3.0
// コアキューブの磁力
// コールバック機能：magneticForceCallback
public Vector3 magneticForce { get; protected set; }

// コアキューブのオイラー
// コールバック機能：attitudeCallback
public Vector3 eulers { get; protected set; }

// コアキューブのクォータニオン
// コールバック機能：attitudeCallback
// 仕様書に規定された座標系は Unity と違いますので、ご注意ください。
public Quaternion quaternion { get; protected set; }

// ver2.4.0
// コネクションインターバル要求値
// コールバック機能：connectionIntervalConfigCallback
public virtual int connectionIntervalMin { get; protected set; }
public virtual int connectionIntervalMax { get; protected set; }
// 現在のコネクションインターバル値
// コールバック機能：connectionIntervalCallback
public virtual int connectionInterval { get; protected set; }


3.2. コールバック

// CallbackProvider<T1>
// CallbackProvider<T1, T2>
// CallbackProvider<T1, T2, T3>
// CallbackProvider<T1, T2, T3, T4>
// ※疑似コード
public class CallbackProvider<T...>
{
    public virtual void AddListener(string key, Action<T...> listener);
    public virtual void RemoveListener(string key);
    public virtual void ClearListener();
    public virtual void Notify(T... args);
}

// ボタンコールバック
public CallbackProvider<Cube> buttonCallback { get; }
// 傾きコールバック
public CallbackProvider<Cube> slopeCallback { get; }
// 衝突コールバック
public CallbackProvider<Cube> collisionCallback { get; }
// 座標角度コールバック
public CallbackProvider<Cube> idCallback { get; }
// 座標角度 Missed コールバック
public CallbackProvider<Cube> idMissedCallback { get; }
// StandardID コールバック
public CallbackProvider<Cube> standardIdCallback { get; }
// StandardID Missed コールバック
public CallbackProvider<Cube> standardIdMissedCallback { get; }

// ver2.1.0
// ダブルタップコールバック
public CallbackProvider<Cube> doubleTapCallback { get; }
// 姿勢検出コールバック
public CallbackProvider<Cube> poseCallback { get; }
// 目標指定付きモーター制御の応答コールバック
public CallbackProvider<Cube, int, TargetMoveRespondType> targetMoveCallback { get; }

// ver2.2.0
// シェイクコールバック
public CallbackProvider<Cube> shakeCallback { get; }
// モータースピードコールバック
public CallbackProvider<Cube> motorSpeedCallback { get; }
// 磁石状態コールバック
public CallbackProvider<Cube> magnetStateCallback { get; }

// ver2.3.0
// 磁力検出コールバック
public CallbackProvider<Cube> magneticForceCallback { get; }
// 姿勢角検出コールバック
public CallbackProvider<Cube> attitudeCallback { get; }

3.3. メソッド

Move

public void Move(int left, int right, int durationMs, ORDER_TYPE order=ORDER_TYPE.Weak);

キューブのモーターを制御します。
toio™コア キューブ 技術仕様（通信仕様）


TurnLedOn

public void TurnLedOn(int red, int green, int blue, int durationMs, ORDER_TYPE order=ORDER_TYPE.Strong);

キューブ底面についている LED を制御します。
toio™コア キューブ 技術仕様（通信仕様）


TurnOnLightWithScenario

// 発光ごとの設定構造体
public struct LightOperation
{
    public int durationMs; // ミリ秒
    public byte red;         // 赤色の強さ
    public byte green;       // 緑色の強さ
    public byte blue;        // 青色の強さ
}
public void TurnOnLightWithScenario(int repeatCount, Cube.LightOperation[] operations, ORDER_TYPE order=ORDER_TYPE.Strong);

キューブ底面についている LED を連続的に制御します。
toio™コア キューブ 技術仕様（通信仕様）


TurnLedOff

public void TurnLedOff(ORDER_TYPE order=ORDER_TYPE.Strong);

キューブ底面についている LED を消灯させます。
toio™コア キューブ 技術仕様（通信仕様）


PlayPresetSound

public void PlayPresetSound(int soundId, int volume=255, ORDER_TYPE order=ORDER_TYPE.Strong);

キューブ内に用意されている効果音を再生します。
toio™コア キューブ 技術仕様（通信仕様）


PlaySound

キューブから任意の音を再生します。
toio™コア キューブ 技術仕様（通信仕様）

// 引数版
// 発音ごとの設定構造体
public struct SoundOperation
{
    public int durationMs; // ミリ秒
    public byte volume;      // 音量(0~255)
    public byte note_number; // 音符(0~128)
}
public void PlaySound(int repeatCount, SoundOperation[] operations, ORDER_TYPE order=ORDER_TYPE.Strong);

// バッファ版
public void PlaySound(byte[] buff, ORDER_TYPE order=ORDER_TYPE.Strong);


StopSound

public void StopSound(ORDER_TYPE order=ORDER_TYPE.Strong);

キューブの音再生を停止します。
toio™コア キューブ 技術仕様（通信仕様）


ConfigSlopeThreshold

public void ConfigSlopeThreshold(int angle, ORDER_TYPE order=ORDER_TYPE.Strong);

キューブの水平検出のしきい値を設定します。
toio™コア キューブ 技術仕様（通信仕様）


ConfigCollisionThreshold

public void ConfigCollisionThreshold(int level, ORDER_TYPE order=ORDER_TYPE.Strong);

キューブの衝突検出のしきい値を設定します。
toio™コア キューブ 技術仕様（通信仕様）


ConfigDoubleTapInterval

public void ConfigDoubleTapInterval(int interval, ORDER_TYPE order=ORDER_TYPE.Strong);

キューブのダブルタップ検出の時間間隔を設定します
toio™コア キューブ 技術仕様（通信仕様）


TargetMove

public void TargetMove(
            int targetX,
            int targetY,
            int targetAngle,
            byte configID = 0,
            byte timeOut = 0,
            TargetMoveType targetMoveType = TargetMoveType.RotatingMove,
            byte maxSpd = 80,
            TargetSpeedType targetSpeedType = TargetSpeedType.UniformSpeed,
            TargetRotationType targetRotationType = TargetRotationType.AbsoluteLeastAngle,
            ORDER_TYPE order = ORDER_TYPE.Strong);

キューブのモーターを目標指定付き制御します。
toio™コア キューブ 技術仕様（通信仕様）


AccelerationMove

public void AccelerationMove(
            int targetSpeed,
            int acceleration,
            ushort rotationSpeed = 0,
            AccPriorityType accPriorityType = AccPriorityType.Translation,
            byte controlTime = 0,
            ORDER_TYPE order = ORDER_TYPE.Strong);

キューブの加速度指定付きモーター制御を実行します。
toio™コア キューブ 技術仕様（通信仕様）


ConfigMotorRead

public UniTask ConfigMotorRead(bool valid, float timeOutSec=0.5f, Action<bool,Cube> callback=null, ORDER_TYPE order=ORDER_TYPE.Strong);

キューブのモーター速度情報の取得の有効化・無効化を設定します。
toio™コア キューブ 技術仕様（通信仕様）


RequestSensor

非推奨になりました。 RequestMotionSensor を使ってください。


RequestMotionSensor

public void RequestMotionSensor(ORDER_TYPE order = ORDER_TYPE.Strong);

キューブにモーションセンサー情報の通知を一回要求します。
toio™コア キューブ 技術仕様（通信仕様）

※ 衝突検出とダブルタップ検出は、発生時のみ通知されるため、変数 Cube.isCollisionDetected Cube.isDoubleTap は他のモーションセンサーによって通知が来ない限り、 True 状態から False に戻るのが不可能です。そのため、RequestMotionSensor を利用して通知を求めることで、この２つの変数を更新させることが可能です。


ConfigIDNotification

public UniTask ConfigIDNotification(
    int intervalMs,
    IDNotificationType notificationType = IDNotificationType.Balanced,
    float timeOutSec = 0.5f,
    Action<bool,Cube> callback = null,
    ORDER_TYPE order = ORDER_TYPE.Strong);

読み取りセンサーの Position ID および Standard ID の通知頻度を設定します。 「最小通知間隔」と「通知条件」の両方を満たした場合に通知が行われます。
toio™コア キューブ 技術仕様（通信仕様）


ConfigIDMissedNotification

public UniTask ConfigIDMissedNotification(
    int sensitivityMs,
    float timeOutSec = 0.5f,
    Action<bool,Cube> callback = null,
    ORDER_TYPE order = ORDER_TYPE.Strong);

読み取りセンサーの Position ID missed および Standard ID missed の通知感度を設定します。
toio™コア キューブ 技術仕様（通信仕様）


ConfigMagneticSensor

public UniTask ConfigMagneticSensor(
    MagneticMode mode,
    float timeOutSec = 0.5f,
    Action<bool,Cube> callback = null,
    ORDER_TYPE order = ORDER_TYPE.Strong);

キューブの磁気センサーの機能のモードを設定します。デフォルトでは無効化されています。(v2.2.0から対応)
toio™コア キューブ 技術仕様（通信仕様）

public UniTask ConfigMagneticSensor(
    MagneticMode mode,
    int intervalMs,
    MagneticNotificationType notificationType,
    float timeOutSec = 0.5f,
    Action<bool,Cube> callback = null,
    ORDER_TYPE order = ORDER_TYPE.Strong);

キューブの磁気センサーの機能のモードを設定します。デフォルトでは無効化されています。(v2.3.0から対応)
toio™コア キューブ 技術仕様（通信仕様）


ConfigAttitudeSensor

public UniTask ConfigAttitudeSensor(
    AttitudeFormat format,
    int intervalMs,
    AttitudeNotificationType notificationType,
    float timeOutSec = 0.5f,
    Action<bool,Cube> callback = null,
    ORDER_TYPE order = ORDER_TYPE.Strong);

キューブの姿勢角検出機能の有効化・無効化を設定します。デフォルトでは無効化されています。(v2.3.0から対応)
toio™コア キューブ 技術仕様（通信仕様）


RequestMagneticSensor

public void RequestMagneticSensor(ORDER_TYPE order = ORDER_TYPE.Strong);

キューブに磁気センサー情報の通知を一回要求します。
toio™コア キューブ 技術仕様（通信仕様）


RequestAttitudeSensor

public void RequestAttitudeSensor(AttitudeFormat format, ORDER_TYPE order = ORDER_TYPE.Strong);

キューブに指定種類の姿勢角検出情報の通知を一回要求します。
toio™コア キューブ 技術仕様（通信仕様）


ConfigConnectionInterval

public virtual UniTask ConfigConnectionInterval(
  int min,
  int max,
  float timeOutSec = 0.5f,
  Action<bool,Cube> callback = null,
  ORDER_TYPE order = ORDER_TYPE.Strong);

コネクションインターバル変更要求。0xFFFF（要求なし）または 6 ~ 3200 の間の値が指定できます。(v2.4.0から対応)
toio™コア キューブ 技術仕様（通信仕様）


ObtainConnectionIntervalConfig

public void ObtainConnectionIntervalConfig(ORDER_TYPE order = ORDER_TYPE.Strong);

コネクションインターバル要求値の取得。1.25ミリ秒単位。（ この値は実際のコネクションインターバル値ではありません。）
toio™コア キューブ 技術仕様（通信仕様）


ObtainConnectionInterval

public void ObtainConnectionInterval(ORDER_TYPE order = ORDER_TYPE.Strong);

現在のコネクションインターバル値の取得。1.25ミリ秒単位。
toio™コア キューブ 技術仕様（通信仕様）


4. Cubeの接続設定

通信接続の内部実装はシミュレータ実装 と リアル実装の 2 つに分かれており、通信関連クラスのコンストラクタ引数にConnectTypeを指定する事で接続方法を変更可能です。

定義

public enum ConnectType
{
    Auto, // ビルド対象に応じて内部実装が自動的に変わる
    Simulator, // ビルド対象に関わらずシミュレータのキューブで動作する
    Real // ビルド対象に関わらずリアル(現実)のキューブで動作する
}

public CubeScanner(ConnectType type = ConnectType.Auto);

public CubeConnecter(ConnectType type = ConnectType.Auto);

public CubeManager(ConnectType type = ConnectType.Auto);

サンプルコード

Cube[] cubes;
async void Start()
{
    // 引数を指定しない場合、ConnectType.Auto がデフォルト値
    // ビルド対象に応じて内部実装が自動的に変わるため、プラットフォーム毎に別々のコードを書かなくても動作します。
    var peripherals = await new CubeScanner().NearScan(2);
    cube = await new CubeConnecter().Connect(peripherals);
}

CubeManager cubeManager;
async void Start()
{
    // 引数を指定しない場合、ConnectType.Auto がデフォルト値
    // ビルド対象に応じて内部実装が自動的に変わるため、プラットフォーム毎に別々のコードを書かなくても動作します。
    cubeManager = new CubeManager();
    await cubeManager.MultiConnect(2);
}

Cube[] cubes;
async void Start()
{
    // どのプラットフォームでもシミュレータキューブに接続する
    var peripherals = await new CubeScanner(ConnectType.Simulator).NearScan(2);
    cube = await new CubeConnecter(ConnectType.Simulator).Connect(peripherals);
}

CubeManager cubeManager;
async void Start()
{
    // どのプラットフォームでもリアルキューブに接続する
    cubeManager = new CubeManager(ConnectType.Real);
    await cubeManager.MultiConnect(2);
}

サンプルプロジェクト

Sample_ConnectType をご参照ください。