Skip to content

Function Reference

This page documents user-facing MATLAB functions in the Bpod_Gen2 repository.


Bpod() - Initializes the system, creating a BpodSystem object in the base workspace

BpodSystem fields

StateMachineInfo - A struct containing info about the connected hardware setup
Status - A struct with system status variables
ProtocolSettings - A settings struct selected by the user for the current session
ProtocolFigures - A struct of handles to online plots, to close when the protocol exits
SoftCodeHandlerFunction - A user function to handle bytes received from the machine mid-trial
EmulatorMode - Indicates whether Bpod is being run in emulator mode (without hardware)
FlexIOConfig - Configuration of individual Flex I/O channels: DI, DO, AI or AO

BpodSystem functions

assertModule() - Ensures that specified Bpod module(s) are connected to the state machine
setStatusLED() - Enables or disables the Bpod State Machine's status LED
startAnalogViewer() - Launches a GUI to view streaming analog input from Flex I/O channels

Creating a state machine

NewStateMachine() - Creates a struct with an empty state machine description
AddState() - Adds a new state to a state machine description struct
EditState() - Edit an existing state in a state machine description struct
SetGlobalTimer() - Adds a global timer to a state machine description struct
SetGlobalCounter() - Adds a global counter to a state machine description struct
SetCondition() - Adds a condition to a state machine description struct

Running a state machine

  • Classic method, with idle time between trials:
    SendStateMachine() - Sends a state machine description to the Bpod FSM via USB
    RunStateMachine() - Runs the current state machine. Returns states + event timestamps.
  • TrialManager, for no idle time between trials:
    BpodTrialManager() - A class to manage state machine execution without blocking.

AddTrialEvents() - Packages raw trial data in a human-readable data structure.

Running a protocol

  • From the Bpod Console GUI:
  • From the MATLAB command prompt:
    • RunProtocol() - Runs a Bpod protocol (a behavior measurement session).

Data storage

SaveBpodSessionData() - Saves the contents of BpodSystem.Data to the current data file
SaveProtocolSettings() - Saves BpodSystem.ProtocolSettings to the current settings file
AddFlexIOAnalogData() - Adds the current session's Flex I/O analog data to the behavior data

General Plugins

BpodParameterGUI() - Generates a parameter GUI from the 'GUI' subfield of protocol settings
PsychToolboxSoundServer() - Plays sounds on trigger using the PC sound card
PsychToolboxVideoPlayer() - Plays videos on trigger using the PC second monitor
BpodNotebook() - Generates a GUI for manual note taking, saved with session data
SideOutcomePlot() - Generates an outcome score card showing left and right-sided trials
TrialTypeOutcomePlot() - Generates an outcome score card showing numeric trial types
TotalRewardDisplay() - Generates a GUI window updated with total liquid reward consumed
StateTiming() - Generates a GUI to show how much time the subject spent in each state

Serial Message setup

LoadSerialMessages() - Program a library of byte messages to send to Bpod modules on trigger
ResetSerialMessages() - Reset the serial message library
Implicit serial messages - A simplified syntax to program serial messages implicitly

Module <-> MATLAB (via USB)

See Bpod Module APIs (itemized in the sidebar)

Module <-> MATLAB (via Bpod State Machine)

ModuleWrite() - Writes data directly from the Bpod State Machine to a connected module
ModuleRead() - Returns data read directly by the Bpod State Machine from a connected module

USB Soft Codes, PC --> FSM

SendBpodSoftCode() - Sends a soft code (trigger byte) to the Bpod State Machine via USB


GetValveTimes() - Returns the time to open a valve to dispense a requested amount of liquid

Updating Bpod

LoadBpodFirmware() - Launches a GUI to load firmware to any Bpod device
UpdateBpodSoftware() - Updates Bpod MATLAB software (use 'pull' instead if using Git)


Bpod's functions, stored in Bpod_Gen2/Functions/, are added onto MATLAB's Path at startup. Please note that the subset of functions documented here are user-facing, for developing experimental protocols.