Step 9 — Full application

What you're adding#

Nothing new. This step is a guided tour of the application you've built across the previous 8 steps, plus pointers to where each concern lives in the code. Use it as a checklist when you start your own application.

If you've been writing code along with the steps, your project should look something like this:

my_fes_app/
├── app/
│   ├── __init__.py
│   ├── strategy.py            (Steps 1–6)  ControlStrategyBase subclass
│   ├── messages.py            (Step 5)     MyControlMessage subclass
│   ├── engine.py              (Steps 4–5)  CalibratedParamEngine subclass
│   └── gui/                   (Step 8)
│       ├── __init__.py
│       ├── main_window.py
│       ├── data_handler.py
│       └── widgets/
└── main.py                    (Steps 1–7)  launch()

End-to-end flow#

Walk through what happens when the operator launches the application:

Process 1 — Launcher (main.py)#

1. launch() is called with MyStrategy, engine_class, lsl_enabled, external_input_streams, etc.
2. multiprocessing.Queue instances are created (control_queue, utility_queue).
3. A backend subprocess is forked running run_engine_process(MyStrategy, ...).
4. (If a GUI is configured) a GUI process is forked too.
5. The launcher's main thread waits on Ctrl-C / process exit.

Process 2 — Backend (run_engine_process)#

1. ExternalInputManager is built in-process for any registered LSL streams (Step 6).
2. MyEngine (your ClosedLoopEngine subclass) is instantiated.
3. The engine auto-creates SuitHandler (which connects to the suit and loads MuscleMap), DataStreamer, Stimulator, LSLStreamer, QueueHandler.
4. engine.run() enters the main loop:
   • strategy.setup(muscles, suit) is called once.
   • on_start() fires — calibration gate runs (Step 4).
   • The 10-step per-cycle pipeline runs at ~100 Hz.
5. On Ctrl-C or STOP_SENTINEL:
   • on_stop() runs (try/except — wrapped).
   • _cleanup() stops mocap, mutes EMS, closes inlets.

Process 3 — GUI (gui_runner, optional)#

1. PyQt5 QApplication is created.
2. MainWindow builds the widgets.
3. A DataHandler attaches to the SharedRingBuffer to read sensor frames at 30 Hz.
4. A QueueHandler listens on utility_queue and pushes onto control_queue.
5. The Qt event loop runs until the window is closed.

Cycle-by-cycle (inside engine.run())#

1. data_streamer.run_cycle()                         ── collect/process/distribute
2. control_strategy.external_data = ext.pull_all()   ── LSL inlets (Step 6)
3. queue_handler.poll_queues()                       ── new ControlMessage / UtilityMessage
4. control_strategy.run_strategy(...)                ── your process(); FES kill switch applied
5. stimulator.run_stimulator(...)                    ── EMS output to SDK
6. (if haptic_library)
   library_stimulator.run_stimulator(...)            ── custom haptic playables
7. lsl_streamer.stream_all_data(...)                 ── 7 outlets pushed
8. on_cycle_complete()                               ── your hook; write SharedRingBuffer

Where each concern lives in your code#

This is the canonical layout. Every full example (examples/elbow_flexion/, examples/haptic_navigation/, examples/haptic_proximity_radar/, examples/vestibular_training/) follows it. When you start a new application, copy examples/elbow_flexion/ and modify in place — it's the closest thing to a project template.

What you can change without breaking things#

What you should NOT change without thinking carefully#

A debugging checklist#

If your full application is misbehaving, walk through this list in order:

1. Is the framework running at all? Look for [MyStrategy] cycle N lines incrementing.
2. Is calibration succeeding? Look for the [CalibratedEngine] quality=... line. If quality is low, see Calibration → Quality checks.
3. Are sensors changing? Print self.joints.KneeFlexExtR and confirm it moves with the user. If not, check set_biomech_collection(True).
4. Is the strategy seeing the right inputs? Print self.params on the first cycle to confirm your MyControlMessage is wired up.
5. Is stimulation being delivered? Print self.ems_output.<muscle> after assignment. If IsMuted=False but you feel nothing, check UtilityMessage.FesIsActive (the kill switch) and the device's enable state.
6. Is the LSL streamer running? Run pylsl.resolve_streams() in another shell and confirm the 7 outlets appear.
7. Is the GUI talking to the backend? Move a slider and look for [engine] on_control_message in the log. If silent, the queue isn't being drained — check that you passed control_queue= to launch().

Reading the example applications#

Each of these is a complete working application built on the patterns from this guide:

Read them in that order. By the time you've read them all, you'll have seen every framework feature in use. All examples are in the RapidKit repository.

Where the framework grows from here#

Things you might find yourself wanting:

• More muscles — extend MuscleMap config + EmsData dataclass.
• Custom sensors — register them as LSL inlets (Step 6) or subclass DataStreamer to read them in-process.
• Different hardware — swap the MuscleMap JSON config (the framework supports Teslasuit 4.x and XR5; ship the JSON that matches the suit on the bench).
• Custom haptic patterns — HapticLibrary subclass + setup() factories. See Messaging — HapticLibrary.
• Real-time analytics — override on_cycle_complete() to push to a metrics sink. Don't block the loop.
• Multi-session orchestration — the framework runs one engine per process; for parallel sessions, fork additional backends with distinct LSL source_ids.

What you've learned#

• The full per-cycle pipeline, from collect → through process → to stimulate.
• Where each concern lives in a typical project layout.
• What you can safely change vs. what to leave alone.
• A debugging order to follow when something goes wrong.

Beyond this guide#

You're done with the linear path. From here:

• Browse the Examples — pick one closest to your application and start from it.
• Use the API Reference as your daily lookup.

Build something with it.