## 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 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. - **The firmware** (`.ino` for 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 1. `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... 2. 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. Then `self.trial_data` is filled with everything registered in the trial; - `after_trial()` is called after every trial. It reads `self.trial_data` and saves values with `register_value`. Registering `water` is mandatory. 3. `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. `````{admonition} Check should_stop in your waiting loops :class: warning 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: ```python 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](#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](tasks_reference.md). ```{admonition} Register water in every trial :class: warning 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)](tasks_bpod.md#a-first-task-habituation): 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](../examples/village_arduino.md), 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 (`I` in `struct.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) and `EVENT_TRIAL_END` (the result of the trial). `elapsed_ms` is 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: ```cpp // 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()`): ```cpp // [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 ```python 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("_START"`, `"STATE__END"` | For every state registered with `register_enter_state`, a list with the times it was entered and left (a list, because a state can be visited several times). A state ends when the next one is entered, or when the trial ends. A state that was **not visited** is not in the dictionary. | | `""` (`"Port1In"`...) | 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 `register_raspberry_event` during the trial are included too, and so are the ones the system registers by itself: `sound` when a sound starts playing, `touch__` for every touch. | | `"ordered_list_of_events"` | 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): ```python 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: - **`.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. - **`_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](../examples/arduino_2_passive.md), 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: ```python 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: ```python 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( " ../examples/village_arduino.md ../examples/arduino_1_habituation.md ../examples/arduino_2_passive.md ../examples/arduino_3_active.md ../examples/arduino_4_center_initiated.md ../examples/arduino_5_introduce_penalty.md ../examples/arduino_6_delay.md ```