03 ‐ Setting Up Your Control Surfaces - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

CSI Control Surface Settings

This page explains how to use the CSI Control Surface Settings screen within Reaper. This screen is where you will configure your MIDI and OSC devices for use within CSI, as well as set up device preferences and advanced Broadcast/Listen options.

If you're migrating from a prior version of CSI, see the Migration Guide for details on which updates to make.

Quick Navigation

Accessing the CSI Control Surface Settings

  1. Open Reaper.
  2. Navigate to Preferences > Control/OSC/Web.
  3. If you've already set up CSI, you should see an option for Control Surface Integrator. Highlight this row. If you have not set up CSI, please see the Installation and Folder Structure page first.
  4. Click the Edit button. The window below should appear (Note: your surface setup may differ).

CSI Preferences Screen

Surfaces

The Surfaces section on the left is where you add MIDI and OSC surfaces to your CSI setup. This is where you define the MIDI ports and/or OSC IP address and ports. Before adding any surfaces, ensure you have at least one Page under the Pages section.

Surface Buttons

  • Add MIDI - Adds a MIDI or MCU surface.
  • Add OSC - Adds an OSC device (e.g., a phone, tablet, or the local PC).
  • Edit - Edits the selected surface.
  • Remove - Removes the selected surface.

MIDI Surface Settings

When you add or edit a MIDI surface, the window below appears.
Note: To enable CSI access to your device's MIDI ports, the device's input and output ports must be disabled in Reaper's Preferences > MIDI Devices.

Add MIDI Device Screen

  • Name - Name for your MIDI device as it will appear in CSI.
  • MIDI In - MIDI input port for your device.
  • MIDI Out - MIDI output port for your device.
  • Number of Channels - Number of channels on the surface.
  • Display Refresh Rate - Surface refresh rate in Hz (default: 15 Hz).
  • Max Messages Per Run - Adjust if MIDI messages are dropped (default: 200).

OSC Surface Settings

When you add or edit an OSC surface, the window below appears.

Add OSC Device Screen

  • Name - Name for your OSC device as it will appear in CSI.
  • Type - Select between a generic OSC device or the Behringer X32.
  • Number of Channels - Number of channels on your OSC device.
  • Remote Device IP - IP address for your OSC device (e.g., phone, tablet, or local PC running TouchOSC).
  • CSI Receives on Port - Port number CSI listens to for OSC messages. Must match the sending port of the OSC device.
  • CSI Sends on Port - Port number CSI sends OSC messages to. Must match the receiving port of the OSC device.
  • Maximum Packets - Default: 0. If experiencing dropped OSC messages, experiment with different values here (e.g., 10, 80, 200).

Note: Setting up or changing an OSC device requires a full restart of Reaper. The "Refresh all surfaces" action does not refresh OSC setup changes.

Pages

In CSI, a Page is the highest hierarchy level, with each Page containing one or more surfaces. You must have at least one page (HomePage or Home), but can define multiple pages.

Why Use Pages?

  • Enable/disable different surfaces depending on tasks.
  • Assign different actions or zone folders per Page.
  • Define surface capabilities uniquely for each Page.

Important Note:

  • Page names cannot contain spaces.
  • CSI includes a default Page called "HomePage." If missing, create a "HomePage" or "Home" page.

Page Buttons

  • Add - Creates a new Page. At least one Page is required.
  • Edit - Edits settings for the selected Page.
  • Remove - Removes the selected Page.

CSI Settings Add Page

Page Settings

  • Page Name - Name of the Page.
  • CSI Follows Track Manager Show/Hide - Set CSI to follow Reaper's Mixer Control Panel (MCP) or Track Control Panel (TCP) track visibility.
  • Bank with Other Pages - Enable to apply banking across all Pages.
  • Ensure Selected Track Visible in Both CSI and Reaper - Ensures track visibility synchronization between CSI and Reaper.
  • Surface and Reaper Mixer Scroll Together - Synchronizes scrolling between CSI and Reaper.

💡 Tip: Avoiding Banking Offset Issues with Surface/Reaper Scroll Sync

When using the Surface and Reaper Mixer Scroll Together setting, users may encounter an issue where the surface "hits an imaginary wall" and won’t bank all the way to the last track if the on-screen Reaper mixer is scrolled to the right.

A reliable workaround is to combine the following:

  • Enable both Surface and Reaper Mixer Scroll Together and Ensure Selected Track Visible in Both CSI and Reaper
  • In your Home zone, use both Bank Track and Bank SelectedTrack actions (e.g., for left/right navigation)

This ensures that selected track banking drives visibility and prevents the premature offset limit. The selected track becomes the anchor point for both CSI and Reaper scroll positions.

Assignments

The Assignments section assigns surfaces to Pages and selects which surface folders they will use.

Assignment Buttons

  • Add - Adds a new surface to the selected Page.
  • Edit - Edits the selected surface.
  • Remove - Removes the selected surface.

Surface Assignment

When you add a surface, the window below appears.

CSI Surface Assignment

  • Surface Selector - Dropdown to select available surfaces.
  • Channel Offset - Adjust for multi-surface setups (e.g., MCU + Extender).
  • Surface Folder Selector - Assigns the surface folder to be used within the page.

Advanced Settings (Broadcast and Listen)

The Advanced button configures how multiple surfaces communicate and behave in CSI. Surfaces can be set as "Broadcasters" to send commands or "Listeners" to receive commands.

Advanced Settings Window

CSI Broadcast and Listen

  • Broadcasters - Surfaces sending commands. Add or remove surfaces from the Broadcasters list.
  • Listeners - Surfaces receiving commands. Add or remove surfaces from the Listeners list.

By default, surfaces broadcast at the Page level, and a Broadcaster will not listen to itself unless explicitly set to.

Listen To Checkbox Options

  • SelectedTrackFX - the Listener will respond to the GoZone SelectedTrackFX action.
  • SelectedTrackSends - the Listener will respond to the GoZone SelectedTrackSend action.
  • SelectedTrackReceives - the Listener will respond to the GoZone SelectedTrackReceive action.
  • FXMenu - the Listener will respond to the GoZone SelectedTrackFXMenu and GoFXSlot actions.
  • GoHome - the Listener will respond to GoHome actions from the Broadcaster surface(s).
  • ModSquad - used to create Modifer groups between one or more surfaces

If you wanted two or more surfaces to mirror each other and act as a single unit, you would need to add all surfaces as broadcasters AND listeners, making sure they were all listening to the same checkbox items from the list above.

Monitoring

The Monitoring section helps track MIDI messages, monitor what CSI is receiving/sending, and identify FX Parameter IDs for manual FX mapping. This is particularly useful when creating a custom surface.txt file or troubleshooting control surface behavior.

Available Monitoring Options:

  • Show MIDI Input
    Opens a ReaConsole window to monitor the raw MIDI input for all CSI surfaces. Useful for verifying MIDI messages directly from the control surface.

  • Show Input
    Opens a ReaConsole window to monitor incoming data at the Widget level for any CSI surfaces. This helps confirm that CSI is correctly interpreting input messages.

  • Show Output
    Opens a ReaConsole window to monitor outgoing data at the Widget level for any CSI surfaces. Useful for verifying that CSI is sending expected feedback to the control surface.

  • Write Params to CSI/ZoneRawFXFiles When FX Inserted
    When an FX is inserted in Reaper, CSI will generate a .txt file in the CSI/ZoneRawFXFiles folder, listing all FX parameter IDs and names. This is helpful for manually mapping FX parameters.

    Note: The CSI/ZoneRawFXFiles folder must exist for this feature to work. If the folder does not exist, create it manually.

CSI.ini

The CSI.ini file contains all the Page, Surface, Assignment, and Broadcast/Listen settings for CSI. This file resides within the CSI sub-folder in the Reaper Resource Path. It is generated automatically when CSI is first set up and typically does not require manual editing. However, understanding its structure is useful for troubleshooting.

Below is an example CSI.ini file:

Version=7.0

SurfaceType=MIDI SurfaceName=X_Touch_One SurfaceChannelCount=1 MidiInput=7 MidiOutput=9 MIDISurfaceRefreshRate=15 MaxMIDIMesssagesPerRun=200 
SurfaceType=MIDI SurfaceName=X_Touch SurfaceChannelCount=8 MidiInput=25 MidiOutput=26 MIDISurfaceRefreshRate=15 MaxMIDIMesssagesPerRun=200 
SurfaceType=MIDI SurfaceName=MFTwister SurfaceChannelCount=8 MidiInput=6 MidiOutput=8 MIDISurfaceRefreshRate=15 MaxMIDIMesssagesPerRun=200 
SurfaceType=OSC SurfaceName=MFTwister_iPad SurfaceChannelCount=8 ReceiveOnPort=8008 TransmitToPort=9009 TransmitToIPAddress=192.168.1.168 MaxPacketsPerRun=0 

PageName=Home PageFollowsMCP=Yes SynchPages=No ScrollLink=Yes ScrollSynch=Yes
	Surface=X_Touch_One SurfaceFolder=X_Touch_One ZoneFolder=X_Touch_One FXZoneFolder=X_Touch_One StartChannel=0
	Surface=X_Touch SurfaceFolder=X_Touch ZoneFolder=X_Touch FXZoneFolder=X_Touch StartChannel=0
	Surface=MFTwister SurfaceFolder=FXTwister_MFT ZoneFolder=FXTwister_MFT FXZoneFolder=FXTwister_MFT StartChannel=0
	Surface=MFTwister_iPad SurfaceFolder=FXTwister_iPAD ZoneFolder=FXTwister_MFT FXZoneFolder=FXTwister_MFT StartChannel=0

	Broadcaster=MFTwister
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 

	Broadcaster=MFTwister_iPad
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 

	Broadcaster=X_Touch_One
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=X_Touch_One GoHome=Yes SelectedTrackSends=Yes SelectedTrackReceives=Yes FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=X_Touch GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 

	Broadcaster=X_Touch
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=X_Touch GoHome=Yes SelectedTrackSends=Yes SelectedTrackReceives=Yes FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=X_Touch_One GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No

Key Elements of CSI.ini

  1. Version
    • Specifies the CSI version. CSI will show an error if this is missing.
Version 7.0
  1. Surfaces
    • Each surface configuration includes:
      • SurfaceType (e.g., MIDI or OSC)
      • SurfaceName
      • SurfaceChannelCount
      • MidiInput and MidiOutput (for MIDI surfaces)
      • ReceiveOnPort and TransmitToPort (for OSC surfaces)
      • Additional parameters such as MIDISurfaceRefreshRate and MaxMIDIMesssagesPerRun.
SurfaceType=MIDI SurfaceName=X_Touch_One SurfaceChannelCount=1 MidiInput=7 MidiOutput=9 MIDISurfaceRefreshRate=15 MaxMIDIMesssagesPerRun=200 
SurfaceType=OSC SurfaceName=MFTwister_iPad SurfaceChannelCount=8 ReceiveOnPort=8008 TransmitToPort=9009 TransmitToIPAddress=192.168.1.168 MaxPacketsPerRun=0
  1. Pages
    • Defines how surfaces and zones are grouped.
    • PageName specifies the name of the page.
    • Parameters include:
      • PageFollowsMCP, SynchPages, ScrollLink, ScrollSynch.
      • Specific surfaces are linked to folders for Surface, Zone, and FX Zone definitions.
PageName=Home PageFollowsMCP=Yes SynchPages=No ScrollLink=Yes ScrollSynch=Yes
	Surface=X_Touch_One SurfaceFolder=X_Touch_One ZoneFolder=X_Touch_One FXZoneFolder=X_Touch_One StartChannel=0
	Surface=X_Touch SurfaceFolder=X_Touch ZoneFolder=X_Touch FXZoneFolder=X_Touch StartChannel=0
	Surface=MFTwister SurfaceFolder=FXTwister_MFT ZoneFolder=FXTwister_MFT FXZoneFolder=FXTwister_MFT StartChannel=0
	Surface=MFTwister_iPad SurfaceFolder=FXTwister_iPAD ZoneFolder=FXTwister_MFT FXZoneFolder=FXTwister_MFT StartChannel=0
  1. Broadcasters and Listeners
    • These define communication groups:
      • Each Broadcaster has associated Listener entries.
      • Listeners specify behaviors such as GoHome, SelectedTrackSends, and FXMenu.
	Broadcaster=MFTwister
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 

	Broadcaster=MFTwister_iPad
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 

	Broadcaster=X_Touch_One
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=X_Touch_One GoHome=Yes SelectedTrackSends=Yes SelectedTrackReceives=Yes FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=X_Touch GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 

	Broadcaster=X_Touch
	Listener=MFTwister GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=MFTwister_iPad GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No 
	Listener=X_Touch GoHome=Yes SelectedTrackSends=Yes SelectedTrackReceives=Yes FXMenu=Yes Modifiers=No SelectedTrackFX=Yes 
	Listener=X_Touch_One GoHome=Yes SelectedTrackSends=No SelectedTrackReceives=No FXMenu=No Modifiers=No SelectedTrackFX=No

Notes

  • Modify the CSI.ini only when necessary.
  • Ensure configurations match the connected devices and expected behaviors.
  • Backup the CSI.ini before making changes.
  • You can manually edit the CSI.ini to share a set of Zone or FXZones folders between one or more surface folders. This can be handy when you have an OSC device that mirrors a MIDI device and you'd like to share the Zones and FXZones between them. Note: changing the CSI Surface Assignments will reset these back to default.