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 with MIN_WEIGHT_THRESHOLD and MAX_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_BOARD and SCALE_BOX are ON (in SETTINGS → BOX SETTINGS). Calibrate it from MONITOR → BOX before 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 from MONITOR → 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.