PiPaw is an automated home-cage system for assessing motor learning and movement kinematics in mice.
- Overview
- Introduction to PiPaw
- Files
- List of Key Files and Directories
- Getting Started with the Program
- Git Branch Structure and Workflow
- Explanation of Repository Branching Strategy
.gitignore # Excludes specific files and directories from Git version control
camera_test.py # Script for testing the camera functionality
encoder_test.py # Script for testing the encoder performance
infrared_test.py # Script for assessing the infrared sensor operation
motor_test.py # Script dedicated to testing motor functionalities
solenoid_test.py # Script for verifying solenoid operation
RFID_buffer_testing.py # Script for testing the RFID reader's data buffering capabilities
classReadEncoder.py # Class file for managing and controlling encoder actions
pwm.py # Interface script for working with the Linux PWM driver via sysfs
piPaw_pert.py # Main executable program for the project
mice.cfg # Configuration file containing data specific to each mouse
monitor.sh # Script to initiate and run the main program
LICENSE # Contains the licensing agreement for this repository
README.md # This file, providing an overview and instructions for the repository
data/ # Directory storing outputted results from the cage experiments
This section guides you through setting up and configuring the program. Follow these steps carefully to ensure everything is correctly established.
Initial Configuration:
- Preparing the SD Card:
- Download the latest NOOBS zip file from the Raspberry Pi Downloads page.
- Format a microSD card (minimum 16GB) to FAT32 and extract the NOOBS files onto it.
- Insert the SD card into your Raspberry Pi.
- Note: If using a pre-loaded NOOBS SD card, it may have an older kernel version. Consider reformatting it and installing the latest NOOBS files to ensure the latest kernel (4.9 or later) and Raspbian version.
Installation and Configuration: 2. Installing Raspbian:
- Power up the Raspberry Pi and install Raspbian Stretch when prompted.
- Enabling Hardware PWM:
- Add
dtoverlay=pwm-2chan
to/boot/config.txt
. Refer to Using the Raspberry Pi Hardware PWM timers for more details.
- Add
- Setting Up Project Files:
- Transfer all cage files, test files, and additional classes (like pwm, classReadEncoder) to a new folder named
piPaw
in the Documents directory.
- Transfer all cage files, test files, and additional classes (like pwm, classReadEncoder) to a new folder named
Data Entry:
- Edit the
mice.cfg
file located in the program directory. - For each mouse, enter the following information in a new row:
- RFID Tag Number: The unique identifier for the mouse.
- Mouse Name: The name assigned to the mouse.
- Day: The current date's day (e.g., "10th" for October 10th).
- Water: The number of water drops the mouse has consumed.
- rwdP (Reward Pulls): The count of successful trials completed by the mouse today.
- Fail: The number of failed trials today.
- totRw: Total successful trials they found from the beginning of the phase.
- totFai (Total Fails): The total number of failed trials since the beginning of the study.
- totDay (Total Day): The total number of days the mouse has been under the current hold time (
ht
). Resets whenht
increases. - entRw (Free Water Rewards): Entrance rewards the mouse has (number of free water drops they have from phase 1).
- ht (Hold Time): The current required hold time for the mouse.
- httri: The number of trials completed with the current hold time today.
- prt (Perturbation Trials): The count of perturbation trials. Perturbations affect 30% of mice in phase 3, increasing with each exposure.
- pha: Phase number.
- frW (Free Water): The number of free water drops the mouse will receive until midnight. If the total is below 100, it indicates less than 1 mL of water consumption. Free water is given every 15 minutes.
Organization:
- In the
data
directory:- Create a new folder for each mouse named after its Mouse Name as listed in
mice.cfg
.
- Create a new folder for each mouse named after its Mouse Name as listed in
File Setup:
- Within each mouse's folder:
- Create a text file named
{your_mouse_name}_data.txt
(replace{your_mouse_name}
with the mouse's name). - This file will store specific data and logs for each mouse.
- Create a text file named
Video Storage:
- In each mouse's folder:
- Create a subfolder named
Videos
.
- Create a subfolder named
Example Structure:
data/
TEST/
Videos/
TEST_data.txt
Execution and Monitoring:
- Assign execute permissions to
monitor.sh
(usechmod 744 monitor.sh
). Logs will be output tolog.txt
in thepiPaw
folder. - Reboot the Raspberry Pi and check for an internet connection (
ifconfig
). - Set the Pi to log in to the CLI via the Raspberry Pi Configuration menu for efficiency.
- Power down the Pi.
- Set
precisePaw
to launch on boot using crontab (as root):- Enter
sudo crontab –e
, choose nano, then add@reboot /home/pi/piPaw/monitor.sh
to the crontab file. - Save and exit (CTRL-X).
- Enter
These steps are crucial for the successful setup and operation of the program. Ensure each step is followed accurately for optimal performance.
In this repository, we use a branching strategy that is tailored to ensure efficient and reliable code development and testing. Here is an overview of each branch and its role in the workflow:
-
Master Branch
- Name:
master
- Purpose: The master branch contains code that is designated for Long-Term Support (LTS). It represents the most stable and tested version of the code, having passed through the rigorous testing processes of the other branches. Code in the master branch is ready for production use.
- Name:
-
Development Branch
- Name:
dev
- Purpose: The development branch (
dev
) is the primary branch for integrating tested code. It contains code that has been developed, tested, and is ready for integration into the next LTS release. This branch does not receive direct merges from the beta branch; instead, it integrates tested and finalized code from feature branches.
- Name:
-
Beta Branch
- Name:
beta
- Purpose: The beta branch is utilized for bulk testing of multiple feature branches simultaneously. It is a testing ground for combinations of new features or major changes before they are considered for integration into the dev branch. This branch allows for comprehensive multi-feature testing without affecting the more stable dev branch.
- Name:
-
Feature Branches
- Name Pattern:
feat/*
- Purpose: Feature branches, named with the
feat/
prefix, are used for the development of individual new features or specific changes. These branches are where the initial development and preliminary testing occur. Upon satisfactory testing at this level, code from these branches may be merged either directly into the dev branch or into the beta branch for combined feature testing.
- Name Pattern:
- Feature Development: New features are developed in their respective
feat/
branches. - Beta Testing: For large-scale or multi-feature testing, feature branches are merged into the
beta
branch. This allows for testing how various features interact with each other in a controlled environment. - Development Integration: Features that have passed individual testing (and optionally beta testing) are then merged into the
dev
branch. This branch serves as the final integration point before code is considered for LTS. - Release: After thorough integration and testing in the dev branch, code is merged into the
master
branch for Long-Term Support.
This branching strategy ensures a robust and multi-tiered testing environment, allowing for both individual feature evaluation and combined feature interaction testing, leading up to a stable and reliable master branch for production releases.