API Reference¶
Session and machine control¶
murineshiftwork.logic.machine_config
¶
Machine-local config at ~/.murineshiftwork/msw_machine.yaml.
Stores machine-specific settings that are independent of the shared config dir.
All external service URLs and credentials use a flat <service>_api_<key> naming
scheme so machine configs across rigs remain consistent.
Expected YAML structure (all keys optional): config_dir: /mnt/maindata/msw_configs data_dir: /mnt/maindata/data
# MSW LogAgent / monitor backend : the FastAPI ingest+query server;
# msw-ui Vue SPA polls this for live session data
logagent_api_url: http://monitor:8080
logagent_api_token: <bearer-token>
# MSW UI frontend: URL to open in browser (served by msw-ui nginx container)
msw_ui_url: http://monitor:3000
# Open Ephys remote control (fallback; prefer setup YAML open_ephys_url)
openephys_api_url: <oe-host-ip>
# labwatch session push: read by msw-labwatch, not by murineshiftwork core
labwatch_api_url: https://labwatch.example.com
labwatch_api_token: <token>
Priority for config_dir resolution (highest wins):
1. CLI --config-dir argument
2. MSW_CONFIG_DIR environment variable
3. ~/.murineshiftwork/msw_machine.yaml config_dir key
4. /mnt/maindata/msw_configs (historical default, if it exists)
read_log_config()
¶
Return LogAgent config from machine config.
Reads new-style prefixed keys first, falls back to legacy names: logagent_api_url (legacy: log_url) logagent_api_token (legacy: log_bearer_token)
read_open_ephys_url()
¶
Return the Open Ephys GUI host from machine config (legacy fallback).
Preferred location is the setup YAML open_ephys_url: field.
Machine config is checked as a fallback; reads new-style key first:
openephys_api_url (legacy: open_ephys_url)
read_ui_url()
¶
Return the MSW UI frontend URL from machine config.
Reads new-style key first, falls back to legacy: msw_ui_url (legacy: ui_url)
resolve_config_dir(cli_override='')
¶
Return the config dir to use, applying the priority chain.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cli_override
|
str
|
value of --config-dir from CLI (empty string = not set). |
''
|
resolve_data_dir(cli_override='')
¶
Return the default data output directory, applying priority chain.
Priority (highest first):
1. --out-path CLI argument (passed as cli_override)
2. MSW_DATA_DIR environment variable
3. ~/.murineshiftwork/msw_machine.yaml data_dir key
4. /mnt/maindata/data (historical default, if it exists)
5. ~/data (fallback)
write_machine_config(config_dir, **extra_fields)
¶
Write (or update) ~/.murineshiftwork/msw_machine.yaml.
murineshiftwork.logic.task_process
¶
TaskProcess
¶
Manages one session: paths, bpod connection, task thread lifecycle.
Bpod injection: pass a pre-opened RobustBpodSession via bpod= to let
the caller (controller/hardware manager) own the hardware connection. When
bpod is None (default), TaskProcess opens the connection itself using
serial_port_bpod.
connect_bpod(max_try=None, retry_delay_s=None)
¶
Connect device on serial port.
max_try and retry_delay_s are forwarded to BpodFactory; when None, BpodFactory uses its own defaults (connect_retries=3, retry_delay_s=2.0).
init_task()
¶
Import specific Task and make self.task_runner Thread.
run_task()
¶
Run the Task thread.
TaskRunner
¶
Bases: Thread
Base class for task threads.
Subclass and override run(). Check self.continue_task in the run
loop so stop() can interrupt gracefully. No Qt dependency: GUI layers
can wrap this in a QThread adapter if needed.
get_path(artifact)
¶
Return the session file path for artifact (e.g. 'df.jsonl', 'log').
prepare()
¶
Override for setup work before the task starts (load settings, open video, etc.).
run()
¶
Override with task loop logic.
trial_index = 0 max_trials = 1500 while self.continue_task and trial_index < max_trials: ...
update_session_yaml(session_file_path, **sections)
¶
Add or update top-level sections in .msw.session.yaml.
Creates the file with msw_format_version: 2 if it does not exist yet. Typical callers: task_objects writing task_settings or stage after init.
Config models¶
murineshiftwork.logic.config.models.SetupConfig
¶
Bases: BaseModel
Hardware configuration for a single behavioural rig.
Describes the physical devices (Bpod, PulsePal, stage, scale), camera
backend, valve calibrations, and per-rig hooks for one named setup.
Loaded from {config_dir}/setups/{name}.yaml by
load_setup_config.
murineshiftwork.logic.config.models.SubjectConfig
¶
Bases: BaseModel
Per-animal configuration stored as a YAML file under subjects/.
Captures identity metadata (name, project, experiment) and optional per-task parameter overrides that are merged on top of the task's default settings at session start.
murineshiftwork.logic.config.models.ExecutionConfig
¶
Bases: BaseModel
Runtime bundle assembled at session start from setup, subject, and task.
Collects the resolved SetupConfig, SubjectConfig, and merged task
settings into a single object that is passed through the session pipeline.
All fields are optional so the object can be built incrementally as each
config source becomes available.
Barcode helpers (re-exported from
ttl-barcoder) and host-session helpers (frommsw-open-ephys) are documented in those packages' own docs.