Frameworks

Glossary

Terms used throughout the documentation, grouped by topic. Skim this once before reading the concept pages — it covers the FES, biomechanics, and Teslasuit-specific vocabulary the rest of the docs assume.

Functional Electrical Stimulation (FES)#

FES — Functional Electrical Stimulation Application of electrical pulses to peripheral nerves or muscles to produce a functional movement (a step, a grasp, a stand). Distinguished from EMS used purely for rehabilitation strengthening or aesthetic toning, where the goal is the contraction itself rather than a useful movement.

EMS — Electrical Muscle Stimulation The general term for delivering electrical pulses to muscles. FES is a subset of EMS aimed at producing functional movement. The Teslasuit SDK calls all stimulation "EMS"; the framework follows that terminology.

Closed-loop Control architecture in which sensor data influences the next stimulation decision. The "loop" is closed by the user's body: sensors observe the response, the algorithm reacts, the next pulse is informed by what just happened. Contrast with open-loop, where stimulation follows a pre-defined script regardless of sensor state.

Stance phase / Swing phase The two halves of a gait cycle. Stance = foot in contact with the ground (60% of the cycle at typical walking speeds). Swing = foot in the air. Many walking-FES strategies key their stimulation to these phases.

Stimulation parameters A pulse train is described by three numbers:

Amplitude (% in the framework, mapped to mA in the SDK): intensity of each pulse.
Pulse width (μs): duration of each pulse.
Period (ms): time between pulse onsets. 1000 / Period is the pulse frequency in Hz.

A typical FES setting is Amplitude=40, PulseWidth=120, Period=20.0 (50 Hz) — start there, adjust upward only with caution.

I-pose Default reference pose for Teslasuit calibration: standing upright, feet shoulder-width apart, arms straight at the sides, head facing forward, still. The calibration routine captures one frame in this pose and uses it as the reference orientation for every joint angle thereafter.

Biomechanics#

Joint angles Angles between adjacent body segments, measured in degrees. The framework exposes 29 of them via BiomechanicalData, named in PascalCase with a suffix indicating side (L / R):

HipFlexExtL — left hip flexion/extension
KneeFlexExtR — right knee flexion/extension
AnkleFlexExtL — left ankle dorsi/plantar flexion
ShoulderAddAbdR — right shoulder adduction/abduction
ElbowFlexExtL — left elbow flexion/extension
… (full list in Data Types Reference)

Bone A rigid body segment in the Teslasuit skeleton model. There are 20 of them (pelvis, spine, chest, neck, head, plus the four limbs each broken into 3–4 segments). Each bone has a 3D position and a quaternion orientation, exposed via ProcessedData.

Foot contact Boolean state: is the foot currently bearing weight on the ground? Sourced from the Teslasuit SDK's built-in step detector. Exposed via StepDetectorData.left_foot_contact and .right_foot_contact.

Mocap — Motion capture The Teslasuit's IMU-based skeletal tracking subsystem. Produces BiomechanicalData (joint angles), ProcessedData (bone positions and rotations), and RawData (raw IMU readings) at ~100 Hz.

PPG — Photoplethysmography Optical heart-rate sensor on the Teslasuit. When available, produces HeartRateData, HRVData (heart-rate variability), and RawPPGData. The framework auto-detects whether PPG is available and only streams those outlets when present.

IMU — Inertial Measurement Unit A combined accelerometer + gyroscope + (optional) magnetometer chip. Each Teslasuit body segment has one. Their fused outputs become the mocap skeleton.

Teslasuit hardware#

Teslasuit Control Center The companion Windows application that brokers the connection between the suit and the host computer (via WiFi). Must be installed and running whenever any RapidKit application is running.

Hardware version (4.x, XR5) Teslasuit ships in different generations with different node and channel layouts. The framework supports versions 4.x and XR5 via different MuscleMap JSON configs. The default config that ships with the package is muscle_map_4R.json (covers the 4.x family).

Node A physical Teslasuit electronics module. Each node hosts multiple haptic / EMS channels. Users do not address nodes directly — the MuscleMap translates anatomical names into node + channel IDs.

Channel A single electrode pair on the suit, capable of delivering one independent EMS signal. The Teslasuit 4.x configuration exposes about 80 channels mapped across 20 muscles; XR5 exposes a comparable layout via its own MuscleMap JSON.

Looped playable / Asset Teslasuit SDK abstractions for delivering haptic patterns. A playable is a single haptic event (a touch, a buzz). A looped playable is one that repeats automatically until muted. The Stimulator translates EmsData writes into looped playables; the LibraryStimulator manages user-defined haptic libraries.

Framework concepts#

ControlStrategy The user's per-application algorithm. A subclass of ControlStrategyBase implementing process(). Receives sensor data on self, writes stimulation commands to self.ems_output.

ClosedLoopEngine The top-level orchestrator that runs the per-cycle pipeline. Owns the SuitHandler, DataStreamer, Stimulator, LSLStreamer, and QueueHandler. Subclassed when a user wants to add lifecycle hooks (on_start, on_stop, on_cycle_complete).

SuitHandler Thin layer over the Teslasuit SDK. Owns the connection, exposes mocap_streamer, haptic_player, and ppg_streamer, and holds the MuscleMap. Auto-created by the engine — users rarely instantiate it directly.

DataStreamer The input layer. Each cycle: collect raw frames from the SDK, parse into typed dataclasses, distribute to LSL and shared memory. Users override process() only when they need custom signal processing (filtering, derived signals, custom step detection).

Stimulator The output layer. Each cycle: read EmsData, translate via MuscleMap into SDK haptic calls, manage looped playables. The global FES kill switch (FesIsActive) is enforced here.

MuscleMap The semantic muscle ↔ hardware lookup table. Loaded from muscle_map_4R.json at startup. Provides by_side(), by_region(), and channel resolution APIs. Accessible from a strategy via self.muscles.

LSLStreamer The Lab Streaming Layer outlet manager. Provides 7 outlets at 100 Hz: biomechanics, step detector, EMS parameters, control message, utility message, bone position, raw data. Off by default; opt in via lsl_enabled=True.

ExternalInputManager The LSL inlet manager. Lets a strategy receive data from external devices (force plate, EEG, optical mocap) on its self.external_data dict. Must be configured at engine construction time.

ControlMessage / UtilityMessage / HapticLibrary Three dataclass families that flow through IPC queues:

ControlMessage — application parameters (subclass to add fields).
UtilityMessage — system flags (FES on/off, recording, calibration).
HapticLibrary — named haptic playable slots (subclass to add slots).

SharedRingBuffer Lock-free circular buffer in shared memory. Backend writes one frame per cycle (~100 Hz); GUI reads the latest N frames at ~30 Hz. Used for high-frequency data streaming where queues would be too slow.

QueueHandler The IPC poller. Drains control_queue and utility_queue each cycle, keeps the most recent message of each type, calls on_control_message / on_utility_message hooks.

FES Active / Kill switch The global stimulation enable bit, stored as UtilityMessage.FesIsActive. When False, the engine writes muted EMSParamData to every muscle regardless of what process() produced. The strategy never needs to check this flag — the framework enforces it.

Calibration A one-time SDK procedure capturing a reference frame in I-pose. The framework wraps it in CalibrationAPI with a quality assessment (overall_score, is_acceptable, per-sensor checks).

LSL (Lab Streaming Layer)#

LSL — Lab Streaming Layer Open-source protocol for synchronised data exchange across the lab. The framework supports it natively as both a data source (outlets) and a data sink (inlets).

Outlet / Inlet LSL terminology. An outlet publishes data; an inlet consumes it. The framework provides 7 outlets via LSLStreamer and accepts arbitrary inlets via ExternalInputManager.

LabRecorder Standard LSL recording GUI (download). Records all visible LSL streams to a single XDF file with synchronised timestamps.

XDF — Extensible Data Format The file format LabRecorder writes. Loadable in Python via pyxdf, in MATLAB via the LSL toolbox.

Source ID A string that identifies a specific instance of an LSL stream ({source_id}_biomech, {source_id}_steps, ...). Useful when running multiple sessions in parallel — set distinct source_ids to keep recordings separate.

Project / process#

MoSCoW Prioritisation scheme used in the PRD: Must-have, Should-have, Could-have, Won't-have-this-time.

Product forms RapidKit is delivered in two forms:

Standalone application executables, such as the Walking FES demo.
The RapidKit Python module (the primary product), which those applications build on. See Audience and use cases.

T2.x Internal task identifiers from the development plan (e.g. T2.5 = the muscle map task). They appear in commit messages and design notes; you don't need them to use the framework, but they're useful when reading the context/ documents.

Walking FES The original walking-FES research project from which RapidKit was extracted. Lives at examples/walking_fes/. Used as the canonical "complete application" example throughout the docs.

Acronyms quick reference#

Term	Meaning
FES	Functional Electrical Stimulation
EMS	Electrical Muscle Stimulation
IMU	Inertial Measurement Unit
Mocap	Motion Capture
PPG	Photoplethysmography (optical heart-rate sensor)
HRV	Heart Rate Variability
LSL	Lab Streaming Layer
XDF	Extensible Data Format (LSL recording format)
ABC	Abstract Base Class (Python)
GUI	Graphical User Interface
IPC	Inter-Process Communication
MoSCoW	Must / Should / Could / Won't (prioritisation)
GDPR	General Data Protection Regulation
SDK	Software Development Kit
GRF	Ground Reaction Force (force-plate measurement)
EEG	Electroencephalography

Design principles

Installation