Aggregates the firmware and hardware documentation for all Ataraxis Micro Controllers (AXMCs) used by Sollertia platform data acquisition systems.
This project is part of the Sollertia AI-assisted scientific data acquisition and processing platform, built on the Ataraxis framework and developed in the Sun (NeuroAI) lab at Cornell University. It specializes the general microcontroller framework provided by the ataraxis-micro-controller library into the concrete hardware modules consumed by Sollertia platform data acquisition systems and exposed to the host PC through the sollertia-experiment runtime.
The firmware is partitioned across microcontroller boards via preprocessor target macros in main.cpp; each board
runs one firmware binary corresponding to one target. The current Mesoscope-VR acquisition system (the only consumer
this project currently supports) uses three target classes: AMC-ACTOR, AMC-SENSOR, and AMC-ENCODER. The Actor
interfaces with the hardware modules that control the experiment environment, for example, to deliver water, lock
the running wheel, and activate Virtual Reality screens. The Sensor monitors most data-acquisition devices, such as
the torque sensor, lick sensor, and Mesoscope frame timestamp sensor. The Encoder uses hardware interrupt logic to
monitor the animal's movement using a rotary encoder and, due to interrupt logic constraints, is segmented into its
own class of microcontrollers. This combination maximizes data acquisition speed while avoiding communication channel
overloading. Future acquisition systems can define any other set of targets with any partitioning of the available
modules across boards.
This project contains both the schematics for assembling the microcontrollers used by the Sollertia platform and the firmware that runs on those microcontrollers. The hardware created and programmed as part of this project is designed to be interfaced through the bindings available from the sollertia-experiment library, which is a core dependency of every Sollertia platform acquisition system.
- Dependencies
- Hardware Assembly
- Software Installation
- Per-Target Configuration
- Usage
- API Documentation
- AI-Assisted Development
- Versioning
- Authors
- License
- Acknowledgments
- PlatformIO IDE to upload the firmware to each microcontroller.
These dependencies are automatically resolved whenever the project is installed via PlatformIO.
To assemble the microcontroller hardware, consult the schematics and instructions reflecting the latest state of the Sollertia platform microcontroller hardware.
Note, the provided link only covers the microcontrollers and does not discuss the assembly of other experiment-facilitating devices used by each data acquisition system. Consult the sollertia-experiment library for details on assembling the other Sollertia platform data acquisition system components.
- Download this repository to a local PC with direct USB access to the microcontrollers. Use the latest stable release from GitHub, as it always reflects the current state of the Sollertia platform data acquisition hardware.
- Open the project in the 'PlatformIO' IDE.
- Optionally disable all hardware modules not used by the target acquisition system. This project is intended to be reused by all Sollertia platform acquisition systems, so it contains all hardware modules the platform supports.
- Connect a single microcontroller to the host PC and select the microcontroller type by modifying the preprocessor directive on line 26 of the main.cpp. Do NOT connect more than a single controller at a time, as some systems have issues selecting the correct upload target otherwise.
- After uploading the firmware, disconnect the microcontroller from the host PC and connect the next microcontroller.
- Repeat steps 4 and 5 until all microcontrollers are configured.
- Connect all microcontrollers to the PC that will manage the data acquisition runtime (the main data-acquisition PC).
The firmware exposes a small set of compile-time identifiers that the companion host-PC runtime (sollertia-experiment) must match. The defaults shipped with this project are:
- Controller IDs (set in main.cpp):
ACTOR = 101,SENSOR = 152,ENCODER = 203. - Keepalive interval:
500ms. The Kernel expects the host PC to send a keepalive message at least this often; if it does not, the microcontroller resets to abort runtime.
Adjust these values directly in main.cpp if a deployment needs different IDs or a different keepalive cadence,
and make sure the host-PC configuration is updated to match.
Once the microcontrollers are assembled, configured, and connected to the main data acquisition PC, they are accessed via the sollertia-experiment library.
See the API documentation for the detailed description of the methods and classes exposed by components of this library.
Claude Code skills and AI development assets for this project are distributed through two marketplaces:
- sollertia marketplace:
- experiment plugin — the firmware-aware
/microcontroller-interfaceskill, a registry of the paired firmware Module and host-PCModuleInterfaceclasses and the cross-side contract they share. This is the entry point for any change that spans this firmware and its sollertia-experiment consumer, and it links out to the ataraxis plugins below for the underlying mechanics. The host-PC interface and configuration skills it references belong to the consumer and are documented there.
- experiment plugin — the firmware-aware
- ataraxis marketplace:
- microcontroller plugin — the foundational C++ firmware mechanics via the
/firmware-moduleskill (baseModulesubclass implementation: template parameters, parameter structs, status and command codes, and stage-based command execution). - automation plugin — shared development skills that enforce Sollertia platform coding conventions (C++ style, README style, commit messages, Sphinx documentation, tox configuration) and general-purpose codebase exploration tools.
- microcontroller plugin — the foundational C++ firmware mechanics via the
Install all three plugins to make the full skill set available to compatible AI coding agents. See CLAUDE.md for the full session-start workflow and the canonical reading order when adding or modifying a firmware module.
This project uses semantic versioning. See the tags on this repository for the available project releases.
- Ivan Kondratyev (Inkaros)
This project is licensed under the Apache 2.0 License: see the LICENSE file for details.
- All Sun lab members for providing the inspiration and comments during the development of this project.
- The creators of all other dependencies and projects listed in the platformio.ini file.