state_machine_base— State Machine Base


class pybpodapi.state_machine.state_machine_base.StateMachineBase(bpod)[source]

Each Bpod trial is programmed as a virtual finite state machine. This ensures precise timing of events - for any state machine you program, state transitions will be completed in less than 250 microseconds - so inefficient coding won’t reduce the precision of events in your data.


A lot of data structures are kept here for compatibility with original matlab library which are not so python-like. Anyone is welcome to enhance this class but keep in mind that it will affect the whole pybpodapi library.

  • hardware (Hardware) – bpod box hardware description associated with this state machine
  • channels (Channels) – bpod box channels handling
  • state_names (list(str)) – list that holds state names added to this state machine
  • state_timers (list(float)) – list that holds state timers
  • total_states_added (int) – holds all states added, even if name is repeated
  • state_timer_matrix (list(int)) – TODO:
  • conditions (Conditions) – holds conditions
  • global_counters (GlobalCounters) – holds global timers
  • global_timers (GlobalTimers) – holds global counters
  • input_matrix (list(tuple(int))) – TODO:
  • manifest (list(str)) – list of states names that have been added to the state machine
  • undeclared (list(str)) – list of states names that have been referenced but not yet added
  • meta_output_names (tuple(str)) – TODO:
  • output_matrix (list(tuple(int))) – TODO:
  • is_running (bool) – whether this state machine is being run on bpod box

hardware (Hardware) – hardware description associated with this state machine

add_state(state_name, state_timer=0, state_change_conditions={}, output_actions=())[source]

Adds a state to an existing state matrix.

  • name (str) – A character string containing the unique name of the state. The state will automatically be assigned a number for internal use and state synchronization via the sync port
  • timer (float) – The state timer value, given in seconds. This value must be zero or positive, and can range between 0-3600s. If set to 0s and linked to a state transition, the state will still take ~100us to execute the state’s output actions before the transition completes
  • state_change_conditions (dict) – Dictionary whose keys are names of a valid input event (state change) and values are names of states to enter if the previously listed event occurs (or ‘exit’ to exit the matrix and return all captured data)
  • output_actions (list(tuple)) – a list of binary tuples where first value should contain the name of a valid output action and the second value should contain the value of the previously listed output action (see output actions for valid values).


    state_change_conditions={'Tup': 'Port3Lit', 'GlobalTimer1_End': 'exit'},
    output_actions=[('PWM1', 255)])
set_global_timer_legacy(timer_id=None, timer_duration=None)[source]

Set global timer (legacy version)

  • timer_ID (int) –
  • timer_duration (float) – timer duration in seconds
set_global_timer(timer_id, timer_duration, on_set_delay=0, channel=None, on_message=1, off_message=0, loop_mode=0, loop_intervals=0, send_events=1, oneset_triggers=None)[source]

Sets the duration of a global timer. Unlike state timers, global timers can be triggered from any state (as an output action), and handled from any state (by causing a state change).

  • timer_ID (int) – the number of the timer you are setting (an integer, 1-5).
  • timer_duration (float) – the duration of the timer, following timer start (0-3600 seconds)
  • on_set_delay (float) –
  • channel (str) – channel/port name Ex: ‘PWM2’
  • on_message (int) –
set_global_counter(counter_number=None, target_event=None, threshold=None)[source]

Sets the threshold and monitored event for one of the 5 global counters. Global counters can count instances of events, and handle when the count exceeds a threshold from any state (by triggering a state change).

  • counter_number (int) – the number of the counter you are setting (an integer, 1-5).
  • target_event (str) – port where to listen for event to count
  • threshold (int) – number of times that should be count until trigger timer
set_condition(condition_number, condition_channel, channel_value)[source]

Set condition

  • condition_number (int) –
  • condition_channel (str) –
  • channel_value (int) –
exception pybpodapi.state_machine.state_machine_base.SMAError[source]