Technical Documentation - Usage - Cube Class

Table of Contents

1. Outline

Cube class implements the functionality for manipulating toio™ core cubes (henceforth called cubes).
This class is a multi-platform class that can switch between implementations for different environments, and supports two execution environments: Cube running on Unity system (Simulator) and a real Cube.

For more information about Simulator, please refer to here page.

In real Cube, you control real Cube through Bluetooth communication from Unity program according to the toio™ Core Cube Technical Specifications (Communication Specifications).

Real/Sim Performance Meter

Currently (07/20/2023), there are 5 BLE protocol versions in Cube.

2.0.0　2.1.0　2.2.0　2.3.0　2.4.0

toio SDK for Unity has two internal implementations: Cube class that runs in real life (Real-compatible) and Cube class that runs in Simulator (Sim-compatible). Since the internal implementations are different, there are differences in the support status.
The following table shows the implementation correspondence.

BLE protocol version 2.0.0

Links are of version 2.3.0, which is the lowerest version supporting English.

Function Type Function Real Support Status Sim Support Status
Identification sensor Position ID o o
  Standard ID o o
Motion sensor Horizontal detection o o
  Collision detection o ※
Button State of button o o
Battery Remaining battery level o x
Motor Motor control x x
  Motor control with specified duration o o
Indicator Turning the indicator on and off o o
  Repeated turning on and off of indicator o o
  Turn off all indicators. x x
  Turn off a specific indicator. x x
Sound Playing sound effects o o
  Playing the MIDI note numbers o o
  Stop playing o o
Configuration Requesting the BLE protocol version o x
  Horizontal detection threshold settings o o
  Collision detection threshold settings o x
  Obtaining the BLE protocol version o x

… The detection function is not implemented on Simulator side, but you can manually switch the judgment on and off from the inspector. For more details, please refer to [here].

BLE protocol version 2.1.0

Links are of version 2.3.0, which is the lowerest version supporting English.

Function Type Function Real Support Status Sim Support Status
Motion sensor Double-tap detection o ※
  Posture detection o o
Motor Motor speed command values (updated) o o
  Motor control with target specified o o
  Motor control with multiple targets specified x x
  Motor control with acceleration specified o o
  Responses to motor control with target specified o o
  Responses to motor control with multiple targets specified x x
Configuration Double-tap detection time interval settings o x

BLE protocol version 2.2.0

Links are of version 2.3.0, which is the lowerest version supporting English.

Function Type Function Real Support Status Sim Support Status
Motion sensor Requesting motion detection information o o
  Shake detection o o
Magnetic sensor Requests for magnetic sensor information o o
  Magnet state o o
Motor Obtaining motor speed information o o
Configuration Identification sensor ID notification settings o o
  Identification sensor ID missed notification settings o o
  Responses to identification sensor ID notification settings o o
  Responses to identification sensor ID missed notification settings o o
  Magnetic sensor settings o o
  Responses to magnetic sensor settings o o
  Motor speed information acquisition settings o o
  Responses to motor speed information acquisition settings o o

BLE protocol version 2.3.0

Function Type Function Real Support Status Sim Support Status
Magnetic sensor Magnetic force detection o o
Posture Angle Requesting posture angle detection o o
  Obtaining posture angle information (notifications in Euler angles) o o
  Obtaining posture angle information (notifications in quaternions) o o
Configuration Magnetic sensor settings(updated) o o
  Posture angle detection settings o o
  Responses to posture angle detection settings o o

BLE protocol version 2.4.0

Function Type Function Real Support Status Sim Support Status
Posture Angle detection Requesting posture angle detection (updated) o o
  Obtaining posture angle information (notifications in quaternions) o o
  Obtaining posture angle information (notifications in high precision Euler angles) o o
Configuration Posture angle detection settings (updated) o o
  Request to change connection interval o x
  Obtaining the requested connection interval value o x
  Obtaining the actual connection interval value o x
  Responses to request to change connection interval o x
  Responses to obtain the requested connection interval value o x
  Responses to obtain the actual connection interval value o x


2. Comparison with existing toio™ library (toio.js)

toio.js is an existing toio library written in javascript.
This library is built in node.js and runs in a PC environment.
We will use two classes, scanner and cube, to manipulate Cube.

toio.js sample code is shown below.

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

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

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

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

main();

toio SDK for Unity is designed to be easy to use for toio.js users, and uses two classes, scanner and Cube, to manipulate Cube.

The following is a sample code of this program with the same behavior.

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

        // connect to 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 Class API

3.1. Variable

// BLE protocol version of the connected cube
public string version { get; }

// Unique identification ID of Cube
// In simulator environment, InstanceID of Cube game object becomes ID
public string id { get; protected set; }

// Address of Cube
public string addr { get; }

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

// Connection status of Cube
public bool isConnected { get; }

// Cube battery status
public int battery { get; protected set; }

// X-coordinate of Cube on the mat
// The coordinates are based on the center position of Cube.
// It will automatically update while Cube is on the mat.
// Callback function: standardIdCallback
public int x { get; protected set; }

// Y-coordinate of Cube on the mat
// The coordinates are based on the center position of Cube.
// It will automatically update while Cube is on the mat.
// Callback function: standardIdCallback
public int y { get; protected set; }

// XY coordinates of Cube on the mat
// The coordinates are based on the center position of Cube.
// It will automatically update while Cube is on the mat.
// Callback function: standardIdCallback
public Vector2 pos { get; }

// Angle of Cube on the mat
// The coordinates are based on the center position of Cube.
// It will automatically update while Cube is on the mat.
// Callback function: standardIdCallback
public int angle { get; protected set; }

// XY coordinates of Cube on the mat
// The coordinates are based on the optical sensor position of Cube.
// It will automatically update while Cube is on the mat.
// Callback function: standardIdCallback
public Vector2 sensorPos { get; }

// Angle of Cube on the mat
// The coordinates are based on the optical sensor position of Cube.
// It will automatically update while Cube is on the mat.
// Callback function: standardIdCallback
public int sensorAngle { get; protected set; }

// Special sticker IDs that can be read
// The ID is obtained from Cube's optical sensor.
// Callback function: standardIdCallback
public uint standardId { get; protected set; }

// Variable for the button-press state of Cube
// Callback function: buttonCallback
public bool isPressed { get; protected set; }

// Cube tilt state variable
// Callback function: slopeCallback
public bool isSloped { get; protected set; }

// Cube collision state variables
// The internal implementation may vary greatly depending on the inherited class.
// Callback function: collisionCallback
public bool isCollisionDetected { get; protected set; }

// Variable to determine if Cube is on the mat.
public bool isGrounded { get; protected set; }

// Variable representing the maximum speed of Cube.
// It is provided for each BLE protocol version differently.
public int maxSpd { get; }

// Variable representing the minimum speed of Cube
// It is provided for each BLE protocol version differently.
public int deadzone { get; }

// ver2.1.0
// Double-tap state of Cube
// Once it is tapped, it will be tapped again within a certain period of time.
// Callback function: doubleTapCallback
public bool isDoubleTap { get; protected set; }

// Cube posture
// The value changes when the orientation of Cube relative to the horizontal plane changes.
// Callback function: poseCallback
public PoseType pose { get; protected set; }

// ver2.2.0
// Shaking state of Cube
// When you shake Cube, the value changes according to the strength of the shake.
// Callback function: shakeCallback
public int shakeLevel { get; protected set; }

// Speed of Cube's motor ID 1 (left)
// Callback function: motorSpeedCallback
public int leftSpeed { get; protected set; }

// Speed of Cube's motor ID 2 (Right)
// Callback function: motorSpeedCallback
public int rightSpeed { get; protected set; }

// Magnet state of Cube
// Callback function: magnetStateCallback
public MagnetState magnetState { get; protected set; }

// ver2.3.0
// Magnetic force of Cube
// Callback function: magneticForceCallback
public Vector3 magneticForce { get; protected set; }

// Attitude of Cube in eulers
// Callback function: attitudeCallback
public Vector3 eulers { get; protected set; }

// Attitude of Cube in quaternion
// Callback function: attitudeCallback
// Please note that the coordinate system specified in the specifications is different from Unity's.
public Quaternion quaternion { get; protected set; }

// ver2.4.0
// Requested connection interval value
// Callback function：connectionIntervalConfigCallback
public virtual int connectionIntervalMin { get; protected set; }
public virtual int connectionIntervalMax { get; protected set; }
// Actual connection interval value
// Callback function：connectionIntervalCallback
public virtual int connectionInterval { get; protected set; }


3.2. callback

// CallbackProvider<T1>
// CallbackProvider<T1, T2>
// CallbackProvider<T1, T2, T3>
// CallbackProvider<T1, T2, T3, T4>
// ※Pseudo code
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);
}

// Button callback
public CallbackProvider<Cube> buttonCallback { get; }
// Tilt callback
public CallbackProvider<Cube> slopeCallback { get; }
// Collision callback
public CallbackProvider<Cube> collisionCallback { get; }
// Coordinate angle callback
public CallbackProvider<Cube> idCallback { get; }
// Coordinate angle Missed callback
public CallbackProvider<Cube> idMissedCallback { get; }
// StandardID callback
public CallbackProvider<Cube> standardIdCallback { get; }
// StandardID missed callback
public CallbackProvider<Cube> standardIdMissedCallback { get; }

// ver2.1.0
// Double tap callback
public CallbackProvider<Cube> doubleTapCallback { get; }
// Attitude detection callback
public CallbackProvider<Cube> poseCallback { get; }
// Response callback for motor control with target specification
public CallbackProvider<Cube, int, TargetMoveRespondType> targetMoveCallback { get; }

// ver2.2.0
// Shake callback
public CallbackProvider<Cube> shakeCallback { get; }
// Motor speed callback
public CallbackProvider<Cube> motorSpeedCallback { get; }
// Magnet state callback
public CallbackProvider<Cube> magnetStateCallback { get; }

// ver2.3.0
// Magnetic force detection callback
public CallbackProvider<Cube> magneticForceCallback { get; }
// Attitude callback
public CallbackProvider<Cube> attitudeCallback { get; }

3.3. Method

Move

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

Controls Cube’s motor.
toio™ Core Cube Technical Specifications (Communication Specifications)


TurnLedOn

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

Controls the LEDs on the bottom of Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)


TurnOnLightWithScenario

// Configuration structure per luminescence
public struct LightOperation
{
    public int durationMs; // Millisecond
    public byte red;         // Red intensity
    public byte green;       // Green intensity
    public byte blue;        // Blue intensity
}
public void TurnOnLightWithScenario(int repeatCount, Cube.LightOperation[] operations, ORDER_TYPE order=ORDER_TYPE.Strong);

Continuously controls the LEDs on the bottom of Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)


TurnLedOff

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

Turn off the LED on the bottom of Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)


PlayPresetSound

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

Play the sound effects provided in Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)


PlaySound

Play any sound from Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)

// Argument version
// A configuration structure for each pronunciation.
public struct SoundOperation
{
    public int durationMs; // Millisecond
    public byte volume;      // Volume (0~255)
    public byte note_number; // Notes(0~128)
}
public void PlaySound(int repeatCount, SoundOperation[] operations, ORDER_TYPE order=ORDER_TYPE.Strong);

// Buffered version (e.g. of a file)
public void PlaySound(byte[] buff, ORDER_TYPE order=ORDER_TYPE.Strong);


StopSound

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

Stops Cube from playing sound.
toio™ Core Cube Technical Specifications (Communication Specifications)


ConfigSlopeThreshold

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

Sets the threshold for horizontal detection of Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)


ConfigCollisionThreshold

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

Sets the threshold for collision detection for Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)


ConfigDoubleTapInterval

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

Set the time interval for double-tap detection of Cube
toio™ Core Cube Technical Specifications (Communication Specifications)


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

Controls Cube’s motor with target designation.
toio™ Core Cube Technical Specifications (Communication Specifications)


AccelerationMove

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

Performs motor control with acceleration specified for Cube.
toio™ Core Cube Technical Specifications (Communication Specifications)


ConfigMotorRead

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

Enables or disables the acquisition of Cube’s motor speed information.
toio™ Core Cube Technical Specifications (Communication Specifications)


RequestSensor

Deprecated. Please use RequestMotionSensor instead.


RequestMotionSensor

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

Requests Cube to notify you of motion sensor information once.
toio™ Core Cube Technical Specifications (Communication Specifications)

Since collision detection and double tap detection are notified only when they occur, it is impossible for the variable Cube.isCollisionDetected Cube.isDoubleTap to return from the True state to False unless it is notified by another motion sensor. Therefore, it is possible to update these two variables by using RequestMotionSensor to ask for notification.


ConfigIDNotification

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

Set the notification frequency for the Position ID and Standard ID from the identification sensor. Notifications are sent when both the [Minimum Notification Interval] and [Notification Conditions] are met.
toio™ Core Cube Technical Specifications (Communication Specifications)


ConfigIDMissedNotification

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

Set the Position ID missed and Standard ID missed notification sensitivity of the identification sensor.
toio™ Core Cube Technical Specifications (Communication Specifications)


ConfigMagneticSensor

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

Sets the mode of the cube’s magnetic sensor. It is disabled by default. (Supported since v2.2.0)
toio™ Core Cube Technical Specifications (Communication Specifications)

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

Sets the mode of the cube’s magnetic sensor. It is disabled by default. (Supported since v2.3.0)
toio™ Core Cube Technical Specifications (Communication Specifications)


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

Enables or disables the cube’s attitude angle detection feature. It is disabled by default. (Supported since v2.3.0)
toio™ Core Cube Technical Specifications (Communication Specifications)


RequestMagneticSensor

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

Requests the cube to notify the magnetic sensor information once.
toio™ Core Cube Technical Specifications (Communication Specifications)


RequestAttitudeSensor

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

Requests that the cube be notified once of the specified type of attitude angle detection information.
toio™ Core Cube Technical Specifications (Communication Specifications)

ConfigConnectionInterval

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

Request to change the connection interval. Values between 0xFFFF (no request) or 6 to 3200 can be specified. (Supported from v2.4.0)
toio™ Core Cube Technical Specifications (Communication Specifications)


ObtainConnectionIntervalConfig

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

Retrieve the requested connection interval value. In 1.25 ms units. (This value is not the actual connection interval value.)
toio™ Core Cube Technical Specifications (Communication Specifications)


ObtainConnectionInterval

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

Get the actual connection interval value between the cube and the central device by writing the following data.
toio™ Core Cube Technical Specifications (Communication Specifications)


4. Cube connection settings

The internal implementation of communication connection is divided into simulator implementation and real implementation, and the connection method can be changed by specifying ConnectType in the constructor argument of the communication related class.

Definition

public enum ConnectType
{
    Auto, // The internal implementation changes automatically depending on the build target.
    Simulator, // Runs in Simulator cube regardless of the build target
    Real // Works with real (real) cubes regardless of the build target
}

public CubeScanner(ConnectType type = ConnectType.Auto);

public CubeConnecter(ConnectType type = ConnectType.Auto);

public CubeManager(ConnectType type = ConnectType.Auto);

Sample Code

Cube[] cubes;
async void Start()
{
    // Auto is the default value if no argument is specified
    // The internal implementation changes automatically depending on the build target, so you don't need to write separate code for each platform.
    var peripherals = await new CubeScanner().NearScan(2);
    cube = await new CubeConnecter().Connect(peripherals);
}

CubeManager cubeManager;
async void Start()
{
    // Auto is the default value if no argument is specified
    // The internal implementation changes automatically depending on the build target, so you don't need to write separate code for each platform.
    cubeManager = new CubeManager();
    await cubeManager.MultiConnect(2);
}

Cube[] cubes;
async void Start()
{
    // Connect to Simulator cube on any platform
    var peripherals = await new CubeScanner(ConnectType.Simulator).NearScan(2);
    cube = await new CubeConnecter(ConnectType.Simulator).Connect(peripherals);
}

CubeManager cubeManager;
async void Start()
{
    // Connect to a real cube on any platform.
    cubeManager = new CubeManager(ConnectType.Real);
    await cubeManager.MultiConnect(2);
}

Sample Projects

Please refer to Sample_ConnectType