SerialValveController

MultiBiOS: Precision Olfactometer Control System

🧪 Overview

MultiBiOS (Multispecies Bilateral Odor delivery System) is a precision olfactometer control system designed for behavioral neuroscience experiments. It provides sub-millisecond timing control, complete experimental reproducibility, and comprehensive data logging.

✨ Key Features

• 🎯 Sub-millisecond precision with hardware-clocked timing via NI-DAQ
• 🔄 Bilateral valve control for complex comparative experiments
• 📊 Complete data provenance with comprehensive logging and replay
• 🛡️ Built-in safety guardrails prevent timing conflicts at compile-time
• 🎲 Reproducible randomization via configurable random seeds
• 📈 Interactive visualization with real-time and post-hoc analysis
• ⏱️ Real-time progress monitoring shows expected protocol state during execution
• 🔌 Teensy 4.1 firmware for microsecond-precise valve preloading
• 📝 YAML protocols for human-readable experimental descriptions

🏗️ System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   YAML Protocol │───▶│ Python Compiler │───▶│   NI-DAQ USB    │
│   Description   │    │   & Runner      │    │    6353         │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
                              ┌─────────────────────────────────────┐
                              │          Teensy 4.1 MCU             │
                              │    (Valve Pattern Preloading)      │
                              └─────────────────────────────────────┘
                                                │
                                                ▼
                              ┌─────────────────────────────────────┐
                              │       TPIC6B595 Shift Registers    │
                              │         (10MHz SPI Chain)          │
                              └─────────────────────────────────────┘
                                                │
                                                ▼
                              ┌─────────────────────────────────────┐
                              │      Olfactometer Valve Arrays     │
                              │    (8-valve bilateral control)     │
                              └─────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Conda or Miniconda
• NI-DAQmx drivers (for hardware execution)
• Spinnaker SDK 4.3.0.189 installed on Windows before installing PySpin
• If you want live Blackfly input in FicTrac on this rig, build a Spinnaker-enabled FicTrac binary and configure the fictrac block in config/hardware.yaml

Installation

# Clone the repository
git clone https://github.com/neurorishika/MultiBiOS.git
cd MultiBiOS

# Create the shared NI-DAQ + Blackfly camera environment
conda env create -f environment.yml
conda activate multibios-blackfly

# Verify the combined stack
python -c "import multibios, nidaqmx, PySpin; print('multibios-blackfly ready')"

# Optional app smoke tests
multibios-explorer --help
multibios-flow-monitor --help

This environment is intended to run both the MultiBiOS DAQ stack and the Blackfly camera scripts in one place. The rig camera model is Teledyne FLIR Blackfly S BFS-U3-13Y3M.

For live FicTrac on the Blackfly side camera, see docs/fictrac.md. MultiBiOS now prepares the Spinnaker runtime DLL path automatically before launching FicTrac, but you still need a FicTrac binary built with the upstream PGR_USB3 option.

If you are on this workstation and want the same validated build that was used for the Blackfly side camera, run:

cd C:\Rishika\MultiBiOS
.\tools\build_fictrac_spinnaker.ps1 -VcpkgRoot C:\Users\markd\vcpkg

The resulting binary is expected at assets/fictrac-spinnaker/fictrac-spinnaker.exe. The step-by-step build and usage guide lives in docs/fictrac.md.

FicTrac is treated as vendored source in this repo because MultiBiOS carries source-level patches in assets/third_party/FicTrac. The local build directory assets/third_party/FicTrac-build should remain untracked.

Your First Protocol

1. Preview a protocol (no hardware required):

     python -m multibios.run_protocol \
      --yaml protocols/example_protocol.yaml \
       --hardware config/hardware.yaml \
       --dry-run --interactive

2. Run on hardware (requires NI-DAQ setup):

     python -m multibios.run_protocol \
      --yaml protocols/example_protocol.yaml \
       --hardware config/hardware.yaml

3. Run with real-time progress monitoring:

     python -m multibios.run_protocol \
      --yaml protocols/example_protocol.yaml \
       --hardware config/hardware.yaml \
       --verbose --progress

   This displays the expected protocol state during execution:

   DO Legend: [0:RCK] [1:LOAD_REQ] [2:S0] [3:S1] [4:S2]
   AO Legend: [0:MFC1] [1:MFC2]
   [  5%] 250.0ms | DO:░█░░█ | AO:0:2.50,1:1.20
   [ 10%] 500.0ms | DO:█░█░░ | AO:0:3.00,1:1.50

   (█=HIGH, ░=LOW, shows all channels at once!)

4. Analyze results:

python -m multibios.viz_protocol data/runs/latest

## 📖 Examples

### Simple Bilateral Odor Delivery

```yaml
protocol:
name: "Bilateral Odor Comparison"
timing:
 sample_rate: 1000  # 1 kHz sampling
 seed: 42          # Reproducible randomization

sequence:
- phase: "Baseline"
 duration: 30000   # 30 seconds
 times: 1
 actions:
   - device: "olfactometer.left"
     state: "AIR"
     timing: 0
   - device: "olfactometer.right"
     state: "AIR"
     timing: 0

- phase: "Odor Presentation" 

Advanced Multi-Device Coordination

sequence:
  - phase: "Complex Trial"
    duration: 45000
    times: 10
    actions:
      # MFC setpoints
      - device: "mfc.air_left_setpoint"
        value: 2.1  # Volts
        timing: 0
      
      # Synchronized valve switching  
      - device: "olfactometer.left"
        state: "ODOR1"
        timing: 5000
      - device: "switch_valve.left"
        state: "ODOR" 
        timing: 5100  # 100ms later
        
      # Continuous camera triggers
      - device: "triggers.camera_continuous"
        state: true
        timing: 1000
      - device: "triggers.camera_continuous" 
        state: false
        timing: 40000

🔧 Hardware Setup

Required Components

Wiring Overview

NI-DAQ ────┐
           ├─── LOAD_REQ (Hardware clock)
           ├─── S-bits (Device selection) 
           ├─── Analog I/O (MFC control)
           └─── Triggers (Microscope/Camera)

Teensy ────┐
           ├─── SPI Chain (10MHz)
           ├─── Interrupt handling
           └─── Safety interlocks

TPIC6B595 ─┼─── Valve Array Left
           ├─── Valve Array Right  
           ├─── Switch Valve Left
           └─── Switch Valve Right

📋 Complete wiring diagrams and setup instructions →

📊 Data Output

MultiBiOS provides comprehensive data logging:

Generated Files

data/runs/2025-08-21_14-07-33/
├── protocol_original.yaml      # Original protocol
├── protocol_compiled.yaml      # Compiled with timing  
├── hardware_config.yaml        # Hardware configuration
├── digital_output.npy          # DO timing arrays
├── analog_output.npy           # AO setpoints
├── analog_input.csv            # MFC feedback (if recorded)
├── timing_log.csv              # Execution timestamps
└── visualization.html          # Interactive plot

Interactive Visualization

The system generates rich interactive plots showing:

• 📈 Commanded vs actual valve states
• 🎛️ Analog input/output traces
• ⏱️ Timing precision analysis
• 🔍 Zoom and pan capabilities

🧪 Use Cases

MultiBiOS is designed for:

• Behavioral choice experiments with precise odor timing
• Optogenetics with synchronized light/odor delivery
• Calcium imaging with triggered acquisition
• Electrophysiology with sub-millisecond precision
• Multi-animal comparative studies
• Reproducible protocols across labs and sessions

🛡️ Safety & Reliability

Built-in Safeguards

• ✅ Compile-time validation prevents hardware conflicts
• ✅ Timing guardrails ensure safe valve switching
• ✅ State verification with sticky S-bit monitoring
• ✅ Hardware interlocks prevent damage
• ✅ Complete logging for audit trails

Experimental Reproducibility

• 🎯 Deterministic randomization with configurable seeds
• 📝 Complete parameter logging
• 🔄 Protocol replay capability
• 📊 Timing validation and verification
• 🏷️ Version tracking of all components

📚 Documentation

Comprehensive documentation is available at neurorishika.github.io/MultiBiOS

Quick Links

• 🏗️ System Architecture
• 🔌 Hardware Setup
• 💾 Firmware Guide
• 📝 Protocol Reference
• 🏃 Runner Application
• 📈 Visualization
• ❓ FAQ
• 🔧 Troubleshooting

🤝 Contributing

We welcome contributions! MultiBiOS is built for the neuroscience community.

Ways to Contribute

• 🐛 Report bugs and request features
• 💡 Submit improvements to code or documentation
• 🧪 Share protocols and use cases
• 🔧 Hardware modifications and extensions
• 📚 Documentation improvements

Getting Started

# Fork the repository on GitHub
git clone https://github.com/yourusername/MultiBiOS.git
cd MultiBiOS

# Install development dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Format code
poetry run black multibios/
poetry run ruff check multibios/

Test And Tool Layout

• tests/ is reserved for automated pytest coverage.
• tools/manual_checks/ is for operator-facing hardware checks, probes, and bench scripts that are meant to be run directly.
• When adding new validation code, put reusable automated assertions under tests/ and keep live camera, DAQ, MFC, or FicTrac helpers under tools/manual_checks/.

For a quick automated smoke pass from the repo root, run:

pytest tests/

📖 Full contributing guide →

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

MultiBiOS was developed for the neuroscience research community. Special thanks to:

• The Ruta and Kronauer Labs for requirements and testing
• National Instruments for DAQ hardware support
• The Arduino/Teensy community for firmware foundations
• Open source contributors who make science better

📞 Contact

• Issues & Support: GitHub Issues
• Email: neurorishika@gmail.com
• Documentation: neurorishika.github.io/MultiBiOS