The first three sections below describe the software UI and engine modes. The rest of this document describes features of the software that are tied to the XML data files (which are semi-documented here). (Yes, I need to work out a better way to document this stuff.)

Main Display Window displays text that is dependent upon the active mode and the function of the switch pressed
Trace Window displays diagnostic messages
Switch Labels display patch names or button descriptions
Switch Indicators show whether a patch is active or inactive (which is patch mode dependent)
Switch Buttons are used in addition to or in place of dedicated hardware switches. Underlined letters in button text show what keyboard letters can be used to activate the button. Pressing a letter causes a button down in addition to a button release. For best results with momentary patches, place focus on the button and use the spacebar (button release does not happen until the spacebar is released).

The app supports up to a total of 64 switches split between preset switches and up to three operating switches. The function of each operating switch is dependent upon the control mode that is active.

Bank mode (default)
Preset switches activate patches
Next and Previous display the next or previous bank and changes to Bank Navigation mode
Mode switch label displays the active bank number and name
Mode switch changes to Mode Select mode
Main Display Window displays patch name and number when a preset switch is pressed

Bank Navigation mode
Any preset switch will load the currently displayed bank (commits the bank) and changes mode back to the default
Next and Previous increment and decrement the displayed bank
Mode switch escapes back to the default mode (with the bank that was previously active)
Main Display Window displays bank information when the displayed bank changes

Bank Description mode
Preset switches display patch state information in the main display window
Next and Previous increment and decrement the displayed bank
Mode switch escapes back to the default mode (with the bank that was previously active)

Bank Direct mode
First 10 preset switches allow a bank number to be typed in
Next switch functions as commit/enter: loads the bank number entered and switches the mode back to the default
Previous switch functions as backspace
Mode switch escapes back to the default mode (with the bank that was previously active)
Main Display Window displays bank number (and name if applicable) of number typed

Mode Select mode
Preset switches select one of the previously described modes
Next and Previous have no function
Mode switch escapes back to the default mode (with the bank that was previously active)
Main Display Window displays mode name

Raw ADC Value mode
Preset switches select ADC port to track
Next and Previous have no function
Mode switch escapes back to the default mode (with the bank that was previously active)
Main Display Window displays ADC value of selected port

The application is not an editor (it only reads the XML files, does not generate them). Version 2.5.1 of Raymond, the PMC10 editor, can be used to generate config.xml files using the Export to XML command.

The current version loads a pair of files, testdata.config.xml (the patches and banks) and testdata.ui.xml (the GUI definitions) automatically at startup (it looks in the startup directory). Press Ctrl+O to load a different set (the last opened set of files is remembered across restarts).

Press F5 to reload the both the UI and config files.
Press Ctrl+T to toggle the visibility of the trace window and resize the main display.
Press Ctrl+R to re-establish communication with the monome board.

Patches can be defined to be Toggle, Momentary, Normal or Sequence. Except for Sequence-mode patches, patches can have commands that are assigned to one of two groups: "A" and "B". Toggle patches operate by sending the group A commands on one press of a switch, and sending the group B commands on a second press of the switch. Momentary patches operate by sending the group A commands on the press of the switch, and sending the group B commands on the release of the switch. Normal patches operate by sending the group A commands on the press of the switch and sending the group B commands when another Normal patch is activated. Pressing the switch for a Normal patch two times in a row results in the group A commands being exectuted, followed by the group B commands and then the group A commands again.

Sequence patches execute a command for each press of a switch.

Calibrating the expression pedal ports is basically a manual task. Use the Raw ADC Value engine mode to display the range of values that your pedal produces. Do full sweeps on the selected pedal while watching the main display. Note the minimum and maximum values that are displayed (make sure to release foot from pedal since you want to see the minimum and maximum values that occur without requiring your foot to always be on the pedal).

In your .config.xml file, record the noted values in the minimumAdcVal and maximumAdcVal attributes of the adc record for the port (specified by the inputNumber attribute) on which you did the full sweeps. You may want to give youself a cushion and record a slightly higher number than the minimum for the minimum; and a slightly lower number than the maximum for the maximum.

Disable any ADC port that is not in use by setting the enable attribute to "0".

The selected ADC port must be enabled for the Raw ADC Value mode to be of value. If a port is not enabled, the main display window will not display values after that port has been selected.

For best results, flash the board with this modified monome firmware (AVR-JTAG programmer required).
[The original adc smoothing/filtering is based on the averaging of 16 reads. Even with the 16 buckets I still had to do some filtering in the app. The modification reduces the number of buckets in the firmware to 4. The firmware does smoothing (based on averaging the contents of the buckets) while the app does jitter filtering (based on hard compares to the last 3 values received). It's a night and day difference in response when doing fast full-off to full-on pedal swings (wah-wah style). Above a certain pedal speed, the 16 buckets meant that the extremes disappeared - the extremes were averaged away. No more.]

Here is an annotated example of the complete expression block.

The opening tag. Here, port refers to the MIDI out port that the expression pedals will transmit to.

<expression port="1">

Next are the adc nodes where the four monome adcs are enabled and where the pedals attached to each adc port are calibrated (each port is calibrated independently).

	<adc inputNumber="1" enable="0" minimumAdcVal="10" maximumAdcVal="1015" />
	<adc inputNumber="2" enable="0" minimumAdcVal="10" maximumAdcVal="1015" />
	<adc inputNumber="3" enable="0" minimumAdcVal="10" maximumAdcVal="1015" />
	<adc inputNumber="4" enable="0" minimumAdcVal="10" maximumAdcVal="1015" />

Next are the global MIDI assignments for each pedal (inputNumber 1 - 4). Each pedal can have up to two global assignments (assignmentNumber 1 - 2). Use two volume assignments where one is inverted to do a cross-fade. The maximum value for the max attribute is 127 for standard single byte controllers and 16383 for double byte controllers (only available for controller numbers 0 - 31 when the doubleByte="1" attribute is specified). When doubleByte="1", the MSB controller value is sent on the controller specifed and the LSB value is sent on controller + 32. The minimum value for the min attribute is 0.

	<globalExpr inputNumber="1" assignmentNumber="1" channel="7" controller="2" 
		min="0" max="127" invert="0" enable="1" />
	<globalExpr inputNumber="1" assignmentNumber="2" channel="8" controller="2" 
		min="0" max="127" invert="1" enable="1" />
	<globalExpr inputNumber="2" assignmentNumber="1" channel="4" controller="2" 
		min="0" max="127" invert="0" enable="1" />
	<globalExpr inputNumber="2" assignmentNumber="2" channel="5" controller="2" 
		min="0" max="127" invert="1" enable="1" />
	<globalExpr inputNumber="3" assignmentNumber="1" channel="11" controller="110" 
		min="0" max="127" invert="0" enable="1" />
	<globalExpr inputNumber="3" assignmentNumber="2" channel="12" controller="110" 
		min="0" max="127" invert="1" enable="1" />
	<globalExpr inputNumber="4" assignmentNumber="1" channel="12" controller="31" 
		min="0" max="16383" invert="0" enable="1" doubleByte="1" />

And finally, the section closing tag.

</expression>

Instant access switches are a common feature on sophisticated foot controllers. While it is possible to emulate them by hardcoding patch assignments in every bank that you define, that can be tedious, prone to error and a pain to maintain. But there is an an alternative.

Bank number 0 is a special bank that can be used to define default patch maps. When you add a mapping to a switch in bank 0, that mapping will be used in every other bank that does not already have a mapping for the switch. The instant access switches are only defined in one bank but are available in all banks. These default mappings are easily overridden in a bank by making a mapping for the same switch in the bank. This way you can have default behavior in all or only some of your banks.

Patches are composed of one or more commands (in one or two groups "A" or "B").

The midiByteString command is used to specify, in hex, a single, or multiple, MIDI commands to send.

The ProgramChange, ControlChange, NoteOn and NoteOff commands are simpler to use than midiByteStrings for those MIDI messages.

The RefirePedal command can be used to resend the current value of an expression pedal. This is useful if you have left an expression pedal at some random value and want to use a patch to toggle between a pre-determined value and that random value.

A meta-patch is a patch that affects the control engine state itself rather than affecting an external MIDI device. Like regular patches, meta-patches are defined in the patches list using the engineMetaPatch tag.

The ResetBankPatches meta-patch resets all of the patches in a bank that are currently considered active (without sending any MIDI data out the MIDI port) and clears the switch LEDs (turns off any lit LEDs). This is useful for clearing patches like toggle or sequence mode patches, but would not have any effect on momentary mode patches.

ResetBankPatches example:
<engineMetaPatch name="Reset bank (meta)" number="50" action="ResetBankPatches" />

The LoadBank meta-patch is a patch that can be assigned to any switch in a bank that causes the controller to load another bank. This could be used to create a sequence of banks and provides for immediate one switch access to any bank from any bank.

LoadBank example:
<engineMetaPatch name="Load bank 1 (meta)" number="51" action="LoadBank" bankNumber="1" />

The Backward and Forward meta-patches are patches that can be assigned to any switch in a bank that operate like the history function of a web browser. They are unlike Next and Previous in that they remember the order of banks that you have actually loaded. The Backward and Forward meta-patches operate instantly (no confirmation switch press is required).

Backward and Forward examples:
<engineMetaPatch name="Last Bank Visited" number="52" action="BankHistoryBackward" />
<engineMetaPatch name="Forward" number="53" action="BankHistoryForward" />

The Recall meta-patch is a patch that can be assigned to any switch in a bank that causes the controller to switch back and forth between the currently loaded bank and the previously loaded one; it is similar to 'channel recall' on TV remote controls. It can be invoked repeatedly to switch back and forth between two banks (map it to the same switch in multiple banks). (This is basically an automatic application of Backward and Forward.)

Recall example:
<engineMetaPatch name="Bank Recall" number="54" action="BankHistoryRecall" />

An ExclusiveSwitchGroup is a list of switches (defined per bank) in which only one switch is allowed to be active (analogous to radio buttons since only one radio station can be selected at a time). When you press a new switch in an exclusive group, the previously selected patch in the group is released. The group does not need to be contiguous; a group could be composed of a column, a row, a block, every other switch, etc. It makes most sense with groups of toggle patches.

ExclusiveSwitchGroup example (defined in a bank along with its PatchMaps):
<ExclusiveSwitchGroup>2 7 12</ExclusiveSwitchGroup>