TeslasuitDocumentation
APIs

Haptics & EMS

The Teslasuit delivers haptic and EMS feedback through electrical stimulation across an array of electrode channels. This page covers the Python API for creating, targeting, and playing haptic effects. For the underlying concepts (what haptics is, haptic versus EMS, channels, signal parameters, calibration, comfort, and safety), see Concept - Haptics.

The haptic subsystem is accessed through the TsHapticPlayer class, which creates haptic effects, controls playback, and customises parameters such as amplitude, period, and pulse width.

⚠️ Calibrate before you stimulate. Calibrate the suit in the Control Center before any haptic or EMS API call. Amplitude is relative to the calibrated range, so calibration keeps a requested level consistent and comfortable. See Concept - Calibration.

Haptic and EMS in the API#

The same channels produce a felt sensation (haptic) at low amplitude or a muscle contraction (EMS) at high amplitude. All 80 channels can deliver haptic; EMS is only useful on channels positioned over a muscle projection. For the full explanation and the comparison table, see Concept - Haptics.

⚠️ EMS parameters on haptic channels. The API does not prevent EMS-strength effects from being applied to channels not associated with a muscle group. On a calibrated suit this is not harmful, though it may cause a strong, uncomfortable sensation or an ineffective contraction rather than useful movement. Selecting the appropriate channels for the intended effect is the developer's responsibility.

See it on the Body & channel map. Switch between the Haptic and EMS layers to see exactly which channels sit over each muscle group.

Key features of the haptic subsystem#

  1. Programmable haptic effects: Create custom effects by specifying amplitude, period, and pulse width, or by using pre-designed assets.
  2. Instant touches and playables: Both instant touches (short, parameterised effects) and playables (longer, asset-based effects that can be looped or sequenced) are supported.
  3. Channel mapping: Effects are targeted to specific body areas or channels, enabling localized sensations and complex patterns.
  4. Real-time control: Playback can be paused, muted, and scaled with multipliers at runtime.

Haptic parameters#

Haptic effects are shaped by four parameters, passed as a TsHapticParam structure:

  • Amplitude — strength of the effect as a percentage of the calibrated range (1 = minimum perceptible, 100 = maximum). Higher values produce a stronger sensation.
  • Period — duration of one signal cycle in microseconds (µs); inversely proportional to frequency (period = 1,000,000 / Hz). Supported range: 1–150 Hz (~6,667–1,000,000 µs).
  • Pulse width — duration of the active pulse within each cycle, controlling the sharpness of the sensation. Supported range: 10–140 µs.
  • Duration — how long the touch lasts in milliseconds (instant touches only; not used for asset-based playables).

For what each parameter feels like and the physiology behind it, see Concept - Haptics.

Amplitude scaling#

All amplitude values passed through the haptic API are relative to the calibrated range, not to absolute current levels. An amplitude of 100 means 100% of the maximum current established during calibration for that channel, not 100% of the hardware maximum; 1 means the minimum perceptible level recorded during calibration.

This scaling is applied automatically to every create_touch_parameters, play_touch, and playable call. There is no API parameter or flag that bypasses or overrides it.

This is a safety feature. It ensures a given amplitude value produces a consistent, safe sensation. Do not run stimulation on an uncalibrated suit, since uncalibrated values may be stronger or weaker than expected. See Concept - Calibration.

Haptic playables#

The haptic player works with two source types, both submitted as a Playable:

  • Touch — an instant, parameterised effect defined in code via create_touch_parameters. Use for short, targeted stimulation.
  • Asset — a pre-designed pattern built in the ES editor (part of Teslasuit Studio), stored as a .ts_asset file. Load it with load_asset_from_path, then pass the result to create_playable in the haptic subsystem.

Intensity control#

Two independent controls scale intensity. Global haptic power is a device-level comfort slider set in the Control Center / Device Manager, described in Concept - Haptics. The API adds multipliers that scale haptic parameters (amplitude, period, pulse width) at three levels of scope:

  • Master — applies to all active playables at once. Use to globally raise or lower intensity without changing individual effects.
  • Playable — applies to one playable independently of the master setting. Use to adjust a specific effect during playback.
  • Touch — applies to a single instant touch, leaving all other touches and playables unchanged.

Addressing the body by channel#

To keep the same code functional across suit sizes and hardware versions, haptic effects are targeted by anatomical bone rather than raw channel numbers. You select a body zone with TsBone2dIndex, and the mapper resolves it to the haptic channels the suit exposes at that location.

→ Open the Body & channel map

An interactive map of all 80 haptic channels (front · back). Click any channel to see its TsBone2dIndex bone, its channel IDs, and the exact create_touch() call to drive it.

Concepts#

Essential API references#

Interactive & visual tools#

  • Body & Channel Map: Explore an interactive visualization showing which suit channels map to which areas of the body (both haptic and EMS layers).

Practical guides & examples#

  • Play a haptic touch: A runnable script that targets a bone and plays a touch on its channels.

Previous

Overview

Next

Mocap