Developed by Sam Centanni & Alex Smith
PiRATeMC is a local-area-network (LAN) based system for controlling a large number of Raspberry Pi video cameras simultaneously.
This works by configuring a 'remote controller' computer as a DHCP server to assign IP addresses, and using ClusterSSH to simultaneously access many devices.
- This code is licensed under the BSD license.
- Find a pre-print of our paper on bioRxiv (stay tuned for updates on publication).
- You can find the operating systems and instructional videos here.
- PiCamOS_cluster is best for LAN use with several Pis.
- PiCamOS_Standalone is best for local use cases using only a single Pi at a time.
- Both operating systems are modified versions of Raspberry Pi OS Buster Lite.
- Instructional videos can be found in the docs/videos folder, or on Google Drive here.
- The Official Raspberry Pi Camera Guide may be usedful, particularly for understanding frame rate and resolution capabilities.
- Please report any issues to us.
We have included a version of rpi-imager in this repository, because newer versions of rpi-imager may not work with Ubuntu 18.04. We plan to update all of this code for Ubuntu 22 in the not-too-distant future.
Flashing the provided PiCamOS is the recommended way to install on a Raspberry Pi. The setupScripts/ folder has information to reproduce this OS. The following packages on the Pi can be installed via apt:
- sshpass
- gpac
- uv4l
- uv4l-raspicam
- uv4l-raspicam-extras
- uv4l-webrtc
We also recommend installing the Adafruit PiTFT driver for use with a 2.8" touch screen if necessary for troubleshooting.
On the server side, the Ubuntu computer that will serve as the remote controller requires the following packages that can be installed via apt:
- git
- openssh-server
- clusterssh
- isc-dhcp-server
- bind9
Detailed installation instructions can be found in our preprint here, and will be updated when a published version is out.
The main script to capture videos is at scripts/recordVideo.sh. This script assumes that several variables are set in your .bashrc file (or from exporting manually): $REMOTE, $REMOTEPASS, $REMOTEVIDPATH, as these provide the location to transfer video to when done recording. If you only want to record locally and not transfer to a network location, you can use recordVideo_local.sh
In addition to the platform for synchronously controlling many cameras through a DHCP server, we also provide several scripts and wiring diagrams for integrating GPIO pins. These scripts can be run simultaneously with the recordVideo.sh script in the terminal, for example:
./recordVideo.sh & python3 pulseTTLandLED.py
Will run both of those scripts, in our hands there is approximately 20-30 millisecond delay between the two actions.
The pulseTTLandLED.py script outputs a 0.5s TTL signal and illuminates an LED at the same time, every 30 seconds. We use this to send a TTL out to a fiber photometry system, and have the LED illuminated in the frame of the video, and these can then be used to time-lock the behavioral data from the video with fiber photometry data. [A picture of how to wire a Pi up to receive a TTL and illuminate a small LED is here](./images/TTL_and_LED_Wiring.png
The script receiveTTL.py allows for triggering recording with a TTL pulse onto a GPIO pin. This script depends on more system variables that are self explanatory: $vidName, $vidLength, $vidFPS. If these variables are not found, defaults will be used, and the defaults can be changed within each script. A picture of how to wire a Pi up to receive this signal is here.
We also provide a script to use DeepLabCut to analyze videos: AnalyzeVideos_DLC.py. Because DLC automatically skips videos that have already been analyzed, it is fine to run a script to analyze videos even if there are no new videos available. This script depends on having a pre-trained DLC network, and you must change a few variables in the script to be correct for your system:
- videoFormat : str, type of video that you want to analyze (most likely '.mp4').
- config : str, path to config file for pre-trained DLC network.
- videoDirectory : str, path to directory where videos to analyze are (most likely $REMOTEVIDPATH from PiRATeMC).
To use cron to run a script automatically on Linux, enter the following command into a terminal:
crontab -e
This will bring up a window that looks like 
:
The window has instructions for how to use cron to automate tasks, and you can enter the command to execute below. In our example the line we have entered will run the script daily at midnight:
0 0 * * * python3 /d1/software/PiRATeMC/AnalyzeVideos_DLC.py)
To break down the components of this line:
0 0
corresponds to 'minute, hour', so 0 0 indicates at 12am (midnight)
The next 3 are 'day of month, month, day of week', and inserting:
* * *
instructs it to run every day.
The final part is the command to run:
python3 /d1/software/PiRATeMC/AnalyzeVideos_DLC.py
tells it to use python3 to run the script to analyze videos.
If you instead wanted to run this weekly, you could use:
0 0 * * 1 python3 /d1/software/PiRATeMC/AnalyzeVideos_DLC.py
You can instead use the script AnalyzeVideos_DLC_Conda.sh after some modification. The top block of code, under 'initialize anaconda' has paths that are specific to the user account, so either manually replace all of the paths that start with /home/smith/anaconda3/ to the correct path to your anaconda installation, or you can copy this block of code from your .bashrc file, as this is automatically added to .bashrc when anaconda is installed.
You then need to modify the line with:
conda activate dlc
by replacing 'dlc' with your environment name.
Finally, you must start the cron service with:
sudo /etc/init.d/cron start
You can find the full manual for the crontab command here.