Getting started

Take your first steps with the Teslasuit Python API — from setting up your environment to running your first haptic interaction.

Requirements#

Install the SDK#

1. Prepare the package#

The SDK ships with Teslasuit Studio, so make sure it is installed and on the desired target version. Then run the commands below in PowerShell to copy the API into your user profile.

$dest = "$env:LOCALAPPDATA\Teslasuit\python_api"
# Mirror the SDK from Teslasuit Studio into your user profile
robocopy "C:\Program Files\Teslasuit\Studio\python_api" $dest /mir /njh /njs
# Create empty README.md (required by pip)
New-Item "$dest\README.md" -ItemType File -Force | Out-Null

Re-run this block after any Studio update to refresh the python_api to the latest version.

2. Install into each environment#

With your target Python environment active, install the prepared package:

pip install "$env:LOCALAPPDATA\Teslasuit\python_api"

Configure the native library path#

TsApi needs the native teslasuit_api.dll that ships with Teslasuit Studio. Studio normally registers it in your system environment variables on install, so no setup is required:

from teslasuit_sdk import ts_api

api = ts_api.TsApi()  # library found automatically

If the import instead fails with the error below, those variables were not set (common on non-admin installs). Fix it with either option.

Set the variables yourself#

User-level, so no admin is needed; restart any open terminals afterwards:

[Environment]::SetEnvironmentVariable("TESLASUIT_API_LIB_PATH", "C:\Program Files\Teslasuit\Studio\teslasuit_api.dll", "User")
[Environment]::SetEnvironmentVariable("TESLASUIT_INSTALL_DIR", "C:\Program Files\Teslasuit\Studio", "User")
[Environment]::SetEnvironmentVariable("TESLASUIT_PYTHON_API_PATH", "C:\Program Files\Teslasuit\Studio\python_api", "User")

Or pass the path in code#

from teslasuit_sdk import ts_api

api = ts_api.TsApi(lib_path=r"C:\Program Files\Teslasuit\Studio\teslasuit_api.dll")

No environment changes needed, and it also covers a non-default install location: just point lib_path at your .dll. Note that this hardcodes a machine-specific path into your script, so it is less portable; prefer the environment variables for code you share or run across setups.

Connect to a device#

Device connection is managed by Teslasuit Control Center (CC), not by your Python script. The Python API can only reach a device that is already connected and active in Control Center — there is no way to initiate or maintain a connection from code alone.

Before running any Python script:

1. Open Teslasuit Control Center.
2. Connect your device and wait for it to appear as active.
3. Complete the calibration procedure in Control Center. Subsystems such as haptic and mocap will not produce correct output on an uncalibrated device.

Once the device is connected and calibrated in Control Center, the Python API can discover it:

from teslasuit_sdk import ts_api

api = ts_api.TsApi()
device = api.get_device_manager().get_or_wait_last_device_attached()
print("Connected:", device)

get_or_wait_last_device_attached() blocks until a Teslasuit device is available, then returns the most recently connected one. If you have multiple suits or gloves connected at the same time, see Selecting a specific device in the Device Manager reference.

Access a subsystem#

Each device exposes its subsystems as attributes:

haptic = device.haptic  # TsHapticPlayer
mocap = device.mocap  # TsMocap
ppg = device.ppg  # TsPpg
mapper = api.mapper  # bone <-> channel mapping

Next#

Once you have a connected device, here is a suggested reading flow through the rest of the documentation.

1. Run something end-to-end — Examples#

Get a feel for the API by running a complete, minimal program on real hardware:

• Examples · Overview — every runnable script, grouped by subsystem.
• Play a haptic touch — play your first touch on the suit.
• Read heart rate — read live heart rate from a photoplethysmography (PPG) node.
• Measure HRV — read the Mean inter-beat interval, a heart rate variability (HRV) metric, from the PPG sensor.
• Stream motion data — stream skeleton data and biomechanical angles.

2. Understand what you just ran — Main concepts#

Each subsystem has a concept page that explains what it senses or does, and the vocabulary the rest of the reference assumes:

• Main concepts · Overview — a map of the XR5 subsystems with a per-topic reading list.
• Haptics & EMS — programmable electrical stimulation, from light touch sensations to EMS-driven muscle contractions and FES.
• Mocap — full-body motion capture from the suit's inertial measurement units (IMUs): skeleton, raw IMU, and biomechanical angles.
• PPG — optical heart-rate sensing, with HRV and raw pulse signals.
• Body & channel map — interactive map of which channels drive which body zones and muscles, with a copy-pasteable haptic snippet.

3. Look things up — API reference#

When you know what you want to build, the reference covers the SDK class by class. It is split into two layers:

API · Core — the layer above subsystems (connecting devices, mapping, shared types):

• Core · Overview — how TsApi, the device manager and the mapper fit together, with the full inheritance diagram.
• TsApi — the central entry point that loads the C library and owns the other managers.
• Device manager — discover, attach and select connected devices.
• Device — a single Teslasuit device and the subsystems it exposes.
• Mapper — bone ↔ channel mapping and the 2D layout used by the body map.
• Asset manager — load, retrieve and unload haptic assets and animations.
• Data structures — the shared types and enums used across every subsystem.

API · Subsystems — one class per device capability:

• Haptic — create, play and control haptic touches and playables.
• Mocap — stream raw IMU, skeleton and biomechanical data.
• PPG — access raw, heart-rate and HRV biometric data.