Variables
Everything that the CMS references is represented by a "variable" of one
sort or another. Variables are used to represent the buttons and axes on
real controllers and the CMS Controls, as well as intermediate results
stored by the script as it is processed. There are basically two types
of variables. Analog Variables and Bit Variables. This section explains
these basic variable types and how they are referenced.
Analog Variables
The first basic variable type is the "Analog" variable. Analog variables
are used to represent a numeric value. That might be the current value of
an axis on a real device, the value of one CMS Controls axes, or just the
result of some computation that the script has defined.
While analog variables can have a very wide range of values to allow some
room for calculation. The values of the axes on real controllers,
however, are always 0 through 255. The Control Manager calibration
routines maintain this, and you can count on that range when referencing
values from real device. Values that are assigned to axes on the CMS
Controls likewise must have a range of 0 through 255 since they will
eventually be sent to Windows as an axis on a Control Manager Device
or set to send Up/Down or Position characters. Either case expects a
range of 0 to 255 for full output.
It is up to the CMS script to see to it
that the values have the proper range before being assigned to the CMS
Controls. If a value less than zero is assigned to a CMS Controls axis,
it will be treated as zero. If a value greater than 255 is assigned,
then it will be treated as 255. Note that this only applies when the values
are finally assigned to the CMS Controls so they can be used by the map.
Values may frequently exceed this range during calculations, etc. and
that will not create a problem for the CMS.
References to actual controller axes, i.e. JS1.A1, within the script
always receive the values before any Range and Gain values have been
applied, though scaling and centering (if applicable) have been applied. This
means the script can count on a stable, full-range, linear value from the
controller axes. Any Gain and Range parameters that are specified aren't
applied until the values are supplied to a CMS axis and sent to its
assigned Control Manager Device. Gain and Range parameters are not applied
at all in cases where a CMS axis is used to send Up/Down or Position
characters.
Bit Variables
The second basic type is the "Bit" variable. Bit variables can have only
one of two values, TRUE or FALSE. These might represent buttons on a real
device or the CMS Controls where TRUE would indicate that the button was
pressed and FALSE would indicate that the button was released. They might
also be the result of some logical operation defined by the script
file, an arithmetic comparison, the output of one of the logical devices,
and anywhere else that a TRUE/FALSE state is what is required.
Constants
Constants are just values entered into the script literally. These
can be decimal analog values such as "241", or they can be bit values in
which case they can be "TRUE" or "FALSE". Constants can be used anywhere
that a variable might be used except that the script cannot assign a
value to a constant. It's defined in the script when required and is not
available for "writing". Constants, like other analog values, can not
be assigned to real devices.
There are also a few predefined constants that have to do with setting
the current Mode. Those will be discussed in the next section on variable
names.
All variables used in the CMS have predefined names. The name is based
on the type of the variable (Analog or Bit) and what the variable
represents. The latter can be a control on a real controller, one of the
CMS Controls, or one of the internal variables that the
CMS provides.
General Naming Conventions
The names for analog variables all start with an "A" followed by a number
indicating which analog variable is being referenced, i.e. "A4". Similarly,
bit variables begin with "B", again followed by an number indicating which
bit variable is being referenced. For example, "B14". This applies to
all variables regardless of their source.
Variable Groups
The variables generally fall into one of several groups. In some cases
the name of the variable itself is enough to place it in a particular
group. In other cases, the variable name is formed by a device designator
followed by a "." followed by an axis or button ID.
Real Controllers
The real controllers, the CH USB devices that you have in the map, are
designated "JS1" through "JS16" (depending on how many you actually have,
of course). The "JS1" controller is the one on the left-most Device Tab
(excepting the "Program Settings" tab) when you view your map in the GUI.
"JS2" is the next device to the right, and so on.
To designate a particular control on that controller, the controller ID
is used, followed by a ".", followed by an analog or bit variable. For
example, if the left-most device tab in your map is the FighterStick,
you could reference the X axis on the FighterStick as:
JS1.A1
Button 7 on the same stick would be:
JS1.B7
If the device on the next tab was
a Pro Throttle, you could reference the button under the micro-stick as
"JS2.B1". In the case of axes and hats, it's not immediately apparent
which axis or button your referencing. In these cases the GUI will append
the appropriate designator to the device name in the Dialog Pane and you
can look there to find it. Hat 1 Up on the CombatStick, for example, is
actually Button 7. The GUI display will show "Hat 1 Up [B7]", the B7
is what you want to reference in the script. Likewise, the throttle axis
will show up as "Throttle [A3]".
Recognized axis references for the JSx devices are "A1" through "A6"
corresponding to the X through V axes respectively. Recognized button
references are "B1" through "B40". The upper limit of "B40" is to allow
for some future expansion. Actual controllers don't have buttons above
B16 since they aren't physically present.
There is one exception to the above. Even though they do not show up
as buttons in the test screen, you can reference the POV positions
on a real devices by referencing buttons "B25" through "B32".
The "B25" position corresponds to "POV Up", the numbers then go in
sequence clockwise around the POV with "B32" being the "POV Up/Left"
position. So, for example, you could reference the POV Up position
in your CMS script as "JS1.B25", POV Up/Right, as "JS1.B26", etc. These
references are active regardless of the mode that the POV is programmed
to use. It can be set to act as an actual POV or programmed to send buttons
or characters and the B25..B32 references will still work within the CMS
script.
Note that these are the positions as they show up in the test
screen when the hat is set as a POV. On the ProThrottle, this doesn't
necessarily correspond to the actual physical direction. In that one case,
"POV Up" is reached by physically moving the hat to the right. The other
positions do follow in a clockwise direction from there.
You cannot assign a value to an axis or
button on a real device. That is strictly controlled by the device itself.
These values are effectively read-only. The analog values coming from the
control will have a range of 0 through 255, assuming the controller has been
properly calibrated in the GUI.
CMS Controls
The CMS Controls, the ones you program in the GUI, are referenced similarly
to the JSx devices, but they use "CMS" rather than "JSx" for the prefix. For
example:
CMS.B1
CMS.A13
Since only one set of CMS Controls can exist in the map, there is no
need for a numeric identifier. The CMS includes 64 axes referenced as
"A1" through "A64", and 128 buttons, referenced as "B1" through "B128".
These correspond to the axes and buttons that are available for programming
in the GUI when the CMS Controls tab is selected. CMS variables can be
both read and set. Setting the value of a CMS variable is how you control
the output of the CMS Control.
Like the JSx variables, the CMS analog values can have a range of 0 through
255. You can exceed that range, but anything outside of that range will
result in the control being seen as at its minimum or maximum value by the
Control Manager. When you assign a CMS Control axis in the GUI, the axis
that tracks it will go from its minimum to its maximum as the value set
in the CMS value goes from 0 to 255.
Internal Variables
The CMS provides internal "scratch pad" variables for use by the script.
These variables cannot be programmed by the GUI directly. Only the CMS
Controls have that capability. These variables are just used for
working storage, etc. It's best to use these variables unless the variable
actually needs to go out through the CMS controls to control a Control
Manager Device button or axis or to send a character string of some sort.
There are 256 internal analog values and 1024 internal bit values. Since
there isn't any "device" associated with these, they are referenced without
a prefix. The valid references are "A1" through "A256" and "B1" through
"B1024".
Device Variables
There are also a set of variables termed "Device Variables". These are bit
values used to indicate the current state of some of the functions used in
the scripting language, particularly timers. This will be covered in some
detail later, for now it's enough to note their existence. There are 256 of
these variables, they are referenced as "D1" through "D256" and they do
not require a prefix.
