cs-midi-docs/docs/manual/03-control-surface/_index.md

Control Surface Singleton

Original: Purpose of the Control_Surface singleton

The Control_Surface object is the central manager for all MIDI elements, interfaces, and lifecycle events.

Program structure

#include "pico/stdlib.h"
#include <cs_midi.h>

using namespace cs;

BluetoothMIDI_Interface midi;
NoteButton button {5, {MIDI_Notes::C[4], Channel_1}};

int main() {
    stdio_init_all();
    Control_Surface.begin();
    while (true) {
        Control_Surface.loop();
        sleep_ms(1);
    }
}

Responsibilities

1. Initialization — begin() activates all registered MIDI interfaces, output elements, input elements, and selectors.
2. Periodic updates — loop() polls physical inputs (buttons, pots, encoders), sends MIDI when values change, and dispatches incoming MIDI to input elements.
3. Message routing — connects output elements to the default MIDI interface and delivers incoming messages to matching input elements.

Element registration

Elements register themselves on construction and deregister on destruction. No explicit add() calls needed.

Enable/disable

Elements can be removed from the update loop at runtime:

button.disable();  // stops polling and sending
button.enable();   // re-adds to update loop

Without the singleton

For direct MIDI sending/receiving without the element system, use the interface object directly:

midi.begin();
midi.sendNoteOn({MIDI_Notes::C[4], Channel_1}, 127);
midi.update();