pycontrol-core 3.0.0a13

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 board wire protocol remains compatible with existing pyControl tasks. The host writes one canonical .pycontrol.zip run bundle per recording. The analysis importer reads both historical TSVs and native bundles and can return the familiar legacy dataframe columns; manual TSV/NPY export remains available only for external tools that require loose files. See wire-protocol.md and data-format.md for the frozen specs.

Install From PyPI Alpha

For the current alpha, allow prereleases:

uv add pycontrol-core --prerelease allow
# or
pip install --pre pycontrol-core

For the GUI workflow, install the app once globally with pycontrol-manager app install, verify it with pycontrol-manager app status, then launch it with pycontrol gui. 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 native .pycontrol.zip run bundles.

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

Run A Task

pycontrol run --setup BoxA --task examples/blinker \
  --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 an explicit --hwdef or a setup default hardware definition.

The run command connects to the board, checks firmware status, uploads the hardware definition when the task needs one, uploads the task, starts the framework, and writes a .pycontrol.zip run bundle 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 NativeEventLogger
from pycontrol.extension import TaskExtension
from pycontrol.workspace import Workspace
from pycontrol.analysis.data_import import session_dataframe

Install pandas dataframe helpers into the global app with pycontrol-manager app extras add analysis, or install pycontrol-core[analysis] in a pip-managed environment. Rig-control, recording, bundles, and the CLI do not require pandas.

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.
• Data-flow walkthrough - one packet's journey through the pipeline.

Orientation and operation:

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

Contracts and internals:

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

Extending pyControl:

• Task extensions - includes integrations and optional extras.
• Experiment extensions
• Extension settings
• Task sharing archives

Project process:

• Testing guide
• Maintainability metrics
• Changelog

Contributing

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