pycontrol-core

pycontrol-core is the host engine for pyControl. It handles board communication, the wire protocol, workspace configuration, data logging, task and experiment handlers, 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, and the analysis importer reads those bundles (not pyControl v2 loose TSV files). See wire-protocol.md and data-format.md for the frozen specs.

Install From PyPI

3.0.0 is in beta, so allow pre-releases:

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:

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.addons import TaskHandler
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

Start with Understanding one run, then use the references below. Release acceptance distinguishes host verification from the hardware evidence required for lab deployment.

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 handlers - includes integrations and optional extras.
• Experiment handlers
• Addon settings
• Task sharing archives

Project process:

• Testing guide
• Maintainability metrics
• Changelog

Contributing

See CONTRIBUTING.md for local development and review.