OBzip

OBzip is a MATLAB/Teensy-based behavioral experiment control framework for odor-guided mouse behavior experiments.

The system coordinates trial logic, odor and reward control, Teensy serial communication, sniff/lick signal acquisition, real-time plotting, GUI-based experiment control, camera preview, and automated session-level data logging.

This repository demonstrates hardware-software integration for behavioral neuroscience experiments, with an object-oriented MATLAB architecture designed for flexible odor discrimination and early-training protocols.

---

Overview

OBzip was designed to control and monitor mouse behavioral experiments involving odor stimulation, licking behavior, reward delivery, sniff/lick analog signals, and real-time performance tracking.

The framework connects MATLAB to a Teensy microcontroller running custom firmware. MATLAB manages experiment parameters, trial logic, GUI interaction, plotting, and data saving, while the Teensy handles low-level timing, valve/reward control, event detection, and analog signal acquisition.

The system is organized around modular MATLAB classes so that each major component of the experiment has a separate responsibility.

---

Key Features

• Object-oriented MATLAB experiment control framework
• GUI-based control of odor discrimination and early-training protocols
• Real-time Teensy/MATLAB serial communication
• Trial parameter transmission from MATLAB to Teensy
• Event packet parsing from Teensy to MATLAB
• Analog packet parsing for sniff and lick-related signals
• Automated trial-level and session-level data logging
• Real-time plotting of behavioral performance and sniff/lick signals
• USB camera preview support
• Modular structure for future extension to additional behavioral protocols

---

System Architecture

The framework is organized into several key MATLAB classes.

Class	Role
MouseBehaviorController	Main experiment controller. Manages experiment logic, trial progression, communication between modules, and overall session state.
GUIManager	Creates and updates the graphical user interface, including tabs for stimulation, acquisition, control, and early training.
TeensyInterface	Manages serial communication with the Teensy board. Sends experiment parameters and parses incoming event/analog packets.
StimulationManager	Generates and manages odor/stimulus lists for each experimental group. Supports updating stimulus probability during the experiment.
DataManager	Handles session folders, metadata, trial data logging, event recording, analog data saving, and merging trial files.
PlotManager	Provides real-time plotting of raw trial data, cumulative success rate, Go/No-Go performance, odor-based performance, and sniff signals.
CameraManager	Controls USB camera preview, including camera selection, resolution settings, and live view.
ExperimentParams	Stores and manages experiment parameters, including trial timing, reward duration, odor parameters, sampling rates, and task settings.
GroupData	Lightweight handle class for sharing and updating group-specific data across different components.

---

Hardware Requirements

This system was designed for a behavioral neuroscience setup with the following hardware components:

• A Teensy microcontroller connected to the computer through a USB serial port
  • Developed for a Teensy-based behavioral control system
  • Teensy 4.1
• Odor delivery hardware / olfactometer
  • Odor valves
  • Clean-air and blank-vial control lines
  • Optional multiple odor groups
• Reward delivery hardware
  • Solenoid valve or pump-based reward control
• Behavioral sensors
  • Lick detection input
  • Sniff analog input
• Optional analog input channels
  • Sniff signal
  • Lick-related analog signals
• USB camera for live behavioral preview
• Windows PC or workstation running MATLAB

The exact hardware configuration can be adapted, but the Teensy firmware and MATLAB packet parsing must match the connected hardware and signal channels.

---

Software Requirements

MATLAB

Developed and tested in:

• MATLAB R2024a

Required MATLAB functionality may include:

• App/GUI components
• Serial communication support
• Webcam support, if using CameraManager
• Standard MATLAB plotting and file I/O functions

Teensy / Arduino Environment

The Teensy board must be programmed with the matching custom firmware.

Recommended software:

• Arduino IDE or PlatformIO
• Teensyduino add-on
• Compatible Teensy board package
• USB serial driver support, if required by the operating system

---

Teensy Firmware

OBzip requires custom Teensy firmware that handles low-level behavioral task timing and communication with MATLAB.

The firmware is responsible for:

• Receiving trial parameters from MATLAB
• Controlling odor valves
• Controlling reward delivery
• Monitoring lick events
• Acquiring analog signals such as sniff and lick-related channels
• Sending event packets to MATLAB
• Sending analog data packets to MATLAB

The MATLAB side expects the Teensy firmware to use a defined binary packet format. If the firmware protocol is changed, TeensyInterface.m must be updated accordingly.

Suggested repository organization:

OBzip/
├── src/
│   ├── MouseBehaviorController.m
│   ├── GUIManager.m
│   ├── TeensyInterface.m
│   ├── StimulationManager.m
│   ├── DataManager.m
│   ├── PlotManager.m
│   ├── CameraManager.m
│   ├── ExperimentParams.m
│   └── GroupData.m
├── teensy_firmware/
│   └── OBzip_Teensy_Firmware/
│       └── OBzip_Teensy_Firmware.ino
├── docs/
├── demo/
└── README.md