Skip to main content

WhizToys SDK (Unity) Documentation

System Requirements
  • SDK Version: TBD
  • Supported Unity Version: TBD
  • Android Minimum Version: TBD
  • iOS Minimum Version: TBD

Installation​

Download the SDK: Whiztoys_SDK.unitypackage (Google Drive)

Add the SDK to your Unity project:

  1. Import Whiztoys_SDK.unitypackage into your project.

Example Scenes​

NormalDemo​

The most basic example, including grid layout, pressure detection, color display, and more.

Muti_Demo​

An example that supports connecting to multiple controllers.

Rotate_Demo (requires grid larger than 2x2)​

Uses a 2x2 block as the play area, demonstrating rotation and designating specific blocks as the working area.

Quick Start​

Initialization​

To use the SDK, first create an instance of the WhizToys class and call the Initialize method to initialize the Bluetooth module:

WhizToys whizToys = new WhizToys();
whizToys.Initialize();

After initialization, you need to register callback functions for each event you want to use:

whizToys.OnInitSuccess = () => { print("Initialization successful"); };
whizToys.OnScanDevice = OnScanDevice;
whizToys.OnScanEnd = OnScanEnd;
whizToys.OnConnected = OnConnected;
whizToys.OnDisconnect = () => { print("Connection lost"); };
whizToys.OnReceiveSignal = OnReceiveSignal;

Scanning for Devices​

Start scanning for available controllers:

whizToys.StartScan(5); // Scan for 5 seconds

Connecting to a Device​

Connect to a discovered device:

whizToys.Connect(address); // Bluetooth address

When a device is found during scanning, the device information is sent as <string address, string deviceName>:

private void OnScanDevice(string address, string deviceName)
{
}

Grid Layout​

After a successful connection, the SDK sends the layout to the user via OnConnected:

private void OnConnected(WhizToysMap whizToysMap)
{
    // Use this to operate on the grid layout
}

Changing Colors​

To change colors, use List<WhizToysSendModel>, and the colorIndex must correspond to the color table. Below is an example of setting all tiles to a specific color:

public void WriteColor(int colorIndex)
{
    List<WhizToysSendModel> sendModels = new List<WhizToysSendModel>();

    int rows = _whizToysMap.Layout.Row;
    int columns = _whizToysMap.Layout.Column;

    for (int i = 0; i < rows; i++)
    {
        for (int j = 0; j < columns; j++)
        {
            if (_whizToysMap.Blocks[i, j].Active)
            {
                WhizToysSendModel sendModel = new WhizToysSendModel();
                sendModel.Layout.Row = i;
                sendModel.Layout.Column = j;
                sendModel.ColorIndex = colorIndex;
    
                sendModel.LightMode = LightModeType.All;
                sendModel.CommandMode = CommandModeType.Immediately;
                sendModel.FeedBackMode = FeedBackModeType.Basic;
                sendModel.ShowTimeMode = ShowTimeModeType.Short;

                sendModels.Add(sendModel);
            }
        }
    }

    whizToys.WriteSignals(sendModels);
}

Receiving Pressure Signals​

The SDK sends List<WhizToysSignal>, and the user needs to handle it with the corresponding callback function. Pressure is divided into 3 levels and has 4 corners, where int[] represents top-left, bottom-left, bottom-right, and top-right respectively.

Below is an example:

private void OnReceiveSignal(List<WhizToysSignal> values)
{
    for (int i = 0; i < values.Count; i++)
    {
        WhizToysSignal whizToysSignal = values[i];

        int row = whizToysSignal.Layout.Row;
        int column = whizToysSignal.Layout.Column;
            
        PressBlock pressBlock = _pressBlocks[row, column];

        int[] pressures = whizToysSignal.Pressures;

        for (int j = 0; j < pressures.Length; j++)
            pressBlock.blocks[j].color = ConvertColor(pressures[j]);
    }
}

Data Structures​

WhizToysLayout​

Defines the position of a tile.

public struct WhizToysLayout
{
    public int Row;
    public int Column;

    public bool Compare(WhizToysLayout layout) // Compares whether two positions are the same
}

WhizToysBlock​

Defines the state of a tile.

public class WhizToysBlock
{
    public readonly bool Active; // Whether it is active; if the tile is physically absent, this will be False

    public bool IsPressure // Whether there is pressure (stepped on)
    public bool AllPressure // All four corners are pressed simultaneously
    public bool IsLeft // Top-left and bottom-left are pressed
    public bool IsRight // Top-right and bottom-right are pressed
    public bool IsUp // Top-left and top-right are pressed
    public bool IsDown // Bottom-left and bottom-right are pressed
}

WhizToysMap​

Defines the grid arrangement.

public class WhizToysMap
{
    public WhizToysLayout Layout; // Row and Column here represent the total count
    public WhizToysBlock[,] Blocks;
}

WhizToysSendModel​

Format used for changing colors.

public class WhizToysSendModel
{
    public WhizToysLayout Layout;
    public int ColorIndex; // Color must correspond to the color table
    public LightModeType LightMode = LightModeType.All; // See reference table below
    public CommandModeType CommandMode = CommandModeType.Immediately; // See reference table below
    public FeedBackModeType FeedBackMode = FeedBackModeType.Basic; // See reference table below
    public ShowTimeModeType ShowTimeMode = ShowTimeModeType.Short; // See reference table below
    
}

WhizToysSignal​

Format used for receiving pressure data.

public class WhizToysSignal
{
    public WhizToysLayout Layout;
    
    // Pressure order: 0: top-left, 1: bottom-left, 2: bottom-right, 3: top-right.
    // Pressure has 4 levels: 0: no pressure, 1: light pressure, 2: medium pressure, 4: strong pressure
    public int[] Pressures; 
}

Available Events​

OnInitSuccess​

Triggered when initialization succeeds.

Usage:

public void OnInitSuccess(){}
whizToys.OnInitSuccess = OnInitSuccess;

OnScanDevice​

Triggered when a device is detected during scanning.

Usage:

public void OnScanDevice(string address, string deviceName){}
whizToys.OnScanDevice = OnScanDevice;

OnScanEnd​

Triggered when the scan duration has elapsed.

Usage:

public void OnScanEnd(){}
whizToys.OnScanEnd = OnScanEnd;

OnConnected​

Triggered when successfully connected to a device.

Usage:

public void OnConnected(WhizToysMap whizToysMap){}
whizToys.OnConnected = OnConnected;

OnDisconnect​

Triggered when the device disconnects.

Usage:

public void OnDisconnect(){}
whizToys.OnDisconnect = OnDisconnect;

OnReceiveSignal​

Triggered when a pressure signal is received.

Usage:

public void OnReceiveSignal(List&lt;WhizToysSignal&gt;){}
whizToys.OnReceiveSignal = OnReceiveSignal;

Color Change Settings​

LightModeType (enum)​

Describes the LED lighting position. When set to "All", regardless of which sensor is stepped on, all 4 LEDs will light up together.

  • All -> All LEDs light up
  • LeftUp -> Top-left lights up individually
  • LeftDown -> Bottom-left lights up individually
  • RightUp -> Bottom-right lights up individually
  • RightDown -> Top-right lights up individually
  • Only -> All light up individually

CommandModeType​

Describes the trigger mechanism -- whether to display feedback immediately when a command is issued.

  • Immediately -> Trigger feedback immediately
  • AfterClick -> Trigger after being stepped on

FeedBackModeType​

Describes the feedback mode when stepped on. When not in feedback mode, issued commands will directly control the LED on/off state.

  • None -> Not specified (indicates feedback mode is not currently being set)
  • ClickNone -> No feedback on step
  • Basic -> Basic
  • Flash -> Flash
  • Marquee -> Marquee
  • Breathe -> Breathing light
  • Neon -> Neon light

ShowTimeModeType​

Describes the feedback duration. Applies to the duration of flash and marquee effects.

  • Short -> Short
  • Long -> Long

Color Table​

Red (R)Green (G)Blue (B)IndexColor
00000
2550001Red
25525002
25550003
25575004
255100005
255125006
255150007
255175008
255200009
255225010
255255011Yellow
225255012
200255013
175255014
150255015
125255016
100255017
75255018
50255019
25255020
0255021Green
02552522
02555023
02557524
025510025
025512526
025515027
025517528
025520029
025522530
025525531Cyan
022525532
020025533
017525534
015025535
012525536
010025537
07525538
05025539
02525540
0025541Blue
25025542
50025543
75025544
100025545
125025546
150025547
175025548
200025549
225025550
255025551Purple
255022552
255020053
255017554
255015055
255012556
255010057
25507558
25505059
25502560
25525525561White