Metadata-Version: 2.4
Name: pycontrol-core
Version: 3.0.0a8
Summary: Sans-IO host library for the pyControl behavioural-experiment framework.
Project-URL: Homepage, https://github.com/karpova-lab/pycontrol-core
Author: pyControl contributors
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: behaviour,micropython,neuroscience,pyboard,pycontrol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=3.0.3
Requires-Dist: pydantic>=2.6
Requires-Dist: pyserial>=3.5
Provides-Extra: integrations
Requires-Dist: boto3>=1.43.22; extra == 'integrations'
Requires-Dist: notion-client>=3.1.0; extra == 'integrations'
Requires-Dist: slack-sdk<4,>=3.27; extra == 'integrations'
Provides-Extra: lint
Requires-Dist: mypy>=1.10; extra == 'lint'
Requires-Dist: ruff>=0.5; extra == 'lint'
Requires-Dist: types-pyserial>=3.5; extra == 'lint'
Provides-Extra: notion
Requires-Dist: notion-client>=3.1.0; extra == 'notion'
Provides-Extra: s3
Requires-Dist: boto3>=1.43.22; extra == 's3'
Provides-Extra: slack
Requires-Dist: slack-sdk<4,>=3.27; extra == 'slack'
Provides-Extra: test
Requires-Dist: hypothesis>=6.100; extra == 'test'
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# 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:

```text
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](docs/wire-protocol.md) and
[data-format.md](docs/data-format.md) for the frozen specs.

## Install From PyPI Alpha

For the current alpha, allow prereleases:

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

To install the GUI workflow, add `pycontrol-gui` instead; it depends on
`pycontrol-core`. See [getting-started.md](docs/getting-started.md).

## Install For Development

From this package:

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

With `uv`:

```bash
uv sync --extra test --extra lint
```

Run checks:

```bash
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.

```bash
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](docs/getting-started.md).

## Run A Task

```bash
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 data under the workspace data directory.

## Run An Experiment

```bash
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.

```bash
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:

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

See [troubleshooting.md](docs/troubleshooting.md) for operator triage.

## Public Imports

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

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

See [public-api.md](docs/public-api.md) for the supported import surface.

## Documentation

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

- [Documentation index](../rewrite-docs/README.md) - map of everything, with a reading order.
- [Architecture tour](../rewrite-docs/ARCHITECTURE-TOUR.md) - learn the system end to end.
- [Technical overview](../rewrite-docs/TECHNICAL.html) - what changed versus pyControl v2 and why.

Orientation and operation:

- [Getting started](docs/getting-started.md)
- [Writing tasks](docs/writing-tasks.md)
- [Hardware definitions](docs/hardware-definitions.md)
- [Architecture](docs/architecture.md)
- [CLI reference](docs/cli-reference.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Migration from pyControl v2](docs/migration-from-official.md)
- [Deleted surface](DELETED.md)

Contracts and internals:

- [Public API](docs/public-api.md)
- [Contracts](docs/contracts.md)
- [Wire protocol](docs/wire-protocol.md)
- [Data format](docs/data-format.md)
- [Threading and state](docs/threading-and-state.md)
- [Subscriber API](docs/subscriber-api.md)

Extending pyControl:

- [Task extensions](docs/task-extensions.md) - includes integrations and optional extras.
- [Experiment extensions](docs/experiment-extensions.md)
- [Extension settings](docs/extension-settings.md)
- [Task sharing archives](docs/sharing.md)

Project process:

- [Testing guide](docs/testing.md)
- [Maintainability and adoption plan](docs/maintainability.md)
- [Changelog](docs/changelog.md)

## Contributing

See the repository-level [CONTRIBUTING.md](../pycontrol-archive/CONTRIBUTING.md)
for editable installs, tests, contracts, firmware notes, and trusted plugin
guidance.
