06 ‐ Surface.txt Files - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

CSI Support Files and Surface Definitions

The CSI Support Files include surface.txt and Zone files for many common surfaces. If your surface already exists in the CSI Support Files, you typically will not need to edit or modify the surface.txt file. However, if you need to create a new surface.txt file for your device, this page, along with the Message Generators and Feedback Processors pages, will provide instructions on how to do so.

The surface.txt file defines what the surface can do. The Zones define what the surface will do in Reaper.

Defining Control Surface Capabilities in CSI

When using one or more control surfaces with CSI, it is necessary to define their capabilities. This includes specifying:

  • Controls: Buttons, faders, encoders, etc.
  • Feedback Mechanisms: Displays, lights, LEDs, etc.

The surface.txt files are configuration files used to describe these capabilities. They define what the surface can do—whether it's MIDI, MCU, or OSC-based. Just to reiterate, these files do not determine the behavior of the controls (e.g., what happens when a button is pressed); they only describe the surface's capabilities.

Each file must be named surface.txt and live inside the root of the Surface folder for your device.

Widget Rotary8
    Fader7Bit b0 20 7f
    FB_Fader7Bit b0 20 00
    Toggle 90 1f 7f
WidgetEnd

Widget RotaryPush8 
    Press 90 1f 7f
WidgetEnd

Widget UpperButton1 
    Press 90 20 7f
    FB_TwoState 90 20 7f  90 20 00
WidgetEnd 

Widget Fader1 
    Fader14Bit e0 7f 7f
    FB_Fader14Bit e0 7f 7f
    Touch 90 68 7f 90 68 00
WidgetEnd

Key Concepts

Widgets

Widgets are named components that typically map to a physical control on a surface (e.g., a button or fader). However, a Widget can also represent a combination of controls, like a button and an LED. A Widget may also simply be a Feedback Processor with no control, as in the case of displays.

Capabilities of Widgets

Each Widget defines its capabilities using one or more of the following:

  • Message Generators: These send messages to CSI, such as Press, Fader14Bit, etc.
  • Feedback Processors: These receive messages from CSI to provide feedback on the surface, such as FB_TwoState, FB_Fader14Bit, etc. The FB prefix stands for "FeedBack."

Parameters

Both Message Generators and Feedback Processors may include parameters to specify details like MIDI message type, behavior, and additional configurations. Refer to the documentation for the specific Message Generators or Feedback Processors you're using to understand their parameters.

MIDI Surface Example Breakdown

UpperButton1 Widget

Widget UpperButton1 
    Press 90 20 7f
    FB_TwoState 90 20 7f  90 20 00
WidgetEnd

The above says this Widget is a combination of a...

  • Message Generator:
  • Press MIDI Generator, which means when pressed it will send the MIDI Message 90 20 7f
  • Feedback Processor:
  • FB_TwoState Feedback Processor, which will:
    • Receive a MIDI Message of either 90 20 7f or 90 20 00 and display that to the user. In this case, this is displayed as an LED Button, where 90 20 7f represents the On state (the LED is on) and 90 20 00 represents the Off state (the LED is off).

RotaryPush8 Widget

Widget RotaryPush8 
    Press 90 1f 7f
WidgetEnd
  • Message Generator:
  • Press Message Generator that sends only the MIDI Message 90 20 7f when it is pressed. This Widget does not process feedback or send messages on release.

OSC Example Breakdown

Below is an excerpt from a surface.txt for an Open Sound Control (OSC) device.

Widget MainDisplay1
     FB_Processor /MainDisplay1
WidgetEnd

Widget RotaryA1
     Control /RotaryA1
     FB_Processor /RotaryA1
WidgetEnd

Widget DisplayUpperA1
     FB_Processor /DisplayUpperA1
WidgetEnd

Widget DisplayLowerA1
     FB_Processor /DisplayLowerA1
WidgetEnd

Widget RotaryPushA1
     Control /RotaryPushA1
     FB_Processor /RotaryPushA1
WidgetEnd

OSC Display Breakdown

Widget MainDisplay1
     FB_Processor /MainDisplay1
WidgetEnd
  • Message Generator:
  • The widget is named MainDisplay1. Since it is only a display, there is no Message Generator. It's only a feedback processor.
  • Feedback Processor:
  • The OSC address for this feedback processor is /MainDisplay1. This will be defined in the .osc file itself.

OSC Control Breakdown

Widget RotaryA1
     Control /RotaryA1
     FB_Processor /RotaryA1
WidgetEnd
  • Message Generator:
  • In this case, the Message Generator is defined as a "Control" followed by the OSC address. Control /RotaryA1
  • This will work the same for all OSC controls. CSI does not define different types of OSC controls differently like it does for MIDI/MCU Message Generators.
  • Feedback Processor:
  • The OSC address for this feedback processor is /MainDisplay1. This will be defined in the .osc file itself.

Additional Notes

  • The surface.txt file does not specify the behavior of the surface, only its capabilities. This means anyone with the same model of control surface can, in theory, reuse the same surface.txt file, even if they assign different behaviors to the controls. For example:

    • If you and someone else both own a BCF2000, you can share the same surface.txt file.
    • However, if you have modified your control surface to send different MIDI messages, someone else’s surface.txt file might not work for you.

  • It’s important to remember that the surface.txt file reflects what the surface does. It does not control the behavior of the surface. For example:

    • If your surface does not send a message on button release, defining a Release message in the surface.txt file will not make it do so.
    • Either modify your surface to send the required messages or reflect its current behavior accurately in the surface.txt file.