MaCaQuE is a visuo-haptic interaction system for unrestrained rhesus monkeys that allows training the animals to goal-directed movement tasks within a cage. The system was developed for sensorimotor neuroscience and tested within the Reach Cage experimental environment:
Berger, M., Agha, N. S., & Gail, A. (2020). Wireless recording from unrestrained monkeys reveals motor goal encoding beyond immediate reach in frontoparietal cortex. eLife, 9(e51322). https://doi.org/10.7554/eLife.51322
This repository contains schematics of the hardware (printed circuit boards and mechanical design of MaCaQuE Cue and Target boxes) and software code (firmware and test software). The software is tested on Mac and Windows.
The presented hard- and software is customized for the research mentioned above and a human psychophysics project involving additional push buttons and tactile (vibration) stimulus delivery:
Berger, M., Neumann, P., & Gail, A. (2019). Peri-hand space expands beyond reach in the context of walk-and-reach movements. Scientific Reports, 9(1), 3013. https://doi.org/10.1038/s41598-019-39520-8
For other projects, a certain level of customization will likely be necessary.
MaCaQuE was designed to perform computerized training of rhesus monkeys within a large unconstrained workspace. The core elements are the cylindrical MaCaQuE Cue and Target boxes (MCT) which contain a touch-sensitive and illuminable front plate. Such MCTs can be placed at any position inside a monkey cage to serve as visual cues or movement targets. MCTs contain a proximity sensor (EC3016NPAPL by Carlo Gavazzi), a custom PCB with four WS2812 (Neopixel) and a custom PCB to communicate with the main board. Standard Ethernet cables are used for signal transmission. For positive reinforcement training, up to two peristaltic pumps can be connected (tested with: OEM M025 DC by Verderflex) that provide fluid reward.
The current implementation can control up to 16 MCTs, however, it would be straightforward to increase this number since MCT in and output is serialized. The MCT-computer interface consists of three PCBs: connector, main and WS2812 board. The connector board has 16 RJ45 connectors and orders the signal lines. The main board is connected to the connector board and contains a Teensy 3.x (PJRC) with USB connection to a controlling computer. The Teensy, an Arduino-compatible microcontroller platform, controls the communication with the computer. In addition, the main board contains hardware for serial-parallel conversion (serial on Teensy side, parallel on MCT side), drivers for peristaltic pumps and a connector for a standard computer power supply (tested with: ENP-7025B by Jou Jye Computer GmbH). The WS2812 LEDs contain a shift-register like circuit to be connected in series. The WS2812 board is an additional PCB connected to the main board that has 16 WS2812 connected in series. This array of WS2812 is used for serial to parallel conversion of the WS2812 signal line that each MCT receives its individual WS2812 input.
Additional breakout pins are available for general-purpose use (GPIO). In the eLife manuscript, those GPIO pins are used for: 1) manual trigger of reward pump, 2) selection of which pump to be triggered manually and 3) synchronization with other recording equipment. In the Scientific Reports manuscript we used the GPIO pins for additional push-button input and controlling circuitry that delivers tactile stimuli. Firmware and test software contain code for each of the tasks.
The firmware is programmed using the Arduino software. It sends the state of the MCT touch sensors (touched or not touched) to the computer and executes commands received from the computer (e.g. set WS2812 or deliver reward).
MaCaQuE incorporates five custom-made PCBs:
- MCT WS2812 ring - for mounting four WS2812 in parallel on the MCT
- MCT board - controls connection between touch sensor and WS2812 with the main board
- Connector board - organizing up to 16 MCT connections
- WS2812 board - 16 WS2812 in series for parallel to serial conversion
- Main board - interface between MCTs and computer
The repository provides Autodesk Eagle board files and schematic files. The electronic parts used with each PCB are listed here:
| Part Name | Company | Amount |
|---|---|---|
| WS2812 RGB-LED | WorldSemi | 4 |
| 100nF Capacitor | - | 4 |
| Part Name | Company | Amount |
|---|---|---|
| L7805 Voltage Regulator | ST | 1 |
| SN75176B Differential Bus Transceiver | Texas Instruments | 1 |
| 100 nF Capacitor | - | 2 |
| 1000 \muF Capacitor | - | 1 |
| 120 Ohm Resistor | - | 1 |
| 470 Ohm Resistor | - | 1 |
| etherCON RJ45 Connector | Neutrik | 1 |
| 2x5 male Header | - | 1 |
| Part Name | Company | Amount |
|---|---|---|
| RJ45 Connector | - | 16 |
| 2x5 male Header | - | 4 |
| 2x6 male Header | - | 1 |
| 2x8 male Header | - | 1 |
| Part Name | Company | Amount |
|---|---|---|
| WS2812 RGB-LED | WorldSemi | 16 |
| 100nF Capacitor | - | 16 |
| single row male Header | - | - |
| Part Name | Company | Amount |
|---|---|---|
| Teensy 3.x | PJRC | 1 |
| CD4021B Shift Register | Texas Instruments | 2 |
| SN74HCT245 Buffer | Texas Instruments | 1 |
| SN75174 Differential Line Driver | Texas Instruments | 4 |
| BUZ11 Transistor | Fairchild | 2 |
| 100 nF Capacitor | - | 7 |
| 1000 \muF Capacitor | - | 1 |
| 470 Ohm Resistor | - | 1 |
| 10 kOhm Resistor | - | 20 |
| 220 Ohm Resistor | - | 2 |
| 20-pin ATX Connector | - | 1 |
| 2x5 male Header | - | 4 |
| 2x6 male Header | - | 1 |
| 2x8 male Header | - | 1 |
| single row female Header | - | - |
| single row male Header | - | - |
The skeleton of the MCT is a custom-designed and 3D-printed construct on which the two MCT PCBs can be screwed on. The proximity sensors can be placed in the middle of the construct and fastened with plastic nuts. For the outer shell, we cut a standard 75mm-diameter PVC pipe to the desired length. The front plate is a round clear polycarbonate plate screwed on top of the PVC pipe. The back plate is connected to the etherCON connector on the MCT board and can be screwed on the PVC pipe. The back plate can be a simple flat PVC plate with custom fitted hole for the etherCON connector. Here, we show a two part design for which the second part can be added to the back plate and provides an inner thread above the connector. We used this thread to connect metal cable protection.
A STEP file contains all parts of the MCT. There is an additional STL file of the component holder that can be directly used for 3D printing.
The repository contains the MaCaQuE firmware, Arduino code that runs on the Teensy microcontroller, test software written in processing and C++ and a C++ library for serial communication with the Teensy.
Arduino code is used to program the microcontroller (Teensy). You need the Arduino software (https://www.arduino.cc/en/Main/Software) and the Teensyduino addon (https://www.pjrc.com/teensy/teensyduino.html) to load the code onto the microcontrolller. If you are new to Arduino, the Arduino website and many others have tons of tutorials and guides. A Teensy-specific tutorial can be found here: https://www.pjrc.com/teensy/tutorial.html
The microcontroller is the gateway between the MCTs and the computer. For each iteration of the main loop, the 16-bit state of the 16 touch sensors (touched, not-touched) is sent out and the serial input is checked. Dependent on the input, different functions will be executed, e.g. the command [t,3,255,0,0] will set the light on the fourth MCT to red (RGB value [255, 0, 0]). See "MaCaQuE_serial_protocol.xlsx" for a description of the serial communication protocol.
The firmware consists of two files: ".ino" is the code and ".h" is a header file that contains definitions. The latter defines which Teensy pins are used for what and which characters are used for interpreting the serial communication.
Processing is a simple scripting language originally designed for visual artists. Because of its ease of use especially with graphical output and serial communication, it is used to make a simple MaCaQuE hardware testing script with graphical user interface.
The user interface presents on the top 16 circles that represent the touch button status. "Green" is touched and "grey" is not touched. Below each circle is a small rectangle. This is a radio button that allows selecting one MCT. Below on the left side, are red, green and blue gradients. By clicking on a position within the gradient, the color of the red, green or blue LEDs of the selected MCT is set to the respective value. On the very bottom are four small circles that display digital state of pins used for synchronization and additional push button input: PIN_DIGITAL_IN_1, PIN_DIGITAL_IN_2, PIN_BUTTON_1, PIN_BUTTON_2 (see "MaCaQuE_defines.h").
The eight additional rectangles are push buttons that execute different functions. From left to right:
- (grey) turn off all lights;
- (grey) handshake with Teensy
- (blue) reward delivery for 1 second on reward system 1
- (blue) reward delivery for 1 second on reward system 2
- (green) turn all lights white
- (red) vibration for 1 second on vibration motor 1
- (red) vibration for 1 second on vibration motor 2
- (grey) execute test code
The research projects incorporating MaCaQuE use C++ experiment control software which communicates with MaCaQuE. Here, we show a simple command line C++ script that can be used to test MaCaQuE hardware and considered as a starting point for developing custom software to be used with a control software of choice. The test script "main.cpp" is just a main function that provides a simplistic command line interface for setting reward or lights and receiving touch sensor data. An additional thread runs in parallel to monitor the serial input. You need to name the correct serial port inside the code that the function can communicate properly with the right Teensy.
To make serial communication as easy as in processing, i.e. simple platform independent function to send or receive an array of 8-bit bytes, the class serial_communication is provided. The code for the functions are adapted from: https://www.pjrc.com/tmp/host_software/
Core functions:
- serial_communication mySerialComm("PORTNAME") - construct class and assign the serial port PORTNAME
- mySerialComm.connect() - establish connection
- mySerialComm.transmit_bytes(BYTE_ARRAY, N) - transmit the array of bytes BYTE_ARRAY with N bytes
- mySerialComm.read_data(INPUT_ARRAY, N) - read up to N bytes from the incoming serial communication and store in INPUT_ARRAY; returns number of bytes read
- mySerialComm.get_status() & mySerialComm.print_communication_state() - infos about the status of the serial communication
- Microcontroller board Teensy by PJRC: https://www.pjrc.com/teensy/
- original C code for serial communication by PJRC https://www.pjrc.com/tmp/host_software/
- Neopixel guide by Adafruit: https://learn.adafruit.com/adafruit-neopixel-uberguide/the-magic-of-neopixels
- Arduino: https://www.arduino.cc/
- Processing: https://processing.org/
- More information about how we use MaCaQuE in our paper: https://doi.org/10.1101/305334