arduino_1_habituation.py
Arduino version of bpod_1_habituation.py: the same task and states (see its diagram), run by an Arduino that reports every state and poke to the Raspberry Pi.
Task
Download arduino_1_habituation.py
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()
Arduino firmware
All the Arduino examples use the same firmware, village_arduino.ino,
uploaded once to the board. This task starts every trial with the CMD_HABITUATION command, and
the trial runs in runHabituation():
// === Habituation (arduino_1_habituation.py) ==============================
//
// [CMD_HABITUATION, duration_s (uint16, LE)]
// Watches the 3 ports for duration_s, ending the trial early the moment any
// one of them is poked. Reports [EVENT_TRIAL_END, port (0 if nobody
// poked)].
const byte HABITUATION_READY_TO_EXPLORE = 1;
byte readAnyPoke() {
if (digitalRead(pokePinLeft) == HIGH) return LEFT_PORT;
if (digitalRead(pokePinCenter) == HIGH) return CENTER_PORT;
if (digitalRead(pokePinRight) == HIGH) return RIGHT_PORT;
return 0;
}
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);
}