This repository holds the documentation of Open-BEATBox (Open — BEhavioural and AuTonomous operant Box): an open-source, modular, low-cost platform for autonomous home-cage operant conditioning and long-duration behavioural data acquisition in rodents.
Read the manual online: https://open-beatbox.github.io/docs/manual/
The manual is written for people who build and use the box, not only for programmers. It explains how a trial flows from the animal to the data file, how to build the hardware, how to flash the boards, how to run experiments, and how the firmware and the CAN protocol work.
| I want to… | Start here |
|---|---|
| Understand what the box is and how it works | Overview and How it works |
| Go from nothing to a first experiment | Getting started |
| Build one | Build your own |
| Run experiments | Software |
| Look up a word | Glossary |
| Fix a problem | Troubleshooting |
| Layer | Repository | Licence |
|---|---|---|
| Hardware (CAD, circuit boards) | Open-BeatBox_Hardware | CERN-OHL-S-2.0 |
| Software (PC application, module firmware, CLI) | Open-BeatBox_Software | AGPL-3.0-or-later |
| Firmware (placeholder; the firmware is in the Software repository) | Open-BeatBox_Firmware | GPL-3.0 |
| Documentation (this repository), including the assembly tutorials and Master BOM | Open-BeatBox_Documentation | CC-BY-4.0 |
| Website | Open-BeatBox.github.io | AGPL-3.0 |
Open-BeatBox_Documentation/
├── source/ the manual: Markdown (MyST) built with Sphinx and the Furo theme
│ ├── index.md landing page and navigation
│ ├── overview.md, how-it-works.md, getting-started.md, glossary.md, troubleshooting.md
│ ├── build/ build guide: BOM, fabrication, safety, assembly, first power-up
│ │ └── assembly-tutorials/ module assembly tutorials, conventions and the Master BOM
│ ├── hardware/ modules, circuit boards, mechanical files, ordering, flashing
│ ├── software/ PC application, stages, configuration, data, firmware, CAN protocol
│ ├── protocols/ behavioural protocols
│ ├── project/ repositories, status and open points
│ └── _static/ logo, stylesheet, small images used by the manual
├── notes/ maintainers' notes: changelog, content style, contributing, project-requirements template
├── assets/ full-size media: CAD renders, photographs, logos, slides
├── requirements.txt Python packages needed to build the manual
└── LICENSE
The Open-BEATBox website consumes this repository as a Git submodule mounted at docs/. That is why source/ and requirements.txt sit at the root here: from the website's point of view they appear as docs/source/ and docs/requirements.txt. The website builds the manual from those paths and publishes it at https://open-beatbox.github.io/docs/manual/.
After a change is merged here, a maintainer updates the submodule pointer in the website repository so that the new version is published.
source/build/assembly-tutorials/ holds the per-module assembly tutorials, the conventions document and the Master BOM. It used to be a separate repository (Open-BeatBox/assembly-tutorials, now archived) included as a submodule; it was imported here with its history so that release archives are complete. Edit the tutorials and the BOM here.
You need Python 3.10 or newer.
pip install -r requirements.txt
python -m sphinx -b html source _build/htmlThen open _build/html/index.html in a browser. Add -d <doctrees> to keep the Sphinx cache outside the output folder. The build should end with build succeeded and no warnings.
If you use this documentation, please cite it with the metadata in CITATION.cff (GitHub's Cite this repository button). Each release is archived on Zenodo with its own DOI.
Contributions are welcome — a typo fix, a screenshot, a correction after building your own box. See the contributing guide in the manual, and the list of open points where help is most useful.
The documentation, notes and media in this repository are licensed under the Creative Commons Attribution 4.0 International licence. The full text is in LICENSE.