API Reference
from xenseglovesdk import XenseGlove, get_glove_layout
Create a connection with XenseGlove.open() or XenseGlove.open_ble(). Pressure reads return a Frame. Records such as device information support both attribute and dictionary access, for example info.serial_number and info["serial_number"].
Unless otherwise stated, all timeout values are in seconds. Settings methods return None on success.
Discovery and connections
| Method | Description |
|---|---|
XenseGlove.list_ports(probe=True, timeout=0.5) | Returns serial port records. By default, identifies gloves; filter results using is_glove. timeout is the query wait time per port. probe=False only lists ports |
XenseGlove.scan_ble(timeout=5.0) | Scans for BLE devices and returns a list of records. timeout must be greater than 0 and at most 120 seconds |
XenseGlove.is_bluetooth_enabled(timeout=2.0) | Returns a bool indicating whether the system's first Bluetooth adapter is enabled. timeout must be greater than 0 and at most 120 seconds |
XenseGlove.open(port) | Connects using a serial port name such as COM5 or /dev/ttyACM0 and returns a connected XenseGlove |
XenseGlove.open_ble(address, timeout=10.0) | Connects over BLE using an address from the scan results. timeout must be greater than 0 and at most 120 seconds |
list_ports() returns all serial ports. Each record contains:
| Field | Description |
|---|---|
port | Serial port name to pass to open() |
description | Device description; may be empty |
hardware_id | USB device identifier; may be empty |
is_glove | Whether the device was successfully identified as a glove |
info | Device information for an identified glove, otherwise None |
error | Reason for a connection or query failure, or None if no error occurred |
Identification can fail when a port is in use or a query times out. With probe=False, is_glove=False means identification was not performed.
BLE scan records contain name (device name), address (connection address), serial_number (identifier available during scanning), and rssi (signal strength in dBm, possibly None). Query the device's serial number with info() after connecting.
Device information and settings
| Method | Parameters and return values |
|---|---|
info(timeout=1.0) | Queries device information and current settings; returns a record |
query_version(timeout=1.0) | Returns the firmware version as a string |
query_battery(timeout=1.0) | Returns the battery voltage as an integer in mV |
set_output_mode(mode, timeout=1.0) | mode is "adc", "raw", or "tare_adc"; see Output modes |
set_frequency(hz, target=None, timeout=1.0) | hz is an integer from 10 to 120. target is "serial" or "ble"; when omitted, sets the frame rate for the current connection type. The device saves this setting |
set_channel(channel, timeout=1.0) | Selects the device's output channel: "serial" or "ble" |
tare(timeout=2.0) | Tares the unloaded glove and switches to tare_adc; serial connections only |
set_config_mode(enabled, timeout=1.0) | True enters configuration mode and pauses device sampling; False exits. Serial connections only |
BLE operation availability depends on device and firmware support. query_battery() returns a voltage: for example, 3900 means 3.9 V.
The device may still be taring when tare() returns. Keep the glove unloaded and wait for readings to stabilize before measuring.
Device information fields
| Field | Description |
|---|---|
serial_number | Device serial number; may be empty if the device does not provide one |
version | Firmware version; use xenseglovesdk.__version__ for the SDK version |
rows / cols | Pressure matrix dimensions: 63 / 39 |
hand | 0 for right hand, 1 for left hand, or None if unavailable |
frequency / ble_frequency | Serial / BLE output frame rate in Hz; the BLE rate may be 0 on devices without BLE support |
output_mode / output_mode_name | Mode number and name: 0 / adc, 1 / raw, or 3 / tare_adc |
channel | Current output channel: 0 for serial, 1 for BLE |
with_ble | Whether BLE is supported |
board_kind | Device type identifier: ble or mcu |
Switch connection types
set_channel() selects the channel through which the glove sends data. To switch your application from USB to BLE, stop reading, close the original connection, connect with open_ble(), and call set_channel("ble"). Use open() and set_channel("serial") to switch back.
Opening a connection or calling reload() preserves the device's current output mode, frame rate, and output channel. Set these explicitly as required by your application.
Reading and connection management
| Method or property | Description |
|---|---|
read_frame(timeout=1.0, data_cmd=None) | Returns the latest pressure Frame. data_cmd=None accepts any mode; pass "adc", "raw", or "tare_adc" to filter by mode. Waits when no matching frame is available and raises TimeoutError on timeout |
read_gyro(timeout=1.0, latest=True) | Returns one IMU sample. By default, takes the latest sample and discards older pending samples. latest=False takes the oldest sample. Raises TimeoutError on timeout |
read_available_gyro_samples(limit=None) | Immediately returns available IMU samples from oldest to newest. limit is a non-negative integer; 0 returns an empty list, and None retrieves up to 4096 samples |
is_connected | Read-only bool property indicating the current connection state |
stop_stream() / start_stream() | Pauses / resumes SDK data reading and clears pending pressure and IMU data. The device continues sampling, and queries and settings remain available |
reload() | Takes no arguments. Closes the existing connection, reconnects using the original connection type and serial port name or BLE address, and resumes data reading. Returns None on success; raises an exception and stays closed if reconnection fails |
close() | Closes the connection and releases resources; safe to call repeatedly |
The SDK keeps the latest pressure frame. Reading it does not remove it, and a returned frame does not change as new data arrives. read_frame() may immediately return the previous frame when no new data has arrived. See Quick Start for continuous reading.
For pressure and IMU reads, timeout=0 means no waiting. The separate IMU pending list holds up to 128 samples; the oldest samples are removed when it reaches capacity.
After changing the mode or output channel, taring, changing configuration mode, or pausing or resuming reading, wait for new data. You cannot read from a closed connection, but previously returned Frame objects remain usable.
To rebuild a connection, wait until the original port or Bluetooth device is available, call glove.reload(), then read the device information and a new frame. This method preserves the device settings and uses the original connection address. To change the connection type or address, close the existing connection and create a new one with open() or open_ble().
Use a context manager to close the connection automatically:
with XenseGlove.open("COM5") as glove:
print(glove.info().serial_number)
Replace the example port name with the actual port returned by the scan.
Frame properties and methods
read_frame() returns a Frame.
| Property | Description |
|---|---|
serial_number | Device serial number; may be empty before device information has been read |
timestamp / timestamp_ms / sequence | Host time, device time, and sequence number; see Timestamps and sequence numbers |
mode | This frame's output mode: adc, raw, or tare_adc |
rows / cols | Number of matrix rows and columns |
values / value_map / data_bytes | A flat list, nested list, and bytes; see Pressure matrix |
gyro | IMU sample attached to this frame, or None |
| Method | Return value and description |
|---|---|
get_point(row, col) | ADC integer or None at the specified position. Rows range from 0 to 62 and columns from 0 to 38. Out-of-range indices raise IndexError |
region_values(name) | Dictionary of valid region readings, keyed by one-dimensional indices in the full matrix. name is thumb, index, middle, ring, little, or palm |
total_value() | Sum of valid ADC values |
max_value() | Maximum valid ADC value, or 0 if none are valid |
mean_value() | Mean valid ADC value, or 0.0 if none are valid |
valid_points() | Number of valid points, including positions with a reading of 0 |
by_region() / by_finger() | Region or finger statistics dictionaries; see Region statistics |
contacts(threshold=1) | Contact points meeting the threshold, ordered from highest to lowest ADC |
contact_uv(threshold=1) | Normalized coordinates [u, v] of the highest contact reading, or None if no point meets the threshold |
to_text() | Text containing frame information and the matrix; invalid positions appear as * |
to_dict() | Dictionary suitable for JSON export; see Export data |
Layout queries
XenseGlove.regions() returns six region records. Each contains name, row_start, row_end, col_start, and col_end. Start indices are inclusive and end indices are exclusive, so the bounds can be used directly in Python slices.
get_glove_layout(rows=63, cols=39) returns the complete layout record. The supported dimensions are 63 × 39:
| Field | Description |
|---|---|
rows / cols / name | Row count, column count, and layout name |
active_indices / empty_indices | One-dimensional index lists for hand regions / empty positions |
palm_indices | Palm index list |
finger_indices | Mapping from finger names to index lists |
index_region | Mapping from indices to empty, finger, or palm |
index_finger | Mapping from indices to finger names; an empty string for other positions |
The layout describes region positions. Check whether a reading is None to determine its validity in a particular frame.
Error handling
| Exception | Suggested action |
|---|---|
ValueError / TypeError / OverflowError | Check parameter values, types, and ranges |
IndexError | Check whether the matrix coordinates are in range |
TimeoutError | Check the output channel, mode, and device state. If a settings operation times out, query the state before deciding whether to retry |
ConnectionError | Check the connection, port availability, drivers, and access permissions |
NotImplementedError | Confirm that the device and connection type support the requested operation |
RuntimeError | Use the error message to check the device state and firmware support |
A timeout does not necessarily mean a settings operation failed. Check the device state before reconnecting, and avoid repeatedly issuing operations such as tare.