Tasks (Raspberry Only)
With BEHAVIOR_CONTROLLER set to OTHER in SETTINGS and no microcontroller, the
Raspberry Pi runs the trial itself: it reacts to what it detects (the box camera
areas, the touchscreen, the GPIO input pin, the box scale) and produces the stimuli
(sounds, the screen, the LED strip, the GPIO output pin). Its timing is less precise
than a microcontroller’s (see Timing, Clocks & Latencies):
for fast and precise timing, use Bpod or a microcontroller. And without a controller
there are no valves: these tasks don’t give water.
A task is a class that inherits from TaskBase, in any .py file inside your
project’s code directory. The name of the class is the name of the task: the one
shown in the GUI and used in next_task by the training protocol. The file name does
not matter.
How a task runs
start()is called once, when the session starts, before the first trial. Compute what the whole session needs: sounds, stimulus positions…Then, trial after trial:
create_trial()is the trial: it registers the start of the trial, waits for what has to happen (or a timeout), registers it, and returns when the trial is over. Thenself.trial_datais filled with everything registered in the trial;after_trial()is called after every trial. It readsself.trial_dataand saves values withregister_value. Registeringwateris mandatory.
close()is called once, when the session ends (session finished, stopped, or error), after the last trial. It can be used to close files or connections.
The session ends when it reaches maximum_duration (set in the training protocol),
when the STOP button is pressed, or when your task sets self.force_stop = True. The
system checks these conditions continuously, not only between trials: if one is met
during a trial, the session ends at once and that trial is cut (it is not saved in the
session file, only in the RAW file). In Manual mode the session also ends after the
number of trials chosen when launching the task.
Check should_stop in your waiting loops
When the session ends, the system waits up to 5 seconds for create_trial to return
before saving, but it cannot stop your Python code: a create_trial waiting for
something would keep running. Every waiting loop must check self.should_stop (and a
timeout), so it can never wait forever:
while not self.should_stop and time_utils.now_timestamp() < deadline:
... # wait for your own condition
The detections arrive through the triggers (camera, touchscreen, GPIO, scale):
classes in your code directory that the system calls, in their own threads, while
the task is running. The usual pattern is: the trigger reacts and signals the task
(with a threading.Event), and the loop of create_trial waits for that signal, or a
timeout, to end the trial. The first task below works this way.
All the methods and attributes a task can use are in Task Reference.
Register water in every trial
Call self.register_value("water", 0) in every after_trial, even though these tasks
give no water. The system adds up the water of every trial to know how much each
subject drinks, and raises an alarm if it is too little.
A first task: entering an area
This task of the example project waits, every trial, for the animal to enter area 1 of the box camera. When it does, a sound plays and an LED of the LED strip turns on. If the animal does not enter in 60 seconds, the trial ends anyway.
It needs two settings: area 1 of the box camera set as a TRIGGER area, and
CAM_BOX_TRACKING_POSITION ON (see
Detection in the Operant Box).
The task
import threading
from sound_functions import whitenoise_generator
from village.custom_classes.task_base import TaskBase
from village.devices.sound_device import sound_device
from village.scripts.time_utils import time_utils
TRIAL_TIMEOUT = 60 # seconds to wait for the animal to enter area 1
class RaspberryArea1Sound(TaskBase):
"""No Bpod, no Arduino (BEHAVIOR_CONTROLLER = OTHER): area 1 entry is
reacted to by a custom CameraTriggerBase (camera_trigger.py, in this
same code directory), which plays the sound and lights an LED strip LED
the moment the animal enters. create_trial just waits for that to
happen (or times out), then ends the trial.
Required setup (in SETTINGS, not in this file):
- CAM_BOX_TRACKING_POSITION must be ON.
- BOX area 1 must be set to TRIGGER status (and positioned/sized as
wanted) in the box area settings.
Without both, area1_is_triggered never becomes True and every trial
will just time out.
"""
def __init__(self):
super().__init__()
self.info = f"""
Area 1 Sound Task
----------------------------------------------------------------
No controller involved -- driven entirely by camera position
tracking, reacted to in camera_trigger.py. Each trial:
- If the animal enters BOX area 1, camera_trigger.py plays a sound
and lights an LED on the strip; the trial ends right after.
- Otherwise, the trial ends anyway after {TRIAL_TIMEOUT} seconds.
Requires CAM_BOX_TRACKING_POSITION ON and BOX area 1 set to TRIGGER
(see SETTINGS).
"""
def start(self):
"""Loads the sound once -- camera_trigger.py's function4 call
replays this same loaded sound every time area 1 is entered, no
reload needed.
"""
gain_left = self.calibrations.sound_calibration.get_sound_gain(
speaker=0, dB=70, sound_name="whitenoise"
)
gain_right = self.calibrations.sound_calibration.get_sound_gain(
speaker=1, dB=70, sound_name="whitenoise"
)
sound_left = whitenoise_generator(duration=1, gain=gain_left)
sound_right = whitenoise_generator(duration=1, gain=gain_right)
sound_device.load(left=sound_left, right=sound_right)
if not self.cam_box.tracking:
print(
"Warning: CAM_BOX_TRACKING_POSITION is OFF -- "
"area1 will never trigger."
)
if not self.cam_box.areas_trigger[0]:
print(
"Warning: BOX area 1 is not set to TRIGGER -- "
"area1 will never trigger."
)
# Set by camera_trigger.py's CameraTrigger.trigger() the moment
# area 1 is entered; create_trial just waits on it.
self.area1_event = threading.Event()
def create_trial(self):
"""Waits for camera_trigger.py to react to area 1, or for
TRIAL_TIMEOUT seconds to pass -- then ends the trial either way."""
self.area1_event.clear()
t0 = time_utils.now_timestamp()
self.register_start_trial(raspberry_timestamp=t0, controller_timestamp=t0)
deadline = t0 + TRIAL_TIMEOUT
while not self.should_stop and time_utils.now_timestamp() < deadline:
if self.area1_event.wait(timeout=0.05):
break
self.register_end_trial(time_utils.now_timestamp())
def after_trial(self):
self.register_value("entered_area1", self.area1_event.is_set())
self.register_value("water", 0)
def close(self):
pass
Step by step:
The imports.
TaskBaseis the class every task inherits from.whitenoise_generatorcomes fromsound_functions.py, a file of the example project (see Playing a sound),sound_deviceis the sound card, andtime_utilsgives the time of the Raspberry Pi.The class name,
RaspberryArea1Sound, is the name of the task.__init__only setsself.info, the description shown when the task is selected in the GUI. Always callsuper().__init__()first.startprepares the session:it loads the sound, a white noise of 1 second at 70 dB from the sound calibration, once: it will be played every time the animal enters the area;
it warns if the camera is not set up for the task;
it creates
self.area1_event, the signal the camera trigger sets when the animal enters area 1.
create_trialruns the whole trial:It clears the signal and registers the start of the trial. Here the Raspberry Pi is also the controller, so there is only one clock: the same time is passed as both clocks.
It waits for the signal, checking every 0.05 seconds whether the task has to stop, up to
TRIAL_TIMEOUTseconds.It registers the end of the trial.
When the trial ends, the next one starts right away with a new call to
create_trial, until the session ends.after_trialsaves whether the animal entered the area (entered_area1), and the water given,0.closehas nothing to clean up.
The camera trigger
The animal is detected by the camera trigger, in
camera_trigger.py: a class that inherits from
CameraTriggerBase, whose trigger method is called on every frame of the box
camera while a task is running (see
Reacting to the Animal’s Position).
This is the part that reacts to area 1:
area1_event = getattr(self.task, "area1_event", None) # only in this task
if (
cam.area1_is_triggered
and area1_event is not None
and not area1_event.is_set()
):
self.task.register_raspberry_event(
"area1_entered", time_utils.now_timestamp()
)
self.task.execute_function(4) # "Play Loaded Sound"
led_strip.set_led_color(0, 255, 255, 255)
led_strip.update_strip(sleep_duration=None)
area1_event.set()
cam.area1_is_triggeredisTruewhile the animal is in area 1. It staysTrueon every frame while the animal is inside, so the trigger only acts if the signal is not set yet: once per trial.It registers the entry as the event
area1_entered, plays the sound loaded instart(direct function 4, see Playing a sound), lights the first LED of the strip, and sets the signal, which ends the wait ofcreate_trial.self.taskis the task that is running.getattris used because the trigger is called for every task, and only this one hasarea1_event.
The complete code of this task and of raspberry_stimulus_menu.py, which follows the same pattern with the touchscreen, are in Task Examples (Raspberry Only).
Trial data
When a trial ends, everything registered in it is put in self.trial_data, a
dictionary that after_trial reads to decide the outcome of the trial. For example,
a trial of the first task in which the animal enters area 1 after 8.11 seconds:
{
"date": "2026-11-07 10:30:00",
"trial": 5,
"subject": "mouse1",
"task": "RaspberryArea1Sound",
"system_name": "village01",
"TRIAL_START": 1793961045.20,
"TRIAL_END": 1793961053.36,
"area1_entered": [1793961053.31],
"sound": [1793961053.32],
"ordered_list_of_events": ["area1_entered", "sound"],
}
If the animal does not enter, there are no area1_entered and sound keys: the
trial just ends after 60 seconds.
The keys are:
Key |
Value |
|---|---|
|
Which session and trial it is. |
|
When the trial started ( |
|
For every state registered with |
|
For every event registered, a list with the times of each occurrence. Events that did not happen are not in the dictionary. The ones the system registers by itself are included too: |
|
The names of all the events, in the order they happened. |
All the times are in seconds (UNIX time), so they can be compared and subtracted directly.
This is how to get the usual information from it in after_trial (the comments
give the results for the trial above):
def after_trial(self):
# Did an event happen? Its key exists.
entered = "area1_entered" in self.trial_data # True
# How many times? The length of its list (an empty list if it did not happen).
number_of_sounds = len(self.trial_data.get("sound", [])) # 1
# When? The first element of its list.
entry_time = self.trial_data["area1_entered"][0] # 1793961053.31
# How long did something take? Subtract two times.
trial_start = self.trial_data["TRIAL_START"]
latency = entry_time - trial_start # 8.11 s
# Was a state visited? Its key exists.
in_iti = "STATE_iti_START" in self.trial_data # False (this task has no states)
# Touches: one key per position, all starting with "touch_".
number_of_touches = sum(
len(times) for key, times in self.trial_data.items() if key.startswith("touch_")
) # 0
What is saved
At the end of each trial, trial_data, with the values registered in after_trial
(entered_area1 and water in the first task), becomes one row of the session
table. When the session ends, two files are saved:
<session>.csv: one row per trial, with a column for each key above and each registered value. It is the file used for the analysis and by the training protocol (self.df). A trial only gets its row when it finishes, so the trial that was running when the session stopped is not in it.<session>_RAW.csv: one line per event, written as they happen, including the trial that was interrupted.
The session is saved if at least one trial was completed. Design the task so that trials end after a reasonable time even if the animal does nothing (with a timeout, as in the first task): a session that is a single trial that never ends would not be saved.
Playing a sound
The sound card is connected to the Raspberry Pi, so the task loads the sound and plays
it directly. This uses a file of your project’s code directory, written by you (the
example project already includes it): sound_functions.py, with functions that
generate sounds as NumPy arrays, such as tone_generator or whitenoise_generator.
See Sound Functions. The sound is loaded with
sound_device.load and played with sound_device.play (see
Using It in Tasks).
In this example, every trial a tone of a random frequency (5 or 10 kHz) is loaded and played, followed by the inter-trial interval:
import random
import time
from sound_functions import tone_generator
from village.custom_classes.task_base import TaskBase
from village.devices.sound_device import sound_device
from village.scripts.time_utils import time_utils
class SoundEveryTrial(TaskBase):
def create_trial(self):
# load this trial's sound before the trial starts
self.frequency = random.choice([5000, 10000])
sound = tone_generator(duration=0.5, gain=0.05, frequency=self.frequency)
sound_device.load(left=sound, right=sound)
t0 = time_utils.now_timestamp()
self.register_start_trial(raspberry_timestamp=t0, controller_timestamp=t0)
self.register_enter_state("sound", t0)
sound_device.play()
self.wait(0.5)
self.register_enter_state("iti", time_utils.now_timestamp())
self.wait(self.settings.iti_time)
self.register_end_trial(time_utils.now_timestamp())
def wait(self, seconds):
"""Waits the given seconds, less if the task has to stop."""
end = time_utils.now_timestamp() + seconds
while not self.should_stop and time_utils.now_timestamp() < end:
time.sleep(0.01)
def after_trial(self):
self.register_value("frequency", self.frequency)
self.register_value("water", 0)
create_trialloads the sound before registering the start of the trial, so it is ready when it is needed. Loading takes longer the longer the sound is; playing a loaded sound starts at once.register_enter_stateorganizes the trial in states, as Bpod does: the trial data getsSTATE_sound_START,STATE_iti_START… A state ends when the next one is entered, or when the trial ends.waitis a method of this task, not ofTaskBase: it waits in short steps, so the task can stop in the middle of a wait.self.frequencyis an attribute of the task, soafter_trialcan register it.gain=0.05is an arbitrary volume. To play the sound at a given level in dB, use the sound calibration, as the first task does (see Sound).When the sound starts playing, the system adds a
soundevent totrial_data.
A trigger can also play a sound, as the camera trigger of the first task does with a
direct function: self.task.execute_function(4) runs function4 of
direct_functions.py, another file of the example project, which plays the sound
that is loaded:
from village.custom_classes.direct_functions_base import DirectFunctionsBase
from village.devices.sound_device import sound_device
class DirectFunctions(DirectFunctionsBase):
def function4(self):
"""Play Loaded Sound"""
sound_device.play()
Direct functions are numbered actions, function1 to function98, that you write in
a class that inherits from DirectFunctionsBase. They can be run from the task, the
triggers or the GUI, and they can do anything the Raspberry Pi can: draw on the
screen, write on the camera image… See
Writing Direct Functions.