KaiSense Developer reference

KaiSense SDK

React NativePythonC++

React Native · Base & Combat

Explore the sensor APIs in Base, or follow the Combat path to an accepted strike.

For React Native 0.77 with Hermes, install the supplied npm tarball and its peer dependencies. On iOS, run pod install. Rebuild your app to link the native SDK. Desktop installation and examples are below.

passed intoemitshandled by

Base SDK

Recording


Python · macOS and Linux

Install the supplied platform wheel with uv pip install /path/to/wheel.whl, substituting its filename. For model inference install the wheel with its combat extra.

import asyncio
from kaisense import Base

async def capture():
    for tag in await Base.scan():
        async with Base.motion(tag, lambda f: print(f.acceleration)):
            await asyncio.sleep(10)
        break

asyncio.run(capture())
Base.scan(timeout=5.0)
Discover advertising KaiTags. Returns devices that can be passed to the stream function.
Base.motion(device, on_frame)
Connect and deliver 60 Hz motion frames. Use an async context manager. Exiting stops capture and disconnects.
Base.decode_motion(packet: bytes)
Decode one or eight motion frames. Each contains an index, a quaternion (w, x, y, z) and acceleration (x, y, z).
Classifier(path).classify(features, limb, sport)
Load a local ONNX model and its matching .json manifest. Pass ten firmware features in manifest order, an arm or leg, and Boxing, Kickboxing or MuayThai to receive a strike label.
Combat.select_label(probabilities, limb, sport)
Select a permitted label from seven model probabilities in elbow, hook, kick, knee, straight, teep, uppercut order.

C++17 · macOS and Linux

Set CMAKE_PREFIX_PATH to the installed SDK, call find_package(KaiSense CONFIG REQUIRED), then link KaiSense::kaisense. Bluetooth requires SimpleBLE 0.6.0. For inference include kaisense/classifier.hpp and link ONNX Runtime with nlohmann/json headers available.

#include <kaisense/bluetooth.hpp>
#include <iostream>

int main() {
    auto tags = kaisense::Bluetooth::scan();
    if (!tags.empty()) kaisense::Bluetooth::stream(tags.front(), [](const auto& frame) {
        std::cout << frame.index << '\n';
        return false;
    });
}
Bluetooth::scan(int milliseconds = 5000)
Discover advertising KaiTags. Returns devices that can be passed to the stream function.
Bluetooth::stream(sensor, onFrame)
Connect and deliver 60 Hz motion frames. The callback runs on the calling thread. Return false to stop capture and disconnect.
Base::decodeMotion(const std::vector<std::uint8_t>& packet)
Decode one or eight motion frames. Each contains an index, a quaternion (w, x, y, z) and acceleration (x, y, z).
Classifier(path).classify(features, limb, sport)
Load a local ONNX model and its matching .json manifest. Pass ten firmware features in manifest order, an arm or leg, and Boxing, Kickboxing or MuayThai to receive a strike label.
Combat::selectLabel(probabilities, limb, sport)
Select a permitted label from seven model probabilities in elbow, hook, kick, knee, straight, teep, uppercut order.

Recording, firmware updates and live strikes

On macOS and Linux, use the same recording handle to stop capture and download it. Current firmware supports raw motion on external flash and compact strikes on SoC flash.

Python

handle = await recording.start(device, format, storage)
await recording.stop(handle)
await recording.download(handle)

await Firmware.update(device, image_bytes, target_version, progress)

combat = Combat()
combat.set_sport(Sport.Boxing)
combat.on_strike(display_strike)
await combat.start({device: Position.LeftArm})
# At the end of training
await combat.stop()

C++

auto handle = recording.start(sensor, options);
recording.stop(handle);
recording.download(handle);

kaisense::Firmware::update(sensor, image, targetVersion, progress);

kaisense::CombatCapture combat;
combat.onStrike(displayStrike);
combat.start({{sensor, kaisense::Position::LeftArm}});
combat.stop();

Firmware progress reports acknowledged bytes and total image size. Retry an interrupted update using the same image. A strike includes its sensor, position, timestamp and label. Without a loaded classifier, the label is Unclassified.