Quick Start

Complete Installation and connect your glove before starting. These examples select the first glove found. When using multiple devices, check the port, device name, and serial number before proceeding.

Read your first frame over USB

from xenseglovesdk import XenseGlove

gloves = [port for port in XenseGlove.list_ports() if port.is_glove]
if not gloves:
    raise RuntimeError("No glove found. Check the USB connection and serial port availability.")

with XenseGlove.open(gloves[0].port) as glove:
    info = glove.info()
    print("Serial number:", info.serial_number)
    print("Firmware version:", info.version)

    glove.set_channel("serial")
    glove.set_output_mode("adc")

    frame = glove.read_frame(timeout=2.0)
    matrix = frame.value_map
    print("Matrix dimensions:", frame.rows, frame.cols)
    print("Maximum ADC:", frame.max_value())
    print("Palm reading at (24, 8):", matrix[24][8])

value_map is a list of 63 rows and 39 columns. Readings are integers; invalid positions are None. The connection closes automatically when the with block ends, including when an exception occurs.

Read your first frame over BLE

from xenseglovesdk import XenseGlove

if not XenseGlove.is_bluetooth_enabled():
    raise RuntimeError("Enable Bluetooth on your computer first.")

devices = XenseGlove.scan_ble(timeout=5.0)
if not devices:
    raise RuntimeError("No BLE glove found. Make sure it is powered on and near the computer.")

for device in devices:
    print(device.name, device.address)

with XenseGlove.open_ble(devices[0].address) as glove:
    print("Serial number:", glove.info().serial_number)
    glove.set_channel("ble")
    glove.set_output_mode("adc")

    frame = glove.read_frame(timeout=2.0)
    print("Maximum ADC:", frame.max_value())

Use the scan result's address to connect. Read the device's serial number from glove.info().serial_number after connecting. Explicitly call set_channel("ble") to direct the glove's data output to BLE.

Read frames continuously

read_frame() returns the latest frame. If no new data arrives between calls, the timestamp and sequence number remain the same. This example runs for 10 seconds and processes only updated frames:

import time

from xenseglovesdk import XenseGlove

gloves = [port for port in XenseGlove.list_ports() if port.is_glove]
if not gloves:
    raise RuntimeError("No glove found.")

with XenseGlove.open(gloves[0].port) as glove:
    glove.info()
    glove.set_channel("serial")
    glove.set_output_mode("adc")

    last_frame_key = None
    deadline = time.monotonic() + 10.0

    while time.monotonic() < deadline:
        try:
            frame = glove.read_frame(timeout=1.0)
        except TimeoutError:
            print("No data received yet.")
            time.sleep(0.01)
            continue

        frame_key = (frame.timestamp, frame.sequence)
        if frame_key != last_frame_key:
            last_frame_key = frame_key
            print(frame.sequence, frame.max_value(), frame.valid_points())

        time.sleep(0.01)

The polling interval determines how often your application reads data. The SDK provides the latest frame, so your application may skip other samples received between reads. Save frames in the loop if you need a history.

Analyze data by region

Use the frame obtained above to inspect finger readings and contact points that meet a threshold:

for finger, summary in frame.by_finger().items():
    print(finger, summary["max"], summary["mean"])

palm = frame.by_region()["palm"]
print("Palm ADC total:", palm["total"])

for point in frame.contacts(threshold=10)[:5]:
    print(point.row, point.col, point.value)

Contact points are sorted by ADC value from highest to lowest. The threshold 10 is an example; choose a value based on your measurements. See the Data Guide for the matrix layout and field descriptions.

Set the frame rate and tare

Run these operations within an open USB connection:

glove.set_frequency(60, target="serial")

# Keep the glove unloaded before taring.
glove.tare()

The frame rate can be set to 10–120 Hz, and the device saves this setting. tare() measures the zero offset again and switches to tare_adc mode. It is available only over USB serial. Keep the glove unloaded after the call returns, and wait for readings to stabilize before measuring.

To use the existing tare result, call glove.set_output_mode("tare_adc"). See Output modes for the differences between modes.