ArenaController

Archived. Replaced by: https://github.com/floesche/LED-Display_G4.1_ArenaController_Slim

Repository Information

• Library Name: ArenaController
• Description: Arduino library for communicating with the Reiser Lab Modular LED panels display arena.
• Version: 7.1.0
• Panel Version: G4 v1.9
• Release Date: 2026-03-13
• Creation Date: 2023-08-16
• License: GPL-3.0
• URL: https://github.com/janelia-arduino/ArenaController
• Author: Peter Polidoro
• Author Email: peter@polidoro.io
• Maintainer: Peter Polidoro
• Maintainer Email: peter@polidoro.io
• Copyright: 2026 Howard Hughes Medical Institute
• References:
  • https://github.com/janelia-python/arena_interface_python
  • https://reiserlab.github.io/Modular-LED-Display/
  • https://github.com/floesche/LED-Display_G4_Hardware_Arena
  • https://github.com/leburnett/G4_Display_Tools
  • https://www.pjrc.com/store/teensy41.html
  • https://www.pjrc.com/store/ethernet_kit.html
  • https://github.com/QuantumLeaps/qp-arduino
  • https://github.com/ssilverman/QNEthernet
  • https://www.adafruit.com/product/4470
  • https://www.adafruit.com/product/1083

Modular LED Display

Abstract from https://doi.org/10.1101/2022.08.02.502550 :

“Visual stimulation of animals in the laboratory is a powerful technique for studying sensory control of complex behaviors.

Since commercial displays are optimized for human vision, we established a novel display system based on custom-built modular LED panels that provides millisecond refresh, precise synchronization, customizable color combinations, and varied display configurations.

This system simplifies challenging experiments.

With variants of this display, we probed the speed limits of motion vision and examined the role of color vision in behavioral experiments with tethered flying Drosophila.

Using 2-photon calcium imaging, we comprehensively mapped the tuning of visual projection neurons across the fly’s field of view.

Finally, using real-time behavior analysis, we developed low-latency interactive virtual environments and found that flying flies can independently control their navigation along two dimensions.

This display system uniquely addresses most technical challenges of small animal vision experiments and is thoroughly documented for replicability.”

System Components

Quarter Panel

A quarter panel is a set of LED pixels arranged in rows and columns.

Panel

A panel is a set of quarter panels arranged in rows and columns.

Region

A region is a set of panels arranged in rows and columns with a common communication interface.

Display

An display is a set of regions arranged in rows and columns.

Display Messages

Quarter Panel

Pixels

Pixel numbering for each pixel in a quarter panel:

Grayscale

In grayscale mode, each LED can be one of sixteen brightness levels.

Binary

In binary mode, each LED can be one of two brightness levels, on or off.

Panel

Quarter Panels in Panel

Quarter panel numbering for each quarter panel in a panel plus pixel numbering for select pixels in a panel:

Region

Regions in Display

Region numbering for each region in an display:

Panels in Region

Panel numbering for each panel in an region:

Display

Panels in Display

Panel update order for each panel in an display:

Synchronous

Asynchronous

Firmware

Active Objects

name	priority	event-queue-count	state-machines
Watchdog	1	2	Watchdog
SerialCommandInterface	2	10	SerialCommandInterface
EthernetCommandInterface	3	10	EthernetCommandInterface
Pattern	4	20	Pattern, Card
Arena	5	20	Arena, AnalogOutput, AnalogInput
Display	6	20	Display
Frame	7	20	Frame

State Diagrams

Watchdog

SerialCommandInterface

EthernetCommandInterface

Pattern

Card

Arena

AnalogOutput

AnalogInput

Display

Frame

Command Set

Development

Download this repository

https://github.com/janelia-arduino/ArenaController.git

sudo apt install -y git
mkdir -p ~/tmp && cd ~/tmp && git clone https://github.com/janelia-arduino/ArenaController.git
cd ArenaController

PlatformIO via pixi

Install pixi

Linux & macOS:

curl -fsSL https://pixi.sh/install.sh | sh
# or, if you do not have curl:
wget -qO- https://pixi.sh/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

Restart your terminal so the updated PATH takes effect, then verify:

pixi --version

(Optional) Update pixi:

pixi self-update

Create the environment

From the repository root:

pixi install

You can also run any task directly; pixi will install the environment automatically if needed.

Linux USB/Serial permissions (udev rules)

Linux users may need udev rules for PlatformIO supported boards/devices:

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/system/99-platformio-udev.rules | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo service udev restart
sudo usermod -a -G dialout $USER
sudo usermod -a -G plugdev $USER
# Log out/in (or reboot) so group changes take effect.

If uploads still fail due to port contention, you can remove ModemManager on Debian-based systems:

sudo apt-get purge --auto-remove modemmanager

Build the firmware

Pixi tasks select which example gets built by setting the PLATFORMIO_SRC_DIR environment variable (so you do not need to edit platformio.ini).

Default example (examples/ArenaControllerTeensy12-12, which now uses QNEthernet as the only Ethernet backend):

pixi run build

Other examples:

pixi run build examples/SDCardDebugTest
pixi run build examples/WatchdogTest

Flash the firmware

Flash first cleans any previous build files, the builds the firmware, then uploads it over the serial port.

List available devices/ports:

pixi run ports

Flash (a port can be provided; default is /dev/ttyACM0):

pixi run flash
pixi run flash examples/ArenaControllerTeensy12-12 /dev/ttyACM1
pixi run flash examples/ArenaControllerTeensy12-12 /dev/cu.usbmodem1234
pixi run flash examples/ArenaControllerTeensy12-12 COM3

Flash other examples:

pixi run flash examples/SDCardDebugTest
pixi run flash examples/SDCardDebugTest /dev/ttyACM1

pixi run flash examples/WatchdogTest
pixi run flash examples/WatchdogTest /dev/ttyACM1

Use serial monitor for debug tests

The serial monitor should not be used for examples/ArenaControllerTeensy12-12 since the output is binary. Use qspy (see below) instead.

The serial monitor is used for examples/SDCardDebugTest however.

List available devices/ports:

pixi run ports

Run monitor (a port can be provided; default is /dev/ttyACM0 @ 115200):

pixi run monitor /dev/ttyACM1
pixi run monitor /dev/ttyACM0 9600
pixi run monitor COM3 115200     # Windows

Version synchronization

Keep the version number consistent across README.org, library.properties, and pixi.toml:

pixi run check-version
pixi run set-version 7.0.0

Quantum Leaps host tools (QM and QTools/QSPY)

This project uses the Quantum Leaps qp-arduino framework (qpcpp 6.9.3), so the host tools must be pinned to compatible versions:

• QM 5.2.3
• QTools (QSPY) 6.9.3

The pixi tasks in this repository download and install these tools locally into:

./.tools/quantum-leaps/

(Recommended) Add this directory to your .gitignore so downloads are not committed:

.tools/

Install QM and QTools

pixi run ql-install

Launch QM

pixi run qm

Install QTools (and build QSPY on Linux/macOS)

On Linux/macOS, QSPY is built from source using make and a C compiler (pixi installs these dependencies automatically for supported platforms).

pixi run qtools-install

Run QSPY

The QSPY output is binary, so do not use the Arduino serial monitor.

Typical serial connection example (Linux):

pixi run qspy -c /dev/ttyACM0 -b 115200

macOS example:

pixi run qspy -c /dev/cu.usbmodem1234 -b 115200

Windows example:

pixi run qspy -c COM3 -b 115200

To show QSPY’s own help (not this wrapper’s help), use the explicit separator:

pixi run qspy -- -h