README.md

harp

Python interface to Harp devices and their recorded data, implementing the Harp binary protocol.

Harp is a standard for asynchronous real-time data acquisition and experimental control in neuroscience. Every command and event is hardware timestamped on the device. Devices sharing a clock line continuously self-synchronize, so events across a rig sit on one clock and need no post-hoc alignment.

This project includes four main packages:

• harp-protocol: Implements the Harp binary protocol in Python, with registers, messages, and payload parsing. See Protocol API Documentation for details.

• harp-device: Implements the transport-agnostic Device interface and the core register set. See Device API Documentation for details.

• harp-serial: Connects to a Device over a serial COM or tty port. See Serial API Documentation for details.

• harp-data: Reads logged register files into pandas DataFrames. See Data API Documentation for details.

Installation

All packages are published to PyPI. The harp package is a metapackage with no code of its own. It depends on the four packages above, so it is the easiest way to get everything:

pip install harp

uv add substitutes for pip install throughout.

To install only part of the stack, for example when reading recorded data with no need for serial I/O, install the individual packages. Each one only pulls in what it actually depends on:

Package	Depends on
harp-protocol	none
harp-device	harp-protocol
harp-serial	harp-protocol, harp-device
harp-data	harp-protocol

pip install harp-protocol
pip install harp-device
pip install harp-serial
pip install harp-data

harp-benchmarks, under src/packages/, is internal-only and is never published to PyPI.

Quickstart

There are two typical ways to use harp: talking to a live device over a serial connection, or reading data recorded to disk.

Talk to a live device. Open a connection and read/write registers by class:

from harp import serial
from harp.device import behavior, core

# Use "COMx" on Windows, "/dev/ttyUSBx" on Linux.
with serial.open_device(behavior, port="COM3") as device:
    print(device.read(core.WhoAmI).payload)         # a core register
    print(device.read(behavior.AnalogData).payload) # a device register
    device.write(
        core.OperationControl,
        core.OperationControlPayload(operation_mode=core.OperationMode.ACTIVE),
    )

Read a recorded session. Point a DatasetReader at a dataset folder and read registers into pandas DataFrames, with no hardware required:

from harp import data

# Finds device.yml in the folder, builds the device, returns a ready-to-use reader
reader = data.open_dataset("session.harp")
df = reader.read("AnalogData")  # by name
df = reader.read(44)            # or by address

# `contents` names every register the folder holds
frames = {name: reader.read(name) for name in reader.contents}

Given a device package already in hand, pass it as the second argument and read by register class. This is the form that type-checks, and it also checks the device identity against the device.yml in the folder:

from harp import data
from harp.device import behavior

reader = data.open_dataset("session.harp", behavior)
df = reader.read(behavior.AnalogData)

Both paths are based on a device schema. Given only a device.yml and no pre-generated package, create_device_module compiles it into a module of register classes at runtime, with no code-generation step. This is exactly what open_dataset does internally:

from pathlib import Path

from harp.device import schema

behavior = schema.create_device_module(Path("device.yml").read_bytes())
AnalogData = behavior.AnalogData                 # registers are accessed by name
assert behavior.REGISTER_MAP[44] is AnalogData   # or by address

See the examples in the documentation for the full walkthroughs, including subscribing to device events and working with custom interface-type converters.

Contributing

harp is a uv workspace: every package under src/packages/ is its own distribution, plus the root harp metapackage. Bug reports and contributions are welcome, so please open an issue or pull request.

Clone the repository and install everything with the dev dependency group: all workspace packages, editable, plus test and lint tooling.

uv sync --group dev

Before opening a pull request, run the same checks CI runs:

uv run ruff format --check   # formatting
uv run ruff check            # lint
uv run pyright               # type checking
uv run codespell             # spelling
uv run pytest --cov harp     # tests

To add a new package, place it under src/packages/<name>/ with its own pyproject.toml and add it to [tool.uv.sources] in the root pyproject.toml. If it should ship as part of harp, add it to the dependencies of the root package as well.

Build the documentation

Install the docs dependency group and run mkdocs through uv:

uv sync --group docs --group dev
uv run mkdocs serve   # live-reloading local preview
uv run mkdocs build   # static site in ./site