Direct Functions
Your project’s code directory can hold three files that work together:
direct_functions.py— numbered, self-contained actions (play a sound, draw a stimulus, toggle a camera annotation, …) that can be triggered from several different places: a GUI button, a camera/GPIO/touchscreen trigger, a Bpod softcode, or a direct call from your task’s own code.sound_functions.pyandvideo_functions.py— small libraries of generator functions that direct functions (or tasks) call to actually produce a sound or a visual stimulus, built on top of thesound_deviceandscreenAPIs described in Sound and Screen & Touchscreen.
Writing Direct Functions
Create a file inside your project’s code directory (e.g. direct_functions.py) and define
a class (e.g. DirectFunctions) that inherits from DirectFunctionsBase. 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.
Each method must be named functionN (N from 1 to 98) and take no arguments other
than self. Its first line, as a docstring, is a short label — it’s what shows up
on the corresponding button in the GUI, so keep it brief.
from village.custom_classes.direct_functions_base import DirectFunctionsBase
from village.devices.camera import cam_box
class DirectFunctions(DirectFunctionsBase):
def function1(self):
"""Camera MSG ON"""
# self.task gives access to the currently running task, so you can read
# anything it defines (settings, calibrations, custom attributes, ...)
cam_box.write_text("ON")
def function2(self):
"""Clear Camera MSG"""
cam_box.write_text("")
Note
The system detects the class automatically — no registration needed. See the demo project’s direct_functions.py for a fuller set of examples covering sound playback and on-screen stimuli.
Ways to trigger a direct function
GUI — the
FUNCTIONStab shows one button per registered function, labeled with its docstring. Clicking it calls that function right away.Camera trigger — call
self.task.execute_function(N)insideCameraTriggerBase.trigger. See Camera Triggers.GPIO trigger — call
self.task.execute_function(N)insidetrigger_on/trigger_off. See GPIO.Scale trigger — call
self.task.execute_function(N)insideScaleTriggerBase.on_weight. See Scale.Touchscreen trigger — call
self.task.execute_function(N)insideTouchTriggerBase.trigger. See Screen & Touchscreen.Bpod softcodes — if
BEHAVIOR_CONTROLLERisBPOD, functions 1-98 can be triggered automatically from inside the state machine (see below).OTHERcontroller (a microcontroller you talk to yourself, or none at all) — there is no state-machine layer to trigger functions for you, so callself.execute_function(N)directly from your task’s own code (create_trial,after_trial, or anywhere else), whenever you want it to run.
Bpod softcodes
A softcode is a short message the Bpod state machine sends back to the Raspberry
Pi while a trial is running, without waiting for the trial to end. You trigger
one by including BpodOutput.SoftCodeN in a state’s output_actions, alongside
any other output (opening a valve, turning on an LED, …). N goes from 1 to 98,
matching direct functions 1-to-1. The moment the state machine executes that
output, Village receives the message and automatically calls
execute_function(N) — this is how a Bpod task can trigger a direct function mid
-trial, from inside the state machine, instead of only between trials.
self.bpod.add_state(
state_name="reward",
state_timer=0.5,
state_change_conditions={BpodEvent.Tup: "exit"},
# opens Valve1 AND triggers function6, at the same time
output_actions=[("Valve1", 1), BpodOutput.SoftCode6],
)
This is not the only softcode channel
The example above is Bpod → Raspberry Pi. There is also a channel the other way
around — the task can send a softcode from the Raspberry Pi to Bpod
(self.task.bpod.send_softcode_to_bpod(N)), for the state machine to branch on
via state_change_conditions={"SoftCodeN": "next_state"}. That’s a different
mechanism (a Bpod input condition, not a direct-function trigger) — see
the “Example” section of Screen & Touchscreen.
Sound and Video Functions
The functions that generate sounds (sound_functions.py) and visual stimuli
(video_functions.py), which direct functions use, are explained with each device:
Sound and
Screen & Touchscreen.
Adding your own functions
sound_functions.py and video_functions.py are plain modules, not subclasses —
unlike direct_functions.py (or camera_trigger.py, gpio_trigger.py, …),
there is only ever one of them per project, so there’s nothing to discover or
swap automatically. Add a new generator alongside the existing ones and import it
directly wherever you need it, the same way direct_functions.py already does:
from sound_functions import tone_generator, whitenoise_generator
from video_functions import draw_circle_generator, draw_rectangle_generator