TeslasuitDocumentation
APIs

Haptics & EMS

The Teslasuit delivers haptic and EMS feedback through electrical stimulation across an array of electrode channels. This page covers the C 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 ts_haptic_api.h header, 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. The tool is Python-first, but the channel-to-bone mapping it shows is identical for the C API.

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 ts_haptic_create_touch, ts_haptic_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 ts_haptic_create_touch. 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 ts_asset_load_from_path, then pass the result to ts_haptic_create_playable_from_asset in the Haptic API.

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 TsBoneIndex, and the Mapping API 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 bone and channel IDs. The tool is Python-first and its code snippets use the Python API, but the bone-to-channel mapping it shows is the same one the C API's TsBoneIndex and ts_haptic_create_touch() resolve to.

Concepts#

Essential API references#

  • Haptic API Reference: Technical documentation for interacting with and customizing the haptic system.
  • Common Types: In-depth information about the data types and structures used in haptic programming.
  • Mapping API: Learn about mapping body zones (bones) to physical haptic channels.
  • API: TsBoneIndex Enum: Details on referencing anatomical targets across different suit types.
  • Asset API: Load, retrieve and unload haptic assets and animations for playback.

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). Python-first tool, but the mapping is the same for the C API.

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