Skip to content

Interfacing with the SDK

Any JSON to the SDK must include a type mentioning what type of data is being sent to the SDK, along with the data.

All JSON from the SDK will include a success key with a boolean value. If success is true, the remaining data is appended. If success is false, it represents an error and is of the following format

{
    "success": false,
    "errorCode": 52, # Represents an error code
    "error": "kaiNotActivated", # Represents a short, dev friendly error code
    "message": "This Kai has not been activated yet" # Represents a string that has been formatted to be shown to the users
}

Authenticating a module

In order to authenticate your module following JSON needs to be sent to SDK.

{
    "type": "authentication",
    "moduleId": "<uuid>",
    "moduleSecret": "an encrypted string"
}

Please note that until the product reaches stable stage, the encrypted still will remain as qwerty as a placeholder.

Possible response for this can be :

{
    "type": "authentication",
    "success": true/false
}

Subscribing for data

In order to subscribe for data from the Kai, the following JSON must be sent to the SDK based on whatever is required.

{
    "type":"setCapabilities",
    "kaiId": <int> | "default" | "defaultLeft" | "defaultRight",
    "gestureData": true / false,
    "pyrData": true / false,
    "fingerShortcutData": true / false,
    "linearFlickData": true / false,
    "fingerPositionData": true / false,
    "quaternionData": true / false,
    "pyrData": true / false,
    "accelerometerData": true / false,
    "gyroscopeData": true / false,
    "magnetometerData": true / false
}

You can safely ignore the data types that you do not care about. That is, if you only want gesture data, you can simply send the following

{
    "type": "setCapabilities",
    "gestureData": true
}

And you get the following JSON in response :

{
    "type": "setCapabilities",
    "kaiId": <int>,
    ?"defaultKai": true / false,
    ?"defaultLeftKai": true / false,
    ?"defaultRightKai": true / false,
    "success": true
}

Notes:

  • The SDK maintains state information of the capabilities that a module has subscribed to. For example, if you initially set gestureData to true , then later set pyrData to true individually, you will be subscribed to both gestureData as well as pyrData, unless you explicitly set any one of them to false.
  • Once the capabilities has been set, the SDK responds with a getCapabilities JSON with all the enabled capabilities as mentioned here.

Query subscribed data

In case you lose state and need to query the capabilities that your module has subscribed to from the SDK's memory, you can send the following JSON

{
    "type": "getCapabilities",
    "kaiId": <int> | "default" | "defaultLeft" | "defaultRight"
}

Once the above JSON is sent, the SDK responds with the following JSON

{
    "success": true,
    "type": "getCapabilities",
    "kaiId": <int>,
    ?"defaultKai": true / false,
    ?"defaultLeftKai": true / false,
    ?"defaultRightKai": true / false,
    "gestureData":true / false,
    "pyrData": true / false,
    "fingerShortcutData": true / false,
    "linearFlickData": true / false,
    "fingerPositionData": true / false,
    "quaternionData": true / false,
    "pyrData": true / false,
    "accelerometerData": true / false,
    "gyroscopeData": true / false,
    "magnetometerData": true / false
}

Gesture Data

When Gesture data is subscribed to, the following JSON is sent from the SDK when a gesture is performed.

{
    "type": "incomingData",
    "kaiId": <int>,
    ?"defaultKai": true / false,
    ?"defaultLeftKai": true / false,
    ?"defaultRightKai": true / false,
    "foregroundProcess": "foregroundProcessName",
    "data": [
        {
            "type": "gestureData",
            "gesture": "X"
        }]
}

Where X can be of the following values:

  • swipeUp
  • swipeDown
  • swipeLeft
  • swipeRight
  • sideSwipeUp
  • sideSwipeDown
  • sideSwipeLeft
  • sideSwipeRight
  • pinch2Begin
  • pinch2End
  • pinch3Begin
  • pinch3Begin
  • grabBegin
  • grabEnd
  • dialBegin
  • dialEnd

Finger Shortcut Data

When finger shortcut data is subscribed to, the SDK returns a boolean array indicating the activation status of the 4 fingers in the order of [little finger, ring finger, middle finger, index]. In the given example only the ring finger is closed.

{
    "type": "incomingData",
    "kaiId": <int>,
    ?"defaultKai": true / false,
    ?"defaultLeftKai": true / false,
    ?"defaultRightKai": true / false,
    "foregroundProcess": "foregroundProcessName",
    "data": [
        {
            "type": "fingerShortcutData",
            "fingers": [
                true/false,
                true/false,
                true/false,
                true/false
            ]
        }]
}

Finger Position Data

When finger positional data is subscribed to, the SDK continously sends an int array indicating the positions of the 4 fingers in the order of [little finger, ring finger, middle finger, index]. For each finger, the value ranges from 0 to 255, which 0 implying the finger completely open and 255 implying the finger being entirely closed.

{
    "type": "incomingData",
    "kaiId": <int>,
    ?"defaultKai": true / false,
    ?"defaultLeftKai": true / false,
    ?"defaultRightKai": true / false,
    "foregroundProcess": "foregroundProcessName",
    "data": [
        {
            "type": "fingerPositionData",
            "fingers": [
                0,
                0,
                255,
                0
            ]
        }]
}

Linear Flick Data

TODO

1.1.5 PYR Data

Includes Accelerometer and Gyroscope data. TODO: explain a bit more. x, y and z are 3 signed integer values.

{
    "type": "incomingData",
    "kaiId": <int>,
    ?"defaultKai": true / false,
    ?"defaultLeftKai": true / false,
    ?"defaultRightKai": true / false,
    "foregroundProcess": "foregroundProcessName",
    "data": [
        {
            "type": "pyrData",
            "pitch": 0.0,
            "yaw": 0.0,
            "roll": 0.0
        }]
}

1.1.6 Quaternion Data

TODO: Explain what quaternions are and how it can be used. w, x, y and z and signed float values ranging from -1 to +1 .

{
    "type": "incomingData",
    "kaiId": <int>,
    ?"defaultKai": true / false,
    ?"defaultLeftKai": true / false,
    ?"defaultRightKai": true / false,
    "foregroundProcess": "foregroundProcessName",
    "data": [
        {
            "type":"quaternionData",
            "quaternion": {
                "w": 0,
                "x": 0,
                "y": 0,
                "z": 0
            }
        }]
}