Tasks (Arduino)
With BEHAVIOR_CONTROLLER set to OTHER in SETTINGS, a microcontroller (an
Arduino, or any other board that talks over a serial port) can run the time-critical
part of every trial: reading the pokes, turning the LEDs on, opening the valves. The
task, on the Raspberry Pi, tells it what to do at the start of every trial and
registers everything it reports. So there are two pieces of code:
The task (
.py): a class that inherits fromTaskBase, in any.pyfile inside your project’scodedirectory. The name of the class is the name of the task: the one shown in the GUI and used innext_taskby the training protocol. The file name does not matter.The firmware (
.inofor an Arduino), uploaded to the board with its own tools (e.g. the Arduino IDE). Village doesn’t upload it.
They talk through the serial port set in CONTROLLER_PORT (SETTINGS). What they
say to each other is up to you: the examples use small binary messages.
How a task runs
start()is called once, when the session starts, before the first trial. Open the serial connection and compute what the whole session needs: valve times, sounds…Then, trial after trial:
create_trial()is the trial: it tells the Arduino to start, registers the start of the trial, listens to the Arduino and registers everything it reports, 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. Close the serial connection here.
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 the
Arduino would keep running. Every waiting loop must check self.should_stop (and a
deadline, in case a message is lost on the way), so it can never wait forever:
while not self.should_stop and time_utils.now_timestamp() < deadline:
... # read from the Arduino
Unlike with Bpod, the Python code is not blocked while the Arduino runs the trial: it
is the loop of create_trial, so it can react in the middle of the trial to what the
Arduino reports (playing a sound, as in Playing a sound), or to
what only the Raspberry Pi sees (the camera, the touchscreen…) by sending a message
to the Arduino.
All the methods and attributes a task can use are in Task Reference.
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.
A first task: habituation
This is the first task of the example project, the Arduino version of Tasks (Bpod): the animal is left alone in the box to explore it. Nothing happens and no water is given, but every poke is recorded. Each trial waits up to 60 seconds and ends earlier if the animal pokes any port.
The firmware
All the Arduino examples share one firmware, village_arduino.ino, uploaded once to the board. Ports 1 (left), 2 (center) and 3 (right) are wired; only the side ports have a valve. The messages are:
Raspberry Pi → Arduino: one command per trial. Its first byte says which task it is for (
CMD_HABITUATION = 11,CMD_PASSIVE = 12…), and the rest are the values that task needs (ports, times in milliseconds…). The times in milliseconds are sent as 32-bit integers (Iinstruct.pack): a 16-bit one only reaches 65,535 ms, about one minute.Arduino → Raspberry Pi: messages of 6 bytes,
[event, value, elapsed_ms]:EVENT_POKE(the port poked),EVENT_STATE(the state entered) andEVENT_TRIAL_END(the result of the trial).elapsed_msis the Arduino’s clock: the milliseconds since it received the command.
The firmware’s loop() reads the command byte, waits for the rest of the message (its
size depends on the command) and runs that task’s trial:
// Reads the command byte first, waits until the whole message has arrived
// (its size depends on the command), and runs the trial it asks for.
void loop() {
if (Serial.available() < 1) {
return;
}
byte command = Serial.peek();
byte size = messageSize(command);
if (size == 0) {
Serial.read(); // unknown command: drop it
return;
}
if (Serial.available() < size) {
return; // the rest of the message has not arrived yet
}
Serial.read(); // the command byte
switch (command) {
case CMD_HABITUATION: {
unsigned int durationS = readUInt16();
runHabituation(durationS);
break;
}
// ... one case per task
}
}
The habituation trial: it reports the state it enters, waits for a poke in any port
for durationS seconds, and reports the result (the port poked, or 0), with its own
clock (millis()):
// [CMD_HABITUATION, duration_s (uint16, LE)]
const byte HABITUATION_READY_TO_EXPLORE = 1;
void runHabituation(unsigned int durationS) {
unsigned long t0 = millis();
unsigned long durationMs = (unsigned long)durationS * 1000UL;
sendEvent(EVENT_STATE, HABITUATION_READY_TO_EXPLORE, 0);
byte pokedPort = 0;
while (millis() - t0 < durationMs) {
pokedPort = readAnyPoke();
if (pokedPort != 0) {
break;
}
}
sendEvent(EVENT_TRIAL_END, pokedPort, millis() - t0);
}
A firmware of your own can follow the same pattern: add a command, a function that runs the trial, and the same 6-byte messages.
The task
import struct
import time
import serial
from village.custom_classes.task_base import TaskBase
from village.scripts.time_utils import time_utils
from village.settings import settings
# Protocol (see runHabituation() in village_arduino/village_arduino.ino):
#
# Pi -> Arduino, 3 raw bytes, sent once at the start of each trial:
# [CMD_START_TRIAL, duration_s (uint16, little-endian)]
# Tells the Arduino how long this trial lasts. From here the Arduino
# watches the 3 poke sensors on its own; the Pi just listens.
#
# Arduino -> Pi, 6 raw bytes per message:
# [EVENT_STATE, state, elapsed_ms (uint32, LE)]
# -- every time the Arduino enters a new state (see STATE_NAMES), so it
# can be registered with register_enter_state, as Bpod does.
# [EVENT_TRIAL_END, port (0 if nobody poked), elapsed_ms (uint32, LE)]
# -- once, when the trial is over.
# elapsed_ms is milliseconds since the Arduino received CMD_START_TRIAL
# for THIS trial (its own timer, reset every trial). It is the controller
# clock: the trial start is registered as controller time 0 at the moment
# the Pi sent CMD_START_TRIAL, and every elapsed_ms as a controller
# timestamp (register_controller_event / register_enter_state), so the two
# clocks never need to be synchronized.
CMD_START_TRIAL = 11 # CMD_HABITUATION in village_arduino.ino
EVENT_TRIAL_END = 2
EVENT_STATE = 3
# State ids sent by the Arduino (same names as bpod_1_habituation.py)
STATE_NAMES = {1: "ready_to_explore"}
BAUDRATE = 9600 # must match the Arduino sketch's Serial.begin(...)
READ_TIMEOUT = 0.05 # seconds; also how often should_stop gets re-checked
MESSAGE_SIZE = 6 # every Arduino -> Pi message is exactly this many bytes
STARTUP_WAIT = 2.0 # seconds; opening the port resets most Arduino boards
STATE_DURATION = 60 # seconds
class Arduino1Habituation(TaskBase):
def __init__(self):
super().__init__()
self.info = """
Habituation Task
----------------------------------------------------------
Lets a mouse get used to being in the box on its own. Every trial,
the Pi tells the Arduino how long to wait (STATE_DURATION), and the
Arduino watches all 3 ports for that whole window, ending the trial
early the moment any one of them is poked. No reward is delivered --
pokes are only recorded, to see the animal is exploring the box.
"""
def start(self):
"""Opens the serial connection to the Arduino."""
self.serial_port = serial.Serial(
port=settings.get("CONTROLLER_PORT"),
baudrate=BAUDRATE,
timeout=READ_TIMEOUT,
)
# Opening the port resets most Arduino boards: wait for the sketch
# to be running, or the first command would be lost.
time.sleep(STARTUP_WAIT)
self.serial_port.reset_input_buffer()
def create_trial(self):
"""Tells the Arduino how long this trial should last, then waits for
its single reply: either a port number (whichever was poked first)
or 0 if the whole duration passed with no poke at all.
The deadline below is only a safety net for a lost/garbled message
-- in normal operation the Arduino's own reply always arrives well
before it.
"""
self.serial_port.write(struct.pack("<BH", CMD_START_TRIAL, STATE_DURATION))
t_sent = time_utils.now_timestamp()
# The Arduino's clock (elapsed_ms) starts at 0 when it gets the command.
self.register_start_trial(raspberry_timestamp=t_sent, controller_timestamp=0.0)
deadline = t_sent + STATE_DURATION + 2.0 # margin for serial/USB latency
buffer = bytearray()
while not self.should_stop and time_utils.now_timestamp() < deadline:
chunk = self.serial_port.read(MESSAGE_SIZE - len(buffer))
if not chunk:
continue # nothing arrived within READ_TIMEOUT; keep waiting
buffer += chunk
if len(buffer) < MESSAGE_SIZE:
continue
event, value, elapsed_ms = struct.unpack("<BBI", bytes(buffer))
buffer.clear()
t = elapsed_ms / 1000.0 # controller clock, seconds
if event == EVENT_STATE:
self.register_enter_state(STATE_NAMES.get(value, f"state{value}"), t)
elif event == EVENT_TRIAL_END:
if value != 0: # the port that was poked
self.register_controller_event(f"Port{value}In", t)
self.register_end_trial(t)
break
# If the loop ended without EVENT_TRIAL_END (task stopped, or a lost
# message), the trial is ended automatically when this returns.
def after_trial(self):
"""Reads back whichever port event create_trial registered, if any,
to label the trial."""
outcome = "miss"
if self.trial_data.get("Port1In"):
outcome = "left_poke"
elif self.trial_data.get("Port2In"):
outcome = "center_poke"
elif self.trial_data.get("Port3In"):
outcome = "right_poke"
self.register_value("outcome", outcome)
self.register_value("water", 0)
def close(self):
"""Closes the serial connection to the Arduino."""
if self.serial_port.is_open:
self.serial_port.close()
Step by step:
The constants at the top are the protocol: the command byte of the habituation trial, the event codes the Arduino sends, and
STATE_NAMES, which translates the number of each state into the name it gets in the trial data.The class name,
Arduino1Habituation, 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.startopens the serial port, waits 2 seconds and discards anything left in it. Opening the port resets most Arduino boards (Uno, Nano…), and the firmware takes a moment to start again: a command sent before would be lost.create_trialruns the whole trial:It sends the command,
[11, 60]: run a habituation trial of 60 seconds.It registers the start of the trial with both clocks at the same moment: the Raspberry Pi’s time (
t_sent) and the Arduino’s (0, since the Arduino starts counting when it receives the command). From then on, every time the Arduino reports is converted to Raspberry Pi time, so the two clocks never need to be synchronized.It reads the messages of the Arduino, 6 bytes each, and registers what they report with the Arduino’s time: the state entered with
register_enter_state, the port poked withregister_controller_event(asPort1In,Port2InorPort3In, the same names as Bpod), and the end of the trial withregister_end_trial.The loop also ends if the task has to stop or the deadline passes. Then the trial is ended automatically when
create_trialreturns.
When the trial ends, the next one starts right away with a new call to
create_trial, until the session ends.after_trialreadsself.trial_datato find out how the trial ended: if there is aPort1In,Port2InorPort3Inevent, the animal poked that port; if not, the time ran out ("miss"). It saves the result withself.register_value("outcome", outcome), and the water given,0, withself.register_value("water", 0).closecloses the serial port.
The complete code of this task and the rest of the example project, from habituation to a full discrimination task, are in Task Examples (Arduino), together with the firmware.
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 habituation task in which the animal pokes the center port after
12.3 seconds:
{
"date": "2026-11-07 10:30:00",
"trial": 5,
"subject": "mouse1",
"task": "Arduino1Habituation",
"system_name": "village01",
"TRIAL_START": 1793961045.20,
"TRIAL_END": 1793961057.50,
"STATE_ready_to_explore_START": [1793961045.20],
"STATE_ready_to_explore_END": [1793961057.50],
"Port2In": [1793961057.50],
"ordered_list_of_events": ["Port2In"],
}
If the animal does not poke, there is no Port2In key: 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. Events registered with |
|
The names of all the events, in the order they happened. |
All the times are in seconds, converted to the Raspberry Pi’s clock (UNIX time), so the Arduino’s and the Raspberry Pi’s 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.
center_poke = "Port2In" in self.trial_data # True
# How many times? The length of its list (an empty list if it did not happen).
number_of_pokes = len(self.trial_data.get("Port2In", [])) # 1
# When? The first element of its list.
poke_time = self.trial_data["Port2In"][0] # 1793961057.50
# How long did something take? Subtract two times.
trial_start = self.trial_data["TRIAL_START"]
reaction_time = poke_time - trial_start # 12.3 s
# Was a state visited? Its key exists.
explored = "STATE_ready_to_explore_START" in self.trial_data # True
What is saved
At the end of each trial, trial_data, with the values registered in after_trial
(outcome and water in the habituation 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 in
the firmware and a deadline in create_trial, as in the habituation task): a session
that is a single trial that never ends would not be saved.
Delivering water
The valves are connected to the Arduino, and the firmware opens them: the valve time must be precise, and only the Arduino can time it to the millisecond. The task gets the valve time that gives a volume from the water calibration of that port, and sends it to the Arduino in the command of the trial.
In arduino_2_passive.py, the second task of the example project, every trial a side port lights up and gives water at once; then the LED stays on until the animal pokes that port, or a timeout. The parts that deliver the water are:
In the task, start computes the valve times once, for the whole session:
def start(self):
... # open the serial port, as in the habituation task
self.valve_l_time = self.calibrations.water_calibration.get_valve_time(
port=1, volume=self.settings.reward_volume
)
self.valve_r_time = self.calibrations.water_calibration.get_valve_time(
port=3, volume=self.settings.reward_volume
)
and create_trial chooses the port and sends the command, with the valve time in
milliseconds:
def create_trial(self):
self.side = random.choice(["left", "right"])
if self.side == "left":
valvetime, port = self.valve_l_time, 1
else:
valvetime, port = self.valve_r_time, 3
valve_time_ms = int(valvetime * 1000)
led_on_timeout_ms = int(self.settings.led_on_time * 1000)
self.serial_port.write(
struct.pack(
"<BBII", CMD_START_TRIAL, port, valve_time_ms, led_on_timeout_ms
)
)
... # register the start and listen to the Arduino, as in the habituation task
In the firmware, runPassive turns the LED on and opens the valve for
valveTimeMs milliseconds, reporting the state it enters:
void deliverWater(byte port, unsigned long valveTimeMs) {
byte valvePin = valvePinOf(port);
digitalWrite(valvePin, HIGH);
delay(valveTimeMs);
digitalWrite(valvePin, LOW);
}
void runPassive(byte port, unsigned long valveTimeMs, unsigned long ledOnTimeoutMs) {
unsigned long t0 = millis();
byte ledPin = ledPinOf(port);
sendEvent(EVENT_STATE, PASSIVE_WATER_DELIVERY, 0);
digitalWrite(ledPin, HIGH);
deliverWater(port, valveTimeMs);
sendEvent(EVENT_STATE, PASSIVE_LED_ON, millis() - t0);
... // wait for the poke, then send EVENT_TRIAL_END
}
In after_trial, the water is registered. In this task it is given in every
trial:
self.register_value("water", self.settings.reward_volume)
In a task where the water depends on the response, register reward_volume only if
the reward state was visited: "STATE_reward_START" in self.trial_data.
reward_volumeis a setting defined in the training protocol. The water calibration must exist for the port, orget_valve_timeraises an error. With an Arduino, the calibration needs a calibration task of its own: see Water Calibration with Arduino.The firmware already has a command that only opens a valve,
CMD_OPEN_VALVE([20, port, time_us (uint32)]), the one the water calibration uses. A task can send it to give water at any moment, e.g. when the camera trigger detects the animal in an area. The firmware replies withEVENT_VALVE_CLOSED, when the valve closes.
Playing a sound
The sound card is connected to the Raspberry Pi, not to the Arduino. So the sound is
loaded by the task, before the trial starts, and played by the task when the Arduino
reports what has to trigger it. 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 it is played when the animal pokes the center port. It uses the habituation trial of the firmware, which ends at the first poke:
import random
import struct
import time
import serial
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
from village.settings import settings
CMD_HABITUATION = 11
EVENT_TRIAL_END = 2
MESSAGE_SIZE = 6
TRIAL_DURATION = 60 # seconds
class PokeForSound(TaskBase):
def start(self):
self.serial_port = serial.Serial(
port=settings.get("CONTROLLER_PORT"), baudrate=9600, timeout=0.05
)
time.sleep(2.0) # opening the port resets most Arduino boards
self.serial_port.reset_input_buffer()
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)
self.serial_port.write(struct.pack("<BH", CMD_HABITUATION, TRIAL_DURATION))
t_sent = time_utils.now_timestamp()
self.register_start_trial(raspberry_timestamp=t_sent, controller_timestamp=0.0)
deadline = t_sent + TRIAL_DURATION + 2.0
buffer = bytearray()
while not self.should_stop and time_utils.now_timestamp() < deadline:
buffer += self.serial_port.read(MESSAGE_SIZE - len(buffer))
if len(buffer) < MESSAGE_SIZE:
continue
event, port, elapsed_ms = struct.unpack("<BBI", bytes(buffer))
buffer.clear()
if event == EVENT_TRIAL_END: # the state messages are not used here
t = elapsed_ms / 1000.0
if port != 0:
self.register_controller_event(f"Port{port}In", t)
if port == 2: # the center port: play the sound
sound_device.play()
time.sleep(0.5) # the trial ends when the sound ends
t += 0.5
self.register_end_trial(t)
break
def after_trial(self):
self.register_value("frequency", self.frequency)
self.register_value("water", 0)
def close(self):
if self.serial_port.is_open:
self.serial_port.close()
create_trialloads the sound before sending the command, so it is ready when it is needed. Loading takes longer the longer the sound is; playing a loaded sound starts at once.The sound starts a few milliseconds after the poke: the time the message takes to reach the Raspberry Pi, plus the time to start the sound (see Timing, Clocks & Latencies).
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 (see Sound).When the sound starts playing, the system adds a
soundevent totrial_data.
The task can also play the sound with a direct function (self.execute_function(4),
“Play Loaded Sound” in the example project), as
arduino_5_introduce_penalty.py does.
Direct functions can also be run from the GUI or from the triggers: see
Direct Functions.