pycontrol-core 3.0.0a1

Sans-IO host library for the pyControl behavioural-experiment framework.

pycontrol-core

pycontrol-core is the host engine for pyControl. It handles board communication, the wire protocol, workspace configuration, data logging, task and experiment extensions, firmware sync, and the pycontrol command-line tool.

The package is designed so GUI and script frontends share the same tested core:

Pyboard <-> Transport <-> protocol codec <-> BoardSession <-> event bus <-> subscribers

The on-disk data format and board wire protocol are kept compatible with existing pyControl sessions. See wire-protocol.md and data-format.md for the frozen specs.

Install From PyPI Alpha

For the 3.0.0a1 alpha, pin the prerelease:

uv add "pycontrol-core==3.0.0a1"
# or
pip install --pre "pycontrol-core==3.0.0a1"

To install the GUI workflow, add pycontrol-gui instead; it depends on pycontrol-core. See getting-started.md.

Install For Development

From this package:

pip install -e ".[test,lint]"

With uv:

uv sync --extra test --extra lint

Run checks:

uv run pytest
uv run ruff check src tests
uv run mypy

Create A Workspace

Most lab-authored files live in a workspace, not inside this package.

pycontrol workspace init my-workspace
cd my-workspace
pycontrol setups add BoxA --port /dev/cu.usbmodemXXXX

The workspace contains:

Path	Purpose
tasks/	Task files uploaded to the board.
hardware_definitions/	Rig wiring files uploaded as hardware_definition.py.
devices/	Workspace device classes uploaded when referenced.
plugins/task_extensions/	Host-side task automation.
plugins/experiment_extensions/	Whole-experiment automation.
plugins/task_plotters/	Optional GUI plotters.
plugins/task_controls/	Optional GUI control panels.
experiments/*.json	Multi-subject experiment definitions.
settings.json / setups.json	Workspace settings and setup registry.
data/	Default output folder for TSV and analog .npy files.

For a full walkthrough, use getting-started.md.

Run A Task

pycontrol run --setup BoxA --task blinker --hwdef example \
  --subject mouse42 --duration 10

--setup looks up the serial port and setup variables from setups.json. --task and --hwdef are resolved against the workspace by stem or by path. Tasks that import hardware_definition need --hwdef.

The run command connects to the board, checks firmware status, uploads the hardware definition and task, starts the framework, and writes data under the workspace data directory.

Run An Experiment

pycontrol experiment blink_demo --duration 10

Experiment identity comes from the JSON file path under experiments/. For example, experiments/training/day1.json is experiment training/day1.

Experiment JSON supports a first-class optional hardware_definition field. When present, it overrides each setup's default hardware definition for that experiment; when omitted, the setup default is used.

Firmware And Board Checks

BoardSession.connect() performs a read-only firmware status check. It never syncs files automatically.

pycontrol firmware status --setup BoxA
pycontrol firmware sync --setup BoxA
pycontrol board info --setup BoxA --json

Setups can pin an expected MCU so the host refuses the wrong board:

pycontrol setups add BoxH7 --port /dev/cu.usbmodemYYYY --mcu stm32h743
pycontrol setups detect BoxH7

See troubleshooting.md for operator triage.

Public Imports

pycontrol.__init__ exports only __version__. Import from explicit modules:

from pycontrol.session import BoardSession
from pycontrol.recording import TsvLogger
from pycontrol.extension import TaskExtension
from pycontrol.workspace import Workspace

See public-api.md for the supported import surface.

Documentation

New to the project? Start with the repo-level guides:

• Documentation index - map of everything, with a reading order.
• Architecture tour - learn the system end to end.
• Why the rewrite - what changed versus pyControl v2 and why.

Orientation and operation:

• Getting started
• Writing tasks
• Hardware definitions
• Architecture
• CLI reference
• Troubleshooting
• Migration from pyControl v2
• Deleted surface

Contracts and internals:

• Public API
• Contracts
• Wire protocol
• Data format
• Threading and state
• Subscriber API

Extending pyControl:

• Task extensions
• Experiment extensions
• Extension settings
• Integrations
• Task sharing archives

Project process:

• Testing guide
• Changelog
• Current code review backlog

Contributing

See the repository-level CONTRIBUTING.md for editable installs, tests, contracts, firmware notes, and trusted plugin guidance.