High-precision, hardware-clocked olfactometer control system for behavioral neuroscience
📚 Documentation • 🚀 Quick Start • 🔧 Installation • 📖 Examples • 🤝 Contributing
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) │
└─────────────────────────────────────┘
- Python 3.8+
- NI-DAQmx drivers (for hardware execution)
- Poetry package manager
# Clone the repository
git clone https://github.com/neurorishika/MultiBiOS.git
cd MultiBiOS
# Install dependencies using Poetry
poetry install
# Activate the virtual environment
poetry shell-
Preview a protocol (no hardware required):
poetry run python -m multibios.run_protocol \ --yaml config/example_protocol.yaml \ --hardware config/hardware.yaml \ --dry-run --interactive -
Run on hardware (requires NI-DAQ setup):
poetry run python -m multibios.run_protocol \ --yaml config/example_protocol.yaml \ --hardware config/hardware.yaml -
Run with real-time progress monitoring:
poetry run python -m multibios.run_protocol \ --yaml config/example_protocol.yaml \ --hardware config/hardware.yaml \ --verbose --progressThis 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!)
-
Analyze results:
poetry run python -m multibios.viz_protocol data/runs/latest
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 15ssequence:
- 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| Component | Description | Quantity |
|---|---|---|
| NI USB-6353 | Hardware-clocked DAQ | 1 |
| Teensy 4.1 | Microcontroller for valve control | 1 |
| TPIC6B595 | High-power shift registers | 4 |
| Olfactometer valves | Pneumatic valves (12V) | 8-16 |
| Mass flow controllers | Precision flow control | 2-4 |
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/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
🧠 Built for Neuroscience • 🔬 Made with Science • 🚀 Open Source