GAMEPADS AND JOYSTICKS AS CSOUND CONTROLLERS VIA SENSEKEY

Art Hunkins - December 2007
abhunkin AT uncg DOT edu
http://www.arthunkins.com


Sensekey is a Csound opcode that accepts ASCII input and makes it available
as control data. It is primarily useful in cases where otherwise, MIDI
buttons or keys would be required.

Recently, in my realtime computer performance compositions, WHAT'S IN A
NAME?, ET ITERUM VENTURUS EST and BEATA VISIONE, I created versions
specifically for the ASCII keyboard. (These compositions are found at the
website listed above.) Following that effort, I went a step further, with
versions for external numeric keypads.

Still not satisfied, I wondered what similar things might be done with
gamepads and joysticks. I found that both of these controller types emulate
ASCII keystrokes (and in some cases sequences of ASCII keystrokes) - at
least with most of their buttons. (The joysticks themselves - and various
rotary knobs, except for the POV hat - operate differently, and so are not
applicable here.)

Of course, gamepads and joysticks have notable limitations: 1) they are not
in the least intended for musical purposes, and often have unique, non-
standard button layouts; 2) they either require special software to be
run during during performance, or a utility that otherwise converts their
output to ASCII. In both respects, external keypads are considerably easier
to deal with.

Nonetheless, I have taken the ASCII keyboard versions of the three
compositions above, and adapted them for performance by a variety of
gamepads/joysticks - using a free, third-party Windows utility for joystick
to ASCII conversion. I've also made a version for Maestro joystick, a
device with a fairly elaborate set of buttons (no software required). These
game controllers include both USB and gameport devices, while the Maestro
joystick connects in-line with the keyboard.

The third-party software is a Windows utility called JoyToKey. It is
available at: http://www.oneswitch.org.uk/2/I/JoyToKey/JoyToKey.htm. This
package works with any USB gamepad that is HID compatible, and also - in
Windows XP - with all Sidewinders and some other legacy gamepads (see
below). Unzip the archive to its own directory, and simply copy the .cfg
files from the current distribution to JoyToKey's directory.

The seven devices tested were: Microsoft Sidewinder gamepad (10-button:
gameport), Microsoft Sidewinder 3D Pro and 3D Pro Plus joysticks (8/9-
button: gameport), Microsoft Sidewinder Pro gamepad (9-button: USB),
Logitech Precision gamepad (10-button: USB), a recent "no-name" USB gamepad
with 10 programmable buttons, and Maestro Joystick. The latter is the only
one of these devices that does not need software for ASCII emulation; the
keystrokes transmitted by its 6 buttons (* 4 programs = 24 characters) are
programmed by the user on the unit itself. The gamepads all include D-pads;
the Sidewinder 3D Pro and 3D Pro Plus joysticks have a POV hat, which can
act (with some inconvenience) as a D-pad.

The mods that enable these devices to perform the ASCII keyboard versions of
my three compositions are described below. Whether they are viable
performance vehicles, I leave it to the reader/performer to decide. (I am
doubtful; the direct ASCII keyboard versions seem much more user-friendly.)
I present this material, including the diverse configuration files for the
gamepads, simply as examples of what *can* be done. Perhaps works designed
*specifically for the features of these controllers* would be more useful
and to the point.

Please note that there is nothing sacrosanct about the button assignments
below; the designated ASCII keys may be freely assigned to any available
button or D-pad (POV hat) function. The user is encouraged to experiment
with alternative, user-friendly arrangements in JoyToKey. (The sole
restriction applies to the Sidewinder 3D Pro and 3D Pro Plus: a POV hat
function cannot serve as "Shift" ["Use Joystick2's configuration"]. Note,
however, that the 3D Pro Plus has an additional "arrow key", button 10
[there is no button 9], that *can* serve as "Shift.") You may also want to
try other legacy game controllers that meet the requirements listed below.

Mods are grouped by controller type. Since the Sidewinder and Sidewinder pro
are similar in design, they are treated together. Their six grouped buttons,
in rows of three (A-C and X-Z), are supplemented by two triggers. The
"arrow"/start button is #9, while the Sidewinder's button M is #10. This
arrangement is different from most gamepads, which have *four* grouped
buttons and four triggers (buttons 5-8). (The Sidewinder 3D Pro and 3D Pro
Plus are also alike, but otherwise quite different in configuration from the
others. They are discussed at the end of this article.) Data below indicate
what ASCII keystroke is assigned to each gamepad/joystick button or D-pad
(POV hat) function.

Gamepad/joystick requirements:
NAME3ASC - 9 buttons
 Sidewinder3DPro version - 8 buttons
ITERUMASC - 9 buttons
 Sidewinder3DPro version - 8 buttons
VISIONASC(R) - 9 buttons (reduced version - 4 sets only)
 Sidewinder3DPro version - 8 buttons
VISIONASCSimp - (simple version) 5 buttons
 Sidewinder3DPro version - 8 buttons, but no POV hat

All require D-pad (or POV hat), unless otherwise indicated



***Microsoft Sidewinder Gamepad (gameport)***
Some legacy gamepads, including all Sidewinders, will work in Windows
XP by doing the following: Connect the gamepad, click on Start |
Settings | Control Panel | Game Controllers | Add, and select your
controller type from the list. It should then show up as installed in
the Game Controllers box.
  also -
***Microsoft Sidewinder Pro Gamepad (USB)***

Open JoyToKey, select your desired .cfg, then minimize (do not close)
JoyToKey. Run Csound file as usual.


programming for NAME3ASC - both .csd and standalone .exe
Both Sidewinders use file NAME3ASCSidewinder.cfg

D-pad Left = (numeric) key 1; D-pad Right = key 3
D-pad Up = key 2; D-pad Down = key 4
Button A-B(1-2) = keys Q and W
Button X-Y(4-5) = keys E and R
Button C(3) = key T; button Z(6) = key Y
Left trigger(7) = key 5
Right trigger(8) = key U
Shifted buttons A-C(1-3) = keys I, O, P
Shifted button X(4) = key [ 
Start/Arrow Button(9) = Shift
Button M(10) = Shift


programming for ITERUMASC - both .csd and standalone .exe
Both Sidewinders use file IterumASC.cfg

D-pad Left = key C [also shifted]
D-pad Up = key X; D-pad Down = key Z [also shifted]
Button A(1) = (numeric) key 1; when shifted, key 9
Button B(2) = key 2; when shifted, key 0
Button C(3) = key 3; when shifted, key Q
Button X(4) = key 4; when shifted, key W
Button Y(5) = key 5; when shifted, key E
Button Z(6) = key 6; when shifted, key R
Left Trigger(7) = key 7
Right Trigger(8) = key 8
Start/Arrow Button(9) = Shift
Button M(10) = Shift


programming for VISIONASC(R) - both .csd and standalone .exe
This is a Reduced version, implementing only the first four "sets".
Both Sidewinders use file VisionASCSidewinder.cfg

D-pad Left = Enter [also shifted]
D-pad Up = + (plus); D-pad Down = - (minus) [also shifted]
Button A(1) = key Z; when shifted, (numeric) key 1
Button X(4) = kay A; when shifted, key Q
Button B(2) = key X; when shifted, key 2
Button Y(5) = key S; when shifted, key W
Button C(3) = key C; when shifted, key 3
Button Z(6) = key D; when shifted, key E
Left Trigger(7) = key V; when shifted, key 4
Right Trigger(8) = key F; when shifted, key R
Start/Arrow Button(9) = Shift
Button M(10) = Shift

programming for VISIONASC(Simp) - both .csd and standalone .exe
Group buttons (Simple) version. Easier to perform than the above.
Both Sidewinders use file VisionASCSimp.cfg

D-pad Left = Enter
D-pad Up = + (plus); D-pad Down = - (minus)
Button A(1) = (numeric) key 1
Button B(2) = key 2
Button C(3) = key 3
Button X(4) = key 4
Button Y(5) = key 5



***Generic 9/10-button Gamepad with D-pad (USB)***
Note that this procedure should work with all 9/10-button gamepads that
are USB and HID compliant, as well as similar legacy pads (see above).
These "arrangements" are primarily designed for pads with four grouped
buttons (on the right-hand top of the unit) and 4 triggers. They were
tested with both a Logictech Precision and a generic, "no-name" gamepad.
(They'll also work with the two Sidewinder gamepads, but in the case of
Name3ASC and VisionASC, awkwardly.) 

Open JoyToKey, select your desired .cfg, then minimize (do not close)
JoyToKey. Run Csound file as usual.


programming for NAME3ASC - both .csd and standalone .exe

Button 9 = Shift
D-pad Left = (numeric) key 1; D-pad Right = key 3
D-pad Up = key 2; D-pad Down = key 4
Button 1-4 = keys Q, W, E, R
Button 5 = key T; button 6 = key 5
Button 7 = key Y; button 8 = key U
Button 10 = key 5
Shifted buttons 1-4 = keys I, O, P, [ 


programming for ITERUMASC - both .csd and standalone .exe

D-pad Left = key C [also shifted]
D-pad Up = key X; D-pad Down = key Z [also shifted]
Button 1 = (numeric) key 1; when shifted, key 9
Button 2 = key 2; when shifted, key 0
Button 3 = key 3; when shifted, key Q
Button 4 = key 4; when shifted, key W
Button 5 = key 5; when shifted, key E
Button 6 = key 6; when shifted, key R
Button 7 = key 7
Button 8 = key 8
Button 9 = Shift
Button 10 = Shift


programming for VISIONASC(R) - both .csd and standalone .exe
This is a Reduced version, implementing only the first four "sets".
(Uses file VisionASC.cfg.)

D-pad Left = Enter [also shifted]
D-pad Up = + (plus); D-pad Down = - (minus) [also shifted]
Button 1 = key Z; when shifted, (numeric) key 1
Button 2 = key A; when shifted, key Q
Button 3 = key X; when shifted, key 2
Button 4 = key S; when shifted, key W
Button 5 = key C; when shifted, key 3
Button 6 = key D; when shifted, key E
Button 7 = key V; when shifted, key 4
Button 8 = key F; when shifted, key R
Button 9 = Shift
Button 10 = Shift

programming for VISIONASC(Simp) - both .csd and standalone .exe
Group buttons (Simple) version. Easier to perform than the above.
(Uses file VisionASCSimp.cfg.)

D-pad Left = Enter
D-pad Up = + (plus); D-pad Down = - (minus)
Buttons 1-5 = (numeric) keys 1-5



***Maestro Joystick JSK13A***
This unit connects in-line through the keyboard port.
6 buttons, 4 programs (= 24 buttons), are programmable on the unit itself.
(Unfortunately, buttons *on the stick* are not programmable.)
Buttons are counted from left to right, lower row first.

(To program the Maestro's buttons: 1) slide the PROG switch to the program
you want; 2) slide the SET switch on (LED lights); 3) hold down the button
you wish to program (LED blinks); 4) briefly press the ASCII key you want to
assign; 5) slide the SET switch off when you're finished assigning keys.


programming for NAME3ASC - both .csd and standalone .exe

Program 1 - buttons 1-5, (numeric) keys 1-5
Program 2 - buttons 1-6, keys Q, W, T, E, R, Y
Program 3 - button 1-5, keys U, I, O, P, [
Program 4 - buttons 1-4, keys 1-4
  (or, in performance, repeat first 4 buttons of Program 1)

In order to avoid confusion, I suggest you program all other buttons with
the Esc key. This is a non-printing character which is unused in my
compositions (most particularly in the ASCII versions). Note that the
performance progresses from program 1 through program 3, then either on to
#4 or back to #1. 


programming for ITERUMASC - both .csd and standalone .exe

Program 1 - Buttons 1-6, (numeric) keys 1-6
Program 2 - buttons 1-6, keys 7-9, 0, Q, W
Program 3 - buttons 1-6, keys E, R, Z, 1, X, C

Performance sequence is as follows: (Program 1) buttons (tones) 1 through 6;
(program 2) buttons 1-6 (tones 7-12); (program 3) buttons 1-2 (tones 13-14),
button 3 (amp gliss), button 4 (tone 1 fadeout), button 5 (freq gliss).
(Program 1) buttons 2 through 6 (tones 2-6 fadeout); (program 2) buttons 1-6
(tones 7-12 fadeout); (program 3) button 1 (tone 13 fadeout), button 3 (amp
gliss [reverse]), button 2 (tone 14 fadeout).


programming for VISIONASC(R) - both .csd and standalone .exe
This is a Reduced version, implementing only the first four "sets".
(It is also somewhat impractical to perform.)

Program 1 - buttons 1-2, keys 1 and Z; buttons 4-5, keys A and Q; button 3,
 Enter; button 6, + (numeric keypad plus)
Program 2 - buttons 1-2, keys 2 and X; buttons 4-5, keys S and W; button 3,
 Enter; button 6, + (plus)
Program 3 - buttons 1-2, keys 3 and C; buttons 4-5, keys D and E; button 3,
 - (minus); button 6, + (plus)
Program 4 - buttons 1-2, keys 4 and V; buttons 4-5, keys F and R; button 3,
 - (minus); button 6, + (plus)

Performance: Each of the four programs implements a "set". Button 1 is the
"group button," while buttons 2, 4 and 5 trigger the individual tones of
each set. In the first two programs, button 3 is Start/Stop; and button 6,
Freq Gliss up. In the last two, button 3 is Freq Gliss down; and button 6,
up. Quite a few program changes are involved in this version.

programming for VISIONASC(Simp) - both .csd and standalone .exe
Group buttons (Simple) version. *Much* easier to perform than the above.

Program 1 - buttons 1-5, (numeric) keys 1-5; buttons 6, Enter
Program 2 - buttons 1, - (minus); button 4, + (numeric keypad plus)

Buttons 1-5, program 1, are the 5 "group" buttons, with button 6 as Start/
Stop. Buttons 1 and 4, program 2, are Freq Gliss down and up, respectively.



***Microsoft Sidewinder 3D Pro Joystick (gameport)***
Set up in Windows XP following procedure outlined for other Sidewinders
above. This device has a POV hat instead of D-pad; assignments for the D-pad
are generally duplicated on the POV hat. The POV hat, however, is more
difficult to perform with; it and the unconventional button layout (buttons
are unnumbered on the unit itself) make the 3D Pro one of the least
attractive control options. The button layout follows: trigger = button 1;
button below POV hat = button 2; top left-side button = #3; bottom left-side
= #4; set of 4 buttons - top left/right = 5/6, bottom left/right = *8/7*.
  also -
***Microsoft Sidewinder 3D Pro Plus Joystick (gameport)***
As above with Sidewinder 3D Pro, except for the following:
Has an additional "arrow" button, button 10 (there is no button 9).
Button layout: trigger = button 1; button to left of POV hat = button 2;
top button to right of POV hat = button 3; bottom button to right of POV hat
= button 4; buttons A-D = buttons 5-8(; arrow button = button 10).
Windows XP recognizes this joystick as a Microsoft Precision Pro.

Open JoyToKey, select your desired .cfg, then minimize (do not close)
JoyToKey. Run Csound file as usual.


programming for NAME3ASC - both .csd and standalone .exe
Both 3D Pros use file NAME3ASCSidewinder3DPro.cfg

POV Left = (numeric) key 1; POV Right = key 3
POV Up = key 2; POV Down = key 4
Button 1 = Shift
Button 2 = 5
Buttons 3 and 4 = T, Y
Buttons 5 and 6 = Q, W
Buttons 8 and 7 = E, R
Shifted button 2 = U
Shifted buttons 5 and 6 = I, O 
Shifted buttons 8 and 7 = P, [


programming for ITERUMASC - both .csd and standalone .exe
Both 3D Pros use file IterumASCSidewinder3DPro.cfg

POV Left = key C [also shifted]
POV Up = key X; POV Down = key Z [also shifted]
Button 1 = Shift
Button 2 = (numeric) key 1; when shifted, key 8
Button 3 = key 2; when shifted, key 9
Button 4 = key 3; when shifted, key 0
Button 5 = key 4; when shifted, key Q
Button 6 = key 5; when shifted, key W
Button 8 = key 6; when shifted, key E
Button 7 = key 7; when shifted, key R


programming for VISIONASC(R) - both .csd and standalone .exe
This is a Reduced version, implementing only the first four "sets".
Both 3D Pros use file VisionASCSidewinder3DPro.cfg

POV Left = key Z; when shifted = (numeric) key 1 
POV Right = key A; when shifted = (numeric) key Q
POV Up = + (plus); POV Down = - (minus) [also shifted]
Button 1 = Shift
Button 2 = Enter [also shifted]
Button 3 = key X; when shifted, key 2
Button 4 = key S; when shifted, key W
Button 5 = key C; when shifted, key 3
Button 6 = key D; when shifted, key E
Button 8 = key V; when shifted, key 4
Button 7 = key F; when shifted, key R

programming for VISIONASC(Simp) - both .csd and standalone .exe
Group buttons (Simple) version. Far easier to perform than the above.
Both 3D Pros use file VisionASCSimpSidewinder3DPro.cfg

Button 1 = Enter
Button 2 = (numeric) key 1
Buttons 3 and 4 = + (plus) and - (minus)
Buttons 5 and 6 = keys 2 and 3
Buttons 8 and 7 = keys 4 and 5