Zepyhr BioHarness LSL Integration

This is an LSL adapter for Medtronic / Zephyr BioModule and BioHarness Bluetooth devices. If you encounter any issues with this program, please use the GitHub issue tracker for this project to report them.

Prerequisites

• Linux: make sure that you have Bluetooth development headers installed (e.g. on Ubuntu 20.04: sudo apt install libbluetooth-dev)
• Every Platform: make sure that you have Miniconda installed and that the conda command-line interface is on your path

Since the Zephyr uses Bluetooth Low Energy (BLE), your machine needs to have the necessary wireless hardware installed (either built in as with many recent laptops, or using a BLE-capable USB dongle).

Installing/Running

• Windows: Invoke the script run.cmd, which will, if necessary, create a fresh Python environment and install the necessary dependencies into it
• Linux/MacOS: Invoke the script run.sh, which will, if necessary, create a fresh Python environment and install the necessary dependencies into it
• Alternative manual install: you can also follow the instructions in conda-environment.yml to install a Python environment yourself or to add the necessary requirements to an existing environment, and then you can use that interpreter to run main.py

Usage

1. Switch on the sensor using the button (it should either blink orange or have a constant orange LED).
2. Optionally configure the device using the tools provided with the device (e.g., set subject info, device clock, configure logging, and so on).
3. Optionally check that you can access the device from a vendor-provided desktop software (e.g., the one used to retrieve log files), particularly if this program appears unable to connect by itself.
4. Run this application, optionally with command-line arguments, to stream real-time data over LSL. No other software is necessary to interface with the device.
   • if you know the Bluetooth MAC address of the device (e.g., from a prior run), you can specify that via the command line as in --address=12:34:56:78:9A to speed up the startup time
   • you can additionally override what modalities you want to stream using the --stream argument (using fewer than all might extend the device's battery running time). See Emitted Streams for a brief summary, and the vendor documentation for the full details. By default, everything is streamed, which is equivalent to the argument --stream=ecg,respiration,accel100mg,accel,rtor,events,summary,general.
   • if you have multiple devices, it can be a good idea to use the --streamprefix argument to prefix the stream name with a string of your choice (e.g., --streamprefix=Subject1) to disambiguate multiple devices.
   • additional command-line arguments are available to further customize the program's behavior, for further information on these, run the program with the --help argument

Emitted Streams

The following streams can be generated by the application (assuming here the Zephyr stream name prefix). See vendor manual for full details.

• ZephyrECG the raw ECG waveform, in mV at 250 Hz (1 channel).
• ZephyrResp the raw respiration (breathing) waveform, measuring chest expansion, at ca. 17.8 Hz, in unscaled units.
• ZephyrAccel100mg a 3-channel stream with acceleration along X, Y, and Z axes (coordinate system is configurable via vendor tools) at 50Hz, in units of g (earth acceleration).
• ZephyrAccel same as Accel100mg, but higher numeric precision (>2x), in unscaled units.
• ZephyrRtoR the interval between the most recent two ECG R-waves, in ms, at ca. 17.8 Hz. The value is held constant until the next R-wave is detected, and alternates the sign with each new incoming R-wave.
• ZephyrMarkers a marker stream with some device events (e.g., button pressed, battery low, worn status changed and a handful of others, along with some event-specific numeric payload).
• ZephyrSummary summary metrics calculated at 1Hz. This has over 60 channels, including things like heart rate, respiration rate (beats/breaths per minute), HRV, various accelerometer-derived measures, confidence measures, and some system status channels, among others.
• ZephyrGeneral an alternative set of summary metrics (subset of summary, plus a handful of channels of limited utility).

Acknowledgements

This open-source LSL application was developed and is maintained by Intheon (www.intheon.io).

For support inquiries please file a GitHub issue on this repo (preferred) or contact support@intheon.io.

Copyright (C) 2020-2021 Syntrogi Inc. dba Intheon.

This work was funded by the Army Research Laboratory under Cooperative Agreement Number W911NF-10-2-0022.

Known Issues

Python's Bluetooth (LE) support on current Mac OS appears to be in an incomplete and/or broken state at this point, and this application is known to not run on Mac OS Big Sur, neither with conda's Python 3.7 nor the default Python 3.7, or with PyBlueZ 0.23 or its current GitHub version (PyBlueZ 0.30). Older Mac OS versions might work but have not been tested.