Control Mate Guide

ControllerMate :: Editor Window

ControllerMate Windows — Editor

When using ControllerMate, most work is done using the Editor window:

The Editor window is divided into three areas. The upper-left portion of the windowcontains the three buttons used to select the current topic of the Editor window:Programming, Controller Types, or Virtual Controllers.

Below the three buttons is a Directory panel which displays the contents of the currenttopic. When the “Programming” topic is selected, this panel will show the currentcontroller configurations and hierarchy of Groups and Pages. When the “ControllerTypes” topic is selected, the controller type entries will be shown. When the “VirtualControllers” topic is selected, the current virtual mouse, tablet, and joystick controllerswill be shown.

The right portion of the Editor window contains the workspace. This area shows thedetails of the item which is selected in the Directory panel.

Between the Topic Buttons and the Directory panel is the Master Enable button. Whenthe Master Enable is turned off, ControllerMate has no function — the internalkeyboard and mouse will be reset, and any virtual devices will be disconnected.Turning the Master Enable back on will reconnect any existing virtual devices.

ControllerMate :: Controller Configurations

Controller Configurations

Controller Configurations are used to change the default behavior of keyboard andmouse devices. They can be used to:

Make keyboard keys behave like other keyboard keysMake mouse buttons behave like other mouse buttonsAssign a custom acceleration curve to a mouseDisable the cursor and/or scroll wheel axes on a mouse

Controller Configurations can be created only for devices that do not usemanufacturer-supplied drivers. The behavior of devices that use custom drivers willbe determined by those drivers. Devices that can be customized with a ControllerConfiguration will be designated by a in the lower-left corner of the device’s icon inthe Palette window.

To create a Controller Configuration, drag a device from the Palette window to theDirectory panel of the Editor window. Controller Configurations may be enabled ordisabled by turning on or off the checkbox next to the configuration’s name in theDirectory panel.

If desired, multiple configurations can be created for each controller. If more than oneController Configuration for a particular device is enabled at any given time, then thesettings of the two configurations will be combined as much as possible. If the settingsin multiple configurations for the same device conflict, the settings of the configurationlower in the Directory panel will override those higher in the list.

ControllerMate :: Building Blocks

Building Block Basics

Building blocks are the basic unit of programming in ControllerMate. Each type ofbuilding block performs a small function. Any number of building blocks can beconnected together to form complex actions.

Every building block has common features. Each block which can accept a value fromanother building block has one or more inputs (a block may have no inputs). Eachblock which can send a value to another building block has one output (a block mayhave no output).

In the image above, the block on theleft has an input which accepts anON/OFF value. The block on the righthas an input which accepts a numbervalue. Note the difference in shape

between the two types of inputs.

Also in the image above, the block on the left has an ON/OFF output value. The blockon the right has a number output value. ON/OFF outputs are always green, numberoutputs are always blue. Each type of output has a shape that is similar to the type ofinput that it attaches to.

Building blocks may be connected together either by positioning them such that anoutput overlaps an input, or by dragging an output value to an empty input.

When the value of a building blockchanges, it sends that new value toto any blocks attached to its output.Those blocks may perform somefunction, perform a calculation, or

combine the new value with other values to determine their own values. If theirvalues change, they will pass the new value on to any blocks that are attached to theiroutputs.

The output of a building block may be attached to multiple other building blocks

simply by dragging the output to an unconnected input.

The following is an example of a verybasic use of building blocks:

The top blockrepresentsButton #7 on a

CH Pro Throttle USB joystick. The bottom block simulates typing usingControllerMate’s internal keyboard. When Button #7 is pressed on the joystick, thevalue of the top block will change from “OFF” to “ON”. When the top block turns ON,it will cause the bottom block to turn ON. Turning on the bottom block will cause it totype “Hello” using ControllerMate’s internal keyboard. Therefore, each time thisparticular joystick button is pressed, “Hello” will appear just as though it had beentyped on a keyboard.

The following is an example of a slightly more complex use of building blocks:

In addition to typing “Hello” as in the previous example, thisexample will play the current system alert sound. Byconnecting several building blocks together, you can addcomplex functions to your HID controllers.

Building blocks are arranged on Pages. To create building blocks, first select a Page (orcreate a new Page). Then, in the Palette window locate the particular type of buildingblock that you want to create. Drag the icon of the building block that you want tocreate from the Palette window to the workspace in the Editor window.

To customize a building block, select the block and adjust the settings in the Inspectorwindow. Each type of building block has its own settings.

Explore the various types of building blocks that are available and the examples tofind out what types of functions you can build.

4/29/11 6:13 PMControllerMate Example :: A Detailed Tutorial

Page 1 of 18http://www.orderedbytes.com/controllermate/help/?show=tutorial

Home News ControllerMate Support Forum HomeIntroduction

New FeaturesScreenshots

ProgrammingHelp / Examples

CompatibilityDownload / Purchase

ControllerMate Basics

A Detailed TutorialProgramming Examples

WindowsPages & Groups

Building Block GuideVirtual Controllers

Controller ConfigurationsController Types

Apple’s Keyboard Viewer

A Detailed Tutorial

This tutorial walks you through all of the steps necessary to create basic ControllerMate programming. It assumes that you arestarting up ControllerMate for the first time and are not familiar with the interface. After you have completed this tutorial, you

should be familiar with the basic concept that ControllerMate uses to program controllers. You can then explore the helppages further to learn more details about ControllerMate’s capabilities.

The Commands

For this tutorial, keyboard functions that may typically be found in first-person shooter games will be assigned to the controlson a gamepad. These functions are general examples and not from a particular application. The following are the commands

to be programmed:

Key FunctionW — Move ForwardA — Move LeftD — Move RightS — Move BackwardQ — Lean LeftE — Lean RightKeypad 8— Look ForwardKeypad 4— Look LeftKeypad 6— Look RightKeypad 2— Look Backward

The Controller



This tutorial uses the Logitech RumblePad 2 USB to perform the functions described above. The RumblePad has four buttonsunder the right thumb (Button #1-4), one button on the right-front (Button #6), and a hatswitch under the left thumb that willbe used. Buttons #1-4 will be used for the movement and leaning and the hatswitch will be used for looking. Button #6 will

be a modifier called “Alpha”. It will be used in combination with Buttons #1 and #3 to alter their behavior.

Key Function ControllerW — Move Forward — Button #4A — Move Left — Button #1D — Move Right — Button #3S — Move Backward— Button #2Q — Lean Left — Alpha + Button #1E — Lean Right — Alpha + Button #3Keypad 8— Look Forward — Hatswitch (up)Keypad 4— Look Left — Hatswitch (left)Keypad 6— Look Right — Hatswitch (right)Keypad 2— Look Backward — Hatswitch (down)

Shift — Button #6

Buttons #1 and #3 will each have two functions: a “normal” function and an “Alpha” function.

If you are using a different controller to follow through this tutorial step-by-step, then it will work out best if you use acontroller that has at least five buttons and one hatswitch.

The Preparation

Building blocks are placed onto pages. The first step in this tutorial is to create a new, blank page. In ControllerMate’s Editorwindow, select “Programming” in the upper-left corner then click on the button with the icon in the lower-left. A new,

blank page “New Page 1” should appear as in the image below.



In the Inspector window, change the name of the new page to “Lean / Move”. If the Inspector window is not open, Select“Show Inspector” from the Windows > Properties Inspector menu, or use Command-I to open the Inspector window.

In the same manner, create another new page and give it the name “View”.

The “Alpha” Modifier



To create a button with two functions, we will create a modifier called “Alpha” and connect it to Button #6. The state of thismodifier (ON or OFF) will then be combined with Buttons #1 and #3 to indicate which function these buttons should perform.

First, we locate the Logitech RumblePad 2 USB in the Palette window. If the Palette window is not open, Select “ShowPalette” from the Windows > Palette menu, or use Command-E to open the Palette window.

Clicking on the RumblePad in the Palette window will cause the Palette window to show a list of controls on the RumblePad.

Pressing Button #6 on the RumblePad will cause the Palette window to automatically scroll Button #6 into view.

In the Editor window, select the “Lean / Move” page by clicking on its name in the panel in the left side of the window.



Create a Button building block which represents Button #6 by dragging it from the Palette window to the workspace portionof the Editor window.

Next, we will create a Modifier building block which represents the “Alpha” modifier. Select “Extras” from the popup menuat the top of the Palette window. The “Modifier” building block is in the middle of the list of “Extra” building blocks.

Create a Modifier building block by dragging it from the Palette window to the Editor window and drop it immediately belowthe Button building block. When dragging the new modifier, the outline will “snap” into place when it gets close to the Button

building block.



With the Modifier building block still selected, change the “Name” parameter in the Inspector window to “Alpha”.

Now, the Alpha modifier is complete. When Button #6 is pressed on the RumblePad, the modifier will be turned ON. WhenButton #6 is not pressed, the modifier will be OFF. In the next section, we will use this modifier to alter the behavior of

Button building blocks.

The “Lean” Buttons



The “Lean Left” and “Lean Right” functions will be assigned to Buttons #1 and #3 respectively. In the same manner that abuilding block was created for Button #6 above, create building blocks for Buttons #1 and #3 by dragging them from the

Palette window to the Editor window.

Since the “Lean Left” and “Lean Right” functions are each performed with one keyboard key (“Q” and “E” respectively), wewill use the Single Key building block to simulate these keys. Select “Outputs” from the popup menu in the Palette window.

The “Single Key” building block is the second item in the list of “Output” building blocks. Drag two Single Key buildingblocks to the workspace portion of the Editor window, drop one below each of the two new Button building blocks.



Select the Single Key building block that is attached to the Button #1 building block. In the Inspector window, click on the“Keystrokes Palette” button. Drag the “Q” key from the Keystrokes Palette window to the image well in the Inspector

window.



Select the Single Key building block that is attached to the Button #3 building block. Drag the “E” key from the KeystrokesPalette window to the image well in the Inspector window.

At this point, if Button #1 is pressed on the RumblePad, the letter “q” will appear in the Output window just as though the Qkey had been pressed on the keyboard. If Button #1 is pressed and held, then several “q” letters will appear in the Outputwindow until the button is released — just as though the Q key had been pressed and held on the keyboard. The same will

happen with the letter “e” if Button #3 is pressed on the RumblePad.

The last step for the lean functions is to combine Buttons #1 and #3 with the “Alpha” modifier. Select the building block forButton #1. In the Inspector window, change the popup menu next to “Alpha” to “ON”. After this change is made, this Buttonblock for Button #1 will not turn ON unless both the RumblePad’s Button #1 is pressed and the Alpha modifier is turned ON.



Make the same change for the Button #3 building block.

After the Button building blocks’ modifier settings are changed, notice that the indicator on the left end of the building blockchanged from black to red.

A red indicator indicates that the building block cannot turn ON because the modifiers for that building block do not have thecorrect value. A green indicator indcates that the building block can turn ON (if its button is pressed) because the modifiers

for that building block do have the correct value. A black indicator simply indicates that there are no definite modifierrequirements for the building block. When Button #6 on the RumblePad is pressed, the indicators for the Button building

blocks change from red to green to indicate that they each now can turn ON because the Alpha modifier has the correct value.



At this point, if Button #1 is pressed on the RumblePad, nothing will appear in the Output window. If Buttons #6 and #1 arepressed at the same time, then the letter “q” will appear in the Output window. The same is true for Button #3 and the “e” key.

Now, the “Lean” functions are complete.

The “Move” Buttons

The “Move” functions will be assigned to Buttons #1 - #4 on the RumblePad. In the same manner that was done for the“Lean” functions above, create building blocks for Buttons #1 - #4. Next, create a Single Key building block below each ofthe Button building blocks. Then, configure each Single Key building block with the keyboard key that corresponds to its

function.



The “Move Left” and “Move Right” buttons need to be setup so that they do not perform their function when the “Lean”functions on those buttons are being used. Therefore, select building block for Button #1. In the Inspector window, change the

popup menu next to “Alpha” to “OFF”. After this change is made, this Button block for Button #1 will not turn ON unlessboth the RumblePad’s Button #1 is pressed and the Alpha modifier is turned OFF.

Make the same change for the Button #3 building block.

After the building blocks’ modifier settings are changed, notice that the indicator on the left end of the building blocks



changed from black to green. As described above, this indicates that these building blocks can turn ON when the Alphamodifier is OFF. When the Alpha modifier turns ON, the indicators on these building blocks will change to red and these

blocks will not be able to turn ON.

Now the “Move” functions are complete.

The “View” Hatswitch

The “View” functions will be assigned to the hatswitch on the RumblePad. Select the “View” page in the Editor window anddrag two RumblePad Hatswitch building blocks from the Palette window to the View page.



By moving the hatswtich around and observing the values that are shown on the building blocks, we find that the hatswitchuses the following values:

Hatswitches on other devices may use different values. It is not uncommon to find a hatswitch that uses “0” as its center valueand 1-8 to indicate various directions.

To simulate the keypad keys, Single Key building blocks will be used in the same manner that they were used for the Leanand Move functions. Single Key building blocks cannot be directly connected to Hatswitch blocks — Single Key blocks

require an ON/OFF value but the Hatswtich provides a Number value. The Value Selector building block is used to convertthe Number value to an ON/OFF value.

In the Inspector window, select “Calculations” from the popup menu. The “Value Selector” building block is toward thebottom of the list of “Calculations” building blocks. Drag four Value Selector building blocks to the workspace portion of the

Editor window, drop two below each of the two Hatswitch building blocks.



Connect the Value Selector building blocks to the Hatswitch building blocks by dragging the output value from eachHatswitch to each of the two Value Selector blocks below it.

When all four are connected, the Editor window should appear as below.



Next, the four Value Selector blocks need to be configured. One will be configured for each of the four view directions:forward, left, right, and backward. We will configure to top-left Value Selector to look forward. From the experiment earlier,

we found that the hatswitch has a value of “0” when pushed up. We also want to take advantage of the hatswitch’s cornervalues, so we will also use “7” and “1” to look forward.

Select the top-left Value Selector. In the Inspector window, check the boxes next to “0”, “1”, and “7”.



Now, when the hatswitch is pushed up, the top-left Value Selector will turn ON.

Next, we setup the remaining three Value Selectors with the values for each of the other three hatswitch directions. Notice thatthe hatswitch corner values each appear in two different Value Selector blocks.



Finally, using the same procedure that was used for the Lean and Move functions above, add a Single Key block to each ofthe Value Selector blocks. Configure the Single Key blocks for the forward/left/right/backward view keypad keys.

Now, when the hatswitch is pushed in a particular direction, the corresponding keypad number will appear in the Outputwindow. When using the corner hatswitch positions, the corresponding number may or may not appear in the Output window.This is a limitation of the simple text box in the Output window. To get a more accurate look at the keys that ControllerMate

is simulating, open Apple’s Keyboard Viewer to see exactly which keys are being pressed.

Download This Example • About Downloaded ExamplesCopyright © 2005 — 2011 OrderedBytes

All rights reserved.

OrderedBytes :: ControllerMate Programming

Building blocks and controller configurations allow you to customize the behavior ofyour devices in an endless variety of ways.

Introduction to building blocks

ControllerMate’s building blocks represent controls on devicesand the actions that those controls can perform. There are building blocks thatsimulate keyboard actions, simulate mouse actions, run AppleScripts, perform logic,perform calculations, perform timing actions, and others. After each building blockperforms its particular action, it may create a value which can be used to trigger otherblocks. By linking together several building blocks of different types, complexsequences of actions can be constructed.

Source building blocks

Source building blocks represent controls on devices. Mostsource blocks represent individual controls, Button Group

building blocks represent an arbitrary set of buttons. A building block whichrepresents a button (or set of buttons) creates an ON/OFF value depending upon thecurrent state of the button(s). Building blocks which represent axes, sliders, dials,hatswitches, etc. create a Number value which indicates the position or movement ofthe control.

Output building blocks

Output building blocks simulate keyboard or mouse actions.These are the building blocks which generate events that can

be used by other applications while ControllerMate is in the background. Most outputbuilding blocks can be configured to perform different actions when they are turnedon and when they are turned off.

AppleScript building blocks

AppleScript building blocks run AppleScripts. Some AppleScript blocks use the valuethat is created by the AppleScript to pass to other building blocks.

Logic building blocks

Logic building blocks combine ON/OFF values in variousways. Standard combinational logic functions such as AND,

OR, NOT, and XOR are available. Other building blocks perform higher-level logicfunctions such as toggles and latches.

Math building blocks

Math building blocks combine or generate Number values.Some math building blocks convert ON/OFF values into

Number values; some convert Number values into ON/OFF values; and othersmodify Number values into other Number values.

Timing building blocks

Timing building blocks create time delays or perform an actionbased on the time between events. The Delay, Dwell, and

Pulse blocks are used to insert time delays in different circumstances. The Auto-Repeater block creates automatically repeating events. The Pulse Count block is usedto detect events such as double-clicks and triple-clicks.

Organizing building blocks on Pages

When building blocks are created, they are placed on pages. A page cancontain any number of building blocks and can either beenabled or

disabled. When a page is disabled, none of its building blocks are active. In order tokeep things organized, it is sometimes helpful to divide the building blocks amongdifferent pages. By doing this, at any given time certain groups of building blocks maybe active while others are inactive.

Organizing Pages in Groups

In addition to organizing building blocks into different pages, pages maybe split up into different groups. A group may contain pages or other

groups and may be enabled or disabled. When a group is disabled, none of thebuilding blocks on its pages are active. A group may also be given certain applicationrequirements. A group can be configured such that it is active only when certainapplications are running, or if certain applications are not running.

Controller configurations

Controller configurations allow you to change the default behavior ofcontrols on keyboard and mouse devices. Keyboard keys can be configured

to behave like keys, mouse buttons can be configured to act like different mousebuttons, and mouse devices can be given custom acceleration curves. Controllerconfigurations can be individually enabled or disabled. When a controllerconfiguration is disabled, it has no effect on the operation of the device. Multiplecontroller configurations can be created for the same device. By enabling and disablingcontroller configurations, the operation of a device can be completely changed veryquickly.

ControllerMate :: Pages & Groups

Pages & Groups

Pages and Groups are used for organizing building blocks. When the “Programming”button is selected in the Editor window, the Directory panel will show the currentcollection of groups and pages. When a group or page is selected, the Editor window’sworkspace will display the contents of the selected item.

Pages

Pages are the primary means for organizing building blocks. A single page maycontain any number of buidling blocks. However, if the number of building blocksgrows large, it may be more convenient to distribute them among different pages.

A Page is created by clicking the button below the Directory panel in the Editorwindow.

To change the name of a page, select that page thenedit its name in the Inspector window.

There are two ways to change the enabled/disabledstate of a page. If the page is selected, its enabled statewill be shown with a checkbox in the Inspectorwindow. A page may also be enabled or disabled bychanging the checkbox next to its name in theDirectory panel in the Editor window. When a Page isdisabled, none of its building blocks will producekeyboard output or affect the cursor.

Some building blocks have an initial value or a defaultvalue. To reset these building blocks back to theirinitial values, select the page and use the “Reset

Contents Now” button in the Inspector window. The page may also be configured toautomatically reset its building blocks just before it is enabled, just before it isdisabled, or both.

When one page is selected in the Directory panel, its contents will be shown in the

workspace.

Groups

Groups are used to organize pages (and other groups). A group may contain anynumber of pages or other groups.

A Group is created by clicking the button below the Directory panel in the Editorwindow.

Groups have three properties that may be edited: itsname, its enabled/disable state, and the applicationswhich affect when the group’s contents are active.When a Group is disabled, none of the building blockson its Pages will produce keyboard output or affectthe cursor.

To change the name of a group, select that page thenedit its name in the Inspector window.

There are two ways to change the enabled/disabledstate of a group. If the group is selected, its enabledstate will be shown with a checkbox in the Inspectorwindow. A group may also be enabled or disabled bychanging the checkbox next to its name in the left side

of the Editor window.

To change the application requirements of a group, change the popup menu based onthe desired behavior:

always — the group is always activeif the following are running — the group is active if any of the listed applicationsare currently runningif the following are not running — the group is active unless any of the listedapplications are currently running

Then, click the “Add...” button and browse to the desired application. Whenapplication requirements have been added to a Group, its icon in the Directory panelwill change to .

If application requirements have been added to a group, then the contents of thegroup may not be active when running ControllerMate. Instead of requiringControllerMate to be added to all groups that have application requirements, a groupmay be temporarily activated by clicking on the Debug icon ( ) immediately to theright of the Group’s enable checkbox in the Directory panel. When the Debug icon isturned on, the Group’s application requirements will be temporarily ignored.

See the example Application-Specific for an example of how application-specificgroups are created.

Documents

Control Mate Guide