用于创建 MIDI 控制器和其他 MIDI 设备的 Arduino 库。
Control Surface is an Arduino library for building MIDI controllers and control surfaces.
At its core, the library features a flexible MIDI abstraction layer with support for serial 5-pin DIN MIDI, MIDI over USB, MIDI over BLE, etc. These MIDI interfaces are compatible with a wide range of Arduino boards (a full table can be found here) and are useful in any Arduino MIDI project.
In addition to MIDI input/output, Control Surface also provides easy-to-use utilities intended for building MIDI controllers, supporting controls that send MIDI messages ─ like potentiometers, push buttons, rotary encoders, etc. ─ and controls that react to incoming MIDI messages ─ LEDs, displays, and so on. More advanced controls that combine MIDI input and output ─ such as motorized faders ─ are supported as well.
In projects with large numbers of inputs and outputs, Control Surface allows you to seamlessly add multiplexers, shift registers and other port expanders, and treat them as if they were ordinary GPIO pins.
Table of contents
¶ Example usage
¶ Getting started
¶ Documentation
¶ Feature overview
¶ Supported boards
¶ Change log and updating
An extensive list of examples can be found in the documentation. Below are a handful of simple examples that give an idea of how the Control Surface library can be used.
Example 1: A complete sketch for a MIDI controller with a potentiometer that sends out MIDI Control Change message can be written in just five lines of code:
#include <Control_Surface.h>
USBMIDI_Interface midi;
CCPotentiometer pot { A0, MIDI_CC::General_Purpose_Controller_1 };
void setup() { Control_Surface.begin(); }
void loop() { Control_Surface.loop(); }
Example 2: Larger MIDI controllers can be implemented very easily as well, with clean and easy to modify code. The following sketch is for 8 potentiometers (connected using an analog multiplexer) that send out MIDI Control Change messages over USB. A detailed walkthrough of this example can be found on the Getting Started page.
…
Example 3: Control Surface also supports many types of MIDI inputs. For example, an LED that turns on when a MIDI Note On message for middle C is received:
#include <Control_Surface.h>
USBMIDI_Interface midi;
NoteLED led { LED_BUILTIN, MIDI_Notes::C[4] };
void setup() { Control_Surface.begin(); }
void loop() { Control_Surface.loop(); }
Example 4: Control Surface's MIDI interfaces can also be used directly, for example, to implement a MIDI-over-USB to MIDI-over-BLE adapter:
…
See the Getting Started
page to get started using the library.
It'll also point you to the Installation Instructions.
The MIDI tutorial might be useful if you want to use Control Surface as a regular MIDI library, for sending and receiving MIDI messages.
Detailed documentation for this library can be found here:
Documentation
Arduino examples can be found here:
Examples
The User Manual is the best entry point to the documentation. To get a complete overview of all features of the Control Surface library, have a look at the following section and at the Topics page.
You can find an answer to some frequently asked questions on the FAQ page.
This library turns your Arduino-compatible board into a MIDI control surface.
Just connect some push buttons, potentiometers, LEDs ... and declare them in
your code.
The following sections give a brief overview of the features of the library.
→ MIDI Interfaces documentation
Digital inputs are debounced, and analog inputs are filtered using digital filters and hysteresis. This results in high accuracy without noise, without introducing latency.
These MIDI control outputs can be used to send MIDI notes, Control Change, Pitch Bend, Program/Patch change, etc.
→ MIDI Output Elements documentation
A large portion of the Mackie Control Universal (MCU) protocol is implemented.
→ MIDI Input Elements documentation
→ Control Surface Motor Fader documentation
All controls can be arranged in banks: for example, if you have only 4
physical faders, you can make them bankable, so they can be used to control
the volume of many more different tracks. Changing banks can be done using push
buttons, rotary encoders, etc.
Apart from banks and bank selectors, you can also add transposers to change
the key of your notes, for example.
In order to save some IO pins, the library natively supports multiplexers (e.g. 74HC4051 or 74HC4067) to read many switches or potentiometers, Shift Registers (e.g. 74HC595) to drive many LEDs, MAX7219 LED drivers, etc.
If you are using a Teensy 3.x or 4.x, you can use it as a
USB audio interface. Just add an I²S DAC (e.g. PCM5102) and 5 lines of code,
and you can start playing audio through your Teensy, by combining Control
Surface with the Teensy Audio library.
You can also add volume controls and VU meters for these audio connections.
Thanks to the structure of the library, you can easily add your own MIDI or display elements, using some minimal, high level code. All low level stuff is completely reusable (e.g. all MIDI operations, debouncing switches, filtering analog inputs, and so on).
Download the repository as a ZIP archive by going to the home page of the
repository and clicking
the green Code button in the top right, then choosing “Download ZIP”.
Alternatively, click the following direct download link:
https://github.com/tttapa/Control-Surface/archive/refs/heads/main.zip
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.
For each commit, the continuous integration tests compile the examples for the following boards:
This covers a very large part of the Arduino platform, and similar boards will also work. For example, the Arduino Nano, Mega, Micro, Pro Micro, Teensy 2.0, Teensy LC, Teensy 3.x, Teensy 4.x are all known to work.
If you have a board that's not supported, please open an issue and let me know!
Note that MIDI over USB and MIDI over Bluetooth are not supported on all boards. See the MIDI over USB documentation page for a table with supported features per board.
ESP32NimBLEBackend for
MIDI over BLE.
The h2zero/NimBLE-Arduino library does not need to be installed in this case
(it is necessary for older versions of arduino-esp32 and for the original
ESP32 only).[^1]: More details about this migration can be found in https://github.com/espressif/arduino-esp32/discussions/10991.
pin_t type is now a distinct type rather than an alias to an integer.
This improves type safety, because pin_t is no longer implicitly
convertible to an integer (although integers are still convertible to
pin_t), and it is no longer possible to accidentally use incorrect
constructs such as mux.digitalRead(mux.pin(0)). A new type, pin_int_t,
was added to represent sizes and offsets of pins (e.g. “the sixth pin of this
multiplexer)”, and the argument types of the member functions of the
ExtendedIOElement class have been modified accordingly. If you were using a
class that inherited from ExtendedIOElement, you should update the signatures
of any overridden methods.MIDI_Notes::X(n) by MIDI_Notes::X[n] to avoid issues with the Arduino F(...) macro.暂无开放 Issues，或尚未同步最近议题。