Troubleshooting

Belt not found

Symptom: BreathBeltError: No Go Direct device found via ble

Solutions:

  • Ensure the belt is powered on (LED blinking)

  • Move the belt closer to the computer’s Bluetooth antenna

  • Try USB as a fallback: set CONNECTION = 'usb' in the config or connect the belt with the included USB cable

  • On Windows, ensure no other application (e.g., Vernier Graphical Analysis) is connected to the belt

  • Restart the belt by pressing and holding the power button

BLE fails on Windows

Symptom: BLE scanning hangs or raises a COM error

Cause: PsychoPy’s graphics backend initialises COM in STA mode, which conflicts with Bleak’s BLE scanner (requires MTA).

Solution: respyra handles this automatically by connecting the belt before importing PsychoPy. If you write custom scripts, ensure belt.start() is called before any import psychopy statement. See respyra/scripts/breath_tracking_task.py for the correct pattern.

Sensor saturation

Symptom: During range calibration, you see “Sensor Saturation Detected”

Cause: Force readings are hitting the sensor limits (0 N floor or ~40 N ceiling). The belt is likely too tight.

Solution: Loosen the belt slightly so comfortable deep breaths stay within the ~2–30 N range. Re-run the range calibration.

PsychoPy version issues

Symptom: Import errors or unexpected behavior after updating PsychoPy

Solution: respyra requires PsychoPy ≥ 2026.1.0 on Python 3.10. PsychoPy does not support Python 3.11+. Create a dedicated virtual environment:

py -3.10 -m venv .venv
.venv\Scripts\activate
pip install respyra

Dropped samples

Symptom: Fewer belt samples than expected (reported by demo_threaded_belt)

Possible causes:

  • Bluetooth interference — move other BLE devices away

  • CPU load — close unnecessary applications during experiments

  • period_ms set below 10 ms — the minimum is 10 ms (100 Hz)

Diagnosis: Run python -m respyra.demos.demo_threaded_belt and check the summary report. At 10 Hz over 10 seconds you should see ~100 samples. A gap of more than 10% triggers a warning.

Frame drops in PsychoPy

Symptom: Visual stuttering during the experiment

Solutions:

  • Set FULLSCR = True in the config (enables VSync)

  • Close other graphical applications

  • Disable desktop compositing on Linux

  • Check that monitor refresh rate matches expectations with win.recordFrameIntervals = True

Linux USB permissions

Symptom: Permission denied when connecting via USB on Linux

Solution: Add a udev rule:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="08f7", MODE="0666"' | \
    sudo tee /etc/udev/rules.d/99-godirect.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

Then unplug and replug the belt.

Data file not created

Symptom: No CSV file in data/

Solutions:

  • Check that the data/ directory exists (it’s created automatically, but verify permissions)

  • Ensure the experiment wasn’t terminated before any data was written

  • Check the console output for the filepath — it’s printed at startup