Open-BEATBox — Open — BEhavioural and AuTonomous operant Box — is an open-source, modular, low-cost box that lets mice take part in behavioural tasks inside their own home cage, day and night, with no experimenter in the room. It delivers food rewards, shows images on two screens, senses what the animal does, and saves everything to files on your computer.
- 🌐 Website: https://open-beatbox.github.io/
- 📘 Manual (start here): https://open-beatbox.github.io/docs/manual/
- 🎥 Assembly videos: https://www.youtube.com/@open-beatbox/
This repository is the project's front door. It contains the website and the machinery that publishes the manual. The designs, code and manual text live in their own repositories — this page explains which is which.
| I am… | I want to… | Go to |
|---|---|---|
| Curious | Understand what this is and how it works | Overview · How it works |
| A lab / technician | Build a box | Build guide · Master BOM · Assembly tutorials |
| A neuroscientist | Run experiments with a box | Getting started · Training stages · Your data |
| An engineer | Read the hardware, firmware and protocol | Hardware · Firmware · CAN protocol |
| A contributor | Fix or improve something | Contributing · Open points |
| Stuck | Solve a problem | Troubleshooting · Glossary · Discussions |
Short, experimenter-driven test sessions are a limitation in behavioural neuroscience: the animal is handled, moved to a test room, and tested for a few minutes. Open-BEATBox brings the task to the animal. Mice choose when to take part, across their own day–night rhythm, for days or weeks.
- Less handling, less stress — no transfer to a test room.
- More data per animal — many more trials, and learning and motivation curves over time.
- Reproducible — standard hardware, fixed task timing, automatic logs.
- Modular and open — feeder, screens, tunnel, lighting and nosepoke are separate modules; hardware, firmware, software and documentation are all open.
Intended uses: autonomous operant conditioning, reward-delivery and sensor-triggered tasks, longitudinal home-cage monitoring, circadian and motivational dynamics, and reproducible behavioural testing across laboratories.
┌──────────┐ ┌───────────────────────────────┐ ┌─────────────┐ ┌──────────┐
│ Mouse │◄────►│ Modules │◄────►│ MAIN module │◄────►│ Your PC │
│ │ │ feeder · screens · tunnel │ CAN │ (switch- │serial│ control │
│ │ │ lighting · nosepoke │ bus │ board) │ │ app │
└──────────┘ └───────────────────────────────┘ └─────────────┘ └────┬─────┘
behaviour sensors + motors, each with a translates ▼
small computer of its own and forwards CSV result files
- The mouse walks through a tunnel, looks at two screens, touches one, and collects a pellet from the feeder.
- Each module senses and acts on its own and announces events on a shared cable (the CAN bus).
- The main module is the only module connected to your PC. It forwards messages; it does not run the experiment.
- The PC application runs the training protocol and writes every event to CSV files you can open in Excel, R or Python.
The full explanation, one trial step by step, is in How it works.
- Plan — read the safety notes and download the Master BOM.
- Order and make the parts — circuit boards from a PCB service, 3D-printed and laser-cut parts (fabrication).
- Flash the boards — put the firmware on each module board before closing it into its housing.
- Assemble the modules — six tutorials, one video each.
- Integrate and power up — first power-up and test.
- Install the PC application — installation.
- Run — using the application, stages S1–S4.
You do not need to be a programmer. You do need basic hand tools, and some soldering for the screen and infrared-sensor boards.
Open-BEATBox is published as several repositories, one per layer, each under the licence that fits it.
| Layer | Repository | What you will find | Licence |
|---|---|---|---|
| Website (this repository) | Open-BeatBox.github.io | The public website; the pipeline that builds and publishes the manual | AGPL-3.0 |
| Documentation | Open-BeatBox_Documentation | The manual (Sphinx source), notes, media | CC-BY-4.0 |
| Build guides | assembly-tutorials | Per-module assembly tutorials and the Master BOM | see repository |
| Hardware | Open-BeatBox_Hardware | CAD, enclosure, KiCad circuit boards, manufacturing files | CERN-OHL-S-2.0 |
| Software | Open-BeatBox_Software | PC application, module firmware (MicroPython), test command-line tool | AGPL-3.0 |
| Firmware | Open-BeatBox_Firmware | Reserved for stand-alone firmware releases — no source published there yet; the firmware is in the Software repository | GPL-3.0 |
Open-BeatBox.github.io (this repository)
├── site/ the website (Next.js)
└── docs/ ─────────────► Open-BeatBox_Documentation (Git submodule)
└── source/build/assembly-tutorials/ ─► assembly-tutorials (nested submodule)
Open-BeatBox_Hardware · Open-BeatBox_Software · Open-BeatBox_Firmware
└── independent repositories, linked from the manual and the website
More about the repositories, licences and versions →
Open-BEATBox is a working platform under active development: boxes have been built and the tutorials are in use, but the software is a development version, and cost figures, protocol templates and some details are still being validated. The manual keeps an honest list of open points.
You only need this section if you edit the website or publish the manual. Everyone else can stop reading here.
Open-BeatBox.github.io/
├── README.md this file
├── LICENSE, CITATION.cff licence and citation information
├── package.json root helper scripts
├── .gitmodules declares the docs/ submodule
├── docs/ submodule → Open-BeatBox_Documentation (the manual source)
├── scripts/build-docs.ps1 local Sphinx build helper (Windows)
├── site/ the website
│ ├── content/ Markdown content of every page — edit this, no coding needed
│ ├── public/ images, videos, presentations; the built manual lands in public/docs/manual/
│ ├── src/ website code (Next.js / React)
│ └── README.md website developer notes
├── resources/ forwarding notes only — the content moved to the repositories above
└── .github/workflows/ ci.yml (checks on pull requests), deploy-site.yml (publishing)
Every page is a Markdown file in site/content/ with a small header (title, hero text, sections). Edit the text, preview it, and open a pull request — see site/README.md for the content model.
-
Change the manual in the Documentation repository (its
source/folder), and merge it there. -
In this repository, move the submodule pointer to the new version and review it:
git submodule update --remote --recursive docs git diff --submodule git add docs && git commit -m "Update documentation"
-
Push. The deployment workflow rebuilds the manual and the website together.
Update the pointer only after the change has been reviewed. To pull assembly tutorials changes, update the nested submodule in the Documentation repository first.
Clone with submodules (the manual does not build without them):
git clone --recurse-submodules https://github.com/Open-BeatBox/Open-BeatBox.github.io.git
cd Open-BeatBox.github.io
# if you cloned without --recurse-submodules:
git submodule update --init --recursivePreview the website (Node.js 20):
cd site
npm install
npm run dev # then open http://localhost:3000Build the manual (Python 3.10+):
python -m pip install -r docs/requirements.txt
python -m sphinx -b html -d docs/_build/doctrees docs/source site/public/docs/manualOn Windows, npm run build:docs runs the same command. Build the manual and the website together with npm run build:all from the repository root.
The manual should build with no warnings: the pull-request check (ci.yml) treats warnings as errors.
.github/workflows/deploy-site.yml builds the Sphinx manual into site/public/docs/manual/, builds the static website, and publishes site/out to the gh-pages branch when site/, docs/, or the workflow changes on main.
While the Documentation repository is private, the workflow needs a repository secret named DOCS_TOKEN (a token with read access to it); it falls back to the default token once that repository is public.
Open-BEATBox uses layer-specific open licences:
- Website and software: GNU AGPLv3 —
LICENSEhere and in Open-BeatBox_Software. - Firmware: GNU GPLv3 — Open-BeatBox_Firmware.
- Hardware: CERN OHL-S v2 (strongly reciprocal) — Open-BeatBox_Hardware.
- Documentation: CC-BY-4.0 — Open-BeatBox_Documentation.
Each repository carries its own LICENSE file, which is authoritative for that layer.
Each repository has a CITATION.cff file, so GitHub's Cite this repository button gives you APA and BibTeX. A reference paper is in preparation; once it is published it will become the preferred citation.
Contributions of every size are welcome. The contributing guide explains which repository takes which contribution. Questions and ideas: Discussions. Website tasks: site/BEATBOX_IMPACT_REDESIGN_TODO.md.
Eric Burguière — eric.burguiere@cnrs.fr — Centre de Recherche en Neurosciences de Lyon (CRNL), Centre Hospitalier Le Vinatier, Bron, France.