TumbleFeeder v2.0 - Complete Behavioral Neuroscience System

All-in-one Arduino library for servo-based pellet feeders

Inspired by the FED3 architecture, TumbleFeeder v2 is a complete, self-contained system that handles everything from hardware initialization to data logging. No more juggling multiple files - just two lines of code!

Quick Start

#include <TumbleFeeder.h>

TumbleFeeder feeder;

void setup() {
  feeder.begin();  // Does EVERYTHING
}

void loop() {
  feeder.run();    // Handles EVERYTHING
}

That's it! The library handles:

• ✅ Pin initialization
• ✅ RTC setup
• ✅ Sharp memory display
• ✅ SD card logging
• ✅ Interactive startup menu
• ✅ Input detection
• ✅ FR schedules
• ✅ Servo control
• ✅ Sleep management
• ✅ Battery monitoring
• ✅ Automatic data saving

What's New in v2.0

Complete Integration

• Display built-in - No external display code needed
• RTC built-in - Automatic time tracking
• SD logging built-in - Automatic CSV creation and logging
• Startup menu - Interactive configuration on boot
• Sleep management - Automatic power saving

Massive Simplification

• v1.0: Required ~13 separate .ino files, manual callbacks, interrupt setup
• v2.0: Just main sketch + library - everything else is automatic

FED3-Style Architecture

Based on the proven FED3 design by Lex Kravitz, adapted for servo feeders.

Hardware Requirements

Hardcoded Pin Configuration:

• Servo: Pin 10
• LED: Pin 13
• Left touch: A2
• Right touch: A0
• Feeder touch: A1
• Display: SCK=5, MOSI=A4, SS=6
• SD Card: CS=4
• Battery: A7
• Menu buttons: Red=A3, Green=1, Blue=A5

Components:

• Arduino M0/SAMD21 (Adafruit Feather M0 recommended)
• Servo motor
• Sharp Memory Display (144x168)
• SD card breakout
• RTC (DS3231)
• 3x Capacitive touch sensors
• 3x Buttons (menu navigation)
• LiPo battery + charger

Installation

Arduino IDE

1. Download latest release ZIP
2. Sketch → Include Library → Add .ZIP Library
3. Select TumbleFeeder.zip
4. Restart Arduino IDE

Library Manager (after approval)

1. Tools → Manage Libraries
2. Search "TumbleFeeder"
3. Click Install

Startup Menu

On first boot (or anytime you restart), you'll see an interactive menu:

Red Button = Start session
Blue Button = Edit settings
Green Button = Navigate menus

You can configure:

1. Mode - FR or Free feeding
2. FR Value - 1 through 10
3. Device Number - 0 through 19 (for multi-cage setups)
4. Open Duration - 10-120 seconds
5. Servo Positions - Fine-tune open/closed angles

All settings are automatically saved to CONFIG.csv on the SD card.

Data Logging

Automatic File Creation

Files are named: TUMBLER_DDD_MMDDYY_NN.CSV

• DDD = Device number (3 digits)
• MMDDYY = Date
• NN = Session number (auto-increments)

Data Columns

Every event is automatically logged with:

• Timestamp (date + time)
• Temperature (from RTC)
• Elapsed time (seconds)
• Battery voltage
• Device number
• Left poke count & duration
• Right poke count & duration
• Feeder access count & duration
• Current paradigm (FR# or Free)

No Code Required

Just call feeder.run() - logging happens automatically!

Examples

Basic Session (Recommended)

#include <TumbleFeeder.h>

TumbleFeeder feeder;

void setup() {
  feeder.begin();
}

void loop() {
  feeder.run();
}

Pre-Configured Session

#include <TumbleFeeder.h>

TumbleFeeder feeder;

void setup() {
  // Optional: Configure before begin()
  feeder.setFR(5);
  feeder.setOpenDuration(30);
  feeder.setDeviceNumber(2);
  
  feeder.begin();  // Still shows menu for final adjustments
}

void loop() {
  feeder.run();
}

Custom Event Triggers

#include <TumbleFeeder.h>

TumbleFeeder feeder;

void setup() {
  feeder.begin();
}

void loop() {
  feeder.run();
  
  // Custom logic based on events
  if (feeder.leftPokeCount == 50) {
    Serial.println("Halfway milestone!");
  }
  
  // Check battery
  if (feeder.measuredvbat < 3.5) {
    Serial.println("Battery low!");
  }
}

API Reference

Main Methods

feeder.begin()

Initialize all hardware, show startup menu, create data file.

feeder.run()

Check inputs, update display, log data, manage sleep. Call this every loop.

Configuration Methods

feeder.setFR(int fr)

Set fixed-ratio schedule (1-10).

feeder.setOpenDuration(unsigned long seconds)

Set how long gate stays open (10-120 seconds).

feeder.setPositions(int openPos, int closedPos)

Set servo angles (open: 0-90, closed: 0-180).

feeder.setDeviceNumber(int num)

Set device ID (0-19).

feeder.setMode(int mode)

Set mode (0 = FR, 1 = Free feeding).

Manual Control (Optional)

feeder.feederOpen()

Manually open gate.

feeder.feederClose()

Manually close gate.

feeder.shakeFood()

Close then open gate (settles food).

feeder.shake()

Blink LED 10 times.

feeder.resetCounts()

Reset all event counters to zero.

feeder.enableSleep() / feeder.disableSleep()

Control automatic sleep (useful for debugging).

Public Variables (Read/Write)

• feeder.leftPokeCount - Total left pokes
• feeder.rightPokeCount - Total right pokes
• feeder.FeederCount - Total feeder accesses
• feeder.leftPokeDur - Last left poke duration (ms)
• feeder.rightPokeDur - Last right poke duration (ms)
• feeder.leftFeederDur - Last feeder duration (ms)
• feeder.FR - Current FR value
• feeder.mode - Current mode (0=FR, 1=Free)
• feeder.deviceNumber - Device ID
• feeder.closedpos - Closed servo position
• feeder.openpos - Open servo position
• feeder.open_duration - Gate open duration (seconds)
• feeder.measuredvbat - Battery voltage

Public Objects (Advanced)

• feeder.display - Sharp display object (Adafruit_SharpMem)
• feeder.rtc - Real-time clock object (RTC_DS3231)
• feeder.SD - SD card object (SdFat)
• feeder.logfile - Current log file (File)

Migrating from v1.0

Good news: Your hardware doesn't change!

v1.0 Code:

#include <TumbleFeeder.h>
TumbleFeeder feeder;

void setup() {
  feeder.begin(150, 0);
  feeder.setFR(1);
  feeder.setLogCallback(logData);
  feeder.setDisplayCallback(updateDisplay);
  attachInterrupt(...);
  // ... lots of setup code
}

void loop() {
  feeder.checkInputs(60);
}
// + 12 other .ino files

v2.0 Code:

#include <TumbleFeeder.h>

TumbleFeeder feeder;

void setup() {
  feeder.begin();
}

void loop() {
  feeder.run();
}
// That's it!

Troubleshooting

"SD Card Error"

• Check SD card is inserted
• Verify connections (CS on pin 4)
• Try reformatting card (FAT32)

"Servo not moving"

• Check servo connected to pin 10
• Verify positions in startup menu
• Test with manual feeder.feederOpen()

"Touch inputs not working"

• Verify wiring (A2=left, A0=right, A1=feeder)
• Check pull-up resistors on touch sensors
• Test with Serial.println in sketch

"Display blank"

• Check display connections (SCK=5, MOSI=A4, SS=6)
• Verify Sharp Memory Display compatibility
• Check contrast/viewing angle

"Data not logging"

• Ensure SD card has space
• Check CONFIG.csv exists (created on first boot)
• Verify RTC is set (shows in startup menu)

Advanced Usage

Custom Display Overlays

void loop() {
  feeder.run();
  
  // Add custom text to display
  feeder.display.setCursor(0, 140);
  feeder.display.print("Trial: ");
  feeder.display.print(feeder.leftPokeCount / feeder.FR);
  feeder.display.refresh();
}

Access Raw RTC

void loop() {
  feeder.run();
  
  DateTime now = feeder.rtc.now();
  if (now.hour() == 18 && now.minute() == 0) {
    Serial.println("Feeding session ending!");
  }
}

Multiple Devices

// Device 1
feeder.setDeviceNumber(1);

// Device 2  
feeder.setDeviceNumber(2);

// Each creates separate log files:
// TUMBLER_001_MMDDYY_NN.CSV
// TUMBLER_002_MMDDYY_NN.CSV

Contributing

Issues and pull requests welcome on GitHub!

License

MIT License - Free to use and modify for research purposes.

Citation

If you use TumbleFeeder in your research, please cite:

Barrett, M. (2025). TumbleFeeder: An Arduino library for servo-based
pellet feeders in behavioral neuroscience. GitHub repository.
https://github.com/MasBarr/TumbleFeeder

Based on FED3 architecture:

Kravitz, A.V., et al. (2020). The Feeding Experimentation Device 
version 3 (FED3): An open-source home-cage compatible device for 
measuring food intake in rodents.

Author

Mason Barrett, Kravitz Lab
Washington University in St. Louis
Psychiatry Department

Acknowledgments

• Based on FED3 by Lex Kravitz
• Inspired by open science and reproducible research
• Built with Arduino, Adafruit libraries, and community contributions