I think I may help create some "Getting Started" Tutorials on the Wiki but the best thing to do is look at existing FX .zon files or surface .zon files and kind of work backwards.
Try this...
1. Open Reaper
2. Open the Action list
3. Search for CSI
4. Run the action that says something like "CSI Toggle Dump Raw FX Zone File when FX inserted" or something like that
Now...
5. Insert an FX
6. Go to your Reaper\CSI\Zones\RawFXZones folder
7. You'll see a .txt file for that effect
8. Open it up, you'll see something like this...
Code:
Zone "VST: Omega TWK (Kush Audio)"
SelectedTrackNavigator
FXParam 0 "Intensity"
FXParam 1 "Phase"
FXParam 2 "-20dB"
FXParam 3 "Output"
FXParam 4 "Input"
FXParam 5 "Bypass"
FXParam 6 "Wet"
ZoneEnd
Now, we need to map those FXParams to our hardware.
9. I like using FocusedFXNavigator so the surface takes over the FX when the window is active, so let's change "SelctedTrackNavigator" to "FocusedFXNavigator"
10. Now start mapping widgets to those plugin parameters until you get something like this...
Code:
Zone "VST: Omega TWK (Kush Audio)"
FocusedFXNavigator
RotaryA1 FXParam 0 "Intensity"
RotaryA2 FXParam 4 "Input"
RotaryA3 FXParam 3 "Output"
RotaryA4 FXParam 6 "Wet"
RotaryA5 NoAction
ButtonA1 FXParam 2 "-20dB"
ButtonA2 FXParam 1 "Phase"
ButtonB8 FXParam 5 "Bypass"
ZoneEnd
So see how the syntax uses the Widget name from the .mst file (e.g. "RotaryA1") followed by the CSI action for the FX Parameter (FXParam 0). The name in quotes isn't necessary, but helpful for mapping.
Also, notice I have A5 assigned to NoAction? It's good to make a list of all your widgets and assign a "NoAction" to all of them in each FX.zon file. So my normal file would have a NoAction for each widget that had no action assigned to it in the fx.zon. I just didn't show them all to keep it simple. Many of us use Excel sheets with the widgets listed out to help make the process of FX.zon creation easier.
Just work backwards from those examples and create the .zon files. The plugin name in the zone must much what's shown in Reaper exactly so use the dump from the RawFXZone in CSI and don't change the name (or anything in the top row).
Here's a more complicated example for a surface that uses two displays for Rotaries, a display button names, and encoder acceleration and colors.
Code:
Zone "VST: The Glue (Cytomic)"
FocusedFXNavigator
DisplayUpperA1 FXParamNameDisplay 1 "Threshold" //This is how you add comments to your file
DisplayLowerA1 FXParamValueDisplay 1
RotaryA1 FXParam 1 [ (0.001,0.0015,0.002,0.0025,0.003,0.0035,0.004,0.005,0.0075,0.01,0.025) ]
DisplayButtonA1 FXParamNameDisplay 0 "Power"
ButtonA1 FXParam 0 [ 0.0 1.0 ] { 90 255 0 255 50 0 }
DisplayUpperShiftA1 NoAction
DisplayLowerShiftA1 NoAction
ShiftRotaryA1 NoAction
ZoneEnd
Save this file using this naming convention:
Zone__VST__The_Glue__Cytomic_.zon and put that file in in the zone folder for your surface.
Now, the final step (probably should've mentioned this first) to making all this work, is to tell CSI to setup the Focused FX. You do that in your surface.zon file. Add the line: OnFXFocus MapFocusedFXToWidgets similar to shown here...
Code:
Zone Home
OnFXFocus MapFocusedFXToWidgets
IncludedZones
"PageOne"
"Buttons"
"Channel"
IncludedZonesEnd
ZoneEnd
Note: If you do this with Reaper open, you need to 1) unload the plugin entirely from your session, 2) Go to Reaper's Preferences -> Control/Web/OSC section, 3) Click on CSI, 4) Click Edit, then 5) Ok your way through to save and apply the changes. There's a "parser" in the code that needs to re-read the zone files any time you make a change to one.
Start with an easy one and try to get it working. Post in the main CSI thread if you have questions. Include examples of your .zon by wrapping them in code blocks. So like this...
[bode]
YourZoneFileText...
[/bode]
Except replace the word bode with code.
Last thing, there are other Navigators than FocusedFXNavigator, I just think it's the easiest to wrap your head around.