08 ‐ Troubleshooting - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

Troubleshooting Common CSI Problems

This troubleshooting guide provides solutions to common issues encountered when using the Control Surface Integrator (CSI) with Reaper. Whether you're setting up for the first time or encountering unexpected behavior, the following steps can help resolve your problem efficiently.

Table of Contents

CSI Doesn't Appear in the Dropdown in Reaper's Preferences -> Control/OSC/Web

If you're not seeing CSI in the dropdown when you go to add a surface in Reaper...

  1. Make sure the .dll or .dylib is installed in your Reaper resource path's "UserPlugins" folder
  2. Are you running an older Reaper build? Try updating to the latest version.
  3. Mac Users: the minimum version of MacOS supported is 10.15 (Catalina). Apple Silicon is natively supported.
  4. Windows Users: the Microsoft Visual C++ 2005 runtime is required. You may already have this installed on your system, but if you successfully install CSI and do not see the CSI option in Reaper's control surface preferences you will need to download and install the Microsoft Visual C++ 2005 Redistributable Package.

If none of these apply to your situation and you're still having trouble, please post in the the main CSI thread in the Reaper Control Surface's sub-forum.

I can't find surface files for my MIDI device

First, check the CSI Support Files to check if your device is one of the included files. The CSI support files can be found here.

If your device is not included, does it support MCU? If yes, the MCU or X-Touch support files may work and could be considered good starting points.

If your device is not included in that list, you have two options: 1) post in the CSI Device Setup thread in the Reaper forums and ask if anyone else with the surface has files they can share or 2) read the [Message Generators]] and [[Feedback Processors]] pages and create your own .mst file for your surface. It's a one-time job. Once you've mapped all the controls on your surface, read the [Zones page for information on how to map those controls. Post in the CSI Device Setup thread if you need additional help.

My Device is Set Up in CSI But Isn't Being Recognized

If your control surface is not being recognized by CSI, the first step is to ensure that CSI and your device are communicating correctly. Follow these steps to troubleshoot:

1. Power On/Off Order Matters

To prevent connection issues:

  • Turn on your control surface before starting Reaper.
  • Turn it off only after closing Reaper.

This ensures Reaper and CSI detect the device properly during initialization.

2. Check CSI Input Monitoring

To confirm CSI is receiving data from your control surface:

  1. Open Reaper’s Preferences > Control/OSC/Web, then double-click Control Surface Integrator.
  2. In CSI’s Settings, click the Advanced button.
  3. Enable the following checkboxes:
    • Show Input from Surfaces
    • Show Raw Input from Surfaces
  4. Click OK to save changes.
  5. Move some knobs, faders, or press buttons on your control surface.

3. CSI Input Monitoring Expected Results and What They Mean

Scenario A: No Input is Displayed

If no input appears in the Reaconsole window, CSI is not receiving data from the control surface. This could indicate a connection issue.

  • For MIDI Devices:

    • Ensure everything is plugged in and connected.
    • Verify your device is DISABLED in Reaper’s Preferences → Audio → MIDI Input and MIDI Output.
      • CSI requires direct access to your MIDI ports. If Reaper is using them, CSI cannot access them.
    • Check that no other programs are using the MIDI ports.
      • Another application may be preventing CSI from accessing the control surface.

  • For OSC Devices:

    • Verify that the IP address and Send/Receive ports are set correctly.
    • Go to CSI Settings > Surfaces and confirm that the device's IP Address, CSI Sends To, and CSI Receives On ports match those in your OSC surface.
    • Ensure your OSC surface has the correct Host IP address and matching port configurations.
      • (Remember: the PC Sends To the port the OSC device Receives On and vice versa.)
    • Try different pairs of Send/Receive ports (e.g. 8000/9000, 8001/9001, 8002/9002, etc.). OSC is very picky about ports.

Scenario B: Input is Displayed, But Only as Raw MIDI/OSC Messages

If you see something like this in the Reaconsole window:

IN <- MFTwister b0 00 3f

This means CSI is receiving input, but isn’t mapping it to a widget in the surface.txt file.

  • If you only see raw input messages and no widget names, check the following:
    • Ensure your control surface is in the correct mode.
      • Some devices have multiple MIDI/OSC modes that affect how they send data.
    • Verify that the surface.txt file exists and is properly configured.
    • See the Surface.txt section for details on defining widgets.

Scenario C: Correct Input and Mapped Widget Appear

If you see output like this:

IN <- MFTwister RotaryA1 -0.001000 
IN <- MFTwister b0 00 3f
  • The first line indicates that the surface.txt file is working because the widget name (RotaryA1) appears.
  • The second line is the raw input from the surface.

If the widget name is not appearing, you may need to create or update your surface.txt file.

4. Additional Troubleshooting Steps

If CSI is receiving input but your device still isn’t working properly, try these steps:

  1. Ensure your .zon files are up to date.

    • If you've made changes, run the Refresh All Surfaces action in Reaper.

  2. Verify your csi.ini file.

    • Delete the existing csi.ini file and allow CSI to generate a new one upon restart.

  3. Check MIDI and OSC settings in CSI.

    • Open CSI Settings > Surfaces and verify:
      • For MIDI devices: Ensure the correct MIDI IN and MIDI OUT ports are selected.
      • For OSC devices: Ensure the IP address, Send To, and Received On ports are correctly configured.

  4. Restart Reaper and Your Control Surface.

    • Always power on your control surface before starting Reaper.
    • Power off your control surface only after exiting Reaper.
    • If your device still isn’t recognized, try disconnecting and reconnecting it, then restarting Reaper.
    • You can also try running the Reaper action Refresh All Surfaces.

5. Still Having Issues?

If you're still experiencing problems, post a detailed description of your issue in the Reaper forum's CSI thread. Include:

  • Your control surface model
  • A sample of your csi.ini file and the entire surface folder
  • Screenshots of your CSI Settings > Surfaces
  • Any troubleshooting steps you’ve already tried

This will help others assist you more effectively.

Not All Tracks Showing on the Surface

If some tracks from your Reaper project are not appearing on your control surface, there are several potential causes and solutions:

Potential Cause #1. CSI Visibility Following TCP or MCP

Cause:

  • CSI is set to follow the Track Control Panel (TCP) or Mixer Control Panel (MCP) in Reaper, and the track is hidden in the selected panel.

Solution:

  • Option 1: Change CSI to follow the other panel (TCP or MCP).
  • Option 2: Adjust track visibility settings within Reaper to ensure the desired tracks are visible in the chosen panel.

Potential Cause #2. "Surface and Mixer Scroll Together" Enabled

Cause:

  • This setting is enabled, and the Reaper mixer has reached its scrolling limit, preventing CSI from displaying additional channels on the surface.

Workaround:

  • Enable "Ensure Selected Track Visible in Both CSI and Reaper" in CSI settings.
  • Modify the home.zon file to include SelectedTrackBank actions in your banking buttons to align CSI with Reaper’s track focus.

Potential Cause #3. Track Zones on Multiple Surfaces

Cause:

  • If you have multiple surfaces that use Track Zones, they all count towards the CSI track count. Example: an SSL UF1 configured to use a Track zone combined with a UF8. In that case, the UF1 will get either the first or last track in the bank depending on how it's configured in CSI, which may not be desired.

Solution:

  • If that's not the desired behavior, you could use a SelectedTrack zone for the single-fader surface rather than a Track zone.

Potential Cause #4. "Scroll View When Tracks Activated" Enabled in Reaper

Cause

  • This setting can cause Reaper’s mixer to scroll in unexpected ways, leading to mismatches between Reaper and the surface.

Potential Solution:

  • Disable "Scroll view when tracks activated" in Reaper’s mixer settings:
    1. Open Reaper's Mixer.
    2. Right-click in some empty space
    3. Uncheck "Scroll view when tracks activated".

Disabling this option can ensure better synchronization between Reaper and CSI, allowing all intended tracks to display correctly on your surface.

Scroll View When Tracks Activated

Some of the new CSI features are not working

If you see something in the CSI Changelog page here but it's not working on your system, the first thing to be sure of is: does that feature exist in a "production build" of CSI or does it exist in the Exp (Experimental) builds? The Exp builds contain all of the latest features but should be considered betas.

The Exp builds can be found here.

If you are running an Exp build, and a brand-new feature still isn't working as expected, please post in the main CSI thread in the Reaper Control Surface's sub-forum. You may have found a bug.

I'm Seeing Strange Behavior With Button Feedback (Lights) on My Surface

Check for Conflicting Assignments

One possible cause of erratic button feedback is conflicting assignments within the same Zone.

For example, try to spot the error in the following Zone definition:

Zone "MasterTrackFXMenu"
     OnZoneActivation      SetXTouchDisplayColors Blue
     OnZoneDeactivation    RestoreXTouchDisplayColors

     DisplayUpper|         FXMenuNameDisplay
     DisplayLower|         FXBypassDisplay
     Rotary|               NoAction
     RotaryPush|           GoFXSlot
     Mute|                 ToggleFXBypass
     Left                  Bank MasterTrackFXMenu -1
     Right                 Bank MasterTrackFXMenu 1

     RecordArm|            NoAction        
     Solo|                 NoAction
     Mute|                 NoAction
     Select|               NoAction
     Fader|                NoAction    
ZoneEnd

Here, Mute is first assigned to ToggleFXBypass but is later overwritten with NoAction.

Solution

If you want Mute to control ToggleFXBypass, remove the conflicting Mute| NoAction entry. This will resolve any flickering or otherwise glitchy button feedback behavior.

Feedback=No May Be Required

In some cases, disabling button feedback is necessary to prevent unwanted behavior, such as:

  • Multiple actions assigned to the same button
  • Using Hold modifiers on a button

When feedback is not disabled in these situations, the button light may flicker or fail to update correctly.

How to Disable Feedback on an Action

To disable feedback for a specific action, add Feedback=No at the end of the assignment.

As a general rule of thumb, feedback should typically be disabled for Hold-modified actions as shown in the below example:

    Stop                        Stop
    Hold+Stop                   Reaper 40042 Feedback=No    // Go to start of project

And if you're chaining multiple actions in CSI, and want only one action to dictate the feedback behavior of a button, that would look like this:

    SomeButton SomeAction
    SomeButton AnotherAction Feedback=No
    SomeButton YetAnotherAction Feedback=No

For more details, see the Widget Properties>Feedback page.

I Made a Change to My Zones But CSI Isn't Reflecting That

If you've updated your .zon files but aren't seeing the changes reflected in CSI, follow these troubleshooting steps:

  1. Run Refresh All Surfaces in Reaper

    • After making any changes to your .zon files while Reaper is open, you must execute the Refresh All Surfaces action in Reaper.

  2. Ensure the .zon File is Saved

    • Verify that you’ve actually saved the .zon file before testing changes.

  3. Check for Multiple Versions of the .zon File

    • If you have multiple versions of the same zone file in different folders, make sure you’re editing and saving the correct one.

CSI Crashes

While crashes are rare and should not happen, they can sometimes occur due to issues with the csi.ini file, particularly if the folder names in csi.ini do not match the surface names in the primary CSI folder.

Potential Causes of Crashes

  1. Mismatched Folder Names

    • Example: You originally set up your csi.ini to reference an X_Touch folder but later manually renamed that folder to X_Touch_Alternate. If csi.ini still points to X_Touch, CSI may crash.

  2. Errors in csi.ini Configuration

    • Corrupt or incorrectly formatted entries in csi.ini can lead to unexpected behavior or crashes.

  3. Incorrect Zone Syntax

    • Syntax errors in .zon files, such as missing brackets or improper formatting, may cause issues with CSI initialization.

How to Resolve Crashes

  1. Recreate csi.ini from Scratch

    • The best first step is to delete your existing csi.ini and let CSI generate a fresh version when restarted.

  2. Verify Folder Structure

    • Double-check that all referenced surface folders in csi.ini exist and are named correctly.

  3. Review Zone Syntax

    • Open your .zon files and confirm there are no missing or misformatted entries.

  4. Still Having Issues?

    • If you've gone through these steps and still experience crashes, post a detailed description of your issue in the main CSI thread.
    • Include your csi.ini file, your folder structure, and any recent changes you made.

This will help the community assist you more effectively.

My iPad/iPhone/Tablet is Dropping OSC Messages (i.e. Labels Can Linger on Displays)

CSI communicates with OSC devices using the User Datagram Protocol (UDP). The advantage of UDP is its extremely low latency, making it ideal for real-time control. However, unlike Transmission Control Protocol (TCP), UDP does not include built-in error checking or message confirmation. This means that if a message is lost in transmission, there is no automatic retry, which can result in OSC display labels lingering or failing to clear properly.

This issue is most commonly observed when using Wi-Fi-connected OSC devices, such as an iPad running an OSC app.

Recommendation: Use a Wired Ethernet Connection

A wired Ethernet adapter can significantly reduce lost OSC packets, improving overall reliability. Since Wi-Fi networks are subject to interference and packet loss, switching to a wired connection ensures a stable and consistent data flow between CSI and your OSC device.

Report a Potential Bug

If you think you've found a bug or are experiencing unexpected behavior, follow these steps to report the issue:

  1. Visit the CSI thread in the Reaper Forums under the MIDI Hardware, Control Surfaces and OSC subforum.
  2. Post the details of your issue, including:
    • A clear description of the problem.
    • A step-by-step list of how to reproduce the issue.
    • Expected vs. actual results to clarify the discrepancy.
  3. If possible, attach your surface folder (zip it up and upload it).
  4. If the issue relates to a specific zone, you can also post a copy of your .zon file in the forum using the following code format:
[code]
Your sample zone.
[/code]

How to File a Great Bug Report

When reporting a bug, following a structured format makes it much easier to diagnose and resolve the issue. Use this template for best results:

Issue:
Provide a short headline that summarizes the issue.

Steps to Reproduce:

  1. List each step required to trigger the bug.
  2. Ensure the instructions are clear and reproducible.
  3. This helps others confirm the issue and determine its cause.

Expected Result:
Describe what should happen if the system is working correctly.

Actual Result:
Describe what is happening instead.

Additional Debugging Info:

  • If applicable, include screenshots or videos demonstrating the issue.
  • Attach your CSI surface folder, relevant .zon files, or a copy of your csi.ini if the issue appears related to configuration.
  • If you suspect a crash or instability, check your Reaper crash logs and include relevant details.

Providing a clear, detailed report greatly improves the chances of getting the issue resolved quickly.

Other Troubleshooting Tips

Some additional troubleshooting tips...

  • Unplug it, then plug it back in: seriously. Units freeze up and/or misbehave. If you can't get your device working and are scratching your head, don't forget about this basic first step of troubleshooting. Even if the surface otherwise seems like it's working, there's no harm in taking 30 seconds to try this step and may just solve your problem! And if not, you've ruled out one more thing.

  • Simplify: if you have a problem where a feature in a .zon is not working as expected, try eliminating everything else, and see if the feature or .zon file works by itself. If yes, then start slowly adding things back until it stops working. That should help narrow down where the problem is.

  • Start from scratch with a portable install. Reaper has a "Portable Installation" option that allows you to install Reaper into another folder. You can try setting up CSI from scratch with a portable install to see if that solves your problem. If yes, the issue could be in your User Plugins folder, or with some Reaper setting.

  • Check for old .zon files or .dll's - clear them out! Maybe you've got an old version of CSI in your User Plugins folder called "reaper_csurf_integrator64.dll.bak" causing a conflict that Reaper is still picking up. Or a "buttons.zon.old" file. Clear that stuff out! When it comes to .zon files, CSI scans all .zon files within your Zone folder on launch.

  • Maybe it's just me? If a particular feature or something isn't working for you, but you know it's working on other people's setups, then trust that as long as you meet the minimum system requirements, it's not you. There's something amiss somewhere in your CSI setup. Check for multiple versions of zon files, confirm you've got the correct installation paths, make sure you are using the correct version of the .mst, proper .zon syntax, ensure you don't have old versions of CSI or unused .zon files littered about. If you still need help, post in the CSI Device Setup thread. It may all look right on the surface, but chances are there's some small quirk out there that's causing issues. It may just take some help and persistence to find the cause. Could be a bug too :) !

Something I saw on this wiki isn't accurate or isn't working

If you've ruled everything else out and something still isn't working, post in the main CSI thread to report the issue. It could be as simple as the wiki not being up to date or it could be a bug.