Skip to content

Examples

The scripts below live in the examples/ folder of the repository. Every one accepts --port (default: auto-detect) and --simulate, which runs it against the simulated controller with no hardware attached:

uv run python examples/06_trials.py --simulate

Getting started

01_connect.py

Connect to the device, print its firmware version, and disconnect.

"""Connect to the device, print its firmware version, and disconnect.

Shows: Device.open(), the context manager, auto-detection.
Requires: a connected device (or use --simulate).
"""

import argparse

from arena_interface import Device


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        print(f"Connected. Firmware version: {dev.firmware_version}")


if __name__ == "__main__":
    main()

02_ports.py

List serial ports, then connect to one by name.

"""List serial ports, then connect to one by name.

Shows: find_ports() (Teensy candidates and all ports), Device.open(port),
probe=False.
Requires: a connected controller (or use --simulate).
"""

import argparse

from arena_interface import Device, DeviceNotFound, find_ports


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    ports = find_ports(all_ports=True)
    print("USB serial ports:")
    for port in (p for p in ports if p.vid is not None):
        print(f"  {port.device:15} {port.vid:04X}:{port.pid:04X}  {port.description}")
    print(f"({sum(p.vid is None for p in ports)} non-USB ports not shown)")

    candidates = find_ports()  # Teensy USB ids only; nothing is sent to them
    print(f"Teensy candidates: {[p.device for p in candidates] or 'none'}")

    if args.simulate:
        dev = Device.open(simulate=True)
    elif args.port:
        dev = Device.open(args.port)  # an explicit port skips detection
    else:
        try:
            # Without probing, more than one candidate is an error.
            dev = Device.open(probe=False)
        except DeviceNotFound as exc:
            print(f"Could not choose a port: {exc}")
            return

    with dev:
        print(f"Connected on {dev.port_name}: {dev.firmware_version}")


if __name__ == "__main__":
    main()

03_open_close.py

Context manager versus manual open/close, and leaving the display on.

"""Context manager versus manual open/close, and leaving the display on.

Shows: `with Device.open(...)`, try/finally with close(), is_open, and
all_off_on_close=False to keep a stimulus running after the script ends.
Requires: a connected controller (or use --simulate).
"""

import argparse

from arena_interface import Device


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    # 1. Context manager: the arena is blanked (ALL_OFF) and the port released
    #    when the block ends, even if an exception is raised inside it.
    with Device.open(args.port, simulate=args.simulate) as dev:
        dev.all_on()
        print(f"inside the block: open={dev.is_open}")
    print(f"after the block:  open={dev.is_open}")

    # 2. Manual: the same, written out.
    dev = Device.open(args.port, simulate=args.simulate)
    try:
        dev.all_on()
    finally:
        dev.close()  # safe to call twice, and after the device has gone

    # 3. Leave the arena lit when the script exits.
    with Device.open(args.port, simulate=args.simulate, all_off_on_close=False) as dev:
        dev.all_on()
    print("arena left on; run ALL_OFF (e.g. example 05) to blank it")


if __name__ == "__main__":
    main()

Core usage

04_device_info.py

Read what the controller reports about itself.

"""Read what the controller reports about itself.

Shows: info (protocol version, capabilities, MAC), firmware (build identity),
supports(), arena (the panel grid), and a short health summary.
Requires: a connected controller (or use --simulate).
"""

import argparse

from arena_interface import Capability, Device, FirmwareFlag


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        print(f"Port:          {dev.port_name}")
        print(f"MAC address:   {dev.info.mac}")
        print(f"Protocol:      v{dev.info.protocol_version}")
        print(f"Capabilities:  {dev.capabilities!r}")
        print(f"Firmware:      {dev.firmware_version}")
        print(f"Arena:         {dev.arena} {dev.arena.pixel_shape} pixels")

        for feature in (Capability.IO_EXT, Capability.HEALTH, FirmwareFlag.TELEMETRY):
            print(f"  supports {feature.name:10} {dev.supports(feature)}")

        if dev.supports(Capability.HEALTH):
            health = dev.diagnostics.health()
            print(f"Uptime:        {health.uptime_ms / 1000:.1f} s")
            print(f"State:         {health.state!r}")
            print(f"SD card:       {'mounted' if health.sd_mounted else 'none'}")
            print(f"Frames sent:   {health.frames_sent}")


if __name__ == "__main__":
    main()

05_display_settings.py

Read and change the display settings.

"""Read and change the display settings.

Shows: all_on(), all_off(), stop(), refresh_rate, panel_display_mode,
frames_sent and reset_frames_sent().
Requires: a connected controller (or use --simulate).
Note: a refresh rate set here stays in force until the controller restarts.
"""

import argparse
import time

from arena_interface import Device, PanelDisplayMode


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        print(f"Refresh rate:       {dev.refresh_rate} Hz")
        print(f"Panel display mode: {dev.panel_display_mode.name}")

        dev.panel_display_mode = PanelDisplayMode.PERSIST  # the default
        dev.reset_frames_sent()

        dev.all_on()
        time.sleep(0.5)
        print(f"Frames sent in 0.5 s of ALL_ON: {dev.frames_sent}")

        dev.stop()  # same effect as all_off(): blank and stop
        print("Arena blanked")


if __name__ == "__main__":
    main()

06_trials.py

Run trials from a pattern stored on the SD card.

"""Run trials from a pattern stored on the SD card.

Shows: start_trial() in open loop (forwards and backwards), closed loop and
with a controller-timed duration; polling frame_position. --pattern takes a
file name (".pat" and case optional, e.g. demo_gs2) or an id (the pattern's
number in alphabetical order, starting at 1).
Requires: a controller with at least one pattern on its SD card (or
--simulate, which provides demo patterns).
"""

import argparse
import time

from arena_interface import Device, TrialMode


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument(
        "--pattern",
        type=lambda s: int(s) if s.isdigit() else s,
        default=1,
        help="pattern file name (e.g. grating.pat) or id (first pattern = 1)",
    )
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        print(f"Pattern {args.pattern!r}")

        # Open loop: the controller advances frames by itself.
        dev.start_trial(args.pattern, TrialMode.OPEN_LOOP, frame_rate=30)
        for _ in range(3):
            time.sleep(0.2)
            print(f"  forwards  {dev.frame_position}")

        dev.start_trial(args.pattern, TrialMode.OPEN_LOOP, frame_rate=-30)
        time.sleep(0.2)
        print(f"  backwards {dev.frame_position}")

        # Closed loop: frame rate = Analog In 1 voltage x gain / 10.
        dev.start_trial(args.pattern, TrialMode.CLOSED_LOOP, gain=20)
        print("  closed loop running (drive Analog In 1 to move the pattern)")
        time.sleep(0.2)

        # A duration makes the controller stop the trial on its own.
        dev.start_trial(args.pattern, TrialMode.OPEN_LOOP, frame_rate=60, duration=0.5)
        time.sleep(0.7)
        print("  timed trial finished; the arena is dark again")


if __name__ == "__main__":
    main()

07_show_frames.py

Choose each displayed frame from the host.

"""Choose each displayed frame from the host.

Shows: show_pattern() (show-frame mode at frame 0), show_frame() stepping,
frame_position, and the local check that rejects an out-of-range frame
before it reaches the controller (which would stop the display).
Requires: a controller with at least one pattern on its SD card (or
--simulate).
"""

import argparse
import time

from arena_interface import Device


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument(
        "--pattern",
        type=lambda s: int(s) if s.isdigit() else s,
        default=1,
        help="pattern file name (e.g. grating.pat) or id (first pattern = 1)",
    )
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        dev.show_pattern(args.pattern)
        count = dev.frame_position.frame_count
        print(f"Pattern {args.pattern} has {count} frames")

        for index in range(0, count, max(1, count // 8)):
            dev.show_frame(index)
            time.sleep(0.05)
            print(f"  showing {dev.frame_position.index}")

        try:
            dev.show_frame(count)  # one past the end
        except ValueError as exc:
            print(f"Rejected locally: {exc}")


if __name__ == "__main__":
    main()

08_pattern_library.py

Manage the patterns on the controller's SD card.

"""Manage the patterns on the controller's SD card.

Shows: iterating device.patterns, info(), upload(), download(), rename(),
find() by name with the name cache on, delete() and archive(). The example
uploads its own pattern and removes it again, so the card ends as it started.
Requires: a controller with an SD card (or --simulate). The display is
stopped first, because transfers need it off.
"""

import argparse

from arena_interface import Device, Pattern


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    # cache_patterns: keep the names, so finding a pattern by name is fast.
    with Device.open(args.port, simulate=args.simulate, cache_patterns=True) as dev:
        dev.stop()
        for entry in dev.patterns:
            info = dev.patterns.info(entry.pattern_id)
            print(
                f"{entry.pattern_id:3} {entry.name:30} {info.frame_count:5} frames "
                f"{info.gray_level.name} {info.rows}x{info.cols}"
            )

        # A one-frame pattern sized for this controller.
        height, width = dev.arena.pixel_shape
        frame = [
            [15 if x < width // 2 else 0 for x in range(width)] for _ in range(height)
        ]
        pid = dev.patterns.upload("zz_example_08.pat", Pattern.from_frames([frame]))
        print(f"Uploaded as id {pid}")

        data = dev.patterns.download(pid)
        print(f"Downloaded {len(data)} bytes; frames: {len(Pattern.from_bytes(data))}")

        pid = dev.patterns.rename(pid, "zz_example_08_renamed.pat")
        print(f"Renamed; id is now {pid}: {dev.patterns.name(pid)}")
        found = dev.patterns.find("ZZ_example_08_renamed")  # case, .pat optional
        print(f"Found by name: id {found}")

        dev.patterns.delete("zz_example_08_renamed")  # by name: safer than an id
        print(f"Deleted; {len(dev.patterns)} patterns remain")

        if args.simulate:  # a full card can take a while to download
            print(f"SD archive: {len(dev.patterns.archive())} bytes (ZIP)")


if __name__ == "__main__":
    main()

09_make_pattern.py

Build a pattern from pixel arrays and save it as a .pat file.

"""Build a pattern from pixel arrays and save it as a .pat file.

Shows: Pattern.from_frames() with numpy arrays (nested lists work too), an
arena preset, gray levels, duty cycle, origin="lower" for bottom-origin data,
to_bytes() and reading the file back with Pattern.from_bytes(). Upload the
result with device.patterns.upload("grating.pat", pattern).
Requires: nothing (no controller needed). Writes grating.pat.
"""

import argparse
from pathlib import Path

import numpy as np

from arena_interface import Arena, GrayLevel, Pattern


def grating(height: int, width: int, shift: int, period: int = 20) -> np.ndarray:
    """A triangle-wave grating with 16 brightness levels, moved by `shift` pixels."""
    phase = ((np.arange(width) + shift) % period) / period
    row = np.round(15 * (1 - np.abs(2 * phase - 1))).astype(np.uint8)
    return np.tile(row, (height, 1))


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (unused: no device needed)")
    parser.add_argument(
        "--simulate", action="store_true", help="accepted for consistency"
    )
    parser.add_argument("--arena", default="G6_2x10", help="arena preset name")
    parser.add_argument("--output", type=Path, default=Path("grating.pat"))
    args = parser.parse_args()

    arena = Arena.preset(args.arena)
    height, width = arena.pixel_shape
    frames = [grating(height, width, shift) for shift in range(20)]

    pattern = Pattern.from_frames(
        frames, gray_level=GrayLevel.GS16, arena=arena, duty_cycle=128
    )
    args.output.write_bytes(pattern.to_bytes())
    print(f"Wrote {args.output}: {pattern}")

    # Orientation: by default row 0 is the TOP of the arena. Data whose row 0 is
    # the bottom (MATLAB / JS convention) needs origin="lower".
    marker = np.zeros((height, width), dtype=np.uint8)
    marker[0, 0] = 15
    top = Pattern.from_frames([marker], arena=arena)
    bottom = Pattern.from_frames([marker], arena=arena, origin="lower")
    row_top = int(np.argmax(top.frame(0)[:, 0]))  # frame() returns a numpy array
    row_bottom = int(np.argmax(bottom.frame(0)[:, 0]))
    print(f"marker in row {row_top} vs {row_bottom} (rows counted from the top)")

    again = Pattern.from_bytes(args.output.read_bytes())
    print(f"Read back: {again}; identical: {again == pattern}")


if __name__ == "__main__":
    main()

10_stream_images.py

Send images from the host straight to the arena.

"""Send images from the host straight to the arena.

Shows: stream_image() with a moving bar in a simple timed loop. Streamed
frames need no SD card. (Precisely paced playback is a planned feature; this
loop just sleeps between frames.)
Requires: a connected controller (or use --simulate).
"""

import argparse
import time

from arena_interface import Device, GrayLevel


def bar(height: int, width: int, x0: int, bar_width: int = 20) -> list[list[int]]:
    """An image with a vertical bright bar starting at column x0."""
    row = [1 if (x - x0) % width < bar_width else 0 for x in range(width)]
    return [list(row) for _ in range(height)]


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--fps", type=float, default=30.0, help="frames per second")
    parser.add_argument("--seconds", type=float, default=2.0, help="how long to run")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        height, width = dev.arena.pixel_shape
        frames = int(args.fps * args.seconds)
        start = time.monotonic()
        for n in range(frames):
            dev.stream_image(bar(height, width, x0=n * 4), gray_level=GrayLevel.GS2)
            time.sleep(max(0.0, start + (n + 1) / args.fps - time.monotonic()))
        elapsed = time.monotonic() - start
        print(
            f"Streamed {frames} frames in {elapsed:.2f} s ({frames / elapsed:.1f} fps)"
        )


if __name__ == "__main__":
    main()

11_analog_io.py

Analog output and inputs.

"""Analog output and inputs.

Shows: io.analog_out (set, and read back from the DAC), a lookup table that
follows the displayed frame, the frame-number output mode, and
io.read_analog_in().
Requires: a controller with the extended I/O capability and a pattern on
its SD card (or --simulate). Use a pattern with several frames to see the
table step. The analog output BNC changes voltage while this runs.
"""

import argparse

from arena_interface import AoLutMode, AoMode, Device, TrialMode


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument(
        "--pattern",
        type=lambda s: int(s) if s.isdigit() else s,
        default=1,
        help="pattern file name (e.g. grating.pat) or id (first pattern = 1)",
    )
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        io = dev.io
        io.set_analog_out_mode(AoMode.PROGRAMMABLE)
        io.analog_out = 2500
        print(f"Analog out set to 2500 mV, DAC reads back {io.analog_out} mV")

        # Lookup table: one level per frame index (up to 21 levels).
        io.load_analog_table([0, 1250, 2500, 3750, 5000], AoLutMode.FRAME_LOCKED)
        dev.show_pattern(args.pattern)
        for frame in range(min(5, dev.frame_position.frame_count)):
            dev.show_frame(frame)
            print(f"  frame {frame}: analog out {io.analog_out} mV")

        # Frame-number mode: 0 V at the first frame, 5 V at the last.
        io.set_analog_out_mode(AoMode.FRAME_NUMBER)
        dev.start_trial(args.pattern, TrialMode.SHOW_FRAME)
        dev.show_frame(dev.frame_position.frame_count - 1)
        print(f"Frame-number mode, last frame: {io.analog_out} mV")
        io.set_analog_out_mode(AoMode.PROGRAMMABLE)

        inputs = io.read_analog_in()
        print(f"Analog in: {inputs.ain1_mv} mV, {inputs.ain2_mv} mV")


if __name__ == "__main__":
    main()

12_digital_io.py

Digital IO BNC ports: roles, outputs and levels.

"""Digital IO BNC ports: roles, outputs and levels.

Shows: io.dio_roles(), io.set_dio_role(), io.set_digital_out() and
io.read_digital(), including the refusal to drive a port configured as an
input.
Requires: a controller with the extended I/O capability (or --simulate).
Port 1 is driven high, then low, while this runs.
"""

import argparse

from arena_interface import CommandError, Device, DioRole


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        io = dev.io
        for number, port in enumerate(io.dio_roles(), start=1):
            level = "high" if port.high else "low"
            print(f"Port {number}: {port.role.name:20} level={level}")

        io.set_dio_role(1, DioRole.OUT_PROGRAMMABLE)
        io.set_digital_out(1, True)
        print(f"Port 1 driven high; levels now {io.read_digital()}")
        io.set_digital_out(1, False)

        # Port 2 boots as the external-trigger input; driving it is refused.
        roles = io.dio_roles()
        if roles[1].role is DioRole.IN_TRIGGER:
            try:
                io.set_digital_out(2, True)
            except CommandError as exc:
                print(f"Refused as expected: {exc.message}")


if __name__ == "__main__":
    main()

13_sample_to_csv.py

Record the analog inputs at a fixed rate into a CSV file.

"""Record the analog inputs at a fixed rate into a CSV file.

Shows: device.sample() with a read method, wall-clock timestamps, and the
count of readings skipped because the computer fell behind.
Requires: a controller with the extended I/O capability (or --simulate).
Writes analog_samples.csv.
"""

import argparse
import csv
from pathlib import Path

from arena_interface import Device


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--rate", type=float, default=100.0, help="samples per second")
    parser.add_argument("--seconds", type=float, default=2.0, help="how long to record")
    parser.add_argument("--output", type=Path, default=Path("analog_samples.csv"))
    args = parser.parse_args()

    with (
        Device.open(args.port, simulate=args.simulate) as dev,
        args.output.open("w", newline="") as f,
    ):
        writer = csv.writer(f)
        writer.writerow(["time_s", "ain1_mv", "ain2_mv"])
        sampler = dev.sample(
            dev.io.read_analog_in, rate_hz=args.rate, duration=args.seconds
        )
        rows = 0
        for s in sampler:
            writer.writerow([f"{s.time:.6f}", s.value.ain1_mv, s.value.ain2_mv])
            rows += 1
    print(f"Wrote {rows} samples to {args.output} ({sampler.skipped} skipped)")


if __name__ == "__main__":
    main()

14_telemetry_events.py

Log what the arena actually displayed, from the controller's own record.

"""Log what the arena actually displayed, from the controller's own record.

Shows: telemetry.events() during an open-loop trial, FrameRecord and
StateRecord events with wall-clock times, and writing a frame log to CSV.
The controller timestamps each frame change itself, so the log is more
accurate than timing on the host.
Requires: a controller with telemetry and a pattern on its SD card (or
--simulate). Writes frame_log.csv.
"""

import argparse
import csv
from pathlib import Path

from arena_interface import Device, FrameRecord, StateRecord, TrialMode


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--seconds", type=float, default=1.0, help="trial length")
    parser.add_argument("--output", type=Path, default=Path("frame_log.csv"))
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        dev.telemetry.drain()  # discard anything logged before now
        dev.start_trial(1, TrialMode.OPEN_LOOP, frame_rate=20, duration=args.seconds)

        frames = 0
        with args.output.open("w", newline="") as f:
            writer = csv.writer(f)
            writer.writerow(["time_s", "pattern", "frame"])
            stream = dev.telemetry.events(duration=args.seconds + 0.3)
            for event in stream:
                rec = event.record
                if isinstance(rec, FrameRecord):
                    writer.writerow([f"{event.time:.6f}", rec.pattern_id, rec.index])
                    frames += 1
                elif isinstance(rec, StateRecord) and rec.new_state is not None:
                    print(f"{event.time:.3f}  state -> {rec.new_state.name}")
    print(f"Logged {frames} frame changes to {args.output} (lost: {stream.lost})")


if __name__ == "__main__":
    main()

15_partial_arena.py

Arena presets, partial arenas, and rigs smaller than the firmware's grid.

"""Arena presets, partial arenas, and rigs smaller than the firmware's grid.

Shows: the built-in Arena presets, installed columns, drawing on a rig's full
grid, Pattern.fit_to() onto a controller's panel grid (e.g. a 3x10 rig on
4x10 firmware), and stream_image() with arena=, which fits automatically.
Requires: a connected controller (or use --simulate).
"""

import argparse

from arena_interface import PRESETS, Arena, Device, GrayLevel, Pattern


def columns_lit(rig: Arena) -> list[list[int]]:
    """Light every installed column; uninstalled grid columns stay blank."""
    height, width = rig.pixel_shape
    return [
        [1 if x // 20 in rig.columns else 0 for x in range(width)]
        for _ in range(height)
    ]


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--rig", default="G6_2x8of10", help="arena preset of the rig")
    args = parser.parse_args()

    for name, arena in PRESETS.items():
        print(
            f"{name:14} id {arena.arena_id}  {arena.rows}x{arena.cols} grid, "
            f"columns {arena.columns[0]}-{arena.columns[-1]}"
        )

    # Offline: a 3x10 rig drawn at its own size, placed on a 4x10 firmware grid.
    small = Arena.preset("G6_3x10")
    pattern = Pattern.from_frames(
        [columns_lit(small)], gray_level=GrayLevel.GS2, arena=small
    )
    fitted = pattern.fit_to(4, 10)
    print(f"{pattern} -> fitted for 4x10 firmware: {fitted}")

    # On the device: stream an image drawn for the rig; it is fitted to the
    # controller's grid (an error explains it if the rig cannot fit).
    rig = Arena.preset(args.rig)
    with Device.open(args.port, simulate=args.simulate) as dev:
        installed = len(rig.columns)
        print(f"Controller grid: {dev.arena_shape}; rig: {rig} ({installed} columns)")
        dev.stream_image(columns_lit(rig), gray_level=GrayLevel.GS2, arena=rig)
        print("Streamed the rig image")


if __name__ == "__main__":
    main()

16_panel_firmware.py

Update the panels' own firmware through the controller.

"""Update the panels' own firmware through the controller.

Shows: panel_firmware.info(), upload() (with CRC check), verify() and
program(). Programming is only done when you ask for it with --program.
Requires: a controller with an SD card and a panel image file (--image), or
--simulate, which uses a dummy image. The display is stopped first.
"""

import argparse
from pathlib import Path

from arena_interface import Device


def dummy_image() -> bytes:
    """A stand-in image with the 32-byte footer the controller reads."""
    return bytes(8192) + b"G6PANEL\0" + b"sim-1.0".ljust(16, b"\0") + bytes(8)


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--image", type=Path, help="panel firmware image to upload")
    parser.add_argument("--program", type=int, metavar="PANEL", help="flash this panel")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        dev.stop()
        fw = dev.panel_firmware
        print(f"Stored image: {fw.info() or 'none'}")

        image = (
            args.image.read_bytes()
            if args.image
            else (dummy_image() if args.simulate else None)
        )
        if image is None:
            print("Pass --image FILE to upload a panel image.")
            return
        crc = fw.upload(image)
        print(f"Uploaded {len(image)} bytes, CRC-32 0x{crc:08x}: {fw.info()}")

        panel = args.program or (1 if args.simulate else None)
        if panel is None:
            print("Pass --program N to flash panel N (the first panel is 1).")
            return
        print(f"Before: {fw.verify(panel)}")
        print(f"Programming panel {panel}: {fw.program(panel)}")
        print(f"After:  {fw.verify(panel)}")


if __name__ == "__main__":
    main()

17_diagnostics.py

Controller diagnostics for troubleshooting.

"""Controller diagnostics for troubleshooting.

Shows: diagnostics.health() (counters and previous-boot breadcrumbs),
crash_report(), sd_info(), spi_clock_mhz and debug_output.
Requires: a controller with the health capability (or --simulate).
"""

import argparse

from arena_interface import Capability, Device, FirmwareFlag


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        diag = dev.diagnostics
        if dev.supports(Capability.HEALTH):
            h = diag.health()
            print(
                f"Uptime {h.uptime_ms / 1000:.1f} s, {h.loop_count} loops, "
                f"longest loop {h.loop_max_us} us"
            )
            print(f"SD reads {h.sd_reads}, slowest {h.sd_read_max_us} us")
            print(f"SD error code {h.sd_error}")
            print(
                f"Last reset cause 0x{h.reset_cause:08x}; previous boot ended in "
                f"{h.previous_op!r}"
                if h.breadcrumb_valid
                else "No previous-boot record"
            )

        if dev.supports(FirmwareFlag.CRASH_REPORT):
            report = diag.crash_report()
            print(f"Crash report: {report.fault_name or 'none recorded'}")

        if dev.supports(FirmwareFlag.SD_FAST_PATH):
            sd = diag.sd_info()
            print(
                f"SD card: {sd.product_name} {sd.capacity_bytes / 1e9:.1f} GB, "
                f"FAT type {sd.fat_type}"
                if sd.mounted
                else "SD card: none"
            )

        print(f"Panel SPI clock: {diag.spi_clock_mhz} MHz")
        print(
            f"Debug text output: {'on' if diag.debug_output else 'off'} "
            "(only debug firmware builds print anything)"
        )


if __name__ == "__main__":
    main()

Robustness

18_errors.py

Handling errors: what each exception means and how to recover.

"""Handling errors: what each exception means and how to recover.

Shows: CommandError (the controller refused), ValueError (rejected locally
before sending), UnsupportedCommand (older firmware), DeviceTimeout (no
answer), and DeviceError as the catch-all base class.
Requires: a connected controller (or --simulate, which can also fake a
silent device; on hardware the timeout case is skipped).
"""

import argparse

from arena_interface import (
    CommandError,
    Device,
    DeviceError,
    DeviceTimeout,
    ErrorCode,
    UnsupportedCommand,
)


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        dev.all_on()
        try:
            dev.patterns.download(1)  # transfers need the display off
        except CommandError as exc:  # exc.status says why: here DISPLAY_ACTIVE
            print(f"CommandError ({ErrorCode(exc.status).name}): {exc.message}")
        dev.stop()

        try:
            dev.refresh_rate = 0  # out of range
        except ValueError as exc:
            print(f"ValueError, nothing sent: {exc}")

        try:
            block = dev.telemetry.read_block()
            print(f"Telemetry available ({len(block.records)} records waiting)")
        except UnsupportedCommand as exc:
            print(f"UnsupportedCommand, nothing sent: {exc}")

        if dev.simulator is not None:
            dev.simulator.muted = True  # the fake device stops answering
            try:
                dev.all_off()
            except DeviceTimeout as exc:
                print(f"DeviceTimeout: {exc}")
            dev.simulator.muted = False

        try:
            dev.start_trial(999)  # no such pattern
        except DeviceError as exc:  # base class of every library error
            print(f"{type(exc).__name__}: {exc}")


if __name__ == "__main__":
    main()

19_reconnect.py

Recover from a controller reset or an unplugged cable.

"""Recover from a controller reset or an unplugged cable.

Shows: reset() (reboots the controller and closes the connection),
reconnect() (waits for the same controller to come back, checked by its MAC
address), and catching DeviceDisconnected to reconnect after an unplug.
Requires: a connected controller (or --simulate, which fakes the unplug).
On hardware, unplug and replug the USB cable when asked.
"""

import argparse

from arena_interface import Device, DeviceDisconnected


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        print(f"Connected to {dev.info.mac} on {dev.port_name}")

        dev.reset()
        print(f"Reset sent; connection open: {dev.is_open}")
        dev.reconnect(timeout=15)
        print(f"Back after reset; uptime {dev.diagnostics.health().uptime_ms} ms")

        if dev.simulator is not None:
            dev.simulator.unplug()
        else:
            input("Unplug the USB cable, then press Enter... ")
        try:
            dev.all_off()
        except DeviceDisconnected as exc:
            print(f"Lost the device: {exc}")
            if dev.simulator is None:
                print("Plug the cable back in (waiting up to 30 s)")
            dev.reconnect(timeout=30)
            dev.all_off()
            print("Reconnected and working again")


if __name__ == "__main__":
    main()

20_threads.py

Share one Device between threads.

"""Share one Device between threads.

Shows: a background thread sampling the analog inputs while the main thread
runs trials. Every Device method is atomic, so the two never corrupt each
other's exchanges; a thread just waits briefly while the other's request is
on the wire.
Requires: a controller with a pattern on its SD card and the extended I/O
capability (or --simulate).
"""

import argparse
import threading
import time

from arena_interface import Device, TrialMode


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        readings = []
        stop = threading.Event()

        def sampler() -> None:
            for s in dev.sample(dev.io.read_analog_in, rate_hz=50):
                readings.append(s)
                if stop.is_set():
                    return

        thread = threading.Thread(target=sampler)
        thread.start()
        for rate in (10, 20, 40):
            dev.start_trial(1, TrialMode.OPEN_LOOP, frame_rate=rate)
            time.sleep(0.3)
            print(f"rate {rate:2} fps: frame {dev.frame_position.index}")
        dev.stop()
        stop.set()
        thread.join()
        print(f"Background thread took {len(readings)} samples meanwhile")


if __name__ == "__main__":
    main()

Recipes

21_traffic_log.py

Log every byte exchanged with the controller, for debugging.

"""Log every byte exchanged with the controller, for debugging.

Shows: the library's loggers. ``arena_interface.transport`` logs raw bytes
at DEBUG level ("->" sent, "<-" received, with status and opcode);
``arena_interface.firmware`` logs the controller's own debug text (debug
firmware builds only). Decoded results are printed by this script.
Requires: a connected controller (or use --simulate).
"""

import argparse
import logging

from arena_interface import Device


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    args = parser.parse_args()

    logging.basicConfig(
        format="%(asctime)s %(name)-26s %(levelname)-7s %(message)s",
        level=logging.WARNING,  # everything else stays quiet
    )
    logging.getLogger("arena_interface.transport").setLevel(logging.DEBUG)
    logging.getLogger("arena_interface.firmware").setLevel(logging.INFO)

    with Device.open(args.port, simulate=args.simulate) as dev:
        print(f"decoded: refresh rate = {dev.refresh_rate} Hz")
        print(f"decoded: pattern 1 = {dev.patterns.name(1)}")
        print(f"decoded: frame position = {dev.frame_position}")


if __name__ == "__main__":
    main()

22_experiment_run.py

A complete experiment run: upload a stimulus, run timed trials, save logs.

"""A complete experiment run: upload a stimulus, run timed trials, save logs.

Shows: a multi-step workflow combining Pattern, patterns.upload(overwrite=True),
start_trial() with a controller-timed duration, and telemetry.events() to
save, per trial, the frames the arena actually showed.
Requires: a controller with an SD card and telemetry (or --simulate).
Writes one CSV per trial into experiment_logs/.
"""

import argparse
import csv
from pathlib import Path

from arena_interface import Arena, Device, FrameRecord, Pattern, TrialMode

TRIALS = [("slow", 10), ("fast", 40), ("reverse", -20)]  # (name, frames per second)


def make_stimulus(arena: Arena) -> Pattern:
    """A 20-frame moving bar sized for the controller's grid."""
    h, w = arena.pixel_shape
    frames = [
        [[15 if (x - f * 10) % w < 20 else 0 for x in range(w)] for _ in range(h)]
        for f in range(20)
    ]
    return Pattern.from_frames(frames, arena=arena)


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--seconds", type=float, default=1.0, help="trial length")
    parser.add_argument("--output", type=Path, default=Path("experiment_logs"))
    args = parser.parse_args()
    args.output.mkdir(exist_ok=True)

    with Device.open(args.port, simulate=args.simulate) as dev:
        dev.stop()
        pid = dev.patterns.upload(
            "moving_bar.pat", make_stimulus(dev.arena), overwrite=True
        )
        dev.telemetry.drain()  # start the logs from here

        for name, rate in TRIALS:
            dev.start_trial(
                pid, TrialMode.OPEN_LOOP, frame_rate=rate, duration=args.seconds
            )
            path = args.output / f"trial_{name}.csv"
            with path.open("w", newline="") as f:
                writer = csv.writer(f)
                writer.writerow(["time_s", "frame"])
                for event in dev.telemetry.events(duration=args.seconds + 0.2):
                    if isinstance(event.record, FrameRecord):
                        writer.writerow([f"{event.time:.6f}", event.record.index])
            print(f"trial {name:8} ({rate:+} fps) -> {path}")


if __name__ == "__main__":
    main()

23_ao_calibration.py

Calibrate Analog In 1 against the analog output with a loopback cable.

"""Calibrate Analog In 1 against the analog output with a loopback cable.

Shows: a measurement workflow: step io.analog_out, read io.read_analog_in()
several times at each level, fit gain and offset by least squares, and save
the table. Analog inputs are uncalibrated in firmware, so a fit like this
converts their readings to real millivolts.
Requires: a BNC cable from the analog output to Analog In 1 (or --simulate,
which fakes the cable with a small gain and offset error).
Writes ao_calibration.csv.
"""

import argparse
import csv
import statistics
from pathlib import Path

from arena_interface import AoMode, Device


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument(
        "--steps", type=int, default=11, help="levels from 0 to 5000 mV"
    )
    parser.add_argument("--output", type=Path, default=Path("ao_calibration.csv"))
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        if dev.simulator is not None:
            dev.simulator.analog_loopback = (1.013, -27.0)  # gain, offset (mV)
        dev.io.set_analog_out_mode(AoMode.PROGRAMMABLE)
        table = []
        for i in range(args.steps):
            dev.io.analog_out = round(5000 * i / (args.steps - 1))
            out_mv = dev.io.analog_out  # what the DAC actually produces
            readings = [
                s.value.ain1_mv for s in dev.sample(dev.io.read_analog_in, 200, count=5)
            ]
            table.append((out_mv, statistics.mean(readings)))
        dev.io.analog_out = 0

    xs, ys = zip(*table, strict=True)
    gain, offset = statistics.linear_regression(xs, ys)  # ain1 = gain * out + offset
    residual = max(abs(y - (gain * x + offset)) for x, y in table)
    with args.output.open("w", newline="") as f:
        writer = csv.writer(f)
        writer.writerow(["ao_mv", "ain1_mean_mv"])
        writer.writerows(table)
    print(f"Analog In 1 = {gain:.4f} x output {offset:+.1f} mV")
    print(f"Largest residual: {residual:.1f} mV")
    print(f"To correct a reading: true_mv = (ain1_mv {-offset:+.1f}) / {gain:.4f}")
    print(f"Table saved to {args.output}")


if __name__ == "__main__":
    main()

24_host_playback.py

Play frame sequences at a fixed rate, paced by the computer.

"""Play frame sequences at a fixed rate, paced by the computer.

Shows: play_frames() (frames of an SD pattern, with verify=True to check what
the controller displayed), play_images() (streamed images), and
start_frames() running in the background while the script does other work.
Requires: a controller with a pattern of 20+ frames on its SD card (or
--simulate).
"""

import argparse
import time

from arena_interface import Device, GrayLevel


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument(
        "--pattern",
        type=lambda s: int(s) if s.isdigit() else s,
        default=1,
        help="pattern file name (e.g. grating.pat) or id (first pattern = 1)",
    )
    parser.add_argument("--fps", type=float, default=100.0, help="frames per second")
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        # 1. Frames of an SD pattern: forwards, then backwards.
        dev.show_pattern(args.pattern)
        n = dev.frame_position.frame_count
        frames = [*range(n), *reversed(range(n))]
        report = dev.play_frames(frames, fps=args.fps, late="skip", verify=True)
        print(f"SD frames:  {report}")

        # 2. Streamed images: a bar moving across the arena.
        h, w = dev.arena.pixel_shape
        images = [
            [[1 if (x - 8 * f) % w < 20 else 0 for x in range(w)] for _ in range(h)]
            for f in range(w // 8)
        ]
        report = dev.play_images(images, fps=args.fps, gray_level=GrayLevel.GS2)
        print(f"Streamed:   {report}")

        # 3. In the background: the script keeps working meanwhile.
        with dev.start_frames(frames, fps=args.fps) as player:
            while player.running:
                print(f"  background progress {player.progress}/{player.total}")
                time.sleep(0.2)
        print(f"Background: {player.report}")


if __name__ == "__main__":
    main()

25_live_pacing.py

Closed loop from the computer: choose each frame live at a fixed rate.

"""Closed loop from the computer: choose each frame live at a fixed rate.

Shows: dev.pace() ticking at a fixed rate; on every tick the script reads
Analog In 1 and moves the pattern by a step proportional to the voltage,
then shows that frame. tick.skipped says when the loop fell behind, and
pacer.report summarises the timing.
Requires: a controller with a pattern on its SD card and the extended I/O
capability (or --simulate, which drives Analog In 1 with a slow sine wave).
"""

import argparse
import math

from arena_interface import Device


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument(
        "--pattern",
        type=lambda s: int(s) if s.isdigit() else s,
        default=1,
        help="pattern file name (e.g. grating.pat) or id (first pattern = 1)",
    )
    parser.add_argument("--rate", type=float, default=100.0, help="frames per second")
    parser.add_argument("--seconds", type=float, default=2.0, help="how long to run")
    parser.add_argument(
        "--gain", type=float, default=2.0, help="frames per tick per volt"
    )
    args = parser.parse_args()

    with Device.open(args.port, simulate=args.simulate) as dev:
        dev.show_pattern(args.pattern)
        frames = dev.frame_position.frame_count
        position = 0.0
        pacer = dev.pace(args.rate, duration=args.seconds, late="skip")
        for tick in pacer:
            if dev.simulator is not None:  # pretend something drives the input
                dev.simulator.analog_in = (round(3000 * math.sin(tick.index / 40)), 0)
            volts = dev.io.read_analog_in().ain1_mv / 1000
            position += args.gain * volts * (1 + tick.skipped)  # catch up after skips
            dev.show_frame(int(position) % frames)
        print(pacer.report)
        print(f"final frame {dev.frame_position.index} of {frames}")


if __name__ == "__main__":
    main()

plotting/live_plot.py

Live plot of the analog inputs with matplotlib.

"""Live plot of the analog inputs with matplotlib.

Shows: device.sample() feeding a matplotlib line plot that updates as data
arrives. With a non-interactive backend (e.g. MPLBACKEND=Agg) the final plot
is only saved to analog_plot.png.
The live window uses matplotlib's default Tk backend (TkAgg), which needs
Python's tkinter; on Linux install it with your distribution's package if
missing (e.g. ``sudo apt install python3-tk``).
Requires: matplotlib (``pip install matplotlib``) and a controller with the
extended I/O capability, or --simulate, which drives a sine wave through a
simulated cable from the analog output to Analog In 1.
"""

import argparse
import math
from collections import deque

import matplotlib.pyplot as plt

from arena_interface import Device

NON_INTERACTIVE = {"agg", "pdf", "ps", "svg", "cairo", "template"}


def redraw(ax, line1, line2, t, a1, a2) -> None:
    """Show the latest data and scroll the time axis."""
    line1.set_data(t, a1)
    line2.set_data(t, a2)
    ax.set_xlim(t[0], max(t[-1], t[0] + 1))


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--seconds", type=float, default=10.0, help="how long to plot")
    parser.add_argument("--rate", type=float, default=50.0, help="samples per second")
    args = parser.parse_args()

    live = plt.get_backend().lower() not in NON_INTERACTIVE
    fig, ax = plt.subplots()
    (line1,) = ax.plot([], [], label="Analog In 1")
    (line2,) = ax.plot([], [], label="Analog In 2")
    ax.set(xlabel="time (s)", ylabel="mV", ylim=(-10500, 10500))
    ax.legend(loc="upper right")
    t, a1, a2 = (deque(maxlen=int(args.rate * 10)) for _ in range(3))

    with Device.open(args.port, simulate=args.simulate) as dev:
        if dev.simulator is not None:
            dev.simulator.analog_loopback = (1.0, 0.0)
        start = None
        for s in dev.sample(dev.io.read_analog_in, args.rate, duration=args.seconds):
            start = start or s.time
            t.append(s.time - start)
            a1.append(s.value.ain1_mv)
            a2.append(s.value.ain2_mv)
            if dev.simulator is not None:
                dev.io.analog_out = round(2500 + 2400 * math.sin(2 * math.pi * t[-1]))
            if live and len(t) % 5 == 0:
                redraw(ax, line1, line2, t, a1, a2)
                plt.pause(0.001)
    redraw(ax, line1, line2, t, a1, a2)
    fig.savefig("analog_plot.png")
    print("Saved analog_plot.png")
    if live:
        plt.show()


if __name__ == "__main__":
    main()

camera/webcam.py

Stream a webcam to the arena in real time. A box with the arena's aspect ratio, moved and resized with the mouse, picks the part of the picture that is shrunk to the arena's pixels and streamed. GS16 with contrast stretching by default; --gs2 uses dithered on/off pixels. --rotate DEG (0-360) moves the picture's centre around the arena. Needs OpenCV (uv sync --extra camera); --simulate uses a moving test picture.

"""Stream a webcam to the arena in real time, through a box you move.

Shows: capturing with OpenCV, cropping a region with the arena's aspect
ratio (chosen live with the mouse), shrinking it to dev.arena.pixel_shape and
sending it with dev.stream_image() as fast as the camera delivers frames.
GS16 with contrast stretching by default; --gs2 sends on/off pixels with
ordered dithering. The image is mirrored, like a mirror you face; --no-mirror
turns that off. See roi_view.py for the mouse and keyboard controls.
The camera is asked for compressed MJPG frames at 30 fps: raw (YUYV) frames
need several times the USB bandwidth and can arrive with bands out of order
(seen with a webcam passed through to a virtual machine).
Requires: opencv-python (``uv sync --extra camera``) and a webcam, or
--simulate, which uses a moving test picture and the simulated controller.
"""

import argparse
import os
import sys
import time

import cv2
from roi_view import RoiSelector, synthetic_frame

from arena_interface import Device


def open_camera(index: int, width: int, height: int) -> cv2.VideoCapture:
    """Open a webcam asking for MJPG frames of the given size at 30 fps."""
    camera = cv2.VideoCapture(index)
    camera.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*"MJPG"))  # before size
    camera.set(cv2.CAP_PROP_FRAME_WIDTH, width)
    camera.set(cv2.CAP_PROP_FRAME_HEIGHT, height)
    camera.set(cv2.CAP_PROP_FPS, 30)
    return camera


def hide_native_warnings() -> None:
    """Drop C-library messages (e.g. libjpeg's harmless "Corrupt JPEG data").

    Many Logitech webcams trigger one per frame. Python's own errors still
    show: sys.stderr is moved to a copy of the original stream first.
    """
    sys.stderr = os.fdopen(os.dup(2), "w", buffering=1)
    os.dup2(os.open(os.devnull, os.O_WRONLY), 2)


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument(
        "--simulate", action="store_true", help="fake device and test picture"
    )
    parser.add_argument("--camera", type=int, default=0, help="camera number")
    parser.add_argument("--width", type=int, default=640, help="camera image width")
    parser.add_argument("--height", type=int, default=480, help="camera image height")
    parser.add_argument("--seconds", type=float, help="stop after this long")
    parser.add_argument("--gs2", action="store_true", help="start in GS2 (dithered)")
    parser.add_argument(
        "--mirror",
        action=argparse.BooleanOptionalAction,
        default=True,
        help="mirror left-right (default: on)",
    )
    parser.add_argument(
        "--rotate", type=float, default=0.0, help="shift around the arena, 0-360 deg"
    )
    parser.add_argument(
        "--brightness", type=int, default=128, help="panel duty cycle 1-255"
    )
    parser.add_argument("--no-gui", action="store_true", help="no windows")
    args = parser.parse_args()

    camera = None
    if not args.simulate:
        camera = open_camera(args.camera, args.width, args.height)
        if not camera.isOpened():
            parser.error(f"cannot open camera {args.camera}")
        hide_native_warnings()

    with Device.open(args.port, simulate=args.simulate) as dev:
        roi = RoiSelector(
            dev.arena.pixel_shape,
            gui=not args.no_gui,
            gs2=args.gs2,
            mirror=args.mirror,
            rotate=args.rotate,
            brightness=args.brightness,
        )
        start, sent = time.monotonic(), 0
        try:
            while roi.poll():
                elapsed = time.monotonic() - start
                if args.seconds is not None and elapsed >= args.seconds:
                    break
                if camera is None:  # a 30 fps "camera"
                    time.sleep(max(0.0, start + sent / 30 - time.monotonic()))
                    frame = synthetic_frame(elapsed)
                else:
                    ok, frame = camera.read()  # waits for the next camera frame
                    if not ok:
                        raise SystemExit("the camera stopped delivering frames")
                dev.stream_image(
                    roi.update(frame),
                    gray_level=roi.gray_level,
                    duty_cycle=roi.brightness,
                )
                sent += 1
        except KeyboardInterrupt:
            pass
        finally:
            roi.close()
            if camera is not None:
                camera.release()
        elapsed = time.monotonic() - start
        print(f"sent {sent} frames in {elapsed:.1f} s ({sent / elapsed:.1f} fps)")


if __name__ == "__main__":
    main()

camera/movie.py

The same for a movie file (.mp4, .avi, .gif, ...), played at its own frame rate with dev.pace().

uv run python examples/camera/movie.py clip.mp4
"""Play a movie file (.mp4, .avi, .gif, ...) on the arena through a box you move.

Shows: reading frames with OpenCV, dev.pace() keeping the movie's own frame
rate (skipping frames if the computer falls behind), and the same
crop -> shrink -> dev.stream_image() path as webcam.py. Space pauses (the box
still moves); the movie loops unless --once. See roi_view.py for the mouse and
keyboard controls.
Requires: opencv-python (``uv sync --extra camera``) and a movie file; with
--simulate and no file, a moving test picture and the simulated controller.
"""

import argparse
from pathlib import Path

import cv2
from roi_view import RoiSelector, synthetic_frame

from arena_interface import Device


def next_frame(video: cv2.VideoCapture, skip: int, loop: bool):
    """The next frame after skipping `skip` (None at the end without --loop)."""
    for _ in range(skip):
        video.grab()
    ok, frame = video.read()
    if not ok and loop:
        video.set(cv2.CAP_PROP_POS_FRAMES, 0)
        ok, frame = video.read()
    return frame if ok else None


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("movie", nargs="?", type=Path, help="movie file")
    parser.add_argument("--port", help="serial port (default: auto-detect)")
    parser.add_argument("--simulate", action="store_true", help="use fake device")
    parser.add_argument("--speed", type=float, default=1.0, help="playback speed")
    parser.add_argument("--once", action="store_true", help="do not loop")
    parser.add_argument("--seconds", type=float, help="stop after this long")
    parser.add_argument("--gs2", action="store_true", help="start in GS2 (dithered)")
    parser.add_argument(
        "--mirror",
        action=argparse.BooleanOptionalAction,
        default=False,
        help="mirror left-right (default: off)",
    )
    parser.add_argument(
        "--rotate", type=float, default=0.0, help="shift around the arena, 0-360 deg"
    )
    parser.add_argument(
        "--brightness", type=int, default=128, help="panel duty cycle 1-255"
    )
    parser.add_argument("--no-gui", action="store_true", help="no windows")
    args = parser.parse_args()

    video, fps = None, 30.0
    if args.movie is not None:
        video = cv2.VideoCapture(str(args.movie))
        if not video.isOpened():
            parser.error(f"cannot open {args.movie}")
        fps = video.get(cv2.CAP_PROP_FPS) or fps
    elif not args.simulate:
        parser.error("give a movie file (or --simulate for a test picture)")

    with Device.open(args.port, simulate=args.simulate) as dev:
        roi = RoiSelector(
            dev.arena.pixel_shape,
            gui=not args.no_gui,
            gs2=args.gs2,
            mirror=args.mirror,
            rotate=args.rotate,
            brightness=args.brightness,
        )
        pacer = dev.pace(fps * args.speed, duration=args.seconds, late="skip")
        frame = None
        try:
            for tick in pacer:
                if not roi.poll():
                    break
                if frame is None or not roi.paused:
                    if video is None:
                        frame = synthetic_frame(tick.index / fps)
                    else:
                        frame = next_frame(video, tick.skipped, loop=not args.once)
                    if frame is None:
                        break
                dev.stream_image(
                    roi.update(frame),
                    gray_level=roi.gray_level,
                    duty_cycle=roi.brightness,
                )
        except KeyboardInterrupt:
            pass
        finally:
            roi.close()
            if video is not None:
                video.release()
        print(f"{fps * args.speed:g} frames/s: {pacer.report}")


if __name__ == "__main__":
    main()

camera/roi_view.py

The box and the preview window shared by both camera examples, with the mouse and keyboard controls in its docstring.

"""Shared helper for the camera examples: a box you move over the video.

Not an example on its own; ``webcam.py`` and ``movie.py`` import it. The box
keeps the arena's aspect ratio (5:1 on a 2x10 arena). What is inside it is
shrunk to the arena's pixel size, optionally rotated around the arena, and
shown, as the panels will show it, in a second window.

Controls (click the "source" window first so it has the keyboard):

| Input | Action |
|---|---|
| drag inside the box | move it |
| click outside the box | centre it there (keep holding to drag) |
| drag a corner | resize it (the opposite corner stays put) |
| mouse wheel, ``+`` / ``-`` | resize about the centre |
| arrow keys, ``w`` ``a`` ``s`` ``d`` | move the box (2% of the picture height) |
| ``r`` | reset to the largest centred box |
| ``m`` | mirror left-right |
| ``g`` | switch GS16 / GS2 (dithered) |
| ``c`` | contrast stretch on/off |
| ``[`` / ``]`` | rotate around the arena (5 columns, 9 degrees on a 2x10 arena) |
| ``,`` / ``.`` | dim / brighten the panels (duty cycle 1-255, x1.25 per press) |
| space | pause (movie.py) |
| ``q`` or Esc | quit |

Requires: opencv-python (``uv sync --extra camera``).
"""

from __future__ import annotations

import time

import cv2
import numpy as np

from arena_interface import GrayLevel

SOURCE_WINDOW = "source"
ARENA_WINDOW = "arena"
MAX_DISPLAY_WIDTH = 960  # larger videos are shown scaled down
CORNER_GRAB = 12  # display pixels around a corner that start a resize
MIN_BOX_WIDTH = 20  # source pixels
ROTATE_STEP_COLUMNS = 5  # arena columns per [ or ] key press
BOX_COLOR = (0, 255, 0)  # BGR
CONTROLS = """\
In the source window: drag the box (or use the arrow keys or w a s d) to move
it; drag a corner (or use the mouse wheel or + / -) to resize it.
Keys: r reset, m mirror, g GS16/GS2, c contrast, [ ] rotate,
, . dim/brighten, space pause, q quit."""
MOVE_STEP = 0.02  # fraction of the picture height per key press
# Arrow-key codes from cv2.waitKeyEx(): Linux, Windows, macOS.
_ARROWS = {
    **dict.fromkeys((65361, 2424832, 63234), (-1, 0)),  # left
    **dict.fromkeys((65362, 2490368, 63232), (0, -1)),  # up
    **dict.fromkeys((65363, 2555904, 63235), (1, 0)),  # right
    **dict.fromkeys((65364, 2621440, 63233), (0, 1)),  # down
}
# 4x4 Bayer matrix: thresholds for ordered dithering in GS2.
_BAYER4 = (
    np.array([[0, 8, 2, 10], [12, 4, 14, 6], [3, 11, 1, 9], [15, 7, 13, 5]]) + 0.5
) / 16


def to_arena_image(
    crop: np.ndarray, shape: tuple[int, int], *, gs2: bool = False, stretch: bool = True
) -> np.ndarray:
    """Turn a BGR crop into an arena image: 0-15 (GS16) or dithered 0/1 (GS2)."""
    h, w = shape
    gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY) if crop.ndim == 3 else crop
    small = cv2.resize(gray, (w, h), interpolation=cv2.INTER_AREA).astype(np.float32)
    if stretch:  # use the full brightness range: 16 levels go a long way
        lo, hi = np.percentile(small, (2, 98))
        level = (small - lo) / max(hi - lo, 1.0)
    else:
        level = small / 255
    level = np.clip(level, 0.0, 1.0)
    if gs2:
        threshold = np.tile(_BAYER4, (h // 4 + 1, w // 4 + 1))[:h, :w]
        return (level > threshold).astype(np.uint8)
    return np.round(level * 15).astype(np.uint8)


def synthetic_frame(t: float, size: tuple[int, int] = (640, 480)) -> np.ndarray:
    """A moving test picture (BGR) standing in for a camera or a movie."""
    w, h = size
    bars = (127 + 120 * np.sin(2 * np.pi * (np.arange(w) / 80 - t / 2))).astype(
        np.uint8
    )
    frame = np.repeat(np.tile(bars, (h, 1))[:, :, None], 3, axis=2)
    centre = (int(w / 2 + w / 3 * np.cos(t)), int(h / 2 + h / 4 * np.sin(2 * t)))
    cv2.circle(frame, centre, 40, (0, 0, 255), -1)
    return frame


class RoiSelector:
    """A box of fixed aspect ratio over the video, moved with the mouse.

    Args:
        arena_shape: ``(height, width)`` of the arena image, e.g.
            ``dev.arena.pixel_shape``.
        gui: Show the windows and take mouse/keyboard input.
        gs2: Start in GS2 (dithered on/off) instead of GS16.
        mirror: Flip the video left-right (natural for a webcam facing you).
        rotate: Move the image's centre around the arena by this many degrees
            (0-360; 360 is the full image width, back to the start).
        brightness: Panel brightness (duty cycle) 1-255; 128 is 50 %.
    """

    def __init__(
        self,
        arena_shape: tuple[int, int],
        *,
        gui: bool = True,
        gs2: bool = False,
        mirror: bool = False,
        rotate: float = 0.0,
        brightness: int = 128,
    ) -> None:
        """Set up the box (sized on the first frame) and the windows."""
        self.arena_shape = arena_shape
        self.aspect = arena_shape[1] / arena_shape[0]  # width / height
        self.gui, self.gs2, self.mirror = gui, gs2, mirror
        self.rotate = rotate
        if not 1 <= brightness <= 255:
            raise ValueError(f"brightness must be 1-255, got {brightness}")
        self.brightness = brightness
        """Duty cycle to send the images with (``dev.stream_image(duty_cycle=)``)."""
        self.stretch = True
        self.paused = False
        self.box = (0.0, 0.0, 0.0)  # x, y, width in source pixels
        self._frame_size = (0, 0)
        self._scale = 1.0  # display pixels per source pixel
        self._drag: tuple[str, float, float] | None = None
        self._fps = 0.0
        self._last = time.monotonic()
        if gui:
            cv2.namedWindow(SOURCE_WINDOW, cv2.WINDOW_AUTOSIZE)
            cv2.namedWindow(ARENA_WINDOW, cv2.WINDOW_AUTOSIZE)
            cv2.setMouseCallback(SOURCE_WINDOW, self._on_mouse)
            print(CONTROLS)

    @property
    def gray_level(self) -> GrayLevel:
        """Gray level to send the images with."""
        return GrayLevel.GS2 if self.gs2 else GrayLevel.GS16

    def update(self, frame: np.ndarray) -> np.ndarray:
        """Crop the box from a BGR frame and return the arena image (and show it)."""
        if self.mirror:
            frame = np.ascontiguousarray(frame[:, ::-1])
        fh, fw = frame.shape[:2]
        if (fw, fh) != self._frame_size:
            self._frame_size = (fw, fh)
            self._scale = min(1.0, MAX_DISPLAY_WIDTH / fw)
            self.reset()
        x, y, w = (round(v) for v in self.box)
        crop = frame[y : y + round(w / self.aspect), x : x + w]
        image = to_arena_image(
            crop, self.arena_shape, gs2=self.gs2, stretch=self.stretch
        )
        shift = round(self.rotate % 360 / 360 * image.shape[1])
        image = np.roll(image, shift, axis=1)  # columns wrap around the arena
        now = time.monotonic()
        self._fps = 0.9 * self._fps + 0.1 / max(now - self._last, 1e-6)
        self._last = now
        if self.gui:
            self._show(frame, image)
        return image

    def poll(self) -> bool:
        """Handle key presses; False once the user quits (always True with no GUI)."""
        if not self.gui:
            return True
        code = cv2.waitKeyEx(1)
        if code in _ARROWS:
            self._move(*_ARROWS[code])
            return True
        key = code & 0xFF
        if key in (ord("q"), 27):
            return False
        actions = {
            ord("r"): self.reset,
            ord("m"): lambda: setattr(self, "mirror", not self.mirror),
            ord("g"): lambda: setattr(self, "gs2", not self.gs2),
            ord("c"): lambda: setattr(self, "stretch", not self.stretch),
            ord(","): lambda: self._dim(1 / 1.25),
            ord("."): lambda: self._dim(1.25),
            ord("["): lambda: self._turn(-1),
            ord("]"): lambda: self._turn(+1),
            ord(" "): lambda: setattr(self, "paused", not self.paused),
            ord("+"): lambda: self._zoom(1.1),
            ord("="): lambda: self._zoom(1.1),
            ord("-"): lambda: self._zoom(1 / 1.1),
            ord("w"): lambda: self._move(0, -1),
            ord("a"): lambda: self._move(-1, 0),
            ord("s"): lambda: self._move(0, 1),
            ord("d"): lambda: self._move(1, 0),
        }
        if key in actions:
            actions[key]()
        # Closing the window with its title-bar button also quits.
        return cv2.getWindowProperty(SOURCE_WINDOW, cv2.WND_PROP_VISIBLE) >= 1

    def close(self) -> None:
        """Close the windows."""
        if self.gui:
            cv2.destroyAllWindows()

    # -- the box ------------------------------------------------------------

    def reset(self) -> None:
        """The largest box that fits, centred."""
        fw, fh = self._frame_size
        w = min(fw, fh * self.aspect)
        self.box = ((fw - w) / 2, (fh - w / self.aspect) / 2, w)

    def _place(self, x: float, y: float, w: float) -> None:
        """Set the box, limiting its size and keeping it inside the frame."""
        fw, fh = self._frame_size
        w = min(max(w, MIN_BOX_WIDTH), fw, fh * self.aspect)
        h = w / self.aspect
        self.box = (min(max(x, 0.0), fw - w), min(max(y, 0.0), fh - h), w)

    def _move(self, dx: int, dy: int) -> None:
        step = MOVE_STEP * self._frame_size[1]
        x, y, w = self.box
        self._place(x + dx * step, y + dy * step, w)

    def _dim(self, factor: float) -> None:
        b = self.brightness
        step = round(b * factor) - b
        if step == 0:  # always move by at least one at the low end
            step = 1 if factor > 1 else -1
        self.brightness = min(max(b + step, 1), 255)

    def _turn(self, direction: int) -> None:
        step = 360 * ROTATE_STEP_COLUMNS / self.arena_shape[1]
        self.rotate = (self.rotate + direction * step) % 360

    def _zoom(self, factor: float) -> None:
        x, y, w = self.box
        cx, cy = x + w / 2, y + w / self.aspect / 2
        fw, fh = self._frame_size
        w = min(max(w * factor, MIN_BOX_WIDTH), fw, fh * self.aspect)
        self._place(cx - w / 2, cy - w / self.aspect / 2, w)

    def _on_mouse(self, event: int, x: int, y: int, flags: int, _param: object) -> None:
        sx, sy = x / self._scale, y / self._scale  # source pixels
        bx, by, bw = self.box
        bh = bw / self.aspect
        if event == cv2.EVENT_LBUTTONDOWN:
            corners = [(bx, by), (bx + bw, by), (bx, by + bh), (bx + bw, by + bh)]
            grab = CORNER_GRAB / self._scale
            for i, (cx, cy) in enumerate(corners):
                if abs(sx - cx) <= grab and abs(sy - cy) <= grab:
                    self._drag = ("resize", *corners[3 - i])  # anchor: opposite
                    return
            if not (bx <= sx <= bx + bw and by <= sy <= by + bh):
                self._place(sx - bw / 2, sy - bh / 2, bw)
                bx, by, _ = self.box
            self._drag = ("move", sx - bx, sy - by)
        elif event == cv2.EVENT_MOUSEMOVE and self._drag is not None:
            kind, a, b = self._drag
            if kind == "move":
                self._place(sx - a, sy - b, bw)
            else:  # resize from anchor (a, b) towards the pointer
                # Size from the pointer's offset projected on the box's
                # diagonal, so dragging mostly sideways resizes a wide box.
                dx, dy = abs(sx - a), abs(sy - b)
                w = (dx * self.aspect + dy) / (self.aspect**2 + 1) * self.aspect
                w = max(w, MIN_BOX_WIDTH)
                h = w / self.aspect
                self._place(a if sx >= a else a - w, b if sy >= b else b - h, w)
        elif event == cv2.EVENT_LBUTTONUP:
            self._drag = None
        elif event == cv2.EVENT_MOUSEWHEEL:
            # The wheel step is the signed top 16 bits of flags (OpenCV 5 has
            # no getMouseWheelDelta); positive means away from the user.
            delta = (flags >> 16) & 0xFFFF
            self._zoom(1 / 1.1 if delta >= 0x8000 else 1.1)

    # -- display ------------------------------------------------------------

    def _show(self, frame: np.ndarray, image: np.ndarray) -> None:
        s = self._scale
        view = (
            cv2.resize(frame, None, fx=s, fy=s, interpolation=cv2.INTER_AREA)
            if s < 1
            else frame.copy()
        )
        x, y, w = self.box
        h = w / self.aspect
        p1 = (round(x * s), round(y * s))
        p2 = (round((x + w) * s) - 1, round((y + h) * s) - 1)
        cv2.rectangle(view, p1, p2, BOX_COLOR, 2)
        status = "  ".join(
            [
                "GS2" if self.gs2 else "GS16",
                f"rotate {self.rotate % 360:.0f} deg",
                f"brightness {self.brightness}",
                f"stretch {'on' if self.stretch else 'off'}",
                *(["PAUSED"] if self.paused else []),
                f"{self._fps:.0f} fps",
            ]
        )
        for color, thickness in (((0, 0, 0), 3), ((255, 255, 255), 1)):
            cv2.putText(
                view, status, (8, 22), cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, thickness
            )
        cv2.imshow(SOURCE_WINDOW, view)
        # The arena as green LEDs, enlarged with square pixels.
        zoom = max(1, 800 // image.shape[1])
        levels = 1 if self.gs2 else 15
        green = (image.astype(np.uint32) * self.brightness // levels).astype(np.uint8)
        green = cv2.resize(
            green, None, fx=zoom, fy=zoom, interpolation=cv2.INTER_NEAREST
        )
        dark = np.zeros_like(green)
        cv2.imshow(ARENA_WINDOW, cv2.merge([dark, green, dark]))

Notebook

examples/notebooks/walkthrough.ipynb is a Jupyter tour of the main features against the simulated controller. Change SIMULATE = True to False to run it on a real arena.