Scale
The Training Village can have two scales: one in the corridor, used by the system, and an optional one in the box, for your tasks.
Setup
The corridor scale, always present. The system uses it to weigh every animal when it goes back home and to detect that it has left the box (see The Animal Doesn’t Leave). The weights are saved with each session. Calibrate it from
MONITOR→CORRIDOR(see Monitor & Hardware Setup), and set the valid range of weights withMIN_WEIGHT_THRESHOLDandMAX_WEIGHT_THRESHOLD(SETTINGS→CORRIDOR SETTINGS).The box scale, optional, connected to the Box Board, for your tasks (a platform, a lever…). It is available when
USE_BOX_BOARDandSCALE_BOXare ON (inSETTINGS→BOX SETTINGS). Calibrate it fromMONITOR→BOXbefore using it. In automatic mode it is tared before every session, just before door 2 opens, while the box is still empty. In manual mode it is not, since the animal may already be inside: tare it fromMONITOR→BOX(TARE SCALE) with the box empty.
Using It in Tasks
While a task is running, the box scale is read continuously (see below), and the last weight read is always available, without making a new reading (outside a task the scale is not read, so it keeps the last value read):
from village.devices.scale import scale_box
weight = scale_box.last_weight # grams
Reacting to the Box Scale
While a task is running, the box scale is read in its own thread every
period seconds (0.1 s by default) and the on_weight method of
ScaleTriggerBase is called with every reading. By default it does nothing.
You can override it to react to the weight (the animal stepping on a platform,
a lever pressed with a given force, …).
Creating a custom ScaleTrigger
Create a file inside your project’s code directory (e.g. scale_trigger.py) and define
a class (e.g. ScaleTrigger) that inherits from ScaleTriggerBase. The file and class names are
up to you: the system detects the class by what it inherits from, and uses it
instead of the default base class. Only one such class is used per project.
from village.custom_classes.scale_trigger_base import ScaleTriggerBase
class ScaleTrigger(ScaleTriggerBase):
def __init__(self) -> None:
super().__init__()
self.period = 0.1 # seconds between readings
self.on_platform = False
def on_weight(self, weight: float, timestamp: float) -> None:
"""Called after every reading of the box scale.
Available via self.task:
- self.task.cam_box — box camera (write_text, areas, position, …)
- self.task.bpod — Bpod controller (send_softcode_to_bpod, …)
- self.task.gpio — set_on()/set_off() for the output pin
- any attribute defined in the task class
"""
if weight > 10 and not self.on_platform:
self.on_platform = True
self.task.register_raspberry_event("PlatformIn", timestamp)
self.task.bpod.send_softcode_to_bpod(1)
elif weight < 5 and self.on_platform:
self.on_platform = False
self.task.register_raspberry_event("PlatformOut", timestamp)
Note
on_weight runs in the scale reader thread, not in the task thread. Keep it
fast and avoid blocking calls: the next reading waits until it returns. It is only
called once the start of the task has finished, so it can read any attribute
start creates, and never in calibrations. If it raises an error, the error is
logged and the readings go on.
A complete example, which records when the animal steps on and off the scale in the trial data of any task: scale_trigger.py.
Choosing the period
A reading takes a few milliseconds and the thread sleeps between readings, so
it barely loads the Raspberry Pi. The limit is the scale itself: it only gives
about 10 new values per second, so a period below 0.1 s just repeats the
same value. The minimum accepted is 0.02 s.