Concepts Overview

The closed-loop in one diagram#

   ┌─────────────────────── Backend subprocess ──────────────────────┐
   │                                                                 │
   │   Teslasuit ──▶ SuitHandler ──▶ DataStreamer ──┐                │
   │   hardware                     (collect/process│                │
   │                                 /distribute)   │                │
   │                                                ▼                │
   │                                        ┌─── self.joints         │
   │                                        ├─── self.contacts       │
   │                  ControlStrategyBase ◀─┤── self.params          │
   │                  .process()            ├─── self.external_data ◀──── ExternalInputManager
   │                                        └─── self.muscles            (LSL inlets)
   │                                                │                │
   │                                                ▼                │
   │                                        self.ems_output          │
   │                                                │                │
   │                       FES kill switch ─▶ Stimulator ──▶ MuscleMap
   │                       (UtilityMessage)         │       ──▶ Teslasuit
   │                                                │       (haptic SDK)
   │                                                ▼                │
   │                                        LSLStreamer ──▶ LSL outlets
   │                                                                 │
   └─────────────────────────────────┬───────────────────────────────┘
                                     │ multiprocessing.Queue, SharedRingBuffer
                                     │
   ┌─────────────────────────────────▼───────────────────────────────┐
   │                  Main process (optional GUI)                    │
   │   PyQt5 widgets   ──▶  control_queue   (parameters)             │
   │                   ◀── utility_queue   (status flags)            │
   │                   ◀── SharedRingBuffer (sensor data, ~30 Hz)    │
   └─────────────────────────────────────────────────────────────────┘

What each piece does#

Read these one-pagers in any order. Each follows the same shape: what it is, why it exists, when you touch it, a code snippet, and links into the API reference.

Hardware and data acquisition (input)#

• SuitHandler — manages the Teslasuit connection, exposes the haptic / mocap / PPG subsystems and the MuscleMap. The framework auto-creates one; you rarely instantiate it.
• DataStreamer — runs the three-phase collect → process → distribute cycle each iteration. Override process() only for custom signal pre-processing.
• Data Types — the typed dataclasses (BiomechanicalData, EmsData, StepDetectorData, …) that flow through the system.
• MuscleMap — anatomical name → SDK channel ID. Loaded from muscle_map_4R.json at startup; accessed via self.muscles in your strategy.

Control (your code)#

• ControlStrategyBase — the user extension point. Subclass it, implement process(). This is where 95% of application code lives.
• ClosedLoopEngine — the orchestrator. It runs the cycle and offers lifecycle hooks (on_start, on_stop, on_cycle_complete).

Output#

• Stimulator — translates EmsData to Teslasuit haptic SDK calls via MuscleMap. The FES kill switch is enforced here.
• LSL Streaming — 7 LSL outlets at 100 Hz for lab integration (LabRecorder, MATLAB, Python). Off by default.

Cross-cutting#

• Calibration — trigger and quality assessment. Typically gated in on_start().
• Messaging — ControlMessage (per-app params), UtilityMessage (system flags), HapticLibrary (custom playables).
• IPC and processes — SharedRingBuffer and multiprocessing.Queue between backend and GUI.
• Safety — kill switch, calibration gating, shutdown guarantees.
• Architecture — the multi-process design and full data-flow diagram.

Per-cycle flow#

Every iteration of the engine's main loop, in order:

The hardware governs timing. There is no software clock.

What you typically write#

For most applications, three files:

my_app/
├── strategy.py         # subclass ControlStrategyBase, implement process()
├── messages.py         # subclass ControlMessage to declare your parameters
└── main.py             # call orchestrator.launch(MyStrategy)

If you add a GUI, two more:

├── engine.py           # subclass ClosedLoopEngine, override on_start / on_cycle_complete
└── gui/                # PyQt5 widgets that read SharedRingBuffer / send to queues

That's it. The framework handles everything else.

See Project anatomy for a complete tour of how a real application is laid out.

What you typically don't write#

When to step outside the defaults#

Each of these is documented as a step in the Implementation Guide.

Mental model checklist#

Before writing your own application, you should be able to answer:

1. What does my strategy read each cycle? (joints, contacts, params, external_data)
2. What does my strategy write? (ems_output)
3. Where does the timing come from? (Teslasuit SDK; never time.sleep)
4. Where is the FES kill switch? (UtilityMessage.FesIsActive, framework-applied)
5. Where do my parameters come from? (ControlMessage subclass, sent via the GUI's queue)
6. What are the two processes? (backend = engine; main = GUI or just wait())

If any of those don't have a one-line answer yet, read the page that covers it.

Next#

Choose your path:

• Start the Implementation Guide and build an application step by step.
• Drill into any concept above.
• Look up an API in the API Reference.