2. Set up Raspberry Pi and tracking system software

The Raspberry Pi needs to be set up for the different sensors and software used by tracking system. These steps need to be performed manually before executing the run_install.sh script that automatically installs the tracking system software.

Step 1. Configure Raspberry Pi for compatibility with the tracking system

Materials

• Raspberry Pi 4 (we used 2 or 4Gb)

• Power supply

• Raspberry Pi SD card (we used 32Gb or 64 Gb with Rasbian Buster pre-installed)

• SD card adapter (unless you have a laptop with a built-in port)

• Computer monitor or display

• mini HDMI to HDMI cable

• USB mouse

• USB keyboard

Methods

1.1. Insert the SD card with Rasbian pre-installed, and connect a USB keyboard, USB mouse, mini-HDMI to HDMI cable connected to a display, and power cord. Then turn the power supply on

1.2. Follow the automated prompts to set up the language, keyboard, Pi password, WiFi connection, and default package installations. We recommend setting a unique password for the Raspberry Pi for better security

1.3. Get IP address:

• Open a terminal window and find the IP address of the Pi. Write this down in a safe place for remote connections via ssh after the system is installed:

  • hostname -I

  • Check out Raspberry Pi Documentation - Remote Access for more information

1.4. Open the Raspberry Pi Configuration menu to begin configuring the Pi for compatibility with different sensors. You can do this by selecting Raspberry Pi Configuration from the Preferences menu as in Step 1.3, or by opening a terminal window and executing:

• sudo raspi-config

1.5. While in the Raspberry Pi Configuration window, make sure the Pi is set up for interfacing with the camera and RFID reader:

• Enable the camera (P1) by navigating to the Interfaces option. Select "Enabled" next to Camera and click OK

• Enable SSH (P2) option too

• In the Interface options, navigate to P6 Serial, then select the options to disable the login shell over serial and enable serial hardware. The result window should look like this:
  

1.6. Select Finish to save these changes and reboot the Pi

1.7. To continue setting up the Pi for the RFID reader, make changes to the /boot/config.txt file:

• Open a terminal window, then open the config.txt file with a text editor:

  • sudo nano /boot/config.txt or sudo vim /boot/config.txt (you may need to install vim)

• Add enable_uart=1 to the bottom of the file (section [all]), unless it's already there. Add dtoverlay=disable-bt to the bottom of the file (section [all])

• Uncomment or add the line dtparam=i2c_arm=off under Uncomment some or all of these to enable the optional hardware interfaces

• Uncomment the line dtparam=spi=on in the same section as immediately above

• Save these changes and exit the text editor

• Reboot the Pi:

  • sudo reboot

1.8. Set the default Python version to Python 3 for compatibility with the RFID reader software:

• Check which Python versions are on the Pi in a terminal window:

  • python --version and python3 --version

• Then list the available alternatives. You'll probably get an error about an empty list:

  • sudo update-alternatives --list python

• Update the Python alternatives to list Python 3 as the default (the last version specified take priority), using the output from the commands above with Python 2 and 3 versions, for instance:

  • sudo update-alternatives --install /usr/bin/python python /usr/bin/python2.7 1

  • sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.7 2

• Check this update:

  • python --version

  • The default should now be the Python 3 version

1.9. Set up the Pi to communicate with the temperature sensor:

• Open the config.txt file:

  • sudo nano /boot/config.txt or sudo vim /boot/config.txt

• Add the following text to the bottom of the file in the section [all]: dtoverlay=w1-gpio, then save and close the file

• Reboot the Pi:

  • sudo reboot

• Once the Pi has rebooted, run modprobe to load the right modules for communication with the sensor:

  • sudo modprobe w1-gpio

  • sudo modprobe w1-therm

• Check the directory for this device to ensure setup was performed correctly. if so, the results of ls should include a subfolder that starts with "28", and the results of ls 28-* should include "w1_slave":

  • cd /sys/bus/w1/devices

  • ls

  • `ls 28-*"

  • Check the contents of the "w1_slave file", this should contain a first line with YES or NO. If YES, then second line should have a temperature value, such as t=12000:

    • cd 28-*

    • cat w1_slave

Step 2. Prepare external hard drives

Materials

• One external hard drive per Raspberry Pi. We used Seagate 1Tb external hard drives

• Raspberry Pi computers

Methods

2.1. Turn on the Pi, then plug the external hard drive into one of the USB 3.0 ports

2.2. Remove the following folders and files inside the hard drive:

• Start_Here_Mac.app
• Start_Here_Win.exe
• Autorun.inf

2.3. Open a terminal window and get the volume label of the external hard drive:

• sudo fdisk -l

The volume label should correspond to a hard drive with 900Gb - 1Tb of storage space, such as /dev/sda1

2.4. Check out the volume format. If the drive is in NFTS format (as are the Seagate hard drives), then make sure that the most recent version of NFTS support is installed on the Pi:

• sudo apt-get update
• sudo apt-get upgrade
• sudo apt-get install ntfs-3g

2.5. Install a disk utility to change the name of the external hard drive. Disk utilities can also be used to reformat hard drives, but make sure any data you have on them is backed up first. Install gparted:

• sudo apt-get install gparted

Then reboot the Pi.

2.6. When the Pi restarts, open gparted by going to the home menu, then System Tools, and enter the pi user password when prompted

2.7. Select the correct volume label from the top right drop down menu. The volume label is from the fdisk -l command above (like /dev/sda).

2.8. Relabel the external hard drive:

• Right-click on the image of the nfts file system
• Select "Unmount" in the pop-up menu
• Right-click again and select "Label File System"
• Type in the new name you'd like to assign to the hard drive. We named hard drives by recording boxes or chambers (e.g. "Box_01")
• Click the green check that pops up to apply all operations
• Reboot the Pi

2.9. To ensure that the external hard drive will be accessible throughout a headless (ssh) connection to the Pi, do the following:

• Unmount the hard drive:
  • umount /media/pi/Box_01
• Create a mount folder with the name of the external hard drive:
  • sudo mkdir /media/pi/Box_01
• Mount the external drive to the mount folder. Make sure to use the correct volume label and drive name:
  • sudo mount /dev/sda1 /media/pi/Box_01
• Make the 'Data' folder inside the drive where data from the behavioral tracking system will be saved:
  • sudo mkdir /media/pi/Box_01/Data
• Change the drive permissions so that the 'pi' user can read/write to the drive:
  • sudo chmod -R 777 /media/pi/Box_01/Data

2.10. Test the hard drive ownership and permissions by creating a test folder and copying a file into it. If you get error messages then check out Linux forums for how to reset hard drive permissions and ownership

Step 3. Set up the tracking system software on the Raspberry Pi

Materials

• A Raspberry Pi computer set up as in steps 1 and 2 above

Methods

3.1. Open a terminal window on the Raspberry Pi and install git:

• sudo apt-get install git

3.2. Go to the directory where you want the tracking system software to be installed, for instance:

• cd ./Desktop/

3.3. Clone the GitHub repository for the tracking system, and enter your GitHub info when prompted:

• git clone https://github.com/lastralab/Abissmal.git

• You will probably have to enter a unique personal access token here, since GitHub doesn’t support using your account password here anymore. You can check out more info here. Although this isn’t very secure, I keep a text file with this personal access token that I can use to copy-paste the code as needed

3.4. Move into the new directory and ensure you're on the main branch:

• cd ./Abissmal
• git checkout main

3.5. Create a local version of the main branch:

• git checkout -b local-main

• git branch to confirm you're on the new branch

This is to ensure that any pushes made to the remote repository don't accidentally overwrite the main branch.

3.6. Automatically install the tracking system software:

• sudo bash run_install.sh

This script will automatically install software dependencies (ntfs-3g, python3, gparted, screen, ssmtp, nmap), and will also prompt you to enter some information so that the tracking system is set up correctly. You can press Enter to skip a configuration step if you've already set it up on the same Pi before. Some quick notes

• After entering these items, the RaspberryPi will auto-restart in 5 seconds to apply these changes

3.7. To start the tracking system for data collection, open a terminal window, navigate to the directory where the tracking system was installed, and execute:

• bash Main.sh

You should see verbose output print to the terminal window confirming that the screens for each data collection or system monitoring module are initializing. In this output you will also see code for stopping the tracking system as needed.

3.8. Open another terminal window and print the contents of the log file to monitor tracking system progress and errors:

• tail -f /home/pi/info/log/YYYY_MM_DD_Box_Number.log

3.9. You can connect remotely to the Pi to start, stop, check the tracking system, or transfer files on the Pi to your local computer. To begin, you can shutdown the Pi, then disconnect the display, keyboard and mouse, and turn the Pi back on. Then open a terminal window on a different computer in the same network (e.g. your "local" machine):

• To connect remotely from a computer using the same network, run the following command in the terminal window:

  • ssh pi@{hostname}
  • Enter the Pi's password when prompted

  Then in the same terminal window, you can run the commands above to run, stop, or check the tracking system. Make sure to mount the external hard drive before starting the tracking system when connecting remotely (if the Pi has been turned off and on between runs). You can connect via multiple terminal windows as well.

• Transfer individual files over to your local computer:

  • scp pi@{hostname}:/pi/path/to/files/single_file.csv /any/local/dir

• Transfer folders and their contents to your local machine:

  • scp -r pi@{hostname}:/pi/path/to/folder /any/local/dir

Important notes:

• The tracking system was developed using the Raspbian Buster 32-bit OS, and we recommend using this OS instead of more recent versions (e.g. Bullseye). Directory names and default software are different on Bullseye

• If you executed run_install.sh through a ssh connection, then you will need to mount the external drive before starting the tracking system

• If you execute run_install more than once on the same Pi, then you'll also need to remove extra lines in the crontab file for the tracking system to operate correctly. See the Troubleshooting page for more info

• You will need to rerun the run_install.sh script after every time you pull changes from GitHub. Ideally, when using the tracking system for experiments, you will install a final version of the software to avoid having to pull updated code over and over from GitHub

• Do not use sudo when starting the tracking system (Step 3.11). This will cause reading and writing issues, and the tracking system software won’t work correctly

• We recommend doing a dry run of the tracking system prior to collecting data with live animals