Skip to content

Welcome to Kai Docs

This documentatioon is meant to serve as a comprehensive guide to understand how the Kai works, how the data is exposed to developers and how you can connect to it


Introduction

The Kai polls for data from the Gyroscope, Accelerometer and Magnetometer built into it. Once it detects a gesture / needs to send data, it sends it using the Bluetooth Low Energy (BLE) protocol of the Bluetooth 4.0 spec. This is meant to give the Kai the highest amount of battery life as possible. You can read more about how the hardware of the Kai works here

Recieveing data from the Kai

Since the Kai hardware is based on the BLE protocol, it works on a request basis. Any device integrating with the Kai must request for the type of data that it requires in order to receive it.

As per the Bluetooth 4.0 spec, the maximum allowed bytes per transmission of Bluetooth is 20 bytes. Hence, all data from the Kai comes in a 20 byte basis.


SDK

For Android and iOS applications, the Kai directly allows connections through Bluetooth. For desktops, however, the Kai only works through the provided dongle.
For desktop applications, the dongle must be used in order to recieve data from the SDK.

The SDK automatically handles the following:

  • Starting on boot
  • Searching for the Kai dongle and connecting to it
  • Subscribing for the Kai data as required
  • Providing that data to other developers in a JSON format
  • Looking for unicorns

The Kai SDK provides the data from the dongle in 2 main ways:

  • A websocket server running on port 2203, for first party integrations
  • A process server, for third party integrations

Modules

Any integration is considered as a Module. Each module is isolated from one another and independently interfaces with the Kai SDK. As mentioned before, a module can either be a WebSocket module or a Process module depending on how it connects to the SDK. The format or data from the SDK for both modules are the exact same. So picking one module over the other is just a matter of how you wish to integrate. The data provided is still the same.


Libraries for supported languages

For most popular languages, we have already made libraries that you can use to integrate with the WebSocket server or the Process Server. These libraries are open-source and available on GitHub (links below). They do most of the heavy lifting allowing you to focus on your business logic.

How do I pick to integrate with the WebSocket server or the Process Server?
This is a question we get asked a lot. As a rule of thumb, if you're a first party getting your application or game to work with the Kai, you should pick the WebSocket server. However, if you're a third party who has a console program which takes data from the Kai and interfaces with another application, you should pick the Process Server.

Officially Supported Languages:

If you would like to see more languages supported, feel free to contact us! We'd love to hear from you


WebSocket Server

The WebSocket server is used for first party integrations. If you're making an application or a game that takes data from the Kai, connecting to the WebSocket server is the recommended way to integrate.

A WebSocket server is a simple HTTP server that keeps its connections alive until explicitly closed. This is highly efficient for data from the Kai since it avoids the initial TCP establishment latency. Once established, the data is transferred only through the loopback interface on the localhost, which avoids any further latency issues. Moreover, the WebSocket server listens on 127.0.0.1 rather than 0.0.0.0, which prevents any foreign clients from connecting to the SDK through the network.

The WebSocket can be connected to using the following details:

  • Host: localhost or 127.0.0.1
  • Port: 2203
  • Path: /
  • Scheme: ws://
  • Use SSL: false

Process Server

The (what we call) Process Server is a system that spawns child processes (your applications) and keeps it running in the background of the user system. Once the Kai sends data that your module needs, the SDK will automatically format the data and send it in a JSON format based on the application that's in focus and if you're module is allowed to recieve data for that application (more on that later). The SDK communicates with the process module using the process's STDIN and STDOUT streams.

Kai Data

The Kai data works on a subscription basis. The Kai is capable of sending different types of data. Each module that integrates with the SDK will have to explicitly mention which capability it wants to recieve. Subscribing to a specific Kai capability will make the Kai start sending data once that event occurs. Initially, the Kai will not send any data until any specific capability is subscribed to. The Kai capability can be one of the following:

  • Gesture Data: Makes the Kai notify when a gesture is performed.
  • Finger Shortcut Data: Makes the Kai notify on changes in finger shortcuts. A finger shortcut is defined when any finger (except thumb) touches the thumb.
  • Linear Flick Data: Makes the Kai notify when a linear flick is perform by translating the hand in any one specific direction.

The next set of Kai capabilities makes the Kai send data on a continous basis, which drains the battery significantly faster. Please subscribe to these capabilities on a need-to basis.

  • Finger Position Data: Makes the Kai send the absolute positions of the 4 fingers
  • Quaternion Data: Makes the Kai send the quaternions of the Kai position in the user's hand.
  • PYR Data: Makes the Kai send the Pitch, Yaw, and Roll (PYR) of the Kai position in the user's hand.
  • Accelerometer Data: Makes the Kai send the accelerometer values from the sensor.
  • Gyroscope Data: Makes the Kai send the gyroscope values from the sensor.
  • Magnetometer Data: Makes the Kai send the magnetometer values from the sensor.

Note: Multiple capabilities can be subscribed to and this will result in the module getting both data parallelly.

In order to optimise battery life, the recommended way is to get this data only when required. An example of such a flow would be as follows. Let's say we need to make an object rotate in real time on the screen.

  1. We would first subscribe for finger shortcut data.
  2. When a grab is detected from the finger shortcut data, we subscribe for either PYR or Quaternion data.
  3. We use the PYR / Quaternion data to rotate the object on the screen corresponding to the user's hand.
  4. Once we detect that the grab has ended (from the finger shortcut data), we unsubscribe from the PYR / Quaternion data, to save battery on the Kai.
  5. Everyone lives happily forever after.

Interfacing with the SDK

For most situations, the libraries provided will handle most of the subscribing / unsubscribing part for you. However, if you are in the unlikely situation that you need to directly interface with the SDK using JSON data, you can see here to find out exactly what JSON to send to the SDK in order to subscribe for Kai data.