cuewire

structured cues over a serial wire — Python ↔ Arduino integer-command bridge for behavioural rigs.

cuewire is the modern descendant of PARROT (Python ARduino seRial cOmmunicaTion). It speaks a compact integer-command protocol to an Arduino running the PARROTard firmware, and ships a rig-specific subclass for the Hüpfburg rocking-platform assay.

Install

pip install -e ".[dev]"

or with conda:

conda env create -f environment.yml
conda activate cuewire
pip install -e ".[dev]"

Quickstart

Generic Arduino link:

from cuewire import ArduinoSerial

with ArduinoSerial("/dev/ttyUSB0") as ard:
    ard.set_write_out(True)
    ard.reset_clock()

Hüpfburg rocking-platform rig:

from cuewire import HuepfburgRig, LedMode, LedPattern

with HuepfburgRig("/dev/ttyUSB0") as rig:
    rig.set_led_mode(LedMode.DOWN_CYCLE, settle_s=1.0)
    rig.set_led_pattern(LedPattern.STRIPES, settle_s=1.0)
    params = rig.get_exp_parameters()
    print(params)

CLI:

cuewire list-ports
cuewire test /dev/ttyUSB0
cuewire run-experiment experiments/configs/rocking.toml

Quickstart: minimal worked example

The examples/two_led_thermo/ directory ships a complete rig in two LEDs + a thermistor + a camera TTL trigger, with a 105 s phasing protocol and 10 Hz CSV telemetry. Two ways to run it:

# Path A — Python simulator (no Arduino, no apt installs)
from cuewire.examples import TwoLedThermoSimulator, run_protocol
with TwoLedThermoSimulator() as sim:
    run_protocol(sim.device_path, "two_led_thermo.log")

# Path B — real firmware inside simavr
sudo apt install simavr libsimavr-dev
arduino-cli compile --fqbn arduino:avr:uno \
    --output-dir /tmp/two_led_thermo_build \
    examples/two_led_thermo/firmware/two_led_thermo
make -C examples/two_led_thermo/simavr
./examples/two_led_thermo/simavr/simrun \
    /tmp/two_led_thermo_build/two_led_thermo.ino.hex &
python examples/two_led_thermo/run_protocol.py --port /tmp/simavr-uart0

See examples/two_led_thermo/README.md for the full walkthrough, hardware wiring, and the install guide.

Repository layout

cuewire/
├── src/cuewire/
│   ├── constants.py     command IDs, LED enums, defaults
│   ├── serial_link.py   ArduinoSerial — generic protocol bridge
│   ├── port_select.py   pyserial port helpers
│   ├── huepfburg.py     HuepfburgRig + ExpParameters dataclass
│   ├── cli.py           click console entry points
│   └── experiments/     concrete experiment protocols
├── firmware/PARROTard/  Arduino sketch (stub — see firmware/README.md)
├── experiments/configs/ TOML config templates
├── tests/               pytest, no hardware required
├── docs/                Sphinx documentation
└── _legacy/             pre-cuewire code (preserved for one commit)

Firmware status

The Arduino sketch shipped here is incomplete relative to the Python API — see firmware/README.md for the list of unimplemented command IDs. The fully-wired firmware lives elsewhere and needs to be folded back in.

Citing

If you use cuewire in academic work, please cite it via the metadata in CITATION.cff. Each tagged release mints a DOI via Zenodo.

Provenance

The Hüpfburg-specific protocol was developed jointly with Sophie Gobeil during a 2021 lab rotation in the Geurten group.

License

MIT — see LICENSE.