Dev branch pull

.gitignore

@@ -0,0 +1,55 @@
+# Compiled source #
+###################
+*.com
+*.class
+*.dll
+*.exe
+*.o
+*.so
+
+# Packages #
+############
+*.7z
+*.dmg
+*.gz
+*.iso
+*.jar
+*.rar
+*.tar
+*.zip
+
+# Logs and databases #
+######################
+*.log
+*.sql
+*.sqlite
+
+# OS generated files #
+######################
+.DS_Store
+Thumbs.db
+
+# IDEs and editors #
+####################
+.vscode/
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Python #
+##########
+*.pyc
+*.pyo
+__pycache__/
+
+# pixi #
+###########
+.pixi/
+pixi.lock
+
+# Environment variables #
+#########################
+.env

README.md

@@ -1 +1,59 @@
-# cagelab
+---
+title: CageLab
+author: Ian Max Andolina
+---
+
+# Table of Contents
+
+1. [Introduction](#introduction)
+1. [Installation](#installation)
+1. [Usage](#usage)
+1. [Parts List](#parts-list)
+1. [Contributing](#contributing)
+1. [License](#license)
+
+# Introduction
+
+![CageLab Render with Eyetracking and Joystick modules attached](images/CageLab.png){width=50%}
+
+CageLab is a low cost in-cage touchscreen training device that prioritises the following features:
+
+1. **Customisable**: The device should be customisable to suit different facility needs. We employ a modular design using  [<img src="images/tslot.png" height="20px"> T-slot framing](https://en.wikipedia.org/wiki/T-slot_structural_framing) for the shell to allow for easy modification without needing a full workshop.
+1. **Scalable**: Integration with the Alyx metadata pipeline ([International Brain Lab, 2023, Nature Methods](https://doi.org/10.1038/s41592-022-01742-6)) to allow for easy management of the data generated by multiple CageLab instances. Each device uploads behavioural data to a central server, which can be accessed and searched by the user through a web interface.
+1. **Automatic Training**: Use behavioural shaping stages with an automated staircase to guide subjects to improved behavioural performance with less experimenter intervention.
+1. **Low Cost**: CageLab should be affordable for most research labs. We aim to keep the total cost of the device below $400.
+1. **Single-enclosure & Battery Operated**: Many animal facilities do not have accesible power outlets near animal housing, or do not want cables or extra trolleys. The device should be self-contained and  battery operated. We added a small UPS to enable hot-swapping of batteries.
+1. **Open Source**: The device software should be open source and easy to contribute to.
+1. **Common Software Path**: The device should be easy to use and maintain; we use [PsychToolbox (PTB)](https://psychtoolbox.org) for easy integration with existing code common in most labs where PTB is prevalent. PTB offers best-in-class experiment timing and a wide range of specialised hardware support.
+1. **Modular**: We have the following modules to use with the device:
+    - **Fluid Pump**: Peristaltic pump, HID interface and costs about $10.
+    - **Food Dispenser**: A pellet dispenser using an arduino driver.
+    - **Camera**: A camera to record the animal's behaviour and stream it over the network.
+    - **Speaker**: A speaker to play sounds.
+1. **Remote Control**: The device must be controllable remotely. We use the fast moonlight remote desktop protocol and server + client protocols where useful.
+
+
+# Installation and Setup
+
+## Multi-Cage Setup
+
+CageLab is designed to be used in a multi-cage setup. Each CageLab instance is connected to a central Alyz server that manages the data generated by each device. The server is accessible through a web interface that allows the user to search and download the data generated by each device. The experiment control software is run on a remote desktop that is connected to the device through the ZeroMQ client server protocol. The remote desktop allows the user to control the device from a distance and monitor the animal's behaviour through a camera that is connected to the device.
+
+![CageLab Multi-Cage Setup](images/CageLab-Network.png)
+
+## Hardware
+
+## Software
+
+You need Octave / MATLAB, PTB and the [opticka toolbox](https://github.com/iandol/opticka)  installed as dependencies. For remote desktop, you need to install moonlight on the device and the client. 
+
+# Parts List
+
+
+# Contributing
+
+Please feel free to open issues or pull requests. We are happy to help you get started with CageLab. We are also looking for collaborators to help us improve the device.
+
+# License
+
+

hardware/CageLab Frame/README.md

@@ -0,0 +1,4 @@
+# Hardware
+
+We use T-slot aluminium framing for the shell to allow for easy modification without needing a full workshop.
+

hardware/Fluid Pump/README.md

@@ -0,0 +1,4 @@
+# Hardware
+
+Docs are WIP.
+

hardware/Food Dispenser/README.md

@@ -0,0 +1,4 @@
+# Hardware
+
+Docs are WIP.
+

hardware/HID Joystick/README.md

@@ -0,0 +1,3 @@
+# HID Joystick
+
+Docs are WIP.

hardware/README.md

@@ -0,0 +1,4 @@
+# Hardware
+
+The hardware modules are designed to be modular and easy to assemble. We use T-slot aluminium framing for the shell to allow for easy modification without needing a full workshop. Both the fluid pump and joystick have a HID interface, allowing them to be used with any computer. The food dispenser is designed to be easy to clean and refill.
+

software/README.md

@@ -0,0 +1,13 @@
+# Software Frameworks
+
+We use the opticka toolbox for the main experiment control, a high-level wrapper for PsychToolbox. A GUI called `CageLab.mlapp` is provided. This GUI is run on your lab machine and will send the experiment settings to the CageLab instance. Each experiment protocol can be run.
+
+## Data pipeline
+
+We use the [International Brain Lab](https://doi.org/10.1038/s41592-022-01742-6) metadata pipeline to manage the data generated by CageLab instances, which opticka supports without other dependencies. 
+
+
+## Remote control
+
+We use Zerotier VPN, SSH and the [moonlight remote desktop protocol](https://moonlight-stream.org) or NoMachine for remote control of the device.
+