Spotlight controller

This repository contains the control software for the Spotlight system presented in Wang-Chen et al. (2026), Precise kinematic and muscle recording in freely behaving flies enabled by closed-loop tracking and annotation-free pose estimation . The firmware for the triggering microcontroller is also included.

The closed-loop control and recording programs implemented in C++. A set of offline tools for calibration, postprocessing, etc. is implemented in Python and lives in tools/. The C++ codebase contains three parts:

• recorder/: The main recorder software that runs on the recording computer.
  • User-facing programs: align-cameras, run-arena-registration-scan, run-spotlight, and run-homography-scan (planned; not yet implemented — see docs/configuration/camera_homography.md).
    • align-cameras: (i) mechanically align the two cameras and the blue excitation light, and (ii) define a cropped ROI on the muscle camera to align both fields of view.
    • run-arena-registration-scan: move the translation stages to predefined positions and capture fiducial-marker snapshots, used by a Python tool to build a camera–stage–arena coordinate mapping.
    • run-spotlight: the main program to record experimental data.
  • The behavior (Euresys) camera runs in-process; the muscle (PCO) camera runs as a separate process (pco-camera-server) communicating over shared memory. See docs/architecture.md for details.
• trigger_firmware/: The embedded code that runs on the triggering microcontroller.
• comm_protocol/: A lightweight JSON-based library for serial communication between the recorder and the microcontroller. Designed to be included by both sides; avoids exceptions to respect the microcontroller's linear workflow.

The repository also contains:

• tools/: Offline Python tools for calibration and postprocessing (fit-arena-registration, postprocess-recording, etc.). See tools/README.md.
• trigger_hardware/: KiCad schematic and PCB layout for the triggering microcontroller circuit board.

Documentation & developer info

Documentation is available in the docs/ folder. Start at the index, docs/README.md, which splits the pages into a short User's manual (running an experiment end to end) and a fuller Developer's manual (internals, environment setup, hardware). A few entry points:

• Architecture overview: threads, cameras, and the trigger microcontroller.

• Data acquisition workflow: how the cameras and lights are controlled and synchronized using continuous acquisition.

• Building and installing and software dependencies: how to build the components and install their dependencies.

• Troubleshooting: common runtime problems (e.g. the behavior camera grabber being held by another program, and hangs on quit).

• Code style and conventions (language standards, formatting, naming, overhead, tests) are documented in docs/code_style.md.