Functions

FED4 Library User Guide

Overview

The FED4 (Feeding Experimentation Device 4) library provides essential functionality for controlling the FED4 device for mouse behavioral experiments. This guide covers the main functions you'll use in your programs.

Library Version: 1.1.1
Authors: Lex Kravitz, Matt Gaidica

---

Table of Contents

1. Getting Started
2. Core Functions
3. Feeding System
4. Touch Detection
5. LED Control
6. Audio Feedback
7. Sensor Readings
8. Data Logging
9. Display Information
10. Public Variables

---

Getting Started

Basic Setup

#include "FED4.h"

FED4 fed;

void setup() {
    // Initialize FED4 with your program name
    if (fed.begin("MyExperiment")) {
        Serial.println("FED4 ready!");
    }
}

void loop() {
    // Main run loop - handles display updates and sleep
    fed.run();
}

begin(programName)

Initializes all FED4 components.

Parameters:

• programName (const char*, optional): Name of your experiment

Returns: bool - true if successful

Example:

fed.begin("PavlovianTraining");

---

Core Functions

run()

Main loop function that updates display, handles sleep, and manages the device.

Use this in your main loop:

void loop() {
    fed.run();
    
    // Your experiment logic here
    if (fed.leftTouch) {
        // Handle left touch
    }
}

feed()

Dispenses a pellet and handles the complete feeding process.

Example:

// Dispense a pellet when center is touched
if (fed.centerTouch) {
    fed.feed();
    fed.centerTouch = false;
}

---

Feeding System

checkForPellet()

Checks if a pellet is currently in the well.

Returns: bool - true if pellet is present

Example:

if (fed.checkForPellet()) {
    Serial.println("Pellet ready for retrieval");
}

didPelletDrop()

Checks if a pellet just dropped from the hopper.

Returns: bool - true if pellet dropped

Example:

if (fed.didPelletDrop()) {
    fed.logData("PelletDropped");
}

---

Touch Detection

Touch State Variables

Use these boolean variables to detect touches:

• fed.leftTouch - Left touch pad was touched
• fed.centerTouch - Center touch pad was touched
• fed.rightTouch - Right touch pad was touched

Example:

void loop() {
    fed.run();
    
    if (fed.leftTouch) {
        fed.leftLight("blue");
        fed.feed();
        fed.leftTouch = false;  // Reset flag
    }
    
    if (fed.centerTouch) {
        fed.centerLight("green");
        fed.centerTouch = false;
    }
    
    if (fed.rightTouch) {
        fed.rightLight("red");
        fed.rightTouch = false;
    }
}

---

LED Control

Port Lighting

Light up the three touch ports:

leftLight(color, brightness)

centerLight(color, brightness)

rightLight(color, brightness)

Parameters:

• color (const char*): "red", "green", "blue", "yellow", "purple", "cyan", "white", "orange"
• brightness (uint8_t, optional): 0-255

Examples:

fed.leftLight("blue");           // Left port blue
fed.centerLight("green", 100);   // Center port green, dim
fed.rightLight("red", 255);      // Right port red, bright

LED Strip Effects

colorWipe(color, wait)

Fills entire strip with a color.

stripRainbow(wait, loops)

Creates rainbow animation.

lightsOff()

Turns off all LEDs.

Examples:

fed.colorWipe("red", 50);        // Red wipe effect
fed.stripRainbow(100, 2);        // Rainbow animation
fed.lightsOff();                 // Turn off all LEDs

Status LED (NeoPixel)

redPix(brightness), greenPix(brightness), bluePix(brightness)

noPix()

Turn off status LED.

Examples:

fed.redPix(50);      // Red status LED
fed.greenPix(100);   // Green status LED  
fed.noPix();         // Turn off status LED

---

Audio Feedback

Basic Sounds

playTone(frequency, duration, volume)

Play a custom tone.

Parameters:

• frequency (uint32_t): Hz (e.g., 1000)
• duration (uint32_t): milliseconds
• volume (float): 0.0-1.0

Predefined Sounds

• fed.click() - Short click
• fed.lowBeep() - Low beep (300Hz)
• fed.highBeep() - High beep (1000Hz)
• fed.bopBeep() - Two-tone beep
• fed.playStartup() - Startup sound sequence

Examples:

fed.click();                    // Quick feedback
fed.highBeep();                 // Success sound
fed.playTone(800, 200, 0.5);    // Custom tone

Haptic Feedback

hapticBuzz(duration)

hapticDoubleBuzz(duration)

hapticTripleBuzz(duration)

Examples:

fed.hapticBuzz(200);        // Single buzz
fed.hapticDoubleBuzz(150);  // Double buzz pattern

---

Sensor Readings

Environmental Data

getTemperature()

getHumidity()

getBatteryPercentage()

getBatteryVoltage()

getLux()

Returns: float values

Example:

float temp = fed.getTemperature();
float battery = fed.getBatteryPercentage();

if (battery < 20) {
    fed.lowBeep();  // Low battery warning
}

Motion Detection

motion()

Checks for motion detection.

Returns: bool - true if motion detected

Example:

if (fed.motion()) {
    fed.logData("MotionDetected");
}

Proximity Sensor

prox()

Gets distance reading.

Returns: int - Distance in mm (0-150), -1 for error

Example:

int distance = fed.prox();
if (distance > 0 && distance < 50) {
    Serial.println("Object nearby");
}

---

Data Logging

logData(event)

Logs an event to the SD card.

Parameters:

• event (const String&, optional): Event name to log

Examples:

fed.logData("TrialStart");
fed.logData("CorrectResponse");
fed.logData();  // Log with current event

Subject Information

setMouseId(id)

setSex(sex)

setStrain(strain)

setAge(age)

Examples:

fed.setMouseId("M001");
fed.setSex("Male");
fed.setStrain("C57BL/6");
fed.setAge("12");

---

Display Information

The display automatically shows:

• Mouse ID and program name
• Touch counters (Left, Center, Right, Pellets)
• Environmental data (temperature, battery)
• Current time and date
• Touch pad indicators

Manual Display Updates

updateDisplay()

Forces display refresh.

Example:

fed.updateDisplay();  // Refresh display manually

---

Public Variables

Counters

Access these to track behavior:

• fed.pelletCount - Total pellets dispensed
• fed.leftCount - Left touches
• fed.centerCount - Center touches
• fed.rightCount - Right touches
• fed.wakeCount - Number of wake-ups

Touch States

• fed.leftTouch - Left touch active
• fed.centerTouch - Center touch active
• fed.rightTouch - Right touch active

Pellet System

• fed.pelletPresent - Pellet in well
• fed.pelletDropped - Pellet just dropped
• fed.retrievalTime - Time to retrieve pellet (seconds)

Environmental Data

• fed.temperature - Current temperature
• fed.humidity - Current humidity
• fed.cellVoltage - Battery voltage
• fed.cellPercent - Battery percentage

System Status

• fed.sdCardAvailable - SD card working
• fed.audioSilenced - Audio disabled

---

Common Usage Patterns

Basic Touch Response

void loop() {
    fed.run();
    
    if (fed.leftTouch) {
        fed.leftLight("blue");
        fed.feed();
        fed.logData("LeftResponse");
        fed.leftTouch = false;
    }
}

Conditional Feeding

void loop() {
    fed.run();
    
    if (fed.centerTouch && fed.pelletCount < 10) {
        fed.feed();
        fed.centerTouch = false;
    }
}

Audio Feedback

void loop() {
    fed.run();
    
    if (fed.pelletCount > 0) {
        fed.highBeep();  // Success sound
    }
    
    if (fed.getBatteryPercentage() < 20) {
        fed.lowBeep();   // Low battery warning
    }
}

LED Patterns

void setup() {
    fed.begin("MyExperiment");
    fed.stripRainbow(100, 2);  // Startup rainbow
    delay(2000);
    fed.lightsOff();
}

void loop() {
    fed.run();
    
    if (fed.leftTouch) {
        fed.leftLight("blue", 200);
        delay(1000);
        fed.lightsOff();
        fed.leftTouch = false;
    }
}

Data Logging

void loop() {
    fed.run();
    
    // Log every 10th pellet
    if (fed.pelletCount % 10 == 0 && fed.pelletCount > 0) {
        fed.logData("Milestone");
    }
}

---

Tips

1. Always call fed.run() in your main loop
2. Reset touch flags after handling: fed.leftTouch = false;
3. Check battery level regularly: fed.getBatteryPercentage()
4. Use fed.logData() to track important events
5. LEDs turn off automatically during sleep to save power, unless you set sleepyLEDs = false
6. Touch sensors auto-calibrate every 20 wake-ups

---