# CageLab-Code

**Repository Path**: CogPlatform/CageLab-Code

## Basic Information

- **Project Name**: CageLab-Code
- **Description**: High-throughput & Low-cost In-Cage Cognitive Training System
- **Primary Language**: Matlab
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-05-26
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: hardware

**Tags**: None

## README

# Software Frameworks

## Distributed Architecture
CageLab is designed to run on a distributed architecture, where each CageLab instance runs on a separate machine. This allows for flexibility in hardware selection and enables the use of multiple machines to run different experiments simultaneously. Each CageLab instance can be controlled remotely, allowing for easy management and monitoring of experiments.

Each CageLab runs a middleware called [cogmoteGO](https://github.com/Ccccraz/cogmoteGO), which establishes communication APIs to:

1. Relay command packets from a remote desktop machine to a local running PTB/MATLAB process (could be Octave, Python or any other experiment framework). The messages are JSON encoded and sent using a HTTP POST request and cogmoteGO forwards them over a local ZeroMQ REQ channel to the PTB/MATLAB process.
2. Broadacast data messages from PTB/MATLAB (or other experiment framework) that can be subscribed to by any number of remote machines.

We use the Opticka toolbox for the main experiment control, a high-level wrapper for PsychToolbox. A GUI called `CageLab.mlapp` is provided. The GUI is run on your desktop machine and will send the experiment settings to the CageLab instance. The CageLab device runs a MATLAB service called `theConductor` that receives commands and orchestrates experiments. Each experiment protocol can be run either locally or remotely. We use another app, Puremote, to visualise the subject screen (streamed via mediamtx server), a video feed from the CageLab camera and to plot the broadcast data. 

## Software Components

- **Opticka**: A high-level wrapper for PsychToolbox, used for experiment control.
- **cogmoteGO**: Middleware for communication between remote desktop and local CageLab instance.
- **theConductor**: A MATLAB service that orchestrates experiments on the CageLab instance. Runs CageLab behavioural tasks.
- **CageLab.mlapp**: A GUI for configuring and controlling experiments on the CageLab instance, run on a remote computer.
- **Puremote**: An app for visualising the subject display, video feed from the CageLab camera, and plotting the broadcast data.

## Viewing the Opticka experiment log remotely

**theConductor** is run vis `systemd` and logs are therefore readable using `journalctl`. You can read the log remotely using ssh to login to the Cagelab instance and then running `journalctl --user -f -u theConductor`.

## 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 any other dependencies. 


## Remote access

We use Zerotier VPN, SSH and NoMachine or [moonlight](https://moonlight-stream.org) for remote control of the device.