bioview 0.9.2

A versatile, extensible, and performant cross-platform app for biomedical and human-computer interface instrumentation control

BioView

BioView is a versatile, extensible, and performant cross-platform app for biomedical and human-computer interface instrumentation control, including Ettus USRPs and BIOPAC devices.

Features

• Real-time USRP Control: Interface with Ettus USRP devices for high-throughput transceiving
• BIOPAC Integration: Synchronized physiological data collection alongside RF measurements
  • You must already possess a copy of the BIOPAC Hardware API purchased from BIOPAC Systems Inc. for this to work
• Live Data Visualization: Sensor data is visualized in real-time
• Synchronized Data Acquisition: Save synchronized hardware data streams with precise timing control
• Experiment Management: Configure and control experimental routines and settings
• Event Annotation: Mark and annotate events during data collection
• Multi-format Data Storage: Flexible data saving with multiple format support

Installation

BioView should run on all platforms but is officially supported on the following platforms -

• Windows
• Linux: Ubuntu LTS, Debian, and derivative distributions.
  • Fedora and RHEL based distributions do not bundle in Python bindings for uhd and require manually buildng from source.
  • Non-LTS versions of Ubuntu are not supported due to missing packages.

Dependencies

• Python: Ensure Python 3.12 is installed on your system. For Windows, use the Microsoft Store app instead of the website executable.
• UHD: You can install it by following the official instructions for your operating system.
• UHD Python Bindings (Linux users only): For Ubuntu/Debian users, python bindings are installed using sudo apt install python3-uhd. For RHEL/Fedora users, these need to be manually generated by building from source.

Once all the dependencies are installed, installing BioView is as simple as running pip install bioview. We recommend running this command in a virtual environment so as to not pollute your operating system Python.

Usage

In order to run an experiment using bioview, you need to create an executable file similar to the example below -

import sys 
import faulthandler

from bioview.app import Viewer
from bioview.types import UsrpConfiguration, ExperimentConfiguration, BiopacConfiguration

from PyQt6.QtWidgets import QApplication

# Usually a good idea to have a crash log 
faulthandler.enable(open('crash.log', 'w'), all_threads=True)

# Experiment variables 
exp_config = ExperimentConfiguration(
    save_dir = '/home',
    file_name = 'example', 
    save_ds = 100,    
    disp_ds = 10, 
    disp_filter_spec = {
        'bounds': 10,
        'btype': 'low',
        'ftype': 'butter' 
    },
    disp_channels = ['Tx1Rx1', 'Tx2Rx2', 'Tx1Rx2', 'Tx2Rx1'],
)

# USRP variables 
usrp = UsrpConfiguration(
    device_name = 'MyB210_4', 
    if_freq = [100e3, 110e3],
    if_bandwidth = 5e3, 
    rx_gain = [25, 35], 
    tx_gain = [43, 37], 
    samp_rate = 1e6, 
    carrier_freq = 9e8,
)

# Biopac Control
bio = BiopacConfiguration(
    device_name = 'MyBIOPAC', 
    channels = [1, 1, 0, 0]
)

# Run application
app = QApplication(sys.argv)

window = Viewer(exp_config=exp_config,
                usrp_config=[usrp], 
                bio_config=bio)
window.show()

sys.exit(app.exec())

Performance Considerations

• Real-time data acquisition requires sufficient system resources
• Large data streams may require SSD storage for optimal performance
• Memory usage scales with buffer sizes and visualization complexity. Visualization is kept efficient by only updating data streams for source that are actually visible
• Spikes may occur in the data if receive buffer is kept low in size due to filtering edge effects
• B210 devices work poorly with default frame sizes, which is why default receive frame size has been kept at 1024

Troubleshooting

Common issues and solutions:

1. USRP Device Not Detected: Verify hardware connections and driver installation
2. High CPU Usage: Adjust buffer sizes and visualization update rates
3. Data Loss: Check storage write speeds and available disk space
4. Synchronization Issues: Verify system clock accuracy and BIOPAC timing

Check crash.log for detailed error information and diagnostic data.

Development

Structure

bioview/
├── app.py              # Main application
├── usrp/               # USRP core functionality
├── common/             # Common functionality
├── components/         # GUI components
├── biopac/             # BIOPAC integration
├── utils/              # Utility functions
├── types/              # Custom data-types 
└── constants/          # App-specific constants

Instructions

Contributing changes requires you to have git installed in your system to be able to install the editable version of the app. In a terminal window, follow the steps listed below. On Windows, use Git Bash for this. On Linux and macOS, use the native terminal app.

# Clone repository 
cd ~ 
git clone https://github.com/meowkash/bioview.git 

# Run installer script
cd bioview
chmod +x install.sh
./install.sh 

Ensure you make your changes in forks and submit PRs for review.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for the complete license text.