This is an old version of the documentation. View the latest version here.
Control Surface  1.0.0
MIDI Control Surface library for Arduino

This document assumes that the Arduino IDE is already installed, as well as the necessary hardware support packages, such as Teensyduino or the ESP32 Core.

You have to install the Control Surface library itself, as well as some dependencies.

If you want to keep up to date with the latest developments, or if you want an easy way to update, the git install is recommended. Otherwise, you can use the no git install.

Installation (no git)

1. Download

Download the repository as a ZIP archive by going to the home page of the repository and click the green Clone or download button on the top right.

2. Install the Library in the Arduino IDE

Open the Arduino IDE, and go to the Sketch > Include Library > Add .ZIP Library menu.
Then navigate to your downloads directory where you just downloaded the library.
Select it, and click Ok.

Installation (git)

0. Install git

If you haven't already, install git from or use your system's package manager.

On Ubuntu and other Debian-based distros:

sudo apt-get install git

1. Browse to your Arduino Libraries folder

Open a terminal window and change the directory to your Arduino folder.

On Linux:

mkdir -p ~/Arduino/libraries && cd $_

2. Clone the Library

git clone

3. Updating to the latest version

If you installed the library using git, you can easily update it when a new version comes out.
To update to the latest master version:

git pull


If you are using an Arduino board with on-board USB capabilities, you need the MIDIUSB library. Install it as explained before, or by using the Library Manager.

The Control Surface Library depends on the PJRC Encoder library for reading the input from rotary encoders. Download and install it if you plan on using those.

If you are using a Teensy, you don't need the MIDIUSB library, and the Encoder library should already be installed.