MultiBiOS: Precision Olfactometer Control System

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.

• 🎯 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

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 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) │
 └─────────────────────────────────────┘

• 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

# 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.

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" 
 duration: 60000 # 1 minute per trial
 times: 5 # 5 trials
 randomize: true # Randomize odor order
 actions:
 - device: "olfactometer.left"
 state: "ODOR1,ODOR2,ODOR3" # Random selection
 timing: 10000 # 10s into trial
 - device: "triggers.microscope"
 state: true
 timing: 15000 # Trigger at 15s

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

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 →

MultiBiOS provides comprehensive data logging:

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

The system generates rich interactive plots showing:

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

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

• ✅ 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

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

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

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

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

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

# 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/

• 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 →

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

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

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