A modular home-cage platform that converts the cage floor into a programmable foraging environment for freely moving rodents. Distributed reward delivery and spatial cueing within a scalable, synchronized architecture enable continuous, ethologically grounded behavior compatible with chronic neural recordings.
View design (Fusion 360) — 3D model and mounting
outline. Mounting DXF and fastener notes live in hardware/.
This repository is the planning, documentation, and manuscript hub for the project. Hardware design files, firmware, host software, and analysis code all live in separate repositories and are linked from the Related repositories table below.
Funded by the McDonnell Center NRP (PI: Gaidica). Total budget: $40,000 over 12
months. See references/McDonnell-NRP_GAIDICA.pdf
for the funded proposal.
| Field | Value |
|---|---|
| Phase | Phase 2 — NTH Engineering Sprint |
| Hardware status | Alpha |
| Software status | Alpha |
| Week | Week 7 (anchored 2026-06-08; see PROJECT.md) |
PROJECT.md— master roadmap: phases, milestones, exit criteria, checkbox tasksdocs/— design + requirements documents (architecture, dispense cycle, sync, UI/UX, calibration, etc.)docs/dispense-cycle.md— dispense cycle flowchart, sensor pinouts, CAN events, and heartbeat snapshotdocs/user-api.md— experiment API, session CSV schema, and behavior reportshardware/— hardware design artifacts (e.g. 3D / DXF)meetings/— meeting notesbom/— budget tracking against the $40k grantreferences/— grant proposal and source planning documentsmanuscript/— manuscript drafting (Phase 8+)CONTRIBUTING.md— how to contribute
| Lab | Role | Lead | GitHub |
|---|---|---|---|
| Neurotech Hub (NTH) | Engineering lead — electronics, firmware, host UI, fabrication, integration, dissemination | Matt Gaidica | TBD |
| Animal Behavior Core (ABC) | UI/UX feedback, common task structures, behavioral benchmarking, animal metrics report | TBD | TBD |
| Hengen Lab (HLAB) | Custom experiment authoring, in vivo electrophysiology validation, recording sync | Keith Hengen | TBD |
The repositories below hold the actual artifacts produced by this project. This planning repo links to them; it does not contain their source.
| Domain | Repository | Owner | Status |
|---|---|---|---|
| Mechanical / CAD | TBD | NTH | TBD |
| Electronics / PCB | TBD | NTH | TBD |
| Module firmware | Neurotech-Hub/VFM | NTH | Active — Node library |
| Base station / host UI | Neurotech-Hub/VFM (tools/dev_gui) |
NTH | Active — alpha GUI + experiment API |
| Experiment API examples | VFM templates | NTH / HLAB | Built-in templates; HLAB custom TBD |
| Analysis / reports | VFM run_report.py |
NTH / ABC | Active — session CSV → HTML reports |
When a sub-repo comes online, replace TBD with the URL and update the status
column.
The base station writes a unified session CSV. run_report.py
turns that log into a self-contained, printable HTML report (inline SVG; stdlib
only). Design is picked from the session’s experiment name; unknown templates
fall back to a generic report. Details: docs/user-api.md.
cd tools/dev_gui
python run_report.py --list
python run_report.py EXP-Test-02 --open
python run_report.py "cohortA_*" --combine -o /tmp/cohortA.html| Design | When it applies | Extra sections |
|---|---|---|
default |
Any session (fallback) | Pellet accounting, latency, presence, funnel, faults |
free_feeding |
free_feeding template |
Intake rate, reload delays |
fixed_and_random |
fixed_and_random template |
Per-node role (off / fixed / random) |
probability_delivery |
probability_delivery template |
Delivery-site distribution |
two_armed_bandit |
two_armed_bandit template |
Choice, block/reversal curves, WSLS |
--combine builds a comparative report (cohort table, learning curve, quality
matrix). Time alignment: relative (default), wall, trial, or event:<name>.
JSON export is planned (--json); metrics are already computed separately from HTML.
If you are new here, read in this order:
- This README — what we are building and where artifacts live.
PROJECT.md— current phase, what is in flight, what is next.docs/architecture.md— system architecture once it exists.- The relevant
docs/*.mdfor your role (e.g. ABC:ui-ux.md,maintenance.md; HLAB:user-api.md,sync-and-recording.md).
Abbreviations used throughout this repository.
| Abbreviation | Expansion |
|---|---|
| ABC | Animal Behavior Core |
| HLAB | Hengen Lab |
| NTH | Neurotech Hub |
| Abbreviation | Expansion |
|---|---|
| BOM | Bill of Materials |
| HW | Hardware (status field) |
| MVP | Minimum Viable Product |
| SW | Software (status field) |
| Abbreviation | Expansion |
|---|---|
| CAD | Computer-Aided Design |
| CAN | Controller Area Network (bus) |
| LED | Light-Emitting Diode |
| MCU | Microcontroller Unit |
| PCB | Printed Circuit Board |
| PCBA | Printed Circuit Board Assembly |
| TTL | Transistor-Transistor Logic (digital sync signal level) |
| Abbreviation | Expansion |
|---|---|
| API | Application Programming Interface |
| CLI | Command-Line Interface |
| UI | User Interface |
| UX | User Experience |
| Abbreviation | Expansion |
|---|---|
| FED3 | Feeding Experimentation Device 3 (open-source rodent feeder, Kravitz lab) |
Documentation, plans, and manuscript content in this repository are released under CC-BY-4.0. Code in linked sub-repositories carries its own licensing.