SAVIOUR - Synchronised Audio Video Input Output Recorder

A modular and highly usable approach to I/O tasks within the Kind lab and beyond
3D Printable Module Cases
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Background
   • System Purpose
   • Scope
   • System Context
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

Background

The habitat project seeks to explore the behaviour and development of up to 50 rodents in a single large enclosure ("the habitat"). The research is being conducted by SIDB/UofE/Kind Lab with the intention of exploring the genetic factors relating to autism in rodents. To achieve this, experimental data must be gathered. Numerous sensors and actuators are currently distributed throughout the environment - cameras, microphones, RFID, and TTL I/O. To date, measurements have been gathered manually. This is time consuming and leads to unsynchronised measurements. A modular, autonomous approach is desired. Such an approach will have externalities well beyond the Habitat project, which serves as the initial context for the system.

System Purpose

The proposed system provides a modular, scalable, and synchronized data capture solution for behavioral testing labs. It enables precise multi-sensor data collection (video, audio, TTL events, RFID) while controlling external equipment. The controller manages synchronization, health monitoring, and data collation, while sensor modules autonomously capture and transmit data to a central repository. All power, synchronisation, control signalling and data transfer shall use a single POE (Power over Ethernet) connection.

Scope

The system consists of a central controller with multiple PoE sensor modules. Planned sensor modules include cameras, microphones, TTL I/O, and RFID units. The controller detects, synchronises, and manages these modules. Data is collected, formatted, and stored for analysis. The system is modular, allowing for easy expansion and maintenance.

Each system includes:

• A main controller responsible for time synchronisation, data processing, and module management
• A PoE switch which connects the controller to all modules
• A storage dump which is likely a samba share running on the controller, a NAS or other dedicated device
• An array of modules, including:
  • A camera module, providing compressed video capture
  • A microphone module, recording ultrasonic mice vocalisations
  • A TTL I/O module, interfacing with various I/O devices
  • An RFID module, providing subject tracking

Getting Started

Prerequisites

• PoE-capable network switch
• 1x Raspberry Pi 5 for controller
• 1x Raspberry Pi 5 per module, plus module specific hardware e.g. camera, audiomoth USV microphone
• An external storage device, e.g., Synology NAS DS1522+, or perhaps a controller Pi with NVME/SSD storage

Installation

1. Clone the repository

   # Navigate to /usr/local/src (standard folder for userspace source code)
   cd /usr/local/src/
   
   # Create folder and give permissions
   sudo mkdir -p saviour
   sudo chown -R pi:pi saviour/
   
   # Clone the repository
   git clone https://github.com/Kind-Wyllie-lab/saviour.git
   cd saviour

2. Run the setup script

   # Make sure you're in the correct directory
   cd /usr/local/src/saviour/
   ./primary_setup.sh
   # Once this has completed, you can select the role of the device.
   ./switch_role.sh
   # Reboot the pi and setup will have completed.
   

Usage

Detailed usage instructions can be found in the System Requirements Specification document.

Roadmap

• Complete system architecture design
• Implement core controller functionality
• Develop sensor module interfaces
• Implement data storage and retrieval
• Add monitoring and health checks
• pyproject.toml style setup
• Graphical user interface
• Reliable PTP synchronisation
• Pre-baked SAVIOUR distributions
• Basler camera modules
• Real time rat tracking for camera modules
• REST endpoints for synchronisation with webapp and other apps
• Add documentation

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingNewModule)
3. Commit your Changes (git commit -m 'Add some AmazingNewModule')
4. Push to the Branch (git push origin feature/AmazingNewModule)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Andrew Scott-George - ascottg@ed.ac.uk

Project Link: https://github.com/Kind-Wyllie-lab/saviour