Task Reference

Everything a task can use: the methods you write, the methods you can call, the attributes of the task and the Bpod primitives. Most of it is the same with Bpod, with an Arduino or with the Raspberry Pi alone; what only works with one of them is marked. For how to write a task, see Tasks (Bpod), Tasks (Arduino) and Tasks (Raspberry Only).


The methods you write

Method

Called

Use it to

__init__(self)

When the task is loaded.

Call super().__init__() and set self.info, the description shown in the GUI.

start(self)

Once, before the first trial.

Compute what the whole session needs: valve times, sounds, stimulus positions… Without Bpod, also open the connections the task needs (the serial port of the Arduino…).

create_trial(self)

At the start of every trial.

With Bpod: build the state machine of the trial with self.bpod.add_state; Bpod runs it when create_trial returns. Without Bpod: run the trial: call register_start_trial, and register everything that happens until the trial is over.

after_trial(self)

After every trial.

Read self.trial_data, decide the outcome, and save values with register_value. Registering water is mandatory.

close(self)

Once, after the last trial (session finished, stopped, or error).

Close files or connections. Usually pass.

Register water in every trial

Call self.register_value("water", ...) in every after_trial, with the microliters delivered in the trial (0 if none). The system adds them up to know how much each subject drinks, and raises an alarm if it is too little.


Methods you can call

All controllers

Method

Use

self.register_value(name, value)

Saves a value in the trial’s row of the session file (a column named name). Call it in after_trial.

self.register_raspberry_event(name, timestamp)

Records an event that happened on the Raspberry Pi (a camera detection, a touch…) with time_utils.now_timestamp() as timestamp. If it happens during a trial, it is added to trial_data.

self.execute_function(i)

Runs direct function i (1-98), see Direct Functions.

time_utils is imported with from village.scripts.time_utils import time_utils.

Without Bpod

With an Arduino, or with the Raspberry Pi alone (BEHAVIOR_CONTROLLER set to OTHER), the task records the trial itself:

Method

Use

self.register_start_trial(raspberry_timestamp, controller_timestamp)

Required at the start of every trial, in create_trial: without it the task stops with an error. Pass time_utils.now_timestamp() and the controller’s time at the same moment (with the Raspberry Pi alone, time_utils.now_timestamp() as both).

self.register_end_trial(controller_timestamp)

Ends the trial. Optional: if create_trial returns without calling it, the trial is ended at that moment.

self.register_enter_state(state_name, controller_timestamp)

Enters a state: closes the previous one and opens this one, as Bpod does.

self.register_controller_event(name, controller_timestamp)

An event detected and timed by the controller (e.g. "Port1In" from the Arduino). With the Raspberry Pi alone it does the same as register_raspberry_event.

These methods, and register_raspberry_event, only record what happens between register_start_trial and the end of the trial: anything registered outside that window is ignored.

With Bpod

Method

Use

self.bpod.add_state(state_name, state_timer, state_change_conditions, output_actions)

Adds a state to the trial’s state machine, see Bpod primitives.

self.bpod.set_global_timer(timer_id, timer_duration)

Configures a global timer, see Global timers.

self.bpod.set_global_counter(counter_number, target_event, threshold)

Configures a global counter.

self.bpod.set_condition(condition_number, condition_channel, channel_value)

Configures a condition.

self.bpod.send_softcode_to_bpod(i)

Sends softcode i from the Raspberry Pi to Bpod, see Softcodes.


Attributes

Attribute

Type

Description

self.settings

Settings

The subject’s training settings, defined in the training protocol (e.g. self.settings.reward_volume). Changes made during the session are kept for the next one.

self.calibrations

Calibrations

Calibrations, e.g. self.calibrations.water_calibration.get_valve_time(port, volume) or self.calibrations.sound_calibration.get_sound_gain(speaker, dB, sound_name).

self.trial_data

dict

Everything that happened in the trial, available in after_trial (see Trial data).

self.bpod

BpodController

The Bpod interface (see the methods above). Only with Bpod.

self.info

str

Description of the task, shown when it is selected in the GUI. Set it in __init__.

self.name

str

The name of the task, which is the name of its class (e.g. "Bpod1Habituation").

self.subject

str

The name of the subject ("None" when a task is launched manually without a subject).

self.current_trial

int

The number of the current trial, starting from 1.

self.system_name

str

The name of the system (SYSTEM_NAME in SETTINGS).

self.date

str

The date and time the session started ("2026-11-07 10:30:00").

self.run_mode

str

"Auto" or "Manual".

self.chrono

Chrono

self.chrono.get_time() is the time in seconds since the session started.

self.force_stop

bool

Set it to True to end the session (see Ending the session from the task).

self.stop_button_pressed

bool

True once the STOP button has been pressed. Read it, don’t set it.

self.should_stop

bool

True once any stopping condition is met (read-only). Without Bpod, check it in every waiting loop of create_trial.

self.system_state

State

The state of the system, e.g. State.RUN_OPEN (Auto mode, the subject can leave the box). Import State from village.classes.enums.

self.cam_box

Camera

The box camera (see Camera).

self.gpio

Gpio

The GPIO output pin: set_on() / set_off() (see GPIO).

self.custom_areas

dict

The detection areas with a custom shape, if the project defines any (see Camera).

You can also add your own attributes (self.side = "left"): they are kept from one method to the next, and the triggers and direct functions can read them through self.task.


Bpod primitives

BpodEvent and BpodOutput are imported together with TaskBase:

from village.custom_classes.task_base import BpodEvent, BpodOutput, TaskBase

A state is added with:

self.bpod.add_state(
    state_name="light_on",           # any name; "exit" ends the trial
    state_timer=5,                   # seconds until the Tup event (0: no timer)
    state_change_conditions={        # event -> next state
        BpodEvent.Port2In: "reward",
        BpodEvent.Tup: "exit",
    },
    output_actions=[(BpodOutput.PWM2, 255)],  # what is on during the state
)

The trial starts in the first state added and ends when a transition goes to "exit". Every state turns off all the outputs of the previous one and turns on only its own output_actions, so there is no need to turn anything off. A state with state_timer=0 and no Tup condition waits for its events indefinitely; with state_timer=0 and a Tup condition, it fires its outputs and moves on at once.

Events

Used as keys of state_change_conditions:

Event

When it happens

BpodEvent.Tup

The state’s timer (state_timer) runs out.

BpodEvent.Port1In … Port8In

The animal pokes into port N (its infrared beam is broken).

BpodEvent.Port1Out … Port8Out

The animal leaves port N.

BpodEvent.BNC1High, BNC1Low, BNC2High, BNC2Low

A TTL signal on a BNC input goes high or low.

BpodEvent.SoftCode1, SoftCode2…

The Raspberry Pi sent that softcode with self.bpod.send_softcode_to_bpod(i).

BpodEvent.GlobalTimer1Start … GlobalTimer5Start, GlobalTimer1End … GlobalTimer5End

A global timer starts or ends.

BpodEvent.GlobalCounter1End … GlobalCounter5End

A global counter reaches its threshold.

BpodEvent.Condition1 … Condition16

A condition is true.

Outputs

Used in output_actions:

Output

What it does

(BpodOutput.PWM1, value) … PWM8

Turns on the LED of port N with an intensity from 0 to 255.

BpodOutput.Valve1 … Valve8

Opens the valve of port N during the state: use the valve time as state_timer.

BpodOutput.BNC1High, BNC2High

Sets a BNC output high (a TTL to another device) during the state.

BpodOutput.SoftCode1 … SoftCode98

Makes the Raspberry Pi run direct function N, at the moment the state starts.

BpodOutput.GlobalTimer1Trig … GlobalTimer5Trig

Starts a global timer.

BpodOutput.GlobalTimer1Cancel … GlobalTimer5Cancel

Cancels a global timer.

BpodOutput.GlobalCounter1Reset … GlobalCounter5Reset

Resets a global counter to 0.

bpod_outputs_and_events.py shows the ports, LEDs, valves and softcodes in a single task.

Softcodes

While Bpod runs a trial, the task’s Python code is waiting. Softcodes connect the Raspberry Pi and Bpod during the trial, in both directions:

  • Bpod → Raspberry Pi: BpodOutput.SoftCodeN in the output_actions of a state runs direct function N on the Raspberry Pi when the state starts: to play a sound, show an image… See Playing a sound and Direct Functions.

  • Raspberry Pi → Bpod: self.bpod.send_softcode_to_bpod(N) produces the event BpodEvent.SoftCodeN in the state machine, so the trial can react to something only the Raspberry Pi sees. It is usually sent from a trigger (which reaches the task as self.task). For example, to give water when the animal enters box area 1, in camera_trigger.py:

    class CameraTrigger(CameraTriggerBase):
        def __init__(self) -> None:
            super().__init__()
            self.inside = False
    
        def trigger(self, cam: Camera) -> None:
            if cam.name != "BOX":
                return
            # only when the animal enters, not on every frame while it is inside
            if cam.area1_is_triggered and not self.inside:
                self.task.bpod.send_softcode_to_bpod(1)
            self.inside = cam.area1_is_triggered
    

    and in the task, a state that waits for it:

    self.bpod.add_state(
        state_name="wait_area1",
        state_timer=60,
        state_change_conditions={
            BpodEvent.SoftCode1: "reward",  # sent by camera_trigger.py
            BpodEvent.Tup: "exit",
        },
        output_actions=[],
    )
    

    See bpod_area2_sound.py for the camera, and bpod_touchscreen.py for the touchscreen.

Global timers, counters and conditions

They are configured in create_trial, before or after adding the states, and are used by all the states of the trial:

  • Global timers (1 to 5): a timer that keeps running across states, independently of each state’s own timer, e.g. a deadline for the whole trial. Configure it with self.bpod.set_global_timer(timer_id=1, timer_duration=10), start it with the output BpodOutput.GlobalTimer1Trig and react to BpodEvent.GlobalTimer1End. See bpod_global_timer.py.

  • Global counters (1 to 5): count an event across states. Configure it with self.bpod.set_global_counter(counter_number=1, target_event=BpodEvent.Port2In, threshold=5) and react to BpodEvent.GlobalCounter1End, which happens when the event has happened 5 times.

  • Conditions (1 to 16): check the current level of an input at the moment of a transition, instead of reacting to a change. Configure it with self.bpod.set_condition(condition_number=1, condition_channel="Port2", channel_value=1) (true while the animal is in port 2) and use BpodEvent.Condition1 in state_change_conditions.

For more details and for Bpod modules, see the Bpod documentation.


Ending the session from the task

Set self.force_stop = True to end the session. The session ends at once, so set it in after_trial, when the trial is already complete: set during a trial (from a trigger or a direct function), it cuts that trial. It works in Auto mode too: the session is saved and the subject is let out, as when maximum_duration is reached, even before minimum_duration. For example, to stop after a maximum number of trials (max_trials defined in the training protocol):

def after_trial(self):
    ...
    if self.current_trial >= self.settings.max_trials:
        self.force_stop = True

The same works for any criterion: an amount of water, a number of correct trials…