GlovePIE 0.30 Documentation

Copyright
Vista
NEW! Languages
GlovePIE Scripts
Commands and other Statements
Functions
Operators
GlovePIE GUI
Overview
Output Device
Channel Box
Category Box
The Item List
The Format Box
Limit Output To Range
Input Source
More… Button
Apply Button
Delete Button
How to use the GUI with other features
GlovePIE OSC (Open Sound Control)
Using the SendOsc and BroadcastOsc functions
Using the OSC objects
Receiving OSC Messages
3D Visualisation
Camera Position
Background colour
Stereoscopic 3D
Camera Lens
Mouse
Mouse.DirectInputX and Mouse.DirectInputY
NEW! FakeMouse.DirectInputX and RealMouse.DirectInputX
Mouse.DirectInput2D
The Scroll Wheel
Mouse.CursorPosX and Mouse.CursorPosY
Mouse.CursorPos
Mouse.X and Mouse.Y
Mouse.ScreenFraction
Mouse.VirtualDesktopX and Mouse.VirtualDesktopY
Mouse.DesktopFraction
Mouse Buttons
Mouse.DoubleClickTime
Mouse.IsDragging
Mouse.Count
Mouse.CursorVisible
Mouse.Cursor
Mouse.PermanentCursor
Swallowing the Mouse
Mouse.Present
Fake Cursors
Cursor2.visible
NEW! Cursor2.Roll
NEW! Cursor2.Colour
NEW! Cursor2.WhiteColour
NEW! Cursor2.Caption
NEW! Cursor2.PermanentCursor = -2
NEW! Cursor2.Image
Cursor2.Shift and Cursor2.Ctrl
NEW! Touchpad
Keyboard
Special Keyboard Fields
Multiple Keyboards
Keys that can’t be used
Keys that sort of work
Unicode Characters
Number Keys
Top Row
Number Row
Qwerty Row
Next Row
Next Row
Space Bar Row
Cursor Pad
Numeric Key Pad
Stupid Bloody F-Lock Function Keys
Multimedia Keys
NEW! Acer laptop Euro and Dollar keys
Other Keys
Left, Right or Don’t Care
PPJoy
Joystick
Force Feedback
Buttons
Axes
POV Hats
Joystick Information
Multiple Joysticks
The “Any” object, for any kind of gamepad
The Joysticks and DPads
The Trigger Buttons
Select and Start buttons
The main buttons
The buttons based on which finger you press them with
Vibration
Wiimote (Nintendo Wii Remote)
Bluetooth
Using the Wiimote in GlovePIE
Buttons
Motion Sensing
Rotations
Sensor Bar
LEDs
Force Feedback
Speaker
Nunchuck, Classic Controller, Guitar, and Balance Board
Nunchuk
Classic Controller
NEW! Guitar Hero 3 Controller
NEW! Wii Fit Balance Board
Low level stuff
Multiple Wiimotes
P5 Glove
Buttons
Fingers
Location
Rotation
MIDI
MIDI Ports
MIDI Channels
Playing notes
Playing Percussion
Reading Notes
Setting the instrument
Pitch Wheel
Controls and Change Control messages
RPN (Registered Parameter Numbers)
NRPN (Non Registered Parameter Numbers)
SysEx (System Exclusive)
Speech
Making GlovePIE talk
Speech Recognition
Push-to-talk
Other Microphone Stuff
NEW! Virtual Reality HMDs
NEW! VR920
Z800
Trimersion
NEW! TrackIR
NEW! TrackIR emulation
NEW! Reading TrackIR like a game
Raw TrackIR camera input
NEW! Novint Falcon
NEW! 3DConnexion SpaceNavigator, etc.
NEW! PlayStation 3 SIXAXIS
Installation
Using SIXAXIS in GlovePIE
Bluetooth
Sometimes it stops working
NEW! PlayStation 3 BDRemote
NEW! XBox360 Controller
Concept 2 Rowing Machine
Screen
NEW! Orientation
NEW! Scrolling the entire screen
Size
Position
Plug & Play Monitor Stuff
ScreenSaver stuff
GlovePIE stuff
Other Stuff
Window
FakeSpace Pinch Gloves
5DT Data Glove
Polhemus Fastrack and compatible trackers
Ascension Flock of Birds
InterSense trackers
WorldViz PPT Tracker

Copyright

GlovePIE is Copyright 2007 by Carl Kenner, except for the scripts by other authors. By using this software you agree to obey the following license conditions:

* Playball Technology, Inc has exclusive rights to use this software for making money from commercial baseball simulations. However other people are free to make money from this program for non-baseball related things.

* You may not use this software directly or indirectly for any military purpose. This includes, but is not limited to, training, research and development, controlling military hardware, directing military personnel, or troop entertainment. You may not use this software anywhere on a military base or vessel. This applies to all versions of PIE. You may also not use it for playing “games” produced by the military to recruit players as real soldiers, including America’s Army. Sorry.

* You may not export this software to Israel, or use it in Israel (including the occupied territories), until Israel has ended its occupation of the West Bank, Gaza Strip, Lebanon, Syria, and anywhere else it may occupy, or until Israel abolishes apartheid (granting all Jews and non-Jews in its territories equal rights). If you try to run it in Israel before then, it will give you an error.

* You may not use this software to cheat at online or multiplayer games. What constitutes cheating depends on the game and the server. Just using a different input device shouldn't be considered cheating, but complex scripted actions to make things easier may be considered cheating. Don't get GlovePIE banned, or you will hurt everyone who wants to play with a VR glove. But feel free to cheat at single player!

Vista

You need to run GlovePIE as administrator if you want to emulate keys and the mouse in fullscreen games on Windows Vista. If you don’t run it as administrator, the keys and mouse will not be emulated. This is a security feature in Windows Vista.

If you use the “Rower” object you also need to run it as administrator.

To run GlovePIE as an administrator, right-click it and choose “Run as Administrator”. If you want it to always run as administrator, then right-click it and choose “Properties”, then choose the “Compatibility” tab, then tick the “Run this program as an administrator” box. Then choose “OK”.

Note that running programs as administrator is less secure, since it allows them to do whatever they want to your system. But it is no less secure than running them on XP.

On Vista, you can’t install the Mike and Mary speech synthesis voices. You also won’t have access to the “Sam” voice. You only have Anna, unless you bought Windows Ultimate in which case you might be able to get Lili.

In GlovePIE 0.30, Speech recognition should now work the same on Vista as it did on XP. The speech recognition window will no longer appear, and you will no longer execute random windows commands and randomly delete files, etc. while you are playing a game. It will however waste resources if you are also using other speech programs at the same time. If you want the speech recognition window to appear, and to randomly execute dangerous commands, you can choose “Vista Shared Speech Recogniser” from the Troubleshooter menu.

I can’t get the minimize-to-tray caption button to work on Vista with themes enabled. The button will still be there, but it will be hiding between other buttons, and it will look out of place.

NEW! Languages
GlovePIE can now be translated into other languages. This will not only translate the menus, but unlike other programming languages, it can also translate the scripting language. So language keywords, names of objects and names of properties of objects can all be translated. You can also translate some of the punctuation. Some languages can use commas as decimal points. So be careful. Those languages still use commas as commas too. So they (usually) need a space after the comma if it is not a decimal point and it is not obvious.

You can change the translation, or add translations for other languages, by changing the .inilng files or creating new ones. You also need to change the languages.ini file to add your language. Both these files must be saved as UTF8. It is best to use Notepad to edit them. If your language has non-English letters you should give the language name in those letters (before the = ), but the file name (after the = ) in English letters only. Menus can have any non-English letters you want, but the scripting language and its keywords and identifiers can only have Western European characters. That is because I haven’t been able to find a good syntax highlighting editor that supports Unicode. Identifiers are the names of things in the scripts. If you see anything in the user interface, or the scripting language that you want to translate, you can add it to the .inilng file in the appropriate section. It doesn’t matter if it already exists or not. Some items don’t exist yet, so you should add them. Because it is a programming language, you can’t have two translations that are the same, but for different things, or the computer will not be able to understand. You can add multiple foreign terms for each English term if you want. The first one will be chosen when translating into the foreign language, but when translating from the foreign language, any of the multiple terms will work.

When you post a script on a forum, it is very important that you translate it back to English first, by choosing English from the Language menu. Also if you cut and paste an English script FROM a forum, you also need to change GlovePIE’s language back to English first.

When you save a script, it is always saved in English automatically. When you load a script, it is always assumed to be in English and translated into your current language.  

GlovePIE Scripts
Here is the syntax for GlovePIE scripts:

Commands and other Statements

Comments

Comments are text which does nothing. They only help the human who is trying to read your script (usually you).
The computer ignores them.

Comments can have the following syntax:

// This is a comment

/* This is a multi-line comment
   It goes over multiple lines
   like this  */

’ This is a BASIC style comment
REM This is also a BASIC style comment

% This is a MATLAB style comment

Assignment statements

The most common kind of statement in GlovePIE is the assignment statement. 

It has one of the following forward syntaxes:

LValue  =  expression [ ; ]

LValue := expression [ ; ]

or the following backwards syntax:

expression => LValue [ ; ]

These statements all set the LValue to the value of the expression.
If it is inside an IF statement then it will always set the value.
If it is not inside an IF statement then it will ONLY set the LValue when the expression changes.
This means you can set a variable, such as a key, several times:

Ctrl = var.a
Ctrl = var.b

Which has a similar effect to:  Ctrl = var.a or var.b

The expressions can be any complicated mathematics that you want, or just another value.

New! Mathematical assignment statements

If you want to add something to a value, you have always been able to say:
LValue = LValue + expression

But now you can write the same thing a shorter way, like in C and Java:

LValue += expression

Both ways change LValue by adding expression onto it.
There are also other ways to increase a value, see the “Increment statements” section below.

You can also do subtraction, multiplication, or division by using -=, *= or /=

IF statements

Sometimes you will want to only do a set of commands when some condition is true.

You can do that with IF statements.

If statements can have one of the following syntaxes:

if condition then statement [ ; ]

if ( condition ) [then] statement [ ; ]

if condition [then] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end [if]] [ ; ]

if condition [then] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end] else [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end [if]] [ ; ]

if condition [then] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end] (else if|elseif) condition2 [then] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end] (else if|elseif) condition3 [then] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end] else [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end [if]] [ ; ]

WHILE loops

While loops are NOT very useful in PIE because PIE is not a linear language.
A PIE script continuously loops through the entire script, even while IF statements are running in the background.
If you think you need a while loop then you are probably looking at the problem the wrong way.

Nevertheless, PIE does support while loops in the unlikely event that you do need them.

The entire while loop will be executed in one go. You can't use it to wait for some condition triggered elsewhere (yet). 

The syntax is one of the following:

while condition do statement [ ; ]

while ( condition ) [do] statement [ ; ]

while condition [do] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end [while]] [ ; ]

If you make a mistake and create an infinite loop, then it will give up after a fifth of a second and speak "infinite loop".

FOR loops

For loops aren't as useful in PIE as they are in other languages, because PIE is not a linear language.
A PIE script continuously loops through the entire script, even while IF statements are running in the background.
If you think you need a for loop then you may be looking at the problem the wrong way.

The entire for loop will be executed in one go. You can't use it to wait for some condition triggered elsewhere (yet). 

The syntax is one of the following:

for variable (=|:=) InitialValue (to|downto) FinalValue [step amount] do statement [ ; ]

for variable (=|:=) InitialValue (to|downto) FinalValue [step amount] [do] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end [for]]

for ( initialization ; condition ; increment ) [do] statement [ ; ]

for ( initialization ; condition ; increment ) [do] [begin] [ { ]
  statement [ ; ]
  statement [ ; ]
  ...
[ } ] [end [for]]

If you make a mistake and create an infinite loop, then it will give up after a fifth of a second and speak "infinite loop".

Wait command

Wait commands are for use in macros. Everything inside an IF statement is considered a macro.
A wait command will pause only the macro it is inside of, while the rest of the script will keep going in the background.
If you have nested if statements inside each other, then it will only pause the innermost if statement. So don’t use it inside an if statement which is already inside an if statement itself.

The syntax is either:

wait duration [ ; ]

wait( duration ) [ ; ]

You should normally specify the units for the duration. Valid units are: milliseconds (ms), seconds (s), minutes, hours, days.

eg.  
wait 100 ms
wait 1 second
wait(500 milliseconds);

Increment statements

You can add one to something using one of these syntaxes:

var.x++
++var.x
Inc(var.x)
These are commands, not functions like in C. So you can’t set something else to equal var.x++.

You can subtract one from something like this:

var.x--
--var.x
Dec(var.x)

SHR and SHL statements

You can shift a value’s bits to the left or right with the SHR and SHL commands:
eg.

shr var.x, 1

Say command

You can use the Say command to make GlovePIE speak:

Say “hello world”

or

Say(“hello world”)

Other Commands

The following other commands also exist:

ExitProgram, ExitPIE, 
Execute(filename), Chain(filename),
Display(text), DebugPrint(text) 
AddCode(text), 
ControlPanel, ControlPanelKeyboard, ControlPanelJoystick, ControlPanelMouse, ControlPanelP5, ControlPanelPPJoy, ControlPanelSpeech, ControlPanelMidi, ControlPanelDisplay,

PlaySound(filename),
Beep([freq, duration]), BeepAsterisk, BeepExclamation, BeepHand, BeepQuestion, BeepDefault,

FlashPieWindow, HidePie, ShowPie, MinimizePie, MaximizePie, RestorePie, UnMinimizePie, UnMaximizePie, 

Press(x), Release(x), Toggle(x),

Type(text), TypeUnicode(text),

SendOsc(ip, port, address, [p1, p2, p3…]), BroadcastOsc(port, address, [p1, p2, p3…])
WiimotePoke([wiimote number], address, value)
WiimoteSend(wiimote number, report number, [p1, p2, p3…])  
Functions

Here are some of the functions that exist in GlovePIE

NEW! Pixel colour Functions

ScreenPixel(x, y): colour of screen pixel at (x, y) as an integer, in hexadecimal it looks like 0xRRGGBB. This is the opposite of the way the windows DLLs do it, but it is the way the internet and DirectX do it. To display it:

Debug = “0x”+ IntToHex(ScreenPixel(0, 0), 6)

You can also treat it like a vector:

[var.r, var.g, var.b] = ScreenPixel(0, 0)

debug = var.r+’, ‘+var.g+’, ‘+var.b

That will set var.r, var.g, and var.b to the values between 0 and 1 corresponding to the amount of red, green, and blue in the colour. The (0, 0) coordinates could be any pixel coordinates.

Trigonometry Functions

All angles are measured in degrees by default.
The following trigonometry functions are implemented:

Standard trig functions: sin, cos, tan, sec, cosec, cotan
Hyperbolic trig functions: SinH, CosH, TanH, SecH, CosecH, CotH

Inverse trig functions: aSin, aCos, aTan, aSec, aCosec, aCotan
Inverse Hyperbolic trig functions: aSinH, aCosH, aTanH, aSecH, aCosecH, aCotanH

2D inverse tan function: atan2

Rounding Functions

These functions preserve the units of their parameters.

ceil: Rounds towards infinity
floor: Rounds towards negative infinity
trunc, int: Rounds towards zero
round: Rounds towards nearest integer.  .5 rounds to nearest even number (Bankers' Rounding)

frac: Returns signed fractional component. eg  Frac(-1.32) = -0.32

RoundTo(x, digits): If digits is negative, rounds to that many decimal places using Banker's Rounding
If digits is positive, rounds to that power of ten using Banker's Rounding.

SimpleRoundTo(x [, digits]): Same as RoundTo except 0.5 always rounds up. Unfortunately -1.5 rounds up to 1.
digits defaults to -2 (meaning 2 decimal places).

Sign Functions

Sign: returns the sign of a number. 1 if it is positive, 0 if it is zero, -1 if it is negative
Abs: returns the modulus or absolute value. Removes the sign of a number. Preserves units.

Exponential and Square Root Functions

Raising things to the power of something:

sqr(x): caculates x^2
sqrt(x): calculates the square root of x.   x^(1/2)
power(x,y): calculates x^y
intPower(x,y): calculates x^y where x and y are integers (the result is not an integer if y is negative)
exp(x): calculates e^x.  e is 2.71828. The derivative of e^x is e^x.
Ldexp(s,p): calculates s * (2^p)

Poly(x, a0, [a1, [a2, [a3, [a4, [a5, [a6]]]]]]): returns a0 + a1*x + a2*(x^2) + a3*(x^3) + a4*(x^4) + ...

Logarithms (undoing raising something to some power):

Log10(x): returns the number you have to raise 10 to the power of, in order to get x.  eg. Log10(1000) = 3
Log2(x): returns the number you have to raise 2 to the power of, in order to get x.  eg. Log2(256) = 8
LogN(N, x): returns the number you have to raise N to the power of, in order to get x.  eg. LogN(10, 1000) = 3
Ln(x): returns the number you have to raise e (2.71828) to the power of, in order to get x
LnXP1(x): the same as above, but for x+1 instead of x

Comparison functions

IsZero(x): returns true if x is zero
IsInfinite(x): returns true if x is infinite
IsNaN(x): returns true if x is not a number

SameValue(a, b [, epsilon]): returns true if a and b are the same, or differ by no more than epsilon
InSet(x,a,b,c,d,e,f,g,...): returns true if x matches one of the values following it.

max(a,b): returns the maximum of two values. Preserves units.
min(a,b): returns the minimum of two values. Preserves units.

Range functions

EnsureRange(x, a, b): Returns the closest value to x which is within the range [a, b]. Preserves units.
InRange(x, a, b): Returns true if x is within the range [a, b].

MapRange(x, a, b, c, d): Returns value x converted from the range [a, b] to the range [c, d].  Values outside the original range will map to the appropriate values outside the new range.

EnsureMapRange(x, a, b, c, d): The same as MapRange except values outside the range are mapped to the closest values inside the range.

NEW! DeadZone(x, a): Returns value x between -1 and 1, but with a deadzone around zero, so that values within the range [-a, a] of the zero point become 0, and other values between -1 and 1 are scaled to compensate. You should only use this function for values roughly between -1 and 1, like joystick values.

Random functions

Random: Returns a random fractional number between 0 and 1.
Random(n): Returns a random whole number between 0 and n-1.
RandomRange(a,b): Returns a random whole number between a and b.
RandG(mean, StandDev): Returns a random number from gaussian distribution around mean. Preserves units.

Ordinal functions

odd(n): Returns true if n is odd
pred(n): Returns n-1
succ(n): Returns n+1

Date/Time functions

NEW! TimeStamp or GetTimeStamp: A precise timestamp measured in seconds, from an arbitrary starting point. Much more accurate than the other time functions (which are measured in days).
Now: Current time and date (in days since December 30, 1899)
Time: Current time (in fractions of a day)
Date: Current date (in days since December 30, 1899)

Tomorrow: Tomorrow's date (in days since December 30, 1899)
Yesterday: Yesterday's date (in days since December 30, 1899)

CurrentYear: Current year of the Gregorian calendar (in years).

DateOf(x): Returns the date part of the date and time in x (in days since December 30, 1899)
TimeOf(x): Returns the time part of the date and time in x (in fractions of a day)

Dayofthemonth(x), dayoftheweek(x), dayoftheyear(x), dayofweek(x), 
Daysbetween(x, y),
Daysinamonth(x, y), daysinayear(x), daysinmonth(x), daysinyear(x), DaySpan(x, y),
HourOfTheDay(x), HourOfTheMonth(x), HourOfTheWeek(x), HourOfTheYear(x),
HoursBetween(x, y), HourSpan(x, y),
IncDay(x, [y])

Temporal functions

NEW! Delta(x)

How much x has changed since the previous GlovePIE frame. It will be negative if x has decreased.

Smooth(x, [ExtraFrames, [DeadbandDistance]])

Smooths out the value of x by averaging with the previous ExtraFrames frames. If it hasn’t changed by more than DeadbandDistance it doesn’t count as changed at all. By default DeadbandDistance is 0.

NEW! Kalman(x, noise1, noise2)

Smooths using a Kalman filter, in theory. It has a tendency to diverge if you get the noise values wrong. Don’t ask me what the correct noise values are.

Pressed(x), Clicked(x), SingleClicked(x), DoubleClicked(x)

Returns true or false.

HeldDown(x, MinTime)

Returns true if x has been held down for at least MinTime.

KeepDown(x, MinTime)

Keeps the result being true after x has stopped being true, until MinTime is up.
Operators

There are lots of different operators you can use in GlovePIE. All of them allow you to mix different units together and rely on GlovePIE to automatically convert the units.

a + b
a plus b

If a and b are numbers they will be added together. If a and b are strings of text then they will be concatenated together. If a and b are true/false values then they must both be true for it to be true (the same as “and”). If a is a vector, but b isn’t, it will extend the length of the vector without changing the direction (not implemented yet).

a and b
a but b

Will only be true if a is true and b is also true (anything greater than 0.5 or less than -0.5 is considered true). This only does logical and. If you want to AND the binary bits together, use & instead.

a & b

If a and b are numbers, then it will only include in the answer the binary bits that are 1 in both a and b for that position. If a and b are not whole numbers, they will be rounded off first. If a and b are strings, they will be concatenated.

a - b
a minus b

If a and b are numbers they will be subtracted. If a and b are true/false values then they must both be true for it to be true (the same as “and”). If a is a vector, but b isn’t, it will decrease the length of the vector without changing the direction (not implemented yet).

-b

Will swap the sign of b.

not b

Will be true if b is false, and vice-versa

a x b
a * b
a times b
a multiplied by b
a cross b

Multiplies a and b together. If a and b are vectors it will do cross multiplication.

a . b
a dot b

If a and b are vectors it will do dot multiplication. Otherwise it does normal multiplication.

a / b
a divided by b

If a and b are numbers they will be divided properly, not like in C where you always get a whole number. 1 / 2 will give you 0.5. If you want integer division, you need to use div instead. If a and b are true/false values, then it will be true if either of them are true (the same as “or”)

a div b

Will give you the whole-number answer of a / b minus the remainder. IMPORTANT: a and b do not have to be integers. They can have decimals. 7.5 div 3.5 gives you the answer 2.

a mod b
a % b

These both give you the remainder of a divided by b. a, b, and the answer may all contain decimals. They don’t have to be whole numbers. For example, 7.5 mod 3.5 gives you 0.5.

a or b
either a or b

This is true if either a or b is true, or both. This only does logical or. If you want to manipulate the binary bits, use | instead.

neither a nor b

This is true if both a and b are false.

a | b

This includes in the answer the binary bits that are 1 in a or b or both.

a xor b
This is true if a or b is true, but not both.

a ^ b
a ** b

This is a raised to the power of b. ab

a ^^ b

This is a tetration b. Don’t ask.

b!

This is b factorial. b + (b-1) + (b-2) + … + 1

b!!

This is b double-factorial. IT IS NOT (b!)!

a shl b
a << b

This is the binary bits of a shifted to the left b bits. It is the same as a * (2^b).

a shr b
a >> b

This is the binary bits of a shifted to the right b bits. It is the same as a div (2^b).

|b|

This is the modulus (otherwise known as absolute value) of b, if b is a number, or the length of b if b is a vector, or the derivative of b if b is a matrix.

a%

This is a divided by 100.

a% of b
a % of b

This is a divided by 100 then multiplied by b.

a = b
a == b

True if a and b are the same (once converted to the same type and units).

a != b
a <> b
a isn’t b
a is not b

True if a and b are different (once converted to the same type and units).

a ~= b

True if a and b are approximately equal. If they are numbers, they must be within PIE.Epsilon of each other, when converted to the units of b. If they are strings then they must be the same except for case and leading and trailing spaces.

a !~= b
a ~!= b

True if a and b are not approximately equal.

a > b

True if a is greater than b. False if a is equal to b.

a < b

True if a is less than b. False if a is equal to b.

a >= b

True if a is greater than or equal to b

a <= b

True if a is less than or equal to b

b <= a <= c
c >= a >= b

True if a is between b and c inclusive.

b < a < c
c > a > b

True if a is between b and c, but is not b or c.

b <= a < c
c > a >= b

True if a is between b and c, but is not c.

b < a <= c
c >= a > b

True if a is between b and c, but is not b.

GlovePIE GUI

GlovePIE has three tabs. The first tab is the script tab, and shows the name of the script file. You can write any script you want here. The third tab is the Variables tab which only works while your script is running, and shows the values of all the variables.

The second tab is the GUI tab. Click on it to modify the file using a Graphical User Interface (GUI) instead of scripting. Once upon a time, the GUI was just for MIDI, but not anymore! Now it works for everything. Well, most of the main things.

The GUI is not the recommended way to make scripts, because it can sometimes be as hard to use as the writing scripts manually and it is less powerful. Please don’t be afraid of writing scripts manually. Scripts are easier than you think.

You can also swap tabs by using the View menu. In the View menu it is still called the MIDI GUI, but that is just so that the Alt+V, M, shortcut key isn’t changed.
Overview

The GUI is what is called a two-way tool, much like the graphical form designer in Delphi, C#, or Visual Basic. It is an alternate view of the same program, which you can edit with either the GUI, or the script editor, or both, swapping between the two as much as you want. Some complex script elements, and anything inside IF statements, will just not appear in the GUI. The GUI won’t delete those things, it just won’t let you see them or change them until you switch back to the script view. The Script view will show everything you created in the GUI or the script editor and let you modify everything to your heart’s content. But all lines which are similar to “something = something”, or “something => something” will be shown in the GUI. Even lines like “x++” will be shown in the GUI (although they don’t make a lot of sense outside IF statements).

You can create, load or save your whole program using only the GUI. It will switch back to script view when you run it, but that is just because the GUI window chews through lots of memory and CPU. But you can switch straight back to GUI to edit it again. You don’t need to do any scripting to create GlovePIE scripts, or even to load other people’s.

The left hand side of the GUI is a list of all the output values that can be set with the GUI. This includes MIDI output, keyboard emulation, mouse emulation, joystick emulation (using PPJoy), and fake mouse cursors. Output values that have already been set to something, are marked with an asterisk (*). If you need to click on the drop-down button of a drop-down box to see the items that have been set, then it will be marked with the drop-down symbol (-v-).

The right hand side of the GUI specifies what input values you want to set the selected value to. You can set it to a constant value or mathematical expression by typing it in, or you can choose parts of the input devices from drop-down boxes. You can also choose what range you want the input to be mapped from or to, or, if you are more advanced, what functions you want to apply to it.

Output Device

You need to start from the top of the left hand side. The top drop-down box lists all the MIDI output devices followed by the keyboard, mouse, joystick and fake cursors. The MIDI output devices show both the number and the name. Choose a device from this list. You can see which output devices have something set in them already by the * symbol. 

If you want to use MIDI then I recommend choosing “Default MIDI”. That way you can choose later what the default MIDI device will be, without having to change your whole file. Another alternative is to choose the MIDI Mapper device. The MIDI Mapper was a complicated MIDI mapping device in Windows 3.1, but these days it is a mere shadow of its former self. From Windows 95 onwards the MIDI Mapper is just a single setting in Control Panel which chooses which MIDI device MIDI playback should go to. You can go to the MIDI page of Control Panel, by choosing MIDI from the CP-Settings menu in GlovePIE. Unlike “Default MIDI”, which can be changed by GlovePIE settings, the Mapper is considered to be just another MIDI device. If you need to output to more than one MIDI device at once, choose the MIDI device in this box, otherwise use the default.

If you chose Keyboard or Mouse then the two drop-down boxes underneath will disappear. That is because you can only emulate the combined system mouse or combined system keyboard, not multiple keyboards or multiple mice individually. Very few programs distinguish between multiple mice or keyboards. Also GlovePIE doesn’t group the keyboard and mouse values into categories yet. There is only a single category for all the keyboard and mouse values.

Channel Box

If you chose PPJoy Virtual Joystick, or Fake Cursor, then there will be a drop-down box underneath, listing all 16 possible Virtual Joysticks numbered 1 to 16, or listing 17 possible fake cursors, numbered from 0 to 16. You need to install PPJoy, and configure PPJoy to add virtual joysticks before they will work in GlovePIE, but they will all be listed here whether they have been installed or not.

If you chose a MIDI output device, then there will be two drop-down boxes underneath. The first drop-down box lists all the MIDI channels, plus the default channel. You should choose “Default Channel” so you can change it later without changing your entire file, unless you need to output on multiple channels at once. There are 16 channels, but if your device uses General Midi then Channel 10 will always be percussion. But all the other channels have their own individual settings, such as instrument and volume, and each channel can play multiple notes at once (of the same instrument).

Category Box

The category box only appears for MIDI. Everything else just uses a single category, because I was lazy. So skip to the next section if you don’t care about MIDI. But because MIDI has so many things you can set, I have grouped them into categories. There is obviously no default category, because that makes no sense.

You need to choose a category. The first category you should choose should probably be “Other Controls” because it allows you to change general settings, like which device is the default, and which channel is the default.

The categories are:
14-bit Controls 0..31
These set main parameters such as volume. They apply separately to each channel. These are the combined Coarse and Fine controls for the first 32 MIDI controls. The controls in this category will set both the coarse and fine settings at once, giving you 14-bits of precision (16 thousand possible levels). This is the recommended way to set these controls, (unless your MIDI system interprets the coarse and fine values as separate things). Some of them have pre-defined names and functions, some of them don’t. But you can set any of them that you like. It will set the coarse value using cc0 to cc31 messages and it will set the fine value using cc32 to cc63 messages.
7-bit Controls 64..95
Other controls have no separate coarse and fine settings. These ones just have a single value for 7 bits of precision (only 128 possible levels). This is the only way to set these controls. These are often used for pedals, buttons and things like that. They can control effects like Hold, Sustenuto, Portamento, Legato, Chorus, AttackTime, etc.
7-bit Controls 96..127
These controls don’t really do anything much. I think most of the later ones actually correspond to other MIDI messages, like All Notes Off, so it doesn’t make much sense to set them. But you can set all these ones anyway if you want, just for completeness.
Coarse Controls 0..31
These controls set only the coarse half of the MIDI value. Since the coarse half is 128 times as significant as the fine half, sometimes it makes sense to only use the coarse half. Some devices (particularly software ones) use the coarse and fine values separately for different things. The coarse control is set with cc0 to cc31 messages.
Fine Controls 0..31
These controls set only the fine half of the MIDI value. Some devices (particularly software ones) use the coarse and fine values separately for different things. The coarse control is set with cc0 to cc31 messages.
Other Controls
This is where you set other important controls. It includes the important DeviceIn, DeviceOut, and DefaultChannel defaults. Set DeviceOut to a constant value of the MIDI output device you want to use. Set DefaultChannel to a constant value of the channel you want to use. 
Of the other controls, some apply to the channel like what instrument to use, what the overall channel pressure is, and what the Pitch Wheel is set to. Others apply to every channel, and use RPN messages, like Master Tuning, and Pitch Bend Range. Others use SysEx messages, like GeneralMidi, and SetupFile. You can set SetupFile to the name of a SysEx file (in quotation marks) that you want to send to the MIDI device at the start of your program. This is useful for all SysEx messages GlovePIE doesn’t support.
Percussion
These are the drum beats, symbol clashes, and other percussion sounds supported by General MIDI devices. These don’t change the instrument, they just turn a specific sound on or off. They all play on channel 10, no matter which channel you set them on, so it is best to set them on the default channel. You should set your MIDI device to General MIDI mode before using these, by setting GeneralMidi to true in “Other Controls”.

Notes Octaves 0..4
These are all the notes below Middle C. Octave 0 being the lowest (If you need a note deeper than C 0, use pitch bend). The octaves go from C to B. The notes are either true or false, representing On and Off. Setting a note to On this way will be like you hit the key with a velocity of 64/127 (50%). Setting a note to Off this way will be like you released the key with a velocity of 50%. You can also turn notes On and Off by setting their velocities using the categories below, if you want more control. If it is channel 10 on a General MIDI device then these play percussion rather than notes.
Notes Octaves 5..10
These are all the notes from Middle C (octave 5) upwards. Octave 10 is the highest, but it is incomplete, since MIDI devices only support 128 keys (If you need notes higher than G 10, use pitch bend). See above for the velocities.
Note Velocity o0..o4 and Note Velocity o5..o10
These are the key hit velocities for all the notes. Set the hit velocity to 0 to switch off the note (although the release velocity will always be 50% in GlovePIE). Set the hit velocity to anything else to turn on the note with that velocity. This is the better way to turn notes on and off when you need fine control over how hard they are struck.
Note Pressure o0..o4 and Note Pressure o5..o10
These are the key aftertouch, or note pressure. It is how much force you want holding down the key after it has been triggered. Most devices probably don’t support this.

The Item List
Once you have chosen which device, channel and category you want, there will be a list of items you can set for that category of that device. Items that have already been set to something will have an asterisk beside them.

When you have clicked on something here, the right hand side will show what it is set to, so you can modify it, or show a blank form you can fill in. Make sure you click Apply before you choose another item in this list, or whatever changes you made will be lost.

The Format Box
The first thing on the right hand side is the Format box. You don’t have to change it. It is purely a matter of preference. For some MIDI items, and all non-MIDI items, the format box will be locked to a particular format.

The format box specifies what format you want to specify the value in. If you prefer to think of the MIDI value as being between 0 and 127 then choose that. If you prefer to think of the MIDI value as being between 0 and 1 then choose that. Or choose any other format. Whichever one you choose is going to be how you have to specify the value in the boxes underneath, unless you use the “Convert From Source Range” button. Even if you choose “Convert From Source Range”, you still need to use the format you choose in the “Limit Output to Range” box.

But whatever format you specify the value in, the computer will later convert it into the correct format for MIDI messages when it sends them.

The default format is 0..1, which means you specify everything as a fraction between 0 and 1. Like 0.75 for 75%.

Limit Output To Range
If you never want to set the value to the maximum or minimum possible, but just want to adjust it within a certain range, then tick this “Limit Output To Range” check-box. When it is checked two more boxes appear specifying the maximum and minimum values (in whatever format you chose). So if you chose the format 0..1, but you don’t want the volume or whatever you are setting to go above 90%, check the box and put 0.9 in the maximum box. On the other hand, if you chose the format 0..127, then you need to put 114.3 in the box instead to stop it going over 90%. Note that decimals are allowed, and often necessary. The maximum and minimum values you choose here are what the source range will be converted to, if you choose “Convert From Source Range” below.
You don’t need to choose anything here, most of the time.

Input Source
In the “Input Source” area, you need to choose where the input is going to come from, that you are using to control the output. Or you can choose a constant, or a mathematical expression that you want the output to be set to.

If you want to set it to a constant value, just type it into the “Part of device, or numeric value, or expression” box. Or choose a constant from the drop down box. If you want to set it to a string (text) value, then you need to put it in quotation marks. For example, file names need quotation marks around them. Then you just need to click “Apply”.
Input Device
On the other hand, if you want to use a device to control the output, then choose which kind of device in the first drop-down box called “Input Device”. The “Remote” device only works on COM Port 2, and only if you enable it from the Troubleshooter menu, and only for a few remotes, like the one that comes with the Pinnacle PCTV card. The Screen and Window devices only return constant values, and aren’t much use in most cases. But the other input devices work for most occasions.

If you don’t want to use any of the devices in the list, just leave it blank, and type what value you want to set it to in the next box.
Number
Once you have selected a device, the number box appears next to it. You normally leave it blank to just use the default device, but if you want to use a specific joystick, or a specific glove, or a specific mouse or keyboard, then choose the number here, starting from 1 being the first device of that kind. Sometimes there is a special 0 device for keyboards or mouses, which represents a virtual software device used for Remote Desktop in Windows XP Pro. MIDI device 0 is the MIDI Mapper, which you can set in Control Panel. But normal devices are numbered starting from 1, with 1 being the first device of that type.
Reading multiple mice and keyboards independently is currently only implemented on Windows XP (or possibly Vista, which isn’t tested). To use all the mice combined into 1 virtual mouse, like Windows normally does, just leave the number box blank. The same applies to keyboards. 
Part of device, or numeric value, or expression
In this box will be a list of all the different parts or values that device supports. It may be a long list, and some of them make no sense to use, so choose wisely.

You can also type something in the box. For example, to use a glove gesture to control something, you should select “Glove” in the device box, and type in the five letter code in the “part of device” box, with one letter representing each finger like this:

xlrnn

In this case, x means don’t care (about the thumb), l (that’s the letter L) means the finger is straight (the index finger in this case), r means the finger is partly bent (the middle finger here) and n means the finger is very bent. The shape of the letter corresponds to its function.

Or if you leave the “device” box blank, you can type in any expression that GlovePIE understands in the “part of device” box.

For midi input, if you need to specify the channel, there is no box for it. So you need to add the channel to the front of this “part of device” box. Specify the channel like this: channel4.volume  (where “volume” could be any part of the device).

Convert From Source Range
The “Convert From Source Range” box is used to convert the input device value from whatever range it uses (for example 0 to 63 for glove finger bends) into the correct values for your chosen format and output range. This box is automatically activated for some common device parts, but you can still turn it on or off manually if you want. When it is checked, two more boxes appear for the minimum and maximum. You should specify the minimum and maximum for the range in these boxes, using whatever units you choose in the “Units” box.
If you want the range to be backwards, for example because the screen and glove use opposite directions for “y”, then just swap the min and max values around. So that max is smaller than min.

Units
Choose the units that you are using for the source value in the “Units” box. If there are no units for that particular value, then just leave it set to “Units”. The Units box is mostly used with the “Convert From Source Range” range, but it can also be used by itself to specify what units the value in the “part of device” box will use. Make sure you use appropriate units for the value you choose, for example speeds should be in meters per second or kilometres per hour rather than in something nonsensical for a speed, like degrees. Of course you can use degrees per second for angular velocities.

More… Button
The “More…” button is used to show extra, more complicated, information for advanced users. It allows you to choose a function to apply to the value (like Smooth), or to do arithmetic or other operations on the value. To hide the extra options again, click “Less…”
Maths
The Maths box (when you click “More…”) lets you choose what you want to do to the value. It includes standard maths, like add or subtract, and it includes comparisons for comparing a value and returning true or false, and it also includes “and” and “or” for when you want to use multiple inputs. Note that in GlovePIE, “*” means multiplied by, “/” means divided by, “^” means raised to the power of, “>=” means is greater than or equal to, “<=” means is less than or equal to, “!=” means is not equal to, “xor” means either a or b but not both, “&” means only include the binary bits that are the same in both, “|” means include all binary bits that are true in either value, “div” means the whole number part of the division, “mod” means the remainder of dividing the two, “shl” means shift all the binary bits of the value left by some amount, and “shr” means shifting all the bits of the value right by some amount.

Note that “div” and “mod” don’t just work on whole numbers. “Div” always returns a whole number result, but “mod” doesn’t, since the remainder of dividing decimal numbers will include decimals. If you have been brainwashed into thinking that “div” and “mod”, or the C language equivalents, only make sense for integers, think again. Actually they are extremely useful for decimals, especially with real world units.

PIE is unusually in the way it handles + and / of values that are both either true or false. In that case “+” means “and” and “/” means “or”. That is useful for keyboard commands like Shift+A which means “Shift and A”. But be careful because that doesn’t work on some things that aren’t considered true or false even if they normally return a value of 0 or 1.
Right Hand Side of Maths Expression
This box sort of speaks for itself. Just type in whatever you want to add, subtract, compare it to, etc. once you have selected an operator in the “maths” box.

You have to type it in manually, which shouldn’t be a problem if you are advanced enough to want to use it. Note that you can type anything here, even complex mathematical equations and other device inputs like Glove2.x   . Remember strings should be in quotation marks, but nothing else should.

Function
The function box lets you choose one of the “temporal” functions to apply to the value. It doesn’t include normal maths functions yet like “Sin” or “Cos”, it only includes functions that change over time. These include the “Smooth” function, which smooths out random noise or sudden bumps. They also include the “Pressed” and “Released” functions which only return true for a single frame when the value is first activated or finally returns to 0 or false. There are other functions like “Clicked”, “DoubleClicked” and “SingleClicked” which only return true when the button has been pressed and released the right number of times. And then there is the “HeldDown” function which only returns true once it has been held down for a certain length of time. Then there is the easily confused “KeepDown” function, which actually keeps the value as true for a while even after the button itself has been released. It is good for values that are normally only true for an instant (like Said() for microphone) but which you want to keep activating the output for longer. 

If you want normal maths functions instead, you need to set the “device” box to blank and type the whole function call in the “DevicePart” box instead.
Apply Button
You need to click the Apply Button once you have made changes, or the changes will be lost when you choose a different output item to set.
You can still edit it after you click the Apply button.
Once you have clicked Apply, an asterisk (*) will appear beside the name of the item to show that it is set to something.
If you added a new item, a line will be added to the end of your script. If you edited an existing item, that line of the script will be changed.
Your entire script is reprocessed by the GUI every time you click Apply, which means you can instantly tell how GlovePIE understood and interpreted your changes. 
There is no Cancel button. If you don’t want to keep your changes, just choose a different output item to set and when you come back your changes will be gone.

Don’t forget, the Apply button doesn’t save your script, it just adds that line to it. You need to use the “File > Save” menu item after you have applied if you want to save your script to disk.
Delete Button
If you have started creating a new item that you don’t want to Apply, or if you want to delete an existing item, use the Delete button. You can’t use it to revert your changes, it will just delete that item rather than restoring it to how it was before. 

How to use the GUI with other features
You can also use the “Search > Find” menu from the GUI. It will search for the specified text which appears anywhere in any of the items you have set. You need to click “Apply” first. Make sure you search in both directions. The search direction depends on when you added things, not their order in the output item list. The search is a powerful and useful way of navigating the GUI.

When you change from one the GUI tab to the Script tab, the cursor will stay on the same item. For example if you are looking at midi1.channel1.Volume in the GUI, then that line of the script will have the cursor when you switch back to the script. The same thing works the other way around. Choose a line of your script and change to the GUI and that item will be displayed in the GUI.

You can’t cut and paste from the GUI. So if you assign a complicated expression to control the Enter key, and you later decide you want it to control the space bar instead, you have to delete it from Enter, and create it again under Space. But an easier method is just to switch to the script editor, where you can more easily cut and paste, or change such things, and then switch back once you have fixed it. You will have the same problem if you apply a lot of things to MIDI device 1 and you want to move them all to MIDI device 2. Just use the script editor. You can even use Find and Replace from the script editor, but not from the GUI.

GlovePIE OSC (Open Sound Control)

Open Sound Control is a simple network protocol for controlling just about anything. It doesn’t need to involve sound.

You can use it to communicate with other computers, which might be Macs, or Linux boxes, or whatever. You might also be able to use it with some other hardware.

GlovePIE now supports OSC input and output, but unfortunately in the current implementation all messages received from different sources are pooled together into one, so you can’t tell where they came from. Also it can’t tell the difference between dots and slashes in addresses. And it doesn’t support bundles at all.

There are two ways to send OSC messages in GlovePIE. The first is with the SendOsc  and BroadcastOsc functions.
Using the SendOsc and BroadcastOsc functions

The BroadcastOsc function sends an OSC message to all computers on the local network. It looks like this:

BroadcastOsc(port, OscAddress, param1, param2, param3, …)

Port is the port number to send it to. It can be any integer, but it is best if it is between 49,152 and 65,535. The machine receiving the OSC messages needs to be set to the same port.

OscAddress is a path, which begins with a / and has a bunch of nodes separated by slashes. For example: “/resonators/3/frequency”

The other parameters can be anything. GlovePIE will send them as single-precision floating-point, or an integer, or true or false, or an array (for vectors), or an array of arrays (for matrices). You need to convert the parameters to the correct type that the machine you are sending to is expecting.

SendOsc will send to a specific address, rather than to every computer. It looks like this:

SendOsc(IpAddress, port, OscAddress, param1, param2, param3, …)

IpAddress is the IP address eg. “192.168.1.4” or the internet address eg. “www.google.com” or “localhost” to send to its own computer, or “broadcast” to send to all computers on the local network 

See the p5osc.PIE sample file for an example.

Using the OSC objects

You can have multiple OSC object. Each object can support input, output or both. But in the current version, all the input sources are pooled into one.

Using OSC output in GlovePIE first requires setting the port and either broadcast or IP address on an OSC object like this:

Osc1.port = 54934
Osc1.broadcast = true

Note that the port can be anything, preferably between 49,152 and 65,535. But it needs to match whatever the receiver is expecting. 

When broadcast is true, the OSC messages will be sent to all computers on the local network, but not the rest of the internet. When broadcast is false, you need to set the IP address of the computer you want to send to, like this:

Osc1.IP = “192.168.1.4”

After you have set either the IP address, or broadcast to true, then you can set any values you like, like this:

Osc1.hello.foo.glove.x = p5.x

That will tell all the receiving computers that the OSC address  /hello/foo/glove/x  is being set to a single-precision floating point number, equal to whatever the horizontal position of the P5 glove is.

Basically, each device that listens to OSC messages has a kind of tree structure of values that can be set. Each element on the tree has an address, starting with a / and with slashes separating each folder, or node on the tree. GlovePIE uses dots instead of slashes, to make it more consistent with the way GlovePIE works, and you can just assign to the address like a normal variable.

GlovePIE can send Single-precision floating point numbers (that’s numbers with decimal points), or it can send 32-bit integers (that’s whole numbers), or it can send True or False values, or it can send strings of text. But it can only send one value at a time.

For example, we could make something like this to send glove data via osc:

Osc1.port = 54934
Osc1.broadcast = true
Osc1.glove.finger.index = p5.index
Osc1.glove.finger.middle = p5.middle
Osc1.glove.finger.ring = p5.ring
Osc1.glove.finger.pinky = p5.pinky
Osc1.glove.finger.thumb = p5.thumb
Osc1.glove.pos.x = p5.x
Osc1.glove.pos.y = p5.y
Osc1.glove.pos.z = p5.z
Osc1.glove.button.A = p5.A
Osc1.glove.button.B = p5.B
Osc1.glove.button.C = p5.C
// etc.

Note that the buttons will be either true or false. If the receiving program can’t handle true or false values, use the int( ) function to convert them to integers like this:

Osc1.glove.button.A = int(p5.A)

You would then have to set up the receiving program or device to listen to port 54934 and understand those addresses, which would become like this:  /glove/finger/index 

Receiving OSC Messages

You can receive OSC messages by setting ListenPort to the port you want to listen to, and setting Listening to true.

Osc2.ListenPort = 54934
Osc2.Listening = true

then you can read any OSC values like this:

var.x = Osc2.glove.pos.x

You don’t have to use separate OSC objects for receiving and sending, but you can if you want.

Beware: OSC has security holes. If you set Listening to true then GlovePIE will accept osc messages from any source. If an internet attacker knows your PIE script is running and what format it uses, they could send OSC messages to you. That isn’t a major problem, and is extremely unlikely, so I wouldn’t worry about it.

3D Visualisation

GlovePIE now supports very simple 3D visualisation. The visualisations will replace the script area when the script that uses them is running.

Use “Obj” followed by a number to represent a 3D object:

Obj1.x = Wiimote.x
Obj1.y = Wiimote.y
Obj1.z = Wiimote.z

The position and size is in metres by default, although you can use whatever units you want.

Obj1.Size = [0.05, 0.04, 0.10]

You can also set it’s angles (in degrees by default):

Obj1.pitch = Wiimote.Pitch
Obj1.roll = Wiimote.Roll
Obj1.yaw = 0

And you can set its shape:

Obj1.model = “box”

You can set the model to the name of a “.x” file, which is a DirectX 3D model. Note that using .x files can mess with the colours of other objects in the scene, I don’t know why.

You can set the colours of objects:

Obj1.colour = [100%, 50%, 30%]

You can also set it as an integer 0xRRGGBB:

Obj1.colour = FF804C

Camera Position

You can also set the camera position and angle with the following fields:

Cam.Yaw, Pitch, Roll, x, y, z, pos (a vector), RotMat (a rotation matrix)

Eg.

Cam.yaw = vr920.yaw
Cam.pitch = vr920.pitch
Cam.roll = -vr920.roll
Cam.z = -2 metres

You can also read the Cam.WalkFwdDir, Cam.WalkBackDir, cam.WalkLeftDir, cam.WalkRightDir, cam.WalkUpDir, and cam.WalkDownDir vectors.

Those vectors are used for adding to the camera position based on user input.

Eg.

If W then cam.pos += Cam.WalkFwdDir * 8 kph
If A then cam.pos += Cam.WalkLeftDir * 8 kph
Etc.

Background colour

Set the background colour to either [r, g, b] or 0xRRGGBB

Cam.BgColour = [10%, 30%, 100%]

Stereoscopic 3D

You can also use stereoscopic 3D if you have Red/Cyan 3D glasses:

Cam.Stereo = true

You can set the screen depth for stereo like this:

Cam.ScreenDepth = 9 feet

You can set the eye separation like this:

Cam.EyeSeparation = 4 cm

Camera Lens

You can change the camera lens by setting its FOV:

Eg.

Cam.vFOV = 60 degrees

That sets the vertical field of view.

You can also set the NearClip and FarClip distances. Only objects between these two distances will be drawn. Setting NearClip too small makes the distant objects intersect when they shouldn’t.

Cam.NearClip = 20cm
Cam.FarClip = 100 metres

Mouse

A computer can have several mice, track-pads, track-balls and other such devices attached. But it only has one real mouse cursor. Also most games only see a single mouse, called the “system mouse”. The system mouse is an imaginary combination of all the hardware mice and track-pads put together. Moving any mouse to the left will move the “system mouse” and the on-screen mouse pointer to the left. Pressing any mouse’s left button will be seen as clicking the left button on the “system mouse”.

The physical movement of each mouse on the desk is measured in units called “mickeys”. The size of this unit depends on the mouse. It is often listed on the box as Dots Per Inch, or DPI. “Dots” here refers to “mickeys”. My Microsoft wireless optical mouse has 400 DPI, meaning one mickey is 1/400 inches, or less then a tenth of a millimetre. There is no way of knowing the exact physical position of the mouse, but you can only tell how far it has moved from its starting position.

The location of the mouse pointer on the screen is measured in pixels. Windows uses a complicated algorithm called “mouse ballistics” to determine how far to move the cursor based on the physical movement of the mouse. It varies for different versions of Windows and for different control panel settings, and for different monitor sizes. Many people have multiple monitors attached to their computer, and the mouse pointer can move from one to the other. If the mouse is on a screen to the left of the primary monitor then it will have a negative pixel coordinate for its x position. If the mouse is on a screen to the right of the primary monitor it will have a pixel coordinate greater than the horizontal resolution of the screen.

Some games use the mouse pointer’s position on the screen. But other games, especially First Person Shooters like DooM, don’t use a mouse pointer, and instead just read the physical movement of the mouse in Mickeys. Just because a game has a mouse pointer, doesn’t mean it uses the normal Windows one. Sometimes it just reads the physical mouse movements and draws its own pointer in its own private location that it is impossible for GlovePIE to know about.

Mouse.DirectInputX and Mouse.DirectInputY

In GlovePIE, you can read and set the physical movement of the mouse, in mickeys, by using the mouse.DirectInputX and mouse.DirectInputY values. It is called DirectInput because games use Microsoft’s DirectInput to read these values directly from the mouse hardware.

If you have multiple mice, and you have Windows XP, you can read the positions of individual mice with mouse1.DirectInputX, mouse2.DirectInputX, etc. Otherwise you can just use mouse.DirectInputX (without any number) to get the combined location of all the mice representing the “System mouse”. You can’t set the position of individual mice (since most games can’t read individual mice), so you always have to set mouse.DirectInputX without a number before the dot. Note that laptops usually have multiple mice, since the track-pad counts as a mouse.

Mouse.DirectInputX is the left/right position, with negative values to the left and positive values to the right. Mouse.DirectInputY is the forwards/backwards position, with negative values meaning forwards and positive values meaning backwards.

Where-ever the mouse was when you pressed the Run button will be considered the point (0, 0) where both mouse.DirectInputX and mouse.DirectInputY are equal to 0.

If you then move the mouse 1 inch to the right, the mouse.DirectInputX value will go up to 400, or whatever DPI your mouse is.

You can read these values, to find out where the mouse is, or you can set them, to trick games into thinking that the mouse has been moved to a new physical location.

Because PIE supports different units, you can also read the value in normal units of distance, like centimetres or inches.

For example:

midi.BassDrum1 = mouse.DirectInputX < -0.5 inches
midi.CrashCymbal1 = mouse.DirectInputX > 0.5 inches
debug = mouse.DirectInputX in inches

This will play a drum when you move the mouse half an inch to the left of its starting point, and play a cymbal when you move the mouse half an inch to the right of its starting point. It will also display the physical location of the mouse in the debug box. Note that people are used to moving the mouse tiny amounts, so it feels weird moving the mouse large distances. But if you want to use the mouse as a physical tracking device like this you can.

Note that if your mouse is not the default 400 DPI, then you need to set the value Pie.MouseDPI to whatever your mouse’s DPI is. For example, for my mum’s new mouse:

Pie.MouseDPI = 800
midi.BassDrum1 = mouse.DirectInputX < -0.5 inches
midi.CrashCymbal1 = mouse.DirectInputX > 0.5 inches
debug = mouse.DirectInputX in inches

You can also check with a ruler to make sure you got it right.

You can also set the values to control the system mouse in any game or application. It doesn’t matter whether the game uses the mouse cursor or reads the mouse directly. For example if you want to control the mouse with a joystick, like this:

mouse.DirectInputX = mouse.DirectInputX + 100*deadzone(joystick.x)
mouse.DirectInputY = mouse.DirectInputY + 100*deadzone(joystick.y)

Every frame (40 times per second) it will add or subtract a certain amount based on the position of the joystick. The deadzone function stops it from drifting if your joystick is not calibrated correctly.

NEW! FakeMouse.DirectInputX and RealMouse.DirectInputX 
 
DirectInputX, DirectInputY, DirectInputZ, and DirectInputH now have 3 kinds:

Mouse.DirectInputX
FakeMouse.DirectInputX
RealMouse.DirectInputX

When you read mouse.DirectInputX it is a total of all the fake mouse motions plus all the real mouse motions. When you read RealMouse.DirectInputX it is the total of all the real mouse motions, without any of the fake ones. FakeMouse.DirectInputX is the total fake mouse motions, and doesn't include the real ones.
You can also set Mouse.DirectInputX or FakeMouse.DirectInputX. For example:

Mouse.DirectInputX = MapRange(Wiimote.Roll,-90,90,-800,800)

The above will set the mouse to a position based on the Wiimote's roll. You will not be able to move it by moving, the real mouse.

FakeMouse.DirectInputX = MapRange(Wiimote.Roll,-90,90,-800,800)

The above will move the mouse relative to the real mouse position. The real mouse can also control it.

But if you use += or add to the DirectInputX value each time instead of setting it to an absolute value, then it makes no difference which one you use.
Mouse.DirectInput2D

Because GlovePIE also supports vectors, you may want to set and read both the DirectInput values at once. For example:

Mouse.DirectInput2D = [200, -400]

Will set the mouse to half an inch to the left and a whole inch forwards from its starting point. Or you can use real units:

Mouse.DirectInput2D = [0.5, -1] inches

You can also read them both at once. eg.

debug = mouse.DirectInput2D

You can read individual mice this way if you have multiple mice plugged into windows XP, by using Mouse1.DirectInput2D and Mouse2.DirectInput2D. But you can’t set individual mice.
The Scroll Wheel

Most mice these days also have a scroll wheel. This is considered to be the mouse’s Z axis. It has no units. But it normally jumps in increments of 120 per click. Some mice have continuous movement in their scroll wheels, but most click in jumps of 120.

Note that the wheel on my Microsoft mouse is extremely dodgy and often jumps in the wrong direction, and I expect many scroll wheels are like that. Some games go to a lot of trouble to compensate.
Mouse.DirectInputZ

You can read or set the scroll wheel position with Mouse.DirectInputZ.

The starting position of the scroll wheel is given the value 0. Negative means scrolled forwards. Positive means scrolled backwards. If you scroll it forwards two clicks it will have a value of -240.

Again this works with multiple mice.
Mouse.DirectInput3D

You can set or read the x, y, and z (scroll wheel) positions at once with Mouse.DirectInput3D. It is measured in Mickeys, even though technically z shouldn’t have units. It works with multiple mice.
Mouse.WheelUp and Mouse.WheelDown

This will be true for an instant (well, a single frame, or a 40th of a second) when you scroll the wheel up or down. You can also set it, if you want to simulate the user scrolling the wheel up or down.

It does not work with multiple mice yet.

Mouse.DirectInputH

If the mouse has a horizontal scroll wheel, or a vertical scroll wheel that can tilt from side to side, then in theory you can read or set the horizontal scroll wheel position with Mouse.DirectInputH. I have no idea whether it works, since it is largely based on guess-work and I don’t have a mouse with horizontal scroll wheels.

I don’t know whether this works with multiple mice, or the system mouse, or both. If you do any experiments and find out, please let me know.

Mouse.WheelLeft and Mouse.WheelRight

This is the horizontal equivalent of Mouse.WheelUp and Mouse.WheelDown. It is purely theoretical, and probably doesn’t work.

Mouse.WheelPresent

Mouse.WheelPresent is true if one of your mice has a scroll wheel, or false if none of them do. It doesn’t work for individual mice yet. You can’t set it, you can only read it.

Mouse.WheelScrollLines

The mouse.WheelScrollLines value is equal to the number of lines of text that will be scrolled in most applications when you move the scroll wheel one click (or 120 units if it doesn’t click).

Mouse.CursorPosX and Mouse.CursorPosY

The other way of thinking about the mouse position is to use the cursor, rather than the physical movement of the mouse on the desk. The Cursor position is measured in pixels. The number of pixels on the screen in each direction is called the resolution. It is usually around about 1024 horizontally and 768 vertically.

Remember that many games ignore the position of the proper cursor, so for these games you need to use the DirectInputX and DirectInputY values above instead.

There is only one real mouse cursor, and it is shared between multiple mice. So you can’t use numbers before the dot to read or set the cursor position for individual mice. If you want more than one cursor you need to use Fake Cursors.

mouse.CursorPosX is the horizontal coordinate of the cursor. 0 is the left edge of the primary monitor. The right edge of the primary monitor is one less than the horizontal resolution of the screen. eg. 1023. You can tell what the resolution of the primary monitor is by reading screen.width.

Note that if the cursor is on a different monitor from the primary monitor then mouse.CursorPosX will be either less than 0 or greater than or equal to the width of the primary monitor. You can tell what the left edge of the left-most monitor is by reading screen.DesktopLeft. You can tell what the right edge of the right-most monitor is by reading screen.DesktopRight. You can also read screen2.left, screen3.left, etc. to find the left edges of individual screens. The same with the right hand sides.

mouse.CursorPosY is the vertical coordinate of the cursor. 0 is the top edge, and the bottom edge is one less than the vertical resolution. It will be outside this range for multiple monitors. Use screen.DesktopTop and screen.DesktopBottom to tell the top and bottom maximum values for all monitors. 

You can also write Cursor.PosX and Cursor.PosY instead, to set the cursor position. It works the same as Mouse.CursorPosX and Mouse.CursorPosY. Don’t use a number after the word “cursor” though, or it will set fake cursors rather than the real one.

If you have a Plug & Play monitor, then GlovePIE can tell roughly what the physical size of your screen is. You can therefore set the location of the cursor in real world units. For example, to set the cursor to be 10 cm to the right of the left edge of the primary monitor, you would write this:

mouse.CursorPosX = 10 cm

You can also get the physical width of the screen like this:

debug = screen.width in cm

GlovePIE will automatically convert between pixels and real world units, so watch out! That may not be what you want.

For example:
mouse.CursorPosX = mouse.DirectInputX

will make the cursor on the screen move the same physical distance that you moved the mouse. If you moved the mouse 1 inch, it will move the cursor 1 inch. That is fun to try, but a pain for people that are used to mice.

If you don’t want to convert the units, try this instead:

mouse.CursorPosX = RemoveUnits(mouse.DirectInputX)

Normally you just set the cursor position using pixels, eg.

mouse.CursorPosX = 512

Mouse.CursorPos

You can read both the horizontal and vertical position at once as a vector, using Mouse.CursorPos.

eg.

debug = mouse.CursorPos

or 

mouse.CursorPos = [512, 300]

Mouse.X and Mouse.Y

Sometimes it is easier to specify the mouse pointer location as a fraction of the screen size. That is good if we don’t know how wide the screen is. Do that with mouse.x and mouse.y. Note that games which don’t use the cursor will still ignore these values, so for some games you need to use DirectInputX and DirectInputY instead. This also makes no sense for multiple mice individually, since they share the cursor.

Mouse.x is the horizontal position of the cursor, between 0 and 1. 0 is the left hand side of the primary monitor, and 1 is the right hand side. Note that if the cursor is on a different monitor it will be outside that range.

Mouse.y is the vertical position of the cursor, between 0 and 1. 0 is the top of the primary monitor, and 1 is the bottom. Again it may be outside this range if on another monitor.

Note that unlike the joystick, which goes from -1 to 1, the mouse only goes from 0 to 1. So to control the cursor based on the joystick position you need to use something like the MapRange function. eg…

mouse.x = MapRange(joystick.x,    -1, 1,    0, 1)

That will convert from the joystick’s range of -1, 1 to the mouse’s range of 0, 1.

Mouse.ScreenFraction

Mouse.ScreenFraction sets or reads both mouse.x and mouse.y at once, as a vector.

Mouse.VirtualDesktopX and Mouse.VirtualDesktopY

The problem with the mouse.x and mouse.y values is that you need to set them to less than 0 or greater than 1 to put the cursor on another monitor.

If you want to set or read the position as a fraction of the entire Virtual Desktop, then you should use mouse.VirtualDesktopX and mouse.VirtualDesktopY instead.

Mouse.x is the horizontal position, with 0 being the left side of the left-most monitor, and 1 being the right side of the right-most monitor.

As you can guess, Mouse.y is the vertical position.

Mouse.DesktopFraction

Mouse.DesktopFraction is the vector equivalent for setting or reading both mouse.VirtualDesktopX and mouse.VirtualDesktopY at once.

Mouse Buttons

PC Mice usually have between 2 and 5 buttons. You can read or set them in GlovePIE with:

mouse.LeftButton
mouse.MiddleButton
mouse.RightButton
mouse.XButton1
mouse.XButton2

The X Buttons do various things like move backwards and forwards in a web browser, and they are only found on special mice. Most modern games will support them, so they are very useful.

In theory some things in windows also support mouse buttons 6, 7 and 8.

You can set or read them with these values:

mouse.button6
mouse.button7
mouse.button8

But current windows versions don’t seem to allow you to set them. Reading them may theoretically work though, although in practice mice with more than 5 buttons probably work a different way.

Note that if you have multiple mice connected to Windows XP, you can read the buttons individually, with mouse1.LeftButton, mouse2.LeftButton, mouse3.LeftButton, etc. Without a number it reads the combination of all the mice.

All the mouse buttons can be set to either True or False. True is equivalent to 1, and false is equivalent to 0, except when you add true/false values it means “and”, and when you divide, it means “or”.

For example:

midi.BassDrum1 = mouse.LeftButton+mouse.RightButton

will play the drum when you have both the left and right buttons held down at once.

Mouse.DoubleClickTime

Mouse.DoubleClickTime is the maximum time between the clicks in double clicks that will still be recognised as a double click. If clicks are further apart than this time, they are two single clicks. It is the same for all the mice connected to the computer.

Actually GlovePIE also uses this same value for keyboard and other double-clicks using it’s DoubleClicked( ) function.

It is in seconds by default, but in GlovePIE you can use any units you like and it will convert them.

Mouse.IsDragging

Mouse.IsDragging will be true while the mouse cursor is busy dragging something, and false when it isn’t.

Mouse.Count

Mouse.Count is the number of mice connected to the computer. It only works on Windows XP, otherwise it will always return 1. This value doesn’t count the extra Windows XP Pro Remote Desktop cursor, which can be accessed as Mouse0 on Windows XP Pro.

Mice are numbered from 1 to mouse.count. Plus an extra mostly useless mouse0 on XP Pro.
Mouse.CursorVisible

Mouse.CursorVisible is true when the cursor is visible, and false when it isn’t. At least, that’s the theory. Some programs and games can hide the cursor and this should tell you whether or not that’s the case. This can’t be used for individual mice. Use Fake Cursors for them instead.

Mouse.Cursor

Mouse.Cursor is equal to whatever cursor is currently being displayed. It can be the following values:

-2.  Wii Hand
1.	Arrow
2.	Cross
3.	I Beam
4.	Icon
5.	Size
6.	Size Diagonal   /
7.	Size Vertical   |
8.	Size Diagonal   \
9.	Size Horizontal –
10.	Up arrow
11.	Hourglass
12.	Symbol for no
13.	Arrow + Hourglass (Application starting)
14.	Arrow + ? (Help)
15.	Size All +
16.	Hand
17.	Drag
18.	Multi-Drag
19.	Symbol for no again
20.	SQL wait
99. None of the above

Setting this value doesn’t really work yet, unless you keep setting it to different values like this:

Mouse.Cursor = Random(21)

Mouse.PermanentCursor

This can be used to set the cursor which should always be displayed when the mouse is over the PIE window. It will even stay that way after your program exits, until you restart PIE, or write a script to set it back to 0. It uses the same numbers as above.

This isn’t all that useful, but may be useful for displaying what state your script is currently in. eg.

if joystick1.Button1 then 
  mouse.PermanentCursor = 11
else
  mouse.PermanentCursor = 0
end if

Swallowing the Mouse

Not as tasty as it sounds. This is actually about stopping windows from receiving real messages from the System mouse (that is from all the real mice), but still receive those messages that are set by GlovePIE.

This only works on Windows 2000 or above. And I don’t think it works with DirectInput games.

It is mainly for use with fake cursors, or with multiple mice. But it can also be used to disable the mouse for any other purpose.

Mouse.Swallow can be set to true to disable the entire mouse, or false to not do that. This prevents the mouse from doing anything in Windows. But you can still set Mouse.LeftButton or Mouse.CursorPosX or whatever to control the mouse cursor. It just won’t be controlled by any of the real mice.

Mouse.SwallowButtons is the same, but it only disables the buttons.

Mouse.SwallowMovement only disables movement.

Mouse.SwallowWheels only disables scroll-wheels.

An unfortunate side-effect of swallowing the mouse is that clicking on GlovePIE’s title bar by controlling the mouse with GlovePIE will temporarily make it hang until you press Alt+Tab, or wait umpteen seconds.

Swallowing the mouse is good for when you want one mouse to control the real cursor, and all the other mice to only control fake cursors. The trick is the swallow the mouse, then set all the mouse values to match mouse1. Then you set the fake cursors to match mouse2.

See the MouseParty.PIE script for an example.

Mouse.Present

Last, but not least, you can tell if there actually is at least one mouse plugged in by using Mouse.Present. It will be true if there is a mouse (or track-pad, or other mouse-like device), and false if there isn’t.

Fake Cursors

In addition to the real mouse cursor, GlovePIE can show multiple fake cursors. These fake cursors look and behave just like the real cursor, and can do most of the same things. They are not quite perfected yet though.

Fake cursors will look funny (non-transparent) if you don’t have at least Windows 2000.

Fake cursors are identified by a coloured number in the bottom-right hand corner. Different numbers are different colours, but it repeats eventually.

Fake cursors could be controlled by multiple separate mice, or they could be controlled by other devices, like keyboards, joysticks, VR Gloves, speech, or whatever. They can even be used when you just want to display values graphically in GlovePIE, for debugging or whatever.

You can create fake cursors with a number between 0 and infinity. You don’t have to use them sequentially. You can show only fake cursor 3 and fake cursor 5 if you want. But using big numbers will waste memory.

See the MouseParty.PIE script for an example of using fake cursors.

Fake cursors have much the same properties as the ones for mouse.

Note that the special properties for fake cursors aren’t displayed in the code-completion box for cursor, the box only displays the same properties as for mouse because I was too lazy to fix it.

But some of the new properties are:

Cursor2.visible

Any fake cursors that you mention are visible by default. You don’t need to set a fake cursor to visible if you want to be able to see it. But you can set it if you want to hide it or show it again. Somewhere in your script write:

Cursor2.Visible = false

If you don’t want to see fake cursor number 2 anymore. You don’t have to use number 2, you can use any number. But using both fake cursor 1 and a real cursor is confusing, since people think of the real cursor as being cursor 1, even though it isn’t. You can even use fake cursor 0, which is also not the same as the real cursor.

Making a cursor visible doesn’t make it do anything. Fake cursors don’t respond to mouse movements. They only go where they are told to go, and click when they are told to click.

NEW! Cursor2.Roll
Fake cursors can rotate like on a Wii:

Cursor1.roll = Wiimote.Roll
Cursor1.x = Wiimote.PointerX
Cursor1.y = Wiimote.PointerY

Roll is measured in degrees, clockwise.
NEW! Cursor2.Colour
Fake cursors can change colour:

Cursor1.colour = [1, 0.5, 0]  // red, green, blue

Cursor1.colour = 0xFF8000 // the same as above

Setting colour will only change the coloured parts of the image. The white and black parts of the cursor will stay the same.

NEW! Cursor2.WhiteColour
You can also change the colour of the white that is in the image by setting Cursor1.WhiteColour. This doesn't just affect the white and grey parts of the image. It also affects the white that is mixed into other colours to make them paler. So for example you could make the white make colours redder instead of paler.

NEW! Cursor2.Caption

You can also set the caption. By default the caption is the fake cursor's number. But you can set it to anything you want:

Cursor1.caption = "the fake is a lie"

NEW! Cursor2.PermanentCursor = -2

If you want the cursor to look like a Wii hand cursor, set Cursor1.PermanentCursor = -2

You can also change the cursor image to a cursor loaded from a file:

NEW! Cursor2.Image

Cursor1.image = "c:\data\mycursor.cur"

If you use an animated cursor, it will not be animated.

Cursor2.Shift and Cursor2.Ctrl

Sometimes applications respond differently to Shift-clicks or Ctrl-clicks. That is when you hold down shift or control, or both, while you click.

Most non-game applications don’t read the keyboard to check this though. Instead they rely on the information that comes with the mouse message to determine whether shift was held down or not.

The good thing about that is that fake cursors can have their own Shift-Click and Control-Click features without using the real shift or control keys. It also means multiple users can be regular-clicking and shift-clicking at the same time without interfering with each other.

So to shift-click with a fake cursor you need to set Cursor2.Shift to true before the mouse button is set. It isn’t enough to hold down the real shift key.

Cursor2.shift and Cursor2.ctrl can be either true or false.

For example, to control cursor2 with a joystick you might write:

Cursor2.Visible = true
Cursor2.Shift = joystick.Button4
Cursor2.Ctrl = joystick.Button5
Cursor2.LeftButton = joystick.Button1
Cursor2.RightButton = joystick.Button2
Cursor2.MiddleButton = joystick.Button3
Cursor2.x = MapRange(joystick.x,  -1, 1,   0, 1)
Cursor2.y = MapRange(joystick.y,  -1, 1,   0, 1)

To shift click you would need to hold down button 4 while you click button 1.

NEW! Touchpad

The touchpad can be read as a mouse. But if you’re the kind of person who thinks a touchpad is just a mouse, GlovePIE isn’t for you. 

A touchpad can measure the absolute position of your finger, and how hard you are pushing it. It also normally comes with buttons. Mine has a LeftButton, RightButton and a DPad in the middle.

GlovePIE can only read Synaptics brand touchpads. They are the most common.

Touchpad.FingerPresent is true when your finger is touching the touchpad, and false when it is not.

Touchpad.x is the horizontal position of your finger. It is between 0 and 1. The right hand edge will be 1. If your finger is not touching the touchpad it will be the same position as last time you touched it.

Touchpad.y is the vertical position of your finger. It is between 0 and 1. It is 0 at the top, and 1 at the bottom. If your finger is not touching it, it will remember the last position.

Touchpad.z and Touchpad.w are how hard you are pushing down with your finger. It is NOT between 0 and 1.  W and Z both measure almost the same thing, but they are in different units. Z is much more precise. Sometimes it will be slightly above zero even when you are not touching the touchpad. 

Warning! Touchpads don’t bend when you push them, your finger does! Touchpads are a solid object that measures how much electricity your finger can store. That changes depending on how much of your finger is touching the touchpad, and how squashed your finger is. 

Touchpad.LeftButton is the touchpad’s left “mouse” button. It does not include left-clicks caused by taps. Touchpad.RightButton is the touchpad’s right “mouse” button. Touchpad.MiddleButton is the touchpad’s middle mouse button, which may or may not exist. 

If your touchpad has a DPad between the left and right buttons (for scrolling) like mine, then you can use the Touchpad.DPadUp, Touchpad.DPadDown, TouchPad.DPadLeft, and Touchpad.DPadRight buttons. It is possible for DPadUp and DPadDown to both be true if you push the whole DPad in, and the same goes for DPadLeft and DPadRight.

Your touchpad might also have other Up and Down buttons. Mine doesn’t. They will be touchpad.UpButton and touchpad.DownButton.

If you want your touchpad to stop controlling the mouse, you need to set Touchpad.swallow = true. Then only GlovePIE, and other programs that know how to read a touchpad will read it.

If your touchpad can work with a stylus then you can read touchpad.StylusPresent to detect when the stylus is touching it. Mine doesn’t work with a stylus.

There are also some other touchpad values you can experiment with.

Keyboard

You can read or write to the keyboard using the keyboard object, or just by using the name of the key without anything in front of it.

You can emulate keys that don’t actually exist on your keyboard if you want. For example the multimedia keys, or the Excel key, etc.

NEW! Keyboard emulation will now trigger the auto-repeat you normally get when you hold down a key on a real keyboard. Although you can disable this if you want. To disable it, set:
Keyboard.RepeatFakeKeys = False

Normally a keyboard will only repeat the most recent key that you pressed. GlovePIE will simulate that same behaviour by default. If you hate that feature, and wish you could move diagonally in Notepad by holding two keys at once, you can disable it like this:

Keyboard.RepeatMultipleFakeKeys = False

By default GlovePIE will use the same key repeat rate as your real keyboard. But you can tell GlovePIE to repeat keys at a different rate if you prefer:

Keyboard.RepeatRate = 10 Hz

It is measured in Hz (Hz just means times per second).

Like a real keyboard, keys don't start repeating until after a delay. After the delay it will start repeating. You can set the delay like this:

Keyboard.RepeatDelay = 0.4 seconds 

NEW! A very cool feature is that you can now swallow keys. When you swallow keys, other programs will not be able to read them. Only GlovePIE will be able to read them.

For example:

A = swallow(Left)
D = swallow(Right)

This means that when you press the Left arrow key the game won't receive the left arrow key, but it will receive the A key. If you didn't use swallow, the game would receive both the real key (Left) and the fake key (A).

If you have multiple keyboards, you can only swallow the key on all keyboards, not on specific keyboards. If you swallow a key on all keyboards, it is impossible for GlovePIE to tell which keyboard it came from.

Keyboard emulation doesn’t work as well on Windows 9x, because it won’t work in DirectInput games on 9x.

Keys can be either true or false. True when they are down and false when they are up. Some keys (like Pause) only tell you when they are pressed but not released, so the computer assumes they are released soon after.

Unless you are using Windows 9x, the keyboard keys will be the actual physical keys, ignoring whatever keyboard layout you are using.

Keyboard values, for example the F1 key can be set or read in various ways:

Keyboard.F1
Key.F1
F1

There are also special ways of writing key combinations:

^C
Ctrl+C
Ctrl and C

Also most keys have multiple names, which include most of the abbreviations you see written on the keys, as well as the full names. So just the guess key names and you will be fine.

Special Keyboard Fields
You can read or set Keyboard.ScanCode or Keyboard.VK to get or set the scancode or the virtual key code of the key that is currently down. They will be 0 when no key is down.

You can read Keyboard.Row to find out the row of the key that is currently down. It returns -1 if no key is down, or if it has no well-defined position (like backslash).

You can read or set Keyboard.AnyKey to tell if any key is currently down.

Set Keyboard.RawInput to force GlovePIE to use RawInput instead of DirectInput for the keyboard.
Multiple Keyboards
You can read from multiple keyboards with GlovePIE, if you have Windows XP. You will probably need extra USB keyboards. Multiple keyboards are rare, and not especially useful. You can’t write to multiple keyboards, because I haven’t seen any programs other than mine that can tell which keyboard you used.

Just put a number after the word keyboard, like this:

midi.BassDrum1 = keyboard2.Enter

It uses RawInput instead of DirectInput for reading multiple keyboards, so sometimes you can get better or worse results just by changing one of your “keyboard”s to a “keyboard1” so that it uses RawInput instead. You only need to mention keyboard1 once in your script to force it to use RawInput. RawInput will conflict with some exclusive-mode DirectInput software.

You can tell how many keyboards there are with Keyboard.Count. You can tell whether a keyboard exists with Keyboard2.Exists.
Keys that can’t be used
F Lock
The (stupid bloody) F Lock key can’t be read or simulated. It doesn’t send information to the computer when pressed. It just changes what the other keys do.
My Documents
The My Documents key doesn’t seem to have a scan-code or an AppCommand, so it is not useable with GlovePIE.
Messenger
The Messenger key doesn’t seem to work with GlovePIE.
Sleep, LogOff, Power
The Sleep, LogOff and Power keys shouldn’t be used because they turn everything off. Which kind of makes responding to them pointless. But the Sleep key does actually work in GlovePIE. 
Acer Laptop special keys
Most of the Acer Laptop special keys don’t work, or only work sometimes. Including the envelope, Saturn, P, and e special keys; the media keys (FB, FF, MediaStop, PlayPause, VOL-, VOL+); the increase/decrease brightness keys, and the ?, Fn+F2, Fn+F3, Fn+F4, Fn+F5, Fn+F6, and Fn+F7. On the other hand, the Mute key (Fn+F8) works, but only triggers for a short while once you release it. The other VolumeUp and VolumeDown keys work fine (Fn+Up, Fn+Down), unlike their VOL- and VOL+ equivalents.

Keys that sort of work
You can use the multimedia keys, and application keys, but they may not work as well as other keys. You can’t usually tell how long they are held down. You can’t tell how long the Pause key was held down either.
Unicode Characters
You can also simulate Unicode characters. This allows you to make typing programs for other languages, or to type special symbols or letters.

The possible values are the word “Unicode” followed by the four hexadecimal digits for that character. See www.unicode.org for tables. For example, to type the Greek letter alpha when the user presses the joystick button:

key.Unicode03B1 = joystick.button1

This may not work on all programs or on all operating systems. 
The TypeUnicode command also send a string of characters by the same method. Although those characters sent by TypeUnicode can currently only be Ansi characters since GlovePIE strings are still Ansi. But they will be sent via the same Unicode messages.
Number Keys
The main number keys, with the symbols above them (eg. 1!, 2@, 3#, 4$ ) are named:
“one”, “two”, “three”, “four”, etc.

eg.

Key.One = Joystick.Button1

The other number keys, on the numeric keypad, are named NumPad1, NumPad2, NumPad3, NumPad4, etc.

Most other keys are named according to what they have written on them.
Top Row
Escape
F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24
PrintScreen, SysReq, Pause, Break, ScrollLock

NOTE: Pause should not be confused with the new Play and Pause keys for music players. This Pause is the original Pause key that has been on every keyboard since the beginning. The new Pause key is called MediaPause.

This Pause key (and coincidently also the MediaPause one) doesn’t usually tell you when it is released. Which means GlovePIE will guess.

SysReq and Break used to be separate keys. Then the Break key got moved onto NumLock. Then the Break key got moved again onto Pause. Then the SysReq got moved onto PrintScreen. But the computer still regards them as separate keys. Break is Ctrl+Pause and SysReq is Alt+PrintScreen.
Number Row
Console, One, Two, Three, Four, Five, Six, Seven, Eight, Nine, Zero, Minus, Equals, Backslash, Backspace

Qwerty Row
Tab, Q, W, E, R, T, Y, U, I, O, P, LeftBracket, RightBracket, Backslash

Next Row
CapsLock, A, S, D, F, G, H, J, K, L, Semicolon, Apostrophe, Enter

Next Row
LeftShift, Z, X, C, V, B, N, M, Comma, Dot, Slash, RightShift

Space Bar Row
LeftCtrl, LeftWindows, LeftAlt, Space, RightAlt, RightWindows, AppMenu, RightCtrl

The AppMenu key is the pointless key with a picture of a menu that works like the right mouse button.
Don’t assume keyboards have a RightWindows keys. New ones only have LeftWindows.
Cursor Pad
NOTE!!!! The End key is tricky because it is also part of the GlovePIE language. Using Key.End is probably least confusing.

Home, End, PageUp, PageDown, Insert, Delete
Up, Down, Left, Right

Numeric Key Pad
NumLock, Divide, Multiply, NumPadMinus
NumPad7, NumPad8, NumPad9, NumPadPlus
NumPad4, NumPad5, NumPad6, NumPadPlus
NumPad1, NumPad2, NumPad3, NumPadEnter
NumPad0, NumPadDot, NumPadEnter

Stupid Bloody F-Lock Function Keys
Help, Undo, Redo, New, Open, Close, Reply, Forward, Send, Spell, Save, Print

These all work in GlovePIE, but they don’t tell you when they are released.
Multimedia Keys

The MyDocuments key doesn’t work!!! It doesn’t seem to have a scancode, or an AppCommand, so GlovePIE can’t detect it or trigger it, and doesn’t even list it. Messenger doesn’t seem to work either.

MyPictures, MyMusic, Mute, 
PlayPause, MediaStop, VolumeUp, VolumeDown, PrevTrack, NextTrack, MediaSelect, 

Mail, WebHome, Messenger, Calculator, LogOff, Sleep

Note that the MyPictures, MyMusic, and LogOff keys can’t be read properly.

The PlayPause, MediaStop, PrevTrack, and NextTrack keys only work for the correct duration if you have XP and your script includes multiple keyboards, or enables RawInput. For example:

key.RawInput = true
debug = PlayPause

Will show correctly when the PlayPause key is released.

MyMusic is the same key as OfficeHome. Intellitype needs to be set up with the correct keyboard type to perform the correct action.

NEW! Acer laptop Euro and Dollar keys

If you have an Acer laptop, you can now use the Euro and Dollar keys (near the arrow keys). But they only work if you exit or disable the Launch Manager program.

eg.

ppjoy.digital0 = Euro
ppjoy.digital1 = Dollar

Emulating these new keys will not type a euro or dollar sign, although some games may allow them to be used as game keys. To type a dollar sign, use Unicode0024. To type a Euro sign, use Unicode20AC. This is not a new feature.

Unicode0024 = Wiimote.A
Unicode20AC = Wiimote.B
Other Keys
Other keys can be specified by their names or by their hexadecimal scan codes, like this:

key.Scan5B

Left, Right or Don’t Care
Keys with Left or Right versions, like Shift or Control, can be specified like this:

LeftShift
RightShift
Shift

If you just say Shift it will respond to either Shift key.

PPJoy

If you want to emulate a joystick with PIE, you need to download and install PPJoy. Download it from http://www.geocities.com/deonvdw/PPJoy.htm

You then need to configure PPJoy to add a virtual joystick or two. Go to “Parallel Port Joysticks” in Control Panel (or the CP-Settings menu of GlovePIE), and choose “Add”. Then under “Parallel Port” choose “Virtual joystick” and under “Controller Number” choose a number between 1 and 16, which will be the number of the Virtual Joystick. It’s best to start with 1.

Then you need to create a custom mapping for the virtual joystick. Choose the number of Axes (I recommend 8),  the number of buttons (I recommend 32), and the number of POV hats (I recommend 2). Then you need to set which axes you want the 8 available axes to be. Then click next and choose which analog axes you want to correspond to those axes. The analog values are how you set that axis in PIE, just choose any numbers here, but remember them later. I recommend using analog 0 to analog 7. Then click next.

Then choose which digital values you want to correspond to the first 16 buttons. I recommend 0 to 15. Then click next and set the next 16. Then set the two POV hats.

Once you have a Virtual Joystick set up in PPJoy, you can set its analog and digital values with PIE:

PPJoy1.analog0 = 0.5
PPJoy1.digital0 = true

Analog values can be between -1 and 1.
Digital values can be either true or false.

If you want to set “PPJoy Virtual Joystick 2” then set the values for PPJoy2.

“PPJoy” by itself without a number refers to “PPJoy Virtual Joystick 1”.

If the analog corresponds to an axis, then 0 is centred and -1 and 1 are the two extremes. 

But if the analog corresponds to a a POV hat switch, then -1 corresponds to pushed at an angle of 0 degrees (forwards). -0.5 corresponds to 90 degrees (right). 0 corresponds to 180 degrees (backwards), 0.5 corresponds to 270 degrees (left) and 1 corresponds to centred.

Games which let you choose which joystick you use will need to be set to the appropriate PPJoy Virtual Joystick in the game. Other games which just use the default Joystick will require you to go to the Control Panel joystick settings (Use GlovePIE’s CP-Settings menu to get there quickly), and change the default joystick there.

If you want to control the game with a real joystick and just add some scripted actions to it, you will set the game or control panel to the virtual joystick and assign values from the real joystick to the PPJoy fields.

Joystick

Joysticks, Game pads, Steering Wheels, and most other Direct Input devices that aren’t keyboards or mice, are considered to be Joysticks by GlovePIE.

If you want to read from a joystick you can use the Joystick object, but if you want to write to it, you need to use the PPJoy object.

Force Feedback

Most fields of the Joystick are read-only, but the two joystick fields which you can set are the Vibration1 and Vibration2 fields. These are the force feedback on the two axes, and can be set to any value between -1 and 1. 0 is no effect. In this case the Joystick is acting as an output device. On a Gamepad, Vibration1 will be rumble, and Vibration2 will be buzz. On a real Joystick they will push the stick in a direction (I think).

Buttons

The Joystick buttons are numbered 1 to 128. Most joysticks won’t have that many buttons though. You can read them with:

Joystick.Button1 to Joystick.Button128

Axes

You can tell how many axes the joystick has with the Joystick.NumberOfAxes value.

Each joystick axis has a value between -1 and 1.

The joystick axes are referred to as follows:

x = sideways position. -1 = left, 0 = centre, 1 = right
y = forwards/backwards position   -1 = forwards, 1 = backwards
z = Right Analog stick forwards/backwards   -1 = forwards, 1 = backwards
roll = joystick twist, or right analog stick left/right    -1 = left, 1 = right
pitch = not usually used
yaw = not usually used
slider = throttle rudder control, -1 = forwards (full speed), 1 = backwards (no speed)
dial = some other dial

vx, vy, vz, vroll, vpitch, vyaw, vslider, vdial = Extra axes which DirectInput supports, supposedly for velocity (which seems kind of redundant), but could be anything. Not normally used. They don’t tell you the velocity on a normal joystick.

You can also read the axes as a vector:

Pos = [x, y, z]
Pos2d = [x, y]
NEW! Pos2d2 = [roll, z] (right-analog stick)
Velocity = [vx, vy, vz]

POV Hats

These are either those little hat switches you get on the top of some joysticks, or they are the D-Pad on a Game Pad with analog sticks when it is in analog mode.

There can be up to 4 POV Hats per joystick, numbered Pov1, Pov2, Pov3 and Pov4.

The number of POV hats the joystick has is given by Joystick.NumberOfPOVs.

POV Hats can be either centred, or they can be pushed out in some direction. You can’t tell how far in that direction they are pushed. Analog POV hats can be pushed in any angle. Digital ones only support 8 different angles.

To tell in PIE whether Pov1 is centred, read: Joystick.Pov1Center. It will be either true or false. If it is true then you can read Joystick.Pov1 and it will be the angle in degrees (or you can convert it to other units if you want). If it is centred then Joystick.Pov1 will be -1.

Another way of reading the POV hat is to use the values Pov1Up, Pov1Down, Pov1Left and Pov1Right. For example if the joystick is pushed to the front-left corner then Pov1Up and Pov1Left will both be true and the others will be false. For analog POV hats it only has to be closer to that direction than to any other. 

The final way of reading the POV hat is to use the values Pov1x and Pov1y. They work just like the x and y values of the joystick, except the values it can return are more restrictive (either both values are 0, or one of them is on the edge).

Joystick Information

There are other joystick fields with information about the joystick. You can look most of them up in the DirectInput documentation. They are:

Alias: true or false
Attached: true or false
Deadband: true or false
DeviceType: number
DeviceSubType: number
Emulated: true or false
FFAttack
FFDriverVersion
FFFade
FFSamplePeriod
FirmwareRevision
ForceFeedback
ForceFeedbackGuid
HardwareRevision
HID
Hidden
HidUsage, HidUsagePage
InstanceGuid
IsFirstPerson, IsFlight, IsGamePad, IsJoystick, IsLimited, IsVirtualJoystick, IsWheel
Name: The name of that individual joystick
Phantom: true or false
PolledDataFormat
PolledDevice
PosNegCoefficients
PosNegSaturation
PPJoyNumber
ProductGuid
ProductName: The brand of the joystick
Saturation
StartDelay

Multiple Joysticks

By default “Joy” or “Joystick” refers to “Joystick1”. You can also specify a joystick by number, eg. “Joystick1” or “Joystick2”.

But you can also specify joysticks by type. Note that that only works if the joystick reports its type correctly, which lots of them don’t. My Game Pad reports itself as a joystick for example.

Joystick.GamePad1 refers to the first gamepad. Joystick.GamePad2 refers to the second gamepad.

Joystick.Joystick1 refers to the first joystick that actually is a joystick.

Joystick.Wheel1 refers to the first wheel.

Joystick.Flight1 refers to the first flight stick.

Joystick.FirstPerson1 refers to the first Virtual Reality DirectInput device (p5 gloves don’t count as DirectInput devices).

Joystick.PPJoy1 refers to PPJoy virtual joystick 1.

Joystick.NotPPJoy1 or Joystick.Real1 refers to the first joystick that is NOT a PPJoy Virtual Joystick.

The number after the type is optional. You then put the item after, like this:

debug = joystick.gamepad1.x

or like this:

debug = joystick.wheel.x

This is useful if you have different types of joysticks (that report their type correctly).

The “Any” object, for any kind of gamepad

When you don’t care whether the user is using a Wiimote and Nunchuk, Classic Controller, SIXAXIS, XBox360 controller, or ordinary gamepad, you can use the “Any” object.

It supports DirectInput gamepads, Wiimotes, Nunchuks, Classic controllers, SIXAXIS, or XBox 360 controllers. It also sort-of supports real joysticks, but not really. 

By convention, the Nunchuk is assumed to be in your left hand, and the Wiimote in your right, even though that is not necessarily the case.

It is not complete yet, and is still a work in progress. I haven’t implemented motion stuff yet.

It doesn’t support multiple players individually. ALL controllers will trigger it, even if you have multiple of the same type.

The Joysticks and DPads

Any.Joy1x, Any.Joy1y:  This is the left joystick on a gamepad with two joysticks (sixaxis, classic, xbox360, etc), or the Nunchuk joystick on Wiimote+Nunchuk, or the joystick on a joystick.

Any.Joy2x, Any,Joy2y: This is the right joystick on a gamepad with two joysticks. On a joystick that twists, Joy2x will be the twist.

Any.DPadLeft, DPadRight, DPadUp, and DPadDown: These are the direction buttons on the DPad. They may be analog or digital (0 to 1). If the device is an actual joystick, it will be the hat switch instead.

Any.Left, Right, Up, Down: Either the DPad or the left joystick, or Nunchuk, can be used to control these, or the joystick if the device is a real joystick

Any.LeftThumbLeft, LeftThumbRight, LeftThumbUp, LeftThumbDown: Any DPad or analog stick controlled by your left thumb, or the Nunchuk. This does not include the Wiimote dpad. On a real joystick this will be the joystick or hat switch even though both are controlled by your right hand.

Any.RightThumbLeft, RightThumbRight, RightThumbUp, RightThumbDown: Either the right analog stick, or the Wiimote’s DPad (the Wiimote is the only controller with a DPad for the right hand).

Any.L3: Pushing in on the left analog stick. This does NOT work on a Classic Controller or Nunchuk, they have no L3 button. It only works on the SIXAXIS, XBox 360 Controller, or regular gamepad.
Any.R3: Pushing in on the right analog stick. This does NOT work on a Classic Controller, they have no R3 button. It only works on the SIXAXIS, XBox 360 Controller, or regular gamepad.

Any.Joy1Run: Left analog stick is pushed to run speed.
Any.Joy2Run: Right analog stick is pushed to run speed.
The Trigger Buttons
Note that R1, RightTrigger and Cross are the same on a Wiimote.

Any.RightTrigger: The B Button on a Wiimote, the R1 button on a SIXAXIS or regular gamepad, the R button on a Classic Controller, or the right trigger on an XBox360 controller.
Any.LeftTrigger: The Z Button on a Nunchuk, the L1 button on a SIXAXIS or regular gamepad, the L button on a Classic Controller, or the left trigger on an XBox360 controller.
Any.L1: The L1 button on a SIXAXIS or regular gamepad, C Button on a Nunchuk, ZL on a Classic Controller, or left shoulder button on an XBox 360 controller.
Any.L2: The L2 button on a SIXAXIS or regular gamepad, Z Button on a Nunchuk, L on a Classic Controller, or left trigger button on an XBox 360 controller.
Any.R1: The R1 button on a SIXAXIS or regular gamepad, B Button on a Wiimote, ZR on a Classic Controller, or right shoulder button on an XBox 360 controller.
Any.R2: The R2 button on a SIXAXIS or regular gamepad, ZR on a Classic Controller, or right shoulder button on an XBox 360 controller. This is impossible to do on a Wiimote.

Select and Start buttons
Any.Select: Select on a SIXAXIS, regular gamepad, or Classic Controller; or Minus on a Wiimote. Back on an XBox360.
Any.Start: Start on a SIXAXIS, regular gamepad, or Classic Controller; or Plus on a Wiimote. Start on an XBox360.
Any.Home: PS on a SIXAXIS, Home on a Wiimote or Classic Controller. Not possible on a regular gamepad, not readable on an XBox360.

The main buttons
Note that R1, RightTrigger and Cross are the same on a Wiimote.

Any.Triangle: Triangle on a SIXAXIS or regular gamepad, x on a Classic Controller, or 1 on a Wiimote. Y on an XBox 360.
Any.Circle: Circle on a SIXAXIS or regular gamepad, A on a Classic Controller or Wiimote. B on an XBox 360.
Any.Cross: Cross on a SIXAXIS or regular gamepad, B on a Classic Controller or Wiimote. A on an XBox 360.
Any.Square: Square on a SIXAXIS or regular gamepad, y on a Classic Controller, or 2 on a Wiimote. X on an XBox 360.

The buttons based on which finger you press them with
Top to bottom, left to right, followed by hard to reach ones.

Any.RightThumbButton1: Wiimote A, Classic x, SixAxis Triangle
Any.RightThumbButton2: Wiimote -, Classic y, SixAxis Square
Any.RightThumbButton3: Wiimote Home, Classic b, SixAxis X
Any.RightThumbButton4: Wiimote +, Classic a, SixAxis Circle
Any.RightThumbButton5: Wiimote 1, Classic/SixAxis Start
Any.RightThumbButton6: Wiimote 2, Classic Home, SixAxis/GamePad R3

Any.LeftThumbButton1: Doesn't exist on Nunchuk, Classic/Sixaxis/Gamepad Select
Any.LeftThumbButton2: Doesn't exist on Nunchuk, Classic Home, Sixaxis/Gamepad L3
Any.LeftThumbButton3: SixAxis Home

Vibration

Any.Vibration1 and Any.Vibration2 control vibration.

Wiimote (Nintendo Wii Remote)

If your computer has Bluetooth, you can control games with the Nintendo Wii Remote. The Wiimote has accelerometers, buttons, an infra-red camera, LEDs, vibration, a speaker, and storage for Miis. Or you can connect a Nunchuk (with joystick, two buttons, and accelerometers) or Classic Controller (with 9 digital buttons, two analog shoulder buttons, two joysticks and a D-Pad). Every feature is now supported.

Bluetooth

You need a Bluetooth adapter. Cheap ones for old Bluetooth versions work fine for me. Different ones come with different Bluetooth drivers called Bluetooth Stacks. Some adapters allow you to install other stacks, some don’t. All Bluetooth stacks are very buggy. But different stacks have different bugs. Most Bluetooth stacks will now work with GlovePIE, but you may need to try the Trouble-Shooter > Bluetooth Fix menu in GlovePIE.

Some Bluetooth devices won’t work on Vista. On Vista I normally use the Microsoft stack. The Microsoft stack needs Bluetooth Fix switched on.

If you have the BlueSoleil Bluetooth Stack, you will be able to connect a Wiimote whenever GlovePIE is loaded, just by pressing the 1+2 buttons on the Wiimote at the same time. The blue B icon will turn green to show that it is connected. Note: BlueSoleil is buggy and unstable, and this feature may cause GlovePIE to stop responding for a while, or may not work sometimes, or sometimes causes BlueSoleil to beep the PC speaker. If this feature causes problems for you, you can disable it by checking the TroubleShooter > No Auto-Bluetooth Connect menu in GlovePIE.

You can show the Bluetooth window by choosing the CP-Settings > Bluetooth menu in GlovePIE.

If you don’t have BlueSoleil, then you will need to connect the Wiimotes manually. You need to start the Bluetooth program, hold down the 1+2 buttons on the Wiimote, tell your Bluetooth program to search for devices, then when it finds a device either tell it to search for services and connect to the HID service, or tell it to connect. There is no PIN (as far as we know) so tell your Bluetooth program to skip the PIN step, or not to use a PIN. Only after it is completely connected, can you release the 1+2 buttons.

You can disconnect a Wiimote at any time, whatever Bluetooth Stack you use, by holding down the Wiimote’s power button. GlovePIE does not have to be running for that.

Normally only connected Wiimotes will show up in GlovePIE. Sometimes unconnected ones will still show up making the connected one Wiimote2, depending on your Wiimote stack.

Using the Wiimote in GlovePIE

You can use the GUI to assign the Wiimote’s actions, or you can use scripting with the “Wiimote” object. The GUI has an automatically detect input feature which will work with the Wiimote or keyboard, or mouse, or joystick, or P5 Glove. The GUI is easy, but it can’t edit or create anything too complex. You should use scripting to make fancier scripts.

GlovePIE supports up to 8 wiimotes (in theory) although only 7 per adapter. Sometimes there will be phantom Wiimotes that show up in GlovePIE but aren’t really there. 

In scripts you can access Wiimotes with “Wiimote” followed the number of the Wiimote, followed by a dot, then followed by the Wiimote property you want to use. eg.  Wiimote1.Home
If you leave out the number then it will assume you mean Wiimote1.

Buttons

The Wiimote has the following buttons, which are either true or false:

Up, Down, Left, Right,
A, B,
Minus, Home, Plus
One, Two

The Power button, and the Sync button (hidden under the battery compartment) aren’t implemented yet.

Motion Sensing

The Wiimote also has three accelerometers which measure forces/accelerations, in each of the three dimensions. Force and Acceleration are basically the same thing, since the mass is constant (F=ma). In GlovePIE they are labelled like this: X is to the right (of the wiimote), Y is up (from the wiimote buttons), and Z is forwards (or wherever the wiimote is pointing). This is the left-handed Direct3D system. 

If you drop a Wiimote and it is in freefall, all the forces will be zero. BUT if you are holding a wiimote up so that it doesn’t fall, then you are pushing it upwards with a force equal to the force of gravity, but in the upwards direction. If you hold the Wiimote flat then the force holding it up will be in the +Y direction, but if you point the Wiimote at the ceiling then the force holding it up will be in the +Z direction. This helps us measure the Wiimotes tilt as well as its acceleration.

There are three values that you should never use anymore, because they are obsolete and only for backwards compatability: RawForceX, RawForceY, and RawForceZ. If your script is currently using them, then replace them with the calibrated force values below. Remember the calibrated force values don’t need an offset, and they are about 1/30 the size of the RawForce values.

There are three calibrated force values:

gx, gy, and gz

They can be zero for no force/acceleration, 1 for the same amount of force/acceleration as gravity, or any value in between or outside that range. There is also the vector version:

g

The accelerations above are effectively measured in Gs. You can use them for measuring actual acceleration, or for measuring tilt.

If you prefer acceleration values in other units, you can use these values:

RawAccX, RawAccY, and RawAccZ.

They are measured in Metres Per Second Per Second. But GlovePIE supports units so you can do things like this:

RawAccX in miles per hour per second

to get the value in different units.

The RawAcc values still include gravity.

If you want to get the real acceleration without gravity then you should use the following values instead:

RelAccX, RelAccY, and RelAccZ

They are not very accurate because it is hard for GlovePIE to separate out the force of gravity, but it makes a good attempt.

All these acceleration values are relative to the Wiimote’s orientation. So Z is wherever the Wiimote is pointing, not necessarily a fixed direction.

Rotations

The Wiimote doesn’t contain gyros (BOO!!!), so it has no way of determining the yaw rotation without using an imitation sensor bar. But it can sort-of tell which way is down, based on the force of gravity. This allows it to measure pitch and roll rotations. You can use the following values:

Pitch, Roll
SmoothPitch, SmoothRoll

The angles are all in degrees.

Pitch is the vertical angle. It is 90 when the wiimote is pointing at the ceiling, -90 when it is pointing at the ground, 0 when it is flat, and a value in between for angles in between.

Roll is how much the top is tilted towards the right. It is -180 or +180 when the Wiimote is upside-down, -90 when it is on its left side, +90 when it is on its right side. and 0 when it is flat.

Pitch and Roll attempt to filter out accelerations. This may make them slightly jagged. You can use SmoothPitch and SmoothRoll if you don’t mind getting the wrong result if the wiimote moves, but you do want it to be smooth.

There is also a rotation matrix, for those who prefer it. It is a 3x3 Direct3D style rotation matrix:
RotMat

Sensor Bar

The sensor bar is just a bunch of Infra Red lights which are always on. You can make your own fake sensor bar with candles, Christmas tree lights, or Infra-Red remote controls with a button held down. Or you can order a wireless sensor bar off the internet, or you can build your own.

You can read the position of the infra-red dots that the Wiimote can see with:
wiimote.dot1x, wiimote.dot1y
…
wiimote.dot4x, wiimote.dot4y

You can tell whether an infra-red dot can be seen with Wiimote.dot1vis  to Wiimote.dot4vis

You can tell the size of a dot (between 0 and 15) with Wiimote.dot1size to Wiimote.dot4size

The size will always be reported as 16 if your script uses the Nunchuk or Classic Controller, because the report needs to contain more information.
LEDs

You can set the 4 LEDs on the Wiimote by setting:

Wiimote.Leds

to a value between 0 and 15. It is binary.

Or you can set:

Wiimote.Led1, Wiimote.Led2, Wiimote.Led3, and Wiimote.Led4

to either true or false individually.

Force Feedback

You can activate force feedback by setting:

Wiimote.Rumble

to either true or false

Speaker

You can play sounds on the Wiimote simply by setting these values:

Frequency, Volume

If you set Frequency to 0 it will switch the speaker off. If you set it to non-zero it will switch the speaker on again. The frequency is measured in Hz. Don’t confuse frequency with pitch, they are different in this context.

You can set the volume to a value between 0 and 2, (between 0% and 200% in other words). I don’t recommend setting it above 100% though, unless you want to go deaf.

You can also turn the speaker on and off by setting either of these values:

Speaker, Mute

Setting speaker to true switches on the speaker (slowly) and setting it to false switches off the speaker. Setting Mute to true mutes the speaker, and setting it to false un-mutes it. Using 
”Mute” works faster than using “Speaker”. Note that you don’t need to turn the speaker on if you set the frequency, because setting the frequency to non-zero does it automatically. Turning sound on and off with mute is also faster than doing it by changing the frequency to 0.

You can also set the sample rate with this variable:

SampleRate

Currently GlovePIE only supports sample rates around 3640 Hz. Sample rates must be multiples of 280 added or subtracted from that value. The default is 3640 Hz. The sample rate is also measured in Hz. The sample rate will automatically increase if you set the frequency higher than 1820 Hz. There isn’t much point in changing the sample rate.

Nunchuck, Classic Controller, Guitar, and Balance Board

To tell whether a Nunchuk, Classic controller, Guitar or BalanceBoard is plugged in, use these values:

Wiimote.HasNunchuck
Wiimote.HasClassic
NEW! Wiimote.HasGuitar
NEW! Wiimote.HasBalanceBoard

They are true or false. Note that GlovePIE now knows the difference between classic controllers and guitar controllers. Old guitar scripts should still work, as long as they didn’t use HasClassic to detect the guitar. But new guitar scripts won’t work if you have a real classic controller plugged in.

The Balance board doesn’t really plug into the expansion port of a real Wiimote. But the Balance Board has its own built in dummy Wiimote. So if you have one real Wiimote, and one Balance Board, then Wiimote1 might be your real Wiimote, and Wiimote2 might be the Balance Board. Then Wiimote1.HasBalanceBoard will be false, and Wiimote2.HasBalanceBoard will be true. You could then the read the balance board by reading Wiimote2.BalanceBoard.Weight or you could read the balance board by reading BalanceBoard2.Weight (which is just a shorter way of saying Wiimote2.BalanceBoard.Weight).

To detect which expansion is plugged in you can also use these, which return a number that says which expansion it is:

Wiimote.Expansion
NEW! Wiimote.Expansion2

Wiimote.Expansion will be one of these values:

0: No expansion
1: Unidentified expansion, or not plugged in properly
2: Nunchuk
3: Classic controller, WiiGuitar or anything compatable with a classic controller (anything that can be used to navigate the Wii Home menu has this value).
4: ??
5: ??
6: Balance Board 
…Other values are possible if someone creates a new expansion.

Wiimote.Expansion2 will be one of these values:

0: No expansion
1: Unidentified expansion, or not plugged in properly
2: Really a nunchuk
3: Really a classic controller
4: Really a balance board
5: Really a guitar controller
…Other values are possible if someone creates a new expansion.

Note that these values all have 2 added to them, compared to the decoded values of the last two bytes of the expansion registers.
Nunchuk

The Nunchuk has accelerometers too! Most of the same acceleration values and rotation values are the same as the Wiimote, so see the description in the sections above. The difference is the Nunchuk accelerometers have lower range.

The Nunchuk also has two buttons. NOTE: Unlike a playstation controller, pushing in the joystick is not a button, don’t try it. The two buttons are:

CButton
ZButton

Unlike the other controllers, you need the word “Button” on the end, because Z is the name of an axis and I’m reserving it for future axis use.

The Nunchuk also has a joystick. It uses the following values:

JoyX, JoyY

JoyX is -1 to the left, 0 in the middle, and +1 to the right.
JoyY is -1 up, 0 in the middle, and +1 down.

These are the same ranges used by PPJoy and other joysticks.

The Nunchuk does NOT have vibration, or a speaker.

Classic Controller

The classic controller does NOT have accelerometers or rumble, or a speaker!

The classic controller does have an unexplained lock button in the top centre, which physically opens and closes two slots in the back. The two slots can’t connect to anything and seem totally pointless. The lock button can’t be read.

You can read the following buttons:

a, b, x, y
Minus, Home, Plus
Up, Down, Left, Right
ZL, ZR
LFull, and RFull

They are either True or False.

The L button and the R button (LFull, and RFull above) also have analog versions:

L, and R

They will be between 0 and 1. Although mine won’t go below 0.03 when fully released, and yours may not reach 1 when fully pressed.

There are also two joysticks. I’m calling the one on the left Joy1, and the one on the right Joy2.

Joy1X, Joy1Y, 
Joy2X, Joy2Y

They are between -1 and 1, the same as the Nunchuk joystick described above.

NEW! Guitar Hero 3 Controller

The WiiGuitar comes with Guitar Hero 3. It has 5 coloured fret buttons, which are either true or false. It has a strum switch which can be strummed upwards, or strummed downwards. You can hold down the strum switch in either position, or you can strum it so that it is only held for a short time. The strum switch is not analog. There is a Plus and a Minus button on the Guitar. There is a whammy bar (a lever) which is analog. It will be between 0 and 1, although it's range is actually much less than that, and varies between guitars. It also has a joystick.

In addition, you can still use the buttons on the front of the Wiimote, which will be embedded in the guitar face. And you can use the accelerometers in the Wiimote to find the angle or motion of the Guitar. And you can play notes through the Wiimote speaker, and you can flash the lights on the Wiimote. I don't know whether you can feel the Wiimote vibrate or not. The IR will no longer work when the guitar is plugged in, and neither will the B button.

The WiiGuitar values will only be true if a Guitar is plugged in. If a Classic controller or Nunchuk is plugged in, the values will always be false.

You can use the following WiiGuitar fields:

Fret1, Fret2, Fret3, Fret4, Fret5: The five fret buttons counting from the end. These are either true or false. You can also use the names of the colours instead.
Plus, Minus: The + and - buttons on the guitar. They are true or false.
JoyX, JoyY: The joystick. It is between -1 and 1, like any joystick in GlovePIE.
Joy: The joystick as a 2D vector [x,y].
StrumUp: True when the strum switch is held in the up position.
StrumDown: True when the strum switch is held in the down position.
WhammyBar: A value between 0 and 1.
Exists: The same as Wiimote.HasGuitar. True if the guitar is attached, false if it isn't.

NEW! Wii Fit Balance Board

The Wii Fit (or Wii Fitness) Balance Board is a new Wii controller that you stand on. It has four weight/pressure sensors, one in each corner. 

They haven’t been released in Australia yet, so this is untested, and based only on our translations of a Japanese website. GlovePIE’s Balance Board support probably doesn’t work.

It behaves like an extra dummy Wiimote with a Balance Board attachment plugged in. The dummy Wiimote’s LED1 controls the power LED on the top of the board, and the dummy Wiimote’s A button is actually the power button on the Balance Board. The other things on the dummy Wiimote do nothing, except the built-in balance board “attachment”.

You can read the raw values of the four sensors like this:

Wiimote2.BalanceBoard.RawFrontLeft
Wiimote2.BalanceBoard.RawFrontRight
Wiimote2.BalanceBoard.RawBackLeft
Wiimote2.BalanceBoard.RawBackRight

Different sensors vary quite a bit.

To read the weight from the sensors in kilograms, use this:

Wiimote2.BalanceBoard.FrontLeft
Wiimote2.BalanceBoard.FrontRight
Wiimote2.BalanceBoard.BackLeft
Wiimote2.BalanceBoard.BackRight

Wiimote2.BalanceBoard.WeightLeft
Wiimote2.BalanceBoard.WeightRight
Wiimote2.BalanceBoard.WeightFront
Wiimote2.BalanceBoard.WeightBack

Wiimote2.BalanceBoard.Weight

You can also use the Balance Board as a human joystick, like this:

Wiimote2.BalanceBoard.JoyX
Wiimote2.BalanceBoard.JoyY
Wiimote2.BalanceBoard.Joy

They are values between -1 and 1 just like any other joystick.

There are some unknown values you can try:

Wiimote2.BalanceBoard.EE
Wiimote2.BalanceBoard.QuestionQuestion

You can set the LED like this:

Wiimote2.BalanceBoard.LED = true

You can read the button like this:

Wiimote2.BalanceBoard.Button
Low level stuff

You can read the data reports from the Wiimote with:

debug  = Wiimote.InByteString

Or you can read them individually with:

var.a = Wiimote.InReport
var.b = Wiimote.InByte1

You can send data reports to the Wiimote with this function (it has no dot):

WiimoteSend(1, 0x12, 1, 0x33)

The first parameter of WiimoteSend is the Wiimote number you want to send it to, normally 1. The second parameter is the report number. The remaining parameters are the report payload. In this case, the report tells the Wiimote to start vibrating, and to send data via report 0x33.

The one-byte reports can also be sent another way by setting one of these values (it will only send the report when the value changes):

Wiimote.Report11, Wiimote.Report13, Wiimote.Report14, Wiimote.Report15, Wiimote.Report19, Wiimote.Report1A

You can set bytes in the Wiimote’s onboard memory (where Miis are stored) with the WiimotePoke command, and read bytes from its memory with the WiimotePeek command.

WiimotePoke(1, 0x04B00033, 0x33)
var.value = WiimotePeek(1, 0x04B00033)

The first parameter is optional, and it is the Wiimote number. The second parameter is the address. The third parameter is the value you want to set it to (between 0 and 255).

Note that the Nunchuk and Classic Controller have their own memory space which is mapped to the Wiimote’s when they are plugged in.

You can set the Channel with Wiimote.Channel. The Channel should be a hexadecimal number between 0x30 and 0x3F, which determines which information the Wiimote sends back to the computer.

Don’t use these low level functions unless you know what you are doing and have read the www.wiili.org/Wiimote page. One person has bricked their nunchuk by experimenting with writing to all its addresses (although that is how we discovered how the nunchuk works).

Multiple Wiimotes

You can tell how many Wiimotes there are with Wiimote.Count

You can access a particular wiimote by putting a number after the word “wiimote” and before the dot. For example:

Enter = wiimote2.A

You can tell whether a particular Wiimote exists with Wiimote.Exists

You can’t read the Serial number (as text) anymore with Wiimote.Serial, because I disabled it. It rebooted computers with BlueSoleil when you tried to read the serial.

Don’t forget to sync both Wiimotes with the PC before you try to use them.

P5 Glove

You can read the P5 Virtual Reality Glove values using either the “P5” object, or the “Glove” object. Using Glove is better if you want to put a number after it (“P52” would look silly).

The Virtual Reality glove has lots of different fields you can set, in four main categories: Buttons, Finger bends, Location, and Rotation.

Buttons
The P5 Glove has 4 buttons on the back, labelled A, B, C, and D. The D button doubles as the Power button. You can only read the D button while the user is turning the glove on (while the user is turning the glove off, the D button is always false). If you want to use the D button, you need to tell the user to double click it, (to your script it will look like a single click).

You can read them like this:

debug = P5.A

They are either true or false.

If the glove is out of range, or switched off, or behind something, they will always be false.

Fingers
The five fingers are called Thumb, Index, Middle, Ring and Pinky. They return a value between 0 and 63 (unless you assign them to something true or false, like a key, then they return true if >= 32).

0 means as straight as the maximum straightness for that finger during calibration.
63 means as bent as the maximum bent-ness during calibration.

You use them like this:

Enter = p5.Index > 32

Raw Finger Bends

If you want to know the raw bend sensor values, then you can get an approximate version by reading the values AbsoluteThumb, AbsoluteIndex, AbsoluteMiddle, AbsoluteRing, and AbsolutePinky. They are converted from the 0 to 63 values, so it won’t give you more precision, or tell you if it is outside the calibration range. But it will let you know what raw bend sensor value it corresponds to. The raw bend sensor values are backwards (small means bent) and may be roughly between 400 and 1000. These values are less useful than the ones above.

Joint Angles

If you want to know what angles the bend values represent for the different finger joints, then you can use the ThumbProximal, ThumbMedial, ThumbDistal, IndexProximal, IndexMedial, IndexDistal, etc. values.

Proximal is the closest joint on your finger where it joins the hand, Medial is the middle one, and Distal is the finger tip joint. Note that the thumb’s proximal joint is actually INSIDE your hand.

These angles are only guesses, since the P5 only returns one value per finger between 0 and 63. They only work if you calibrate the glove to the range: fingers completely flat to fingers bent as much as possible.

Index Fingertip Position

You can find the position of the index finger tip by using the P5.IndexPos vector. It is measured in P5 Units (51.2ths of an inch, or half a mm) but you can convert it to whatever units you want. It is unfiltered, so you should use the Smooth function, preferably with a both an average and a deadband parameter. It is calculated based on the position of LED 4, and the joint angles above. It is not very reliable, it is more experimental.

Finger Gestures

You can recognize various hand-shapes in GlovePIE by using the 5 letter codes for fingers. Each letter corresponds to one finger, and can be either “l” (L) for straight, “r” for partly bent, “n” for completely bent, or “x” for “don’t care”. Note that the shape of the letter corresponds to the shape of the finger.

So for example, to find out if the user is pointing, use this:

debug = p5.xlnnn

The first letter x means don’t care about the thumb. The second letter (l) means the index finger must be straight. The third letter (n) means the middle finger must be completely bent, and the same for the last two fingers.

Note that the thumb comes first in these codes, even if it is your left hand.

You can use any five-letter combination of those letters.

It will be either true or false.

You can set the values of p5.maxl and p5.minn to values between 0 and 63 if you don’t like the default bend amounts that correspond to those three ranges.
Finger Velocity and Acceleration

I stupidly decided to use the absolute values for velocity and acceleration. So they will be in the opposite direction to what you expect, and have a different magnitude. Sorry.

They are FingerVelocity0, FingerVelocity1, FingerVelocity2, FingerVelocity3, and FingerVelocity4 for velocity, and FingerAcceleration0, etc. for acceleration.

These values probably need smoothing, or they aren’t very useful.
Values that have nothing to do with Finger Bends

Beware of values like ThumbUp or FingersForwards. They have absolutely nothing to do with the thumb or finger bends, and are actually about the glove’s ROTATION. They say what direction those parts WOULD be pointing IF they were not bent at all.

Location

The glove’s filtered location is given by P5.x, P5.y, and P5.z. Or you can read them as a vector with P5.Pos.

The units are in P5 Units by default. P5 Units are equal to a 51.2th of an inch, or roughly half a mm. But because GlovePIE supports units, you can read these values in any units that you want, like this:

debug = p5.x in cm

Also GlovePIE allows you to compare values that are in different units like this:

Enter = p5.x > 1.5 inches

GlovePIE uses Left-Handed coordinates, like Direct3D does (which was a bad decision in hindsight). So x is the sideways position, with negative to the left and positive to the right. y is the vertical position with negative down and positive up. And z is the forwards/backwards position with negative away from the screen and positive towards the screen. Note that the z value will always be negative, since you can’t physically move the hand past the receptor. That makes z values confusing, and I’m sorry. Just get used to negative numbers.

Filtering

You can set the amount of filtering with P5.FilterFrames and P5.FilterDistance. P5.FilterFrames is the number of past frames to average together with the current frame to calculate a smoother position. P5.FilterDistance is the minimum distance the glove has to move in order to register any movement at all. It is good for keeping the position completely still even if you move the glove a tiny bit. It is in P5 Units by default, but you can use any units you want.

eg.

P5.FilterFrames = 10
P5.FilterDistance = 5 mm
debug = P5.x

Unfiltered Position

You can also read the unfiltered position of the glove using P5.AbsoluteX, P5.AbsoluteY and P5.AbsoluteZ. You can also read it as a vector with P5.AbsPos.

Relative Mode

Back in the dark ages of the P5 Glove, it was only able to support Relative Mode. Relative Mode means it works like a 3D mouse. You can read its movements, but you can’t tell where it is currently located in physical space. The advantage of relative mode is that it is smoother, and that it doesn’t matter if the rotation isn’t calculated correctly. The disadvantage is that you don’t know where the glove is.

You can read the Relative Mode position with P5.RelativeX, P5.RelativeY, and P5.RelativeZ, (or P5.RelativePos for a vector). The units are still in P5 Units.

I recommend using RelativeMode (with the smooth function) for things like aiming where you don’t care about the glove’s position, and the normal x, y, and z values when you care about the position.
LED Positions

The glove has 8 yellow infra-red LEDs mounted on it at fixed locations. The receptor needs to see one of them to calculate a rough position, and three of them to calculate a rotation. It can see a maximum of four of them at a time.

You can read the positions of each LED individually with P5.Led0x, P5.Led0y, P5.Led0z, P5.Led1x, P5.Led1y, P5.Led1z, …, P5.Led7x, P5.Led7y, P5.Led7z. The default units are P5 Units. You can also use P5.Led0Pos, etc. if you prefer a vector.

If the LED is visible it will return the actual position of the LED, otherwise it will guess the position based on the positions of the other LEDs it can see.

LED 0 is the top one above the right hand side of your wrist.
LED 1 is the one to the right of your little (pinky) finger.
LED 2 is the one on the left of your little (pinky) finger.
LED 3 is the one on the back of your hand.
LED 4 is the one near your index finger.
LED 5 is the top one above your thumb.
LED 6 is the lower one on the right hand side of your wrist.
LED 7 is the lower one near your thumb.

You can tell whether an LED is visible or not, using p5.Led0vis, etc.

You can also find out the raw (well almost raw) tan values that the glove returns for that LED. There are 3 values. 

“h” is the horizontal position measured by the sensor at the top of the receptor tower. Negative means left, positive means right. 512 means roughly 45 degrees to the left, -512 means roughly 45 degrees to the right. It can exceed that range.

“v1” is the vertical position measured by the sensor at the top of the receptor tower. Negative means down, positive means up. This sensor is angled downwards about 10 degrees. The range is the same.

“v2” is the vertical position measured by the sensor at the bottom of the receptor tower. This sensor is angled up about 17 degrees.

These values are p5.Led0h, p5.Led0v1, p5.Led0v2, p5.Led1h, etc.

These raw tan values are the ONLY values the glove hardware gives the computer about the position of the glove. Everything else is to be calculated from these values. Use them for testing how to improve the driver, or if you think you can do better than my driver.

If you want to know the position of the LEDs relative to the glove (their unchanging physical position) use p5.ActualLed0Pos, p5.ActualLed1Pos, etc. They are vectors. Their values never change, unless you buy a new version of the glove.

P5.LedsVisible tells you how many LEDs are currently visible.
Speed and Acceleration

You can tell how fast the glove is moving with P5.Speed. It is just a number measured in P5Units Per Second.

If you want to know the velocity (speed with direction) of the glove, on the x, y and z axes, then you can use P5.XVelocity, P5.YVelocity and P5.ZVelocity. They are also in P5Units per second.

XVelocity is how fast it is moving to the right. Or negative if it is moving to the left.
YVelocity is how fast it is moving up. Or negative if it is moving down.
ZVelocity is how fast it is moving towards the screen. Or negative if it is moving backwards.

If you want a vector, use P5.Velocity.

To find out how fast the velocity is increasing (the acceleration) you can read P5.XAcceleration, P5.YAcceleration, and P5.ZAcceleration. Or the vector P5.Acceleration. They are measured in metres per second per second.

Velocity is good for detecting punches and gestures like that.

When the glove is in range

You can tell whether or not the glove is visible to the receptor by reading P5.InRange, or by the number P5.LedsVisible.

If you want to know WHY the glove isn’t visible you can use one of these other values:

P5.BehindSomething
P5.SwitchedOff
P5.TooFarLeft
P5.TooFarRight
P5.TooFarUp
P5.TooFarDown
P5.TooFarForward
P5.TooFarBack
P5.UntrackableAngle

They are all only GlovePIE’s best guess. They are not guaranteed. The UntrackableAngle one doesn’t work very well.

They are true if the glove isn’t visible for that reason, and false if the glove is visible or if it is not visible for some other reason.

Rotation
Note that rotation requires at least 3 LEDs to be visible and accurate before it can be calculated. Otherwise the rotation will stay much the same as it was before.
Directions of Parts of the Hand

The recommended way to get the glove’s orientation in GlovePIE is to use the values that tell you which way the parts of the glove are facing.
For example:

debug = P5.FingersForward

Or if you want to be more precise:

debug = P5.FingersForward and P5.PalmDown

You need to specify two values to uniquely identify an orientation.

IMPORTANT: These do NOT refer to the finger bends. The fingers are assumed to be straight and the thumb is assumed to be sticking out the side of your hand at right angles, for the purposes of these rotation values. The finger bends make no difference to these values.

You can check the direction of the following parts:

BackOfHand, Fingers, Palm, Thumb, or Wrist

And you can check for one of the following directions:

Forwards, Backwards, Left, Right, Up, Down

The part will always be pointing in one, and only one, of those 6 directions. It can be pointing in that direction +/- 45 degrees in order to count as that direction.

Note that a Left handed glove the thumb is on the other side. So for example:

debug = P5.FingersForward and P5.ThumbRight

Will be palm-up if your glove is right-handed, and palm-down if your glove is left-handed. If you want to make your right-handed glove left-handed, please download the Dual Mode Driver and read the instructions about how to create a .ini file.
Diagonal Directions

You can also check for the diagonal directions:

DownBackLeft, DownBack, DownBackRight,
DownLeft, DownRight
DownForwardsLeft, DownForwards, DownForwardsRight
BackLeft, BackRight
ForwardsLeft, ForwardsRight
UpBackLeft, UpBack, UpBackRight
UpLeft, UpRight
UpForwardsLeft, UpForwards, UpForwardsRight.

But these directions overlap with each other, and the non-diagonal directions above. For example the Fingers might register as both DownBackLeft and DownBack at the same time.

It needs to be within +/- 45 degrees of that angle for it to be true.

Vague Directions

If you don’t want to be that precise, for example, you only want to know whether the palm is facing up or down, you can use the vague directions.

For example:

debug = P5.PalmUpVague

Will be true whenever the Palm is closer to being up than it is to being down. Either PalmUpVague or PalmDownVague will always be true. Even if the palm is facing left or forwards.

In other words, the angle only has to be +/- 90 degrees.

Vague also works for diagonals

Strict Directions

If you want to be even more precise than normal, you can use the strict directions. For example if you want to know if the palm is facing directly up, but not facing diagonally up and to the left, then you can use the Strict version.

eg.

Debug = P5.PalmUpStrict.

This also works with diagonals (which is the whole point).

The angle must be within 22.5 degrees.

Angle from Directions

You can also tell how far the part of your hand is from pointing in that direction. For example, how close are your fingers to pointing forwards?

You can do comparisons like this:
Enter = P5.FingersAngleFromForward <= 30 degrees

That will hold down the Enter key whenever the fingers are within 30 degrees of pointing forwards.

Direction Vectors and Matrix

The other way of finding which direction the parts of the hand are pointing is to use the following direction vectors:

P5.FingersDir
P5.ThumbDir
P5.PalmDir
P5.WristDir
P5.BackOfHandDir

These are vectors, which means they have an x, y, and z component like this:

[1, 0, 0]

The total length will equal 1.

The first component is the x component. It says how much of it is pointing in a right/left direction. In this example it is 1 which means it is pointing all the way to the right. The second component is the y component, which says how much of it is pointing in an up/down direction. In this case none, because it is pointing exactly to the right. The third component is the z component, how much is pointing forwards/backwards, in this case none.

There is also a rotation matrix, which is just three rows of direction vectors like the ones above.

The third row of the rotation matrix is the fingers direction. The second row is the back of hand direction. And the first row of the rotation matrix is the right hand side of your hand direction (which isn’t mentioned above). 

You can read the components of the rotation matrix individually, by specifying the row first and then the column:

debug = p5.mat31
In the above example it will use the fingers direction (row three), and get the x component of it. In other words, how much are the fingers pointing to the right? 

debug = p5.mat22

The above example would get the back-of-hand direction (row two) and get the y component of it. In other words, how much is the back of the hand pointing up?

You can also get the entire matrix as a 3x3 matrix, by using P5.RotMat.

You can also access the unfiltered rotation matrix with P5.UnfilteredRotMat for the whole matrix, or P5.UnfilteredRotMat11 to P5.UnfilteredRotMat33.

Using Trigonometry to Convert Them to Angles (Isn’t as hard as you might think)

If you understand a very tiny bit of trigonometry then you can convert those numbers into an angle. For example, if we want to know how much the fingers are pointing up, that would be p5.mat32. But that is a fraction, between 0 and 1, or 0 and -1. To convert a fraction to an angle, you use the inverse of the sin, cos, and tan functions. The inverse is called ArcSin, ArcCos, and ArcTan in GlovePIE (But in C they are shortened to asin, acos and atan).

ArcSin converts 0 to 0 degrees, and converts 1 to 90 degrees.
ArcCos does the opposite, and converts 0 to 90 degrees and converts 1 to 0 degrees.
ArcTan converts 0 to 0 degrees and converts 1 to 45 degrees.

Note that you have to use these functions, rather than just multiplying by 90, because it is not linear. Sin(45 degrees) is actually about 0.7 not 0.5.

Let’s say we want an angle which says how much the fingers are angled upwards. We want 1 (completely up) to be 90 degrees, so we choose ArcSin.

debug = ArcSin(p5.mat32)  // a half-circle kind of pitch

You could also write it like this:

debug = ArcSin(p5.FingersDir[2]) // the same half-circle kind of pitch

That will tell you how much the fingers are angled upwards. If they are angled downwards the value will be -90 degrees. In other words, this is a version of the “pitch” angle.

There is also an ArcTan2 function, which works like ArcTan but it can give you the angles of a full circle if you give it the fractions for the two directions. It can tell the difference between 45 degrees and 225 degrees.

ArcTan2 works like this: the first parameter is the fraction which corresponds to 90 degrees and the second parameter is the fraction that corresponds to 0 degrees. For example, lets say we want to find the horizontal angle of the fingers, with 0 degrees meaning forwards, 90 degrees meaning right, 180 degrees meaning backwards and -90 degrees meaning left. So we will use the forwards component (z or column 3) of the fingers for the second parameter (which represents 0 degrees) and we will use the right component (x or column 1) of the fingers for the first parameter (which represents 90 degrees). So it looks like this:

debug = ArcTan2(p5.mat31, p5.mat33) // a full circle, from forwards, kind of yaw

This gives us a version of the “yaw” angle. Note that it is different from what we did above, because we want a complete circle for the yaw, from -180 to 180. But for the pitch we only wanted -90 to +90. Of course, we just decided that arbitrarily. We could have got different versions of the angles. For example, with these two angles, if you pitch your hand back 110 degrees then it will be considered to be a yaw of 180 degrees and a pitch of 80 degrees, because we made pitch only go up to 90, and yaw go all the way around. We could just as easily choose the opposite way around:

Lets say we want the pitch to have forwards as 0, up as 90, and backwards as 180. That means we need to use ArcTan2 (for the whole circle) and we want the first parameter (90 degrees) to be the y part of the fingers row, and we want the second parameter (0 degrees) to be the z part of the fingers row.

debug = ArcTan2(p5.mat32, p5.mat33)   // a full-circle, from forwards, kind of pitch

That kind of pitch actually makes less sense to most people, since if you tilt your hand up a bit (say 10 degrees), then rotate it to the right 80 degree, the pitch will stay the same as you expect, but if you then rotate it 20 degrees more to the right, the pitch will change to 170 degrees. Of course that was the same problem we would have with the yaw if we rotated up more than 90 degrees, the yaw would have jumped.

There is no perfect set of angles that makes the most sense. It depends which angles suit you and your application most. Just think what information you really want.

Euler Angles

Euler angles suck. They exist solely to make a set of three steps to get to a particular orientation. Individually they mean nothing though.

If you rotate an object several times, the order is important. A different order gives you a different orientation. Not all programs use the same order, or directions.

The Euler angles GlovePIE provides are in the order pitch, yaw, roll. First it rotates the hand upwards by the first angle. Then it takes the result of that and twists that thing sideways to the right by the second angle. Then whatever is left you tip over to the right by the third angle, so that whatever was at the top after the first two steps becomes at the right after the third step.

So the Pitch, Yaw and Roll angles provide one way to get to the current orientation of the glove in three steps.

Anyway, these angles can be read form P5.Pitch, P5.Yaw, and P5.Roll, but their usage is not recommended.

Angular (rotation) velocity (speed)

If you want to measure how fast the hand is rotating, you can use PitchVelocity, YawVelocity and RollVelocity. Unlike Pitch, Yaw and Roll, they are not steps, and they do make sense individually. Their usage is recommended.

They are measured in degrees per second.

PitchVelocity is how fast the front is becoming the top.
YawVelocity is how fast the front is becoming the right.
RollVelocity is how fast the top is becoming the right.

You can also get the acceleration in degrees-per-second per second. They are PitchAcceleration, YawAcceleration and RollAcceleration.

All these values may require smoothing to make them worth using.

MIDI

MIDI is a system for musical instruments to communicate with each other and with computers.

If you want to control MIDI software with GlovePIE, you will need to download and install MidiYoke from http://www.midiox.com/myoke.htm. MIDI Yoke will also allow you to read MIDI output from other programs.

Otherwise you can only control the soundcard or external MIDI devices. You can also read input from MIDI devices.

MIDI devices can be plugged into your joystick port, if you have the right cable. Then you can use them for input.
MIDI Ports
Each computer may have multiple MIDI output ports, and multiple MIDI input ports. The output ports will include your sound card, software synthesisers, the external ports on the back of your computer, and MIDI Yoke ports. Input ports will include the input ports on the back of your soundcard, and the MIDI Yoke ports. There is no guarantee that input and output ports match up. There is also an output port called the “MIDI Mapper” which in Windows 3.1 was a complicated system for forwarding MIDI messages to different devices, but now it is just a setting in control panel which forwards everything to a chosen device.

Each MIDI port has 16 channels. It is possible to have multiple MIDI devices connected to the same port, but for each one to be listening to a separate channel. It is also possible for one MIDI device to use all the channels, with each channel representing a separate virtual instrument.

You can set which MIDI output port you want GlovePIE to use, like this:

midi.DeviceOut = 2

Where 1 is the first output port, and 0 is the MIDI mapper.

Future writes to midi values will then go to port 2.

You can set the input port like this:

midi.DeviceIn = 2

But there is no guarantee that input port 2 is connected to the same device as output port 2. In fact, most of the time it won’t be.

If you want to know what the name of that device is, use:

debug = midi.OutDevName

or

debug = midi.InDevName

You can also look at OutVersion, OutTech, InVersion and InTech.

Instead of using the default ports that you set with DeviceOut and DeviceIn, you can also use several ports at once, by explicitly putting them after the “midi” part of the value. For example to set the volume on (the default channel) of MIDI output port 2:

midi2.Volume = 50%

Or you could do the same thing like this:

midi.DeviceOut = 2
midi.Volume = 50%

A better way to control output ports, is to use the different port categories:

midi.mapper.volume = 50%
midi.soundcard.volume = 50%
midi.software.volume = 50%
midi.wavetable.volume = 50%
midi.playback.volume = 50%
midi.yoke2.volume = 50%
midi.external2.volume = 50%

You can optionally put a number after the category to use the nth device in that category.

If you want to set the default output device to one of those, then you can read from the DeviceOut or DeviceIn on one of those devices and use it to set the default device. Observe:

midi.DeviceOut = midi.yoke3.DeviceOut

That will set the default output port to the 3rd MIDI Yoke port.

MIDI Channels

Each MIDI port has 16 channels, numbered 1 to 16. You can set the default channel like this:

midi.DefaultChannel = 4

Each channel has its own instrument number, volume and other parameters, and each channel can play multiple notes at once.

Or you can specify the channel explicitly, like this:

midi.Channel4.Volume = 50%

You can specify both the port and the channel like this:

midi.Yoke3.Channel4.Volume = 50%

All the channels behave the same, except for Channel 10 on General MIDI devices (which most devices are these days). Channel 10 is always in percussion mode, and will play a different percussion instrument for each note of the scale. You can turn General Midi on or off by setting:

midi.GeneralMidi = True
or 
midi.GeneralMidi = False

If you tell GlovePIE to play a percussion instrument, it will automatically do it on channel 10, regardless of which channel you specify.

Playing notes

You can turn notes on and off by setting the note to either true or false. For example to play middle C when the press the space bar:

midi.MiddleC = space

Middle C is octave 5, so you can also write it like this:

midi.C5 = space

You can also play other notes like this:

midi.FSharp8 = Enter

The lowest note is C0. The highest note is G10.

Striking notes with a particular velocity

If you want more control over how fast the note is struck, you can set the velocity instead. If you turn notes on and off like above they will always be struck with a velocity of 50%. But you can also turn notes on by setting their velocity:

if pressed(Space) then midi.C5Velocity = 80%
if released(Space) then midi.C5Velocity = 0

Note that velocities are between 0 and 1 (80% is the same as 0.8). Setting the velocity to 0 turns the note off. Notes are always released with a release-velocity of 50%.

Some instruments will sound the same whatever velocity you use.

Applying Pressure to a note

You can also apply extra pressure to a note when it is down. By default 0 extra pressure is applied. Applying extra pressure to a note may not have any effect on most instruments. The extra pressure is called “aftertouch”.

if pressed(space) then
  midi.C5 = true
  midi.C5Aftertouch = 20%
else
  midi.C5 = false
end if

You can also apply extra pressure to every note that is played on that channel by setting the ChannelPressure:

midi.ChannelPressure = 20%
Playing notes by number

You can also play a note by setting midi.FirstNote to the number of the note you want to play. There are 12 notes per octave, including sharps and flats (anyone who tells you 8 is an idiot, even without sharps and flats there are only 7). C0 is note number 0. C1 is note number 12. MiddleC is note number 60. G10 is note number 127. You need to set it to -1 to turn the note off.

if pressed(Space) then midi.FirstNote = 60
if released(Space) then midi.FirstNote = -1

There is also a SecondNote, ThirdNote, and FourthNote, so you can play 4 notes by number at once. 

These notes are all struck (and released) with a velocity of 50%.

You can’t read the note you are playing, so if you want to remember it, store it in a variable. Reading from midi.FirstNote will read from the MIDI input device instead!

Playing Percussion

You can play percussion instruments by setting one of the percussion instruments:

midi.AcousticBassDrum = space

  AcousticBassDrum, BassDrum2, SideStick, AcousticSnare, HandClap, ElectricSnare, LowFloorTom, ClosedHiHat, HighFloorTom, PedalHiHat, LowTom, OpenHiHat, LowMidTom, HighMidTom, CrashCymbal1, HighTom, RideCymbal1, ChineseCymbal, RideBell, Tambourine, SplashCymbal, Cowbell, CrashCymbal2, Vibraslap, RideCymbal2, HiBongo, LowBongo, MuteHiConga, OpenHiConga, LowConga, HighTimbale, LowTimbale, HighAgogo, LowAgogo, Cabasa, Maracas, ShortWhistle, LongWhistle, ShortGuiro, LongGuiro, Claves, HiWoodBlock, LowWoodBlock, MuteCuica, OpenCuica, MuteTriangle, OpenTriangle

You can also set other percussion instruments by setting Percussion0 to Percussion127.
Reading Notes

You can read whether notes are being played on a MIDI input device like this:

debug = midi.MiddleC

or you can read by number by using midi.FirstNote (SecondNote, ThirdNote and FourthNote don’t work for MIDI input yet).

if midi.FirstNote = 60 then say(“hello”)

You can use these methods to control games by using a MIDI keyboard:

Space = midi.MiddleC
Up = midi.MiddleDSharp
Down = midi.MiddleE
Left = midi.MiddleD
Right = midi.MiddleE

You can also read the velocities and aftertouches.

Setting the instrument

You can set the instrument to a number between 1 and 128 by setting midi.Instrument. See a midi instrument chart on the internet if you want to know what each instrument is.

If you normally use instrument numbers between 0 and 127, you can set midi.Instrument0 instead.

Note that each channel has its own instrument (except channel 10 on GeneralMidi)

By default instrument 1 is used, which is normally a piano.

If your instrument contains multiple banks of instruments, you can also set BankSelectLevel. But you need to divide by 16383… for example, to set it to bank 2:

midi.BankSelectLevel = 2 / 16383

The first bank is bank 0. Instrument banks may have no effect on some devices.

Pitch Wheel

You can also set the pitch bend using the pitch wheel.

The pitch wheel can be set to a value between 0 and 1. Setting it to 0.5 means no effect.

midi.PitchWheel = 50%

Each channel has its own Pitch Wheel.

You can also try setting the PitchBendRange to change the range that the maximum pitch bend represents, in semitones.

Controls and Change Control messages

Each channel of each device has a set of 32 different 14-bit controls, numbered 0 to 31, and a set of 7-bit controls numbered 64 onwards. You can also access the two 7-bit components of the 14-bit controls separately, as Coarse and Fine controls or as byte controls numbered 0 to 63.

Some of them have standard names, and some of them just have numbers. But you can use any control by number if you prefer. Sometimes the controls aren’t used for their defined function.

For example, setting Midi.Volume is the same as setting Midi.Control7.

So you can either write this:

midi.Volume = 52.38%

or

midi.Control7 = 52.38%

It is a 14-bit control, so it is a value between 0 and 1, but with about 4 or 5 decimal places. In this case we are setting it to 0.5238

You can also access the coarse and fine parts separately, like this:

midi.Control7Coarse = 0.5

midi.Control7Fine = 0

The controls numbered 32 to 63 are the same as the fine parts of the controls numbered 0 to 31. So Control7Fine and Control38 are the same thing.

You can also use ByteControl7 to refer to the coarse part of Control7, or ByteControl38 to refer to the fine part of Control7.

Controls numbered 64 onwards are only 7-bit controls, and have no coarse or fine components. They are also set to a value between 0 and 1, but they will be accurate to less decimal places (about 2). They also often have names.

RPN (Registered Parameter Numbers)

MIDI also has RPN messages. These include:

MasterTuning, MasterTuningCoarse, MasterTuningFine, PitchBendRange, TuningProgramSelect and TuningBankSelect.

You can set them in GlovePIE like this:

Midi.PitchBendRange = 2 octaves
Midi.MasterTuning = -0.5 semitones // all notes will be off by half a note

I can’t guarantee these will work.

You can also set other RPN values manually, Eg. to set RPN 0,1 like this:

Midi.Control101 = 0 / 127
Midi.Control100 = 1 / 127
Midi.DataEntry = 0.75 // whatever value you want to set it to
Midi.Control101 = 127 / 127
Midi.Control100 = 127 / 127

NRPN (Non Registered Parameter Numbers)

There are no standard NRPN values (that’s the point of NRPN). But you can set them manually like this (for NRPN 0,1):

Midi.Control99 = 0 / 127
Midi.Control98 = 1 / 127
Midi.DataEntry = 0.75 // or whatever value
Midi.Control99 = 127 / 127
Midi.Control98 = 127 / 127

SysEx (System Exclusive)

You can set standard System Exclusive midi values like this:

Midi.GeneralMidi = true
Midi.MasterVolume = 76%
Midi.IdentityRequest = pressed(space)

If you want to set other System Exclusive midi values, you need to save them in a .SYX file. You can then tell GlovePIE to send that file like this:

Midi.SetupFile = “c:\coolsounds.syx”

Speech

You need to install SAPI 5.1, (It comes with Windows XP and Office XP) to use speech in GlovePIE. If you don’t have speech recognition installed, download and install this:

http://www.chant.net/downloads/sapi51.exe

Unless you have XP Pro, in which case download and install this to get a later version:

http://www.voicewebsolutions.net/community/tutorials/voicewebstudio/salt/MicrosoftInternetExplorerSpeechAddInSetup.exe

If you just want the Mike and Mary text-to-speech voices for XP, download this:
http://www.aldostools.com/sapi51xp.msi

Making GlovePIE talk

You can make GlovePIE speak by using the “say” command, like this:

say(“Hello World”)

Or you can set speech.text, like this:

speech.text = “Hello World”

The advantage/disadvantage of setting speech.text is that it won’t say it again until you set speech.text to something different. Say will say it every time you use say.

You can get it to speak in different voices like this:

speech.sam.text = “Hello, my name is Sam.”
speech.mike.text = “Hello, my name is Mike.”
speech.mary.text = “Hello, my name is Mary.”

If Mike and Mary sound the same as Sam, and you have XP, then you need to download this (don’t download this on Vista!!!):
http://www.aldostools.com/sapi51xp.msi

You can also use other popular text to speech engines by name, if you have them.

If you want to try out and download some high-quality voices, and don’t mind using up disk space, you can go to:

http://www.cepstral.com/demos/

You can download the Cepstral voices, but they are trial versions which add stuff at the start of everything it says. Please buy them rather than cracking them with a keygen, as they are good quality.

There are lots of other speech parameters you can read or set. Just type “speech.” and use the code completion box.

Speech Recognition
You can use Speech recognition in GlovePIE to control games with speech.

Just use the said( ) function like this:

Enter = said(“jump”)

That will press the “Enter” key, whenever you say “jump” into the microphone.

You can also use the AskedFor( ) function like this:

Four = AskedFor(“rocket launcher”)

The AskedFor function will only trigger if you say something like “can I please have a rocket launcher?”. It will not trigger if you just say “rocket launcher” or “rocket launcher please”. AskedFor does understand lots of different ways of phrasing a request, everything from “I need a rocket launcher now” to “please give me a rocket launcher”.

Amount of Confidence Required

You can change the amount of confidence required by specifying a second parameter which is a number. The default is 2.

Eg.

Enter = said(“jump”, 3)

The higher the number, the more confidence is required to recognise it. If it thinks you said “jump” when you actually said “pump”, set the confidence value higher. If it doesn’t recognise it when you do say “jump” set the confidence value lower.

The following confidence values exist:

0: No confidence required: Will always recognise at least one of the phrases in your script, no matter how different what you said is, unless you only said the first word of a multi-word phrase.
1: Partial phrase, low confidence: Will quickly guess what you said based on the first syllable or two, unless it is a multi-word phrase in which case it will wait for the start of the last word. Will accept anything that is even vaguely close, and respond quickly.

2: Partial phrase, medium confidence: Will quickly guess what you said based on the first syllable or two, unless it is a multi-word phrase. It will accept things that are reasonably close to what it is expecting.

3: Partial phrase, high confidence: Will quickly guess what you said based on the first syllable, unless it is a multi-word phrase. It will only accept things that it is sure matches.

4: Complete phrase, low confidence: Will wait until it is sure you have finished speaking, and it has processed the complete phrase before guessing. The whole phrase must be vaguely close to what it was expecting.

5: Complete phrase, medium confidence: Will wait until it is sure you have finished speaking, and it has processed the complete phrase before guessing. The whole phrase must be reasonably close to what it was expecting.

6: Complete phrase, high confidence: Will wait until it is sure you have finished speaking, and it has processed the complete phrase. The whole phrase must be very close to what it was expecting.

If your script has a phrase that contains another phrase, like this:

W = Said(“weapon”)
X = Said(“weapon fire linked”)

then you need to set the shorter phrase to wait for the complete phrase, like this:

W = Said(“weapon”, 5)
X = Said(“weapon fire linked”)

Otherwise it will press W before you have finished saying “weapon fire linked”.

If you are expecting the user to say things that aren’t in your script, and you want them to be ignored, you need to set the confidence reasonably high.

Other than that, which confidence levels you choose is up to you. 

But if GlovePIE isn’t recognising what you say, the first thing you should do is go to the Speech Control Panel (You can use the CP-Settings menu in GlovePIE), and do some training. You should also change the recognition settings in Control Panel to change how quickly it responds, and how much accuracy it requires.

Push-to-talk
If you only want it to recognise you when you are holding down a button, you need to set Microphone.Enabled. eg.

Microphone.Enabled = joystick1.Button1

It will only trigger the speech commands when you are holding down the joystick button. The rest of the time it will ignore your speech. It doesn’t turn the microphone off, or let other applications use it, it just ignores you when it hears you.

You can also do the opposite, like this:

Microphone.PushToNotTalk = joystick1.Button2

Now, when you hold down button 2 it will ignore anything you say. Good for when you are talking to your team-mates.

Don’t use Microphone.PushToTalk, it doesn’t work.

Other Microphone Stuff

There are other Microphone values you can read and set.

For example:

Mouse.LeftButton = Microphone.AudioLevel > 0.5

That will click the left mouse button whenever you make a loud noise.

TooFast, TooSlow, TooLoud and TooQuiet will be true for an instant when GlovePIE is trying to recognise your speech but you are speaking too fast, slow, loud or quietly.

For example:

if Microphone.TooFast then say(“Don’t talk so fast.”)
if Microphone.TooSlow then say(“You need to talk faster.”)
if Microphone.TooLoud then say(“Stop shouting. I’m not deaf.”)
if Microphone.TooQuiet then say(“Speak up, I can’t hear you.”)

HeardNoise will be true for an instant when GlovePIE is trying to recognise your speech and it hears some other noise.

if Microphone.HeardNoise then say(“I can’t hear you over the noise.”)

InPhrase will be true while you are speaking, and false while you are not.
InSound will be true while there is sound which might be speech, and false otherwise.

Microphone.CompletePhrase will be whatever text you said, but it only works if you said one of the phrases in your script. It will only be set to something for an instant. For example:

var.saidsomething = said(“hello”) or said(“goodbye”) or said(“thank you”)
if microphone.CompletePhrase <> "" then Say(microphone.CompletePhrase)

Microphone.PartialPhrase will be set to whatever partial text you said, but it only works if you said one of the phrases in your script. It will only be set to something for an instant. For example:

var.saidsomething = said(“this is a test”) or said(“does it work”) or said(“I don’t know”)
if microphone.PartialPhrase <> "" then debug = microphone.PartialPhrase

Speak slowly for the above example. Notice how what you say appears one word at a time in the debug box?

NEW! Virtual Reality HMDs

GlovePIE supports two kinds of Virtual Reality head mounted displays. The Vuzix (previously known as Icuiti) VR920, and the eMagin Z800.

The Trimersion could theoretically also be used with GlovePIE, if you have Windows 2000, XP, or Vista because GlovePIE supports reading multiple mice and multiple keyboards individually, and the Trimersion acts as a mouse and keyboard.

The VR920 has 3 accelerometers, and 3 magnetometers (a compass). The accelerometers are for measuring gravity which tells you pitch and roll, and the compass is for measuring yaw.

The Z800 also has 3 accelerometers, and 3 magnetometers (a compass). But unlike the VR920, it also has 3 rate gyros which help make the other measurements more accurate. 

The main values that you will use are the yaw, pitch, and roll. Which are angles in degrees.

Yaw is the angle when you turn your head left and right. Positive means to the right.
Pitch is the angle when you look up and down. Positive means up.
Roll is the angle when you tilt your head to the side. Positive means to the right.

Normally you will want to either emulate the mouse for mouse-look games (either first person, or third person ones), or emulate TrackIR for games that support TrackIR (mostly flight simulators, or car racing games, but some other types of games).

For a list of TrackIR enabled games, see here: 
http://www.naturalpoint.com/trackir/03-enhanced-games/enhanced-games-all.html
Note that you may not use GlovePIE with America’s Army. America’s Army is not a game, it is a military recruitment drive. Real people die because of it.

In mouse-look games, it is not possible to get head-tracking to work perfectly. Almost all mouse-look games use some sort of acceleration based on how fast the mouse is moving, and you can’t switch it off. They also often cap the maximum amount that you can move the mouse in a certain period. These mean that when you turn 90 degrees in one direction and then turn back 90 degrees, you will not end up looking exactly the same direction you were at the start, only nearly. Also when you look up and down, the vertical angle in game can get out of sync with the angle of your head. Ideally you want the game to have a key which re-centres the view. 

See the VR920Scripts folder for examples of TrackIR emulation, and mouse-look emulation.

NEW! VR920

You can read the following angles from the VR920:

VR920.yaw, VR920.pitch, and VR920.roll

Yaw will be between -180 and +180. Pitch will be between -90 and +90. Roll will be between -180 and 180.

There is also VR920.ContinuousYaw which is between –infinity and +infinity.  It keeps counting when you keep turning in the same direction. So if you spin around twice, it will go up to 720 degrees.

For First Person Shooters you should always use VR920.ContinuousYaw.

These values are all read straight from the VR920 SDK supplied by Vuzix. These values will shake a little bit, because the sensors are not precise. You also need to run the iWear Calibration program that came with your VR920. It is very important that it is calibrated correctly.

You may want to use GlovePIE’s Smooth function. It averages several frames together. This causes lag, but it also makes it smoother. For example:

Var.yaw = smooth(vr920.yaw, 10)

will smooth the current frame by averaging it with the previous 10 frames. You can choose how many frames to use. The maximum is 30.

Don’t use the SmoothPitch, and SmoothRoll values for smoothness. They are not actually smoothed, they are the same as the Wiimote.SmoothPitch and Wiimote.SmoothRoll, and are calculated from the acceleration, making the false assumption that all acceleration is due to gravitỵ. 

GlovePIE also lets you read the VR920’s acceleration and compass sensors directly. This completely bypasses the SDK, and reads the values straight from the USB port. Before this will work, you need to choose VR920 Accelerometer Calibration from the CP-Settings menu, and calibrate the accelerometers. This calibration only affects GlovePIE and has nothing to do with other programs that use the VR920.

RawForceX, RawForceY, and RawForceZ give you the raw, uncalibrated accelerometer values. You don’t need to use the accelerometer calibration for this to work. RawMagnetX, RawMagnetY, and RawMagnetZ give you the raw compass values. Note that the Z value will always be high, presumably due to the magnets in the VR920 earphones.

gx, gy, and gz give you the calibrated accelerometer values. This includes both the opposite of gravity plus the real acceleration of the glasses. They will be zero for no force, or +/-1 for 1G of force. If you drop the glasses (not recommended!!) all the values will be zero. But if you are holding them up, then gy will be 1 and gx and gz will be 0.

 RawAccX, RawAccY and RawAccZ are the same as gx, gy, and gz, but are measured in metres per second per second, instead of Gs. So they will be 9.8 m/s/s for 1G of force.

RelAccX, RelAccY, and RelAccZ are intended to be just the acceleration with the force of gravity filtered out. This is not completely possible, and thus not completely accurate. But it gives you a reasonable approximation of the acceleration of the glasses. It is measured in 9.8 m/s/s. Unfortunately the acceleration of the glasses is normally caused by turning your head, rather than by moving your head.

StrictPitch, and StrictRoll are the pitch and roll of the glasses calculated by GlovePIE from the accelerometers. It does not use the SDK, and is only affected by GlovePIE’s accelerometer calibration, not by the iWear calibration. It is only calculated when the glasses are not accelerating and thus the total force is about 1G. 

SmoothPitch and SmoothRoll are the pitch and roll, but they are updated (wrongly) even when the glasses are accelerating. This will produce a slightly wrong answer when the glasses are accelerating, but it will be smoother instead of jerky.

BedYaw and BedPitch are the equivalent of Yaw and Pitch, but for when you are lying down in bed.

Z800

 I don’t have a Z800, so many of these features aren’t really tested.

Z800 has yaw, pitch, and roll, measured in degrees.

But it also has many other values from all the various sensors.

In addition to reading the inputs, you can also set the screen brightness, colours, etc.

I’ll document this more later. In the meantime, you can look at VR920 examples and apply the same techniques.

Trimersion

I don’t have a Trimersion, and nobody with a Trimersion has tested my program, so this section is entirely theoretical.

The Trimersion head-tracker acts as an ordinary mouse. So you can read it like this:

Var.mickeys = 1200
Var.yaw = MapRange(mouse2.DirectInputX, -var.mickeys,var.mickeys, -90 degrees,90 degrees) 
Var.pitch = MapRange(-mouse2.DirectInputY, -var.mickeys,var.mickeys, -90 degrees,90 degrees)

You may need to experiment with changing var.mickeys to other numbers. I don’t know how many mickeys the Trimersion emulates per 90 degrees of rotation.

That code allows you to read it independently of the real mouse, which will probably be mouse1. There is no guarantee that the Trimersion will be mouse2. If you are using a laptop, then the touchpad will probably be mouse1, the mouse will probably be mouse2, and the Trimersion will probably be mouse3.

Normally, all the mice, including the Trimersion, will control the system mouse, and thus control the view in an FPS.

But GlovePIE can swallow the mouse input so that it doesn’t control the system mouse anymore, if that is what you want…

mouse.Swallow = true
mouse.DirectInputX += Delta(mouse1.DirectInputX)
mouse.DirectInputY += Delta(mouse1.DirectInputY)
mouse.LeftButton = mouse1.LeftButton
mouse.RightButton = mouse1.RightButton
mouse.MiddleButton = mouse1.MiddleButton
mouse.XButton1 = mouse1.XButton1
mouse.XButton2 = mouse1.XButton2

debug = var.yaw+', '+var.pitch

Adding the above code will allow mouse1 to control the system mouse, but the Trimersion and other mice will not have any effect on the system mouse.

This is good for if you want to emulate TrackIR with the Trimersion, while controlling other things with the mouse, or for emulating the joystick with the Trimersion.

To emulate a TrackIR you would add:

FakeTrackIR.yaw = var.yaw
FakeTrackIR.pitch = var.pitch

If you have more than one real mouse, you might want to add “or mouse2.LeftButton1”, and “+ Delta(mouse2.DirectInputX)”, etc.

The Trimersion also acts as a keyboard. And GlovePIE can also read multiple keyboards individually. But unlike with the mouse, GlovePIE can’t swallow the keyboard while still reading keyboards individually. So you can tell whether input came from the real keyboard or the Trimersion, but you can’t suppress the input from one while still allowing the input from another. However you can tell the game to ignore the input from the regular keys on both, and have the regular keys on the Trimersion emulate a different set of keys, and have the regular keys on the keyboard emulate a separate different set of keys. In that way, the keyboard and the Trimersion can control different things.

Trimension acts like the following keys (you can use either keyboard2.whatever, or key2.whatever, it makes no difference):

Key2.R, Key2.Space, Key2.E, Key2.F, Key2.Esc, Key2.Enter, Key2.Up, Key2.Down, Key2.Left, Key2.Right, Key2.G, Key2.Tab, Key2.X, Key2.Q, Key2.Z, Key2.LCtrl, Key2.W, Key2.A, Key2.S, Key2.D

Mouse2.LeftButton, Mouse2.RightButton, Mouse2.DirectInputX, Mouse2.DirectInputY

NEW! TrackIR

GlovePIE allows you to read from a real TrackIR, or emulate a fake TrackIR. You can even do both at once. You can also read from other Optitrack devices.

TrackIR support has changed since the previous version. The previous version only used the OptiTrack SDK which anyone can download. For the new version I reverse engineered the TrackIR API that games use, so GlovePIE can also read TrackIR the same way games do. And I added TrackIR emulation.

Let me know if any of the TrackIR reading doesn’t work, because I don’t have a TrackIR to test it on.
NEW! TrackIR emulation

Warning! TrackIR emulation support adds settings to your registry. The first time you run a script that uses fake TrackIR emulation, GlovePIE will add a registry setting which tells programs where to look for the TrackIR driver. GlovePIE tells it that the TrackIR driver is in the GlovePIE directory. The TrackIR driver in the GlovePIE directory is a fake one. This fake driver will then be loaded by any TrackIR game, even if GlovePIE is not running. The fake driver just returns zeroes if GlovePIE isn’t running. GlovePIE will also add another registry entry which says where the real driver is, so that GlovePIE can still use the real driver, but other programs can’t.

To restore the registry to the correct setting, use the CP-Settings > Restore Real TrackIR menu. You only need to do that if you have a real TrackIR and you want to be able to use it instead of the fake one.

There are six values that TrackIR tells the games: Yaw, pitch, roll, x, y, and z.

The first three are angles in degrees. Yaw is turning to the right, pitch is looking up, and roll is tilting your head to the right. The last three are the position of your head: x is how far you moved your head to the right, y is how far you moved your head up, and z is how far you moved the head towards the screen. The position is measured in metres.

In your script you can set them like this:

TrackIR.yaw = VR920.yaw

But I recommend that you be more specific that it is the FakeTrackIR:

FakeTrackIR.yaw = vr920.yaw

They both work, but to prevent ambiguity for things like TrackIR.yaw = TrackIR.yaw + 1, you can specify RealTrackIR.yaw or FakeTrackIR.yaw. Normally reading TrackIR.yaw uses the real TrackIR, but writing it uses the fake one.

When you set the roll, you need to think about whether you want the game world to turn the same direction as your head to exaggerate the movement (like real TrackIR), or do you want the game world to turn in the opposite direction as your head turns, to counteract the movement (like in VR glasses)?

For Virtual Reality, you want roll to be the opposite, like this:
FakeTrackIR.roll = -vr920.roll

For a fixed screen not attached to your head, you want roll to be in the same direction, like this:
FakeTrackIR.roll = wiimote.roll

In both cases it will feel backwards if you do it wrong.

Unfortunately, how a game responds to TrackIR input is not entirely standardised. The value that turns you 180 degrees in one game, might only turn you 90 degrees in another game. I tried to guess which behaviour was most common and used that as the standard, but it still varies from game to game. So sometimes you will have to multiply it or divide it to make it right:

FakeTrackIR.yaw = vr920.yaw / 2

Some games need a totally different multiplier or divisor for the roll than for pitch and yaw. And some games may invert the roll.

Many TrackIR games limit the maximum amount you can turn in each direction. But some games allow you the complete 360 degrees. 

To tell which TrackIR game is running, you can read FakeTrackIR.ProfileID. It will be a different number for different games.

You can read FakeTrackIR.Active to tell whether any TrackIR game is currently reading from the fake TrackIR. Games set their ProfileID when they start, but often only set Active while in the main game play part.

FakeTrackIR.RequestFormat tells you which data the TrackIR game wants. GlovePIE provides the same complete data regardless of what the game wants. I’m guessing the RequestFormat is a bitflag representing the x, y, z, yaw, pitch, and roll fields. This may allow you to work out which fields a game supports. But games sometimes ask for the wrong RequestFormat.
 
FakeTrackIR.WindowHandle tells you the handle of the window that the game registered with TrackIR. 

FakeTrackIR.Cursor is true or false and can be turned on or off by games. I don’t know what it means. It may be an attempt to switch between TrackIR being used for mouse-look and being used for TrackIR.

FakeTrackIR.Version is the only value that you can set and the game reads. Games often ask for the version of TrackIR. You can tell it whatever you want. I don’t know the format of this value.

To get a list of at least 87 TrackIR games you can try, see:
http://www.naturalpoint.com/trackir/03-enhanced-games/enhanced-games-all.html

The license agreement prohibits use with America’s Army.

TrackIR emulation won’t work with applications that use the Optitrack SDK.

NEW! Reading TrackIR like a game

In theory, if you have a real TrackIR, then GlovePIE can read from it the same way a game would. GlovePIE pretends to be a game, and asks for the Yaw, Pitch, Roll, x, y, and z values. The TrackIR software must be running for this to work.

You can read it like this:
RealTrackIR.yaw, RealTrackIR.pitch, RealTrackIR.roll, RealTrackIR.x, RealTrackIR.y, and RealTrackIR.z

Note that these values are NOT the angles and position of the physical vector clip. They are the angles and position of the virtual in-game head which is normally a large exaggeration of the physical movements. You can change that behaviour if you want.

Also note that TrackIR may change the way the x, y ,z values move based on the yaw, pitch, and roll values. Which is good if you are only interested in the virtual head, but bad if you are interested in the real head. You can turn that feature off in TrackIR.

You can also read the TrackIR version:

RealTrackIR.version

Raw TrackIR camera input

You can also use the Optitrack SDK to read from a physical TrackIR camera. This existed in previous versions, but didn’t work, because I forgot to start the camera. In theory it should be fixed now. Although some of the names have been changed so as not to clash with the new TrackIR stuff.

The TrackIR software should NOT be running when using the TrackIR like this.

TrackIR.Illumination controls the IR LEDs on the TrackIR that shine on things so TrackIR can see them. It is true or false.

TrackIR.GreenLED controls the green status LED. TrackIR.RedLED controls the red LED. TrackIR.BlueLED controls the blue LED.

You may need to set the lights a couple of times if their actual state didn’t match the state GlovePIE thought they were in.

VectorClipX, VectorClipY, and VectorClipZ give the 3D position of the vector clip.
VectorClipYaw, VectorClipPitch, and VectorClipRoll give the orientation of the vector clip.

You can tell whether it can see all the dots that make up the clip by reading AllDotsVisible.

You can set Dist01, Dist02, Dist12 and DistoL if you have a custom vector clip that doesn’t match the standard one. They are the distances between dots and between certain points on the clip.

If you don’t have a vector clip, or if you just want to read dots individually, you can use:

Dot0x, Dot0y, Dot1x, Dot1y, Dot2x, Dot2y.

You may need to read the width and the height of the camera resolution, which are in Width, and Height. You can also read the framerate of the camera in FrameRate. Note that this might not match GlovePIE’s frame rate.
 
You can also read Serial, ModelNumber, ModelName, RevisionNumber, and RevisionName. 

NEW! Novint Falcon

The Novint Falcon is a consumer-priced 3D input device with extremely sophisticated haptic feedback. To create the sense of touch, or physical objects accurately, it normally updates the forces 1000 times per second. GlovePIE can’t really go that fast, but you can set GlovePIE’s frame rate quite high with lines like this:

PIE.FrameRate = 500Hz

With the normal grip, the falcon has 4 buttons, which you can read as follows. They are either true or false:

Falcon.Button1, Falcon.Button2, Falcon.Button3, and Falcon.Button4

But the Falcon supports grips with up to 31 buttons, so GlovePIE also supports Button5 to Button31 just in case Novint releases new grips one day.

The Falcon can measure the 3D position of the grip, which will be in these values:

Falcon.x (How far to the right the grip is)
Falcon.y (How far up the grip is)
Falcon.z (How far towards the body of the falcon the grip is)

They are all measured in metres by default. But GlovePIE supports units, so you can use whatever units you want, like this:

Key.D = Falcon.X > 1 inch
Key.A = Falcon.X < -1 inch
Key.W = Falcon.Z > 3 cm
Key.S = Falcon.Z < -3 cm

The range of the Falcon is small, it goes from -2 inches to +2 inches in each direction.

You can also read the position as a vector, with falcon.pos.

Warning! Danger! The Falcon also allows you to set forces. This means that the falcon can push your hand in any direction. It also means it can injure you, break things, or whatever else a robot arm can do. Even if your script is perfect, GlovePIE is not, it has bugs, so there is a chance that the grip may move about in unexpected ways. So hold it carefully and in such a way that it won’t injure you if it moves suddenly. And start by using only small forces in your script, then make them bigger.

You can set the forces in the 3 directions like this:

Falcon.ForceX, Falcon.ForceY, Falcon.ForceZ

The force is in Newtons by default. The force of Gravity is -9.8 Newtons per kilogram. That means that when you hold something that weighs 100 grams in your hand, it will push down on your hand with a force of 1 Newton.
But you can also use units of weight to specify the force, and GlovePIE will convert them. For example:

Falcon.ForceY = -0.5 pounds

That will make the grip feel half a pound heavier.

The maximum force is about 2 pounds, 1 kilogram, or 10 Newtons.

Here is an example of how to make a force at a certain point:

If falcon.x < -1 inch then 
falcon.ForceX = 2 newtons 
else 
falcon.ForceX = 0
end if

That makes the falcon push you back if you try to move too far to the left.

You can also set the force as a vector with Falcon.Force

Falcon.exists will be true when the falcon (and driver) exists, and false when it doesn’t.

Falcon.homed will be true when the falcon has been homed, and false when it hasn’t.

See http://home.novint.com/community/message_boards.php for discussion on using the Novint Falcon.

NEW! 3DConnexion SpaceNavigator, etc.

GlovePIE now supports 3DConnexion 6DOF input devices like the SpaceNavigator, SpaceTraveler, SpaceExplorer, and SpacePilot. These are the modern descendents of the original SpaceBall which you might have heard of many years ago.

GlovePIE calls them all “SpaceBall”.

The “SpaceBall” provides 3 position values, and three rotation values:

SpaceBall.x, SpaceBall.y, and SpaceBall.z.

X is how far you are pushing to the right
Y is how far you are pulling up
Z is how far you are pushing forwards (away from your body)

SpaceBall.yaw, SpaceBall.pitch, and SpaceBall.roll

Yaw is how far you are twisting it to the right
Pitch is how far you are tilting it upwards
Roll is how far you are tilting it to the right

The spaceball can only move a limited amount in each direction.

The units for x, y, z, yaw, pitch and roll are the same. But they depend on the settings in the control panel. 3DConnexion does that deliberately so that users can choose the speed and sensitivity they want outside the applications. So the maximum value could be 80 or it could be more than a thousand, depending on control panel settings.

It is not recommended to require the full use of the spaceball’s range. Most of the time users will only use about 75% of the range. 

Most people will only have a SpaceNavigator. It has two buttons. But the user can choose what those two buttons are in Control Panel. You need to know what those buttons are set to, if you want to use them in GlovePIE.

For example if the left button is set to be the “Fit” button in control panel, then you need to read it like this in GlovePIE:

Enter = SpaceBall.Fit

In control panel, the buttons can be set to either “Fit”, “ApplicationPanel”, or “Button1”… “Button29”.

If you have a SpaceExplorer or SpacePilot, then there will be more than two buttons and they might have fixed functions.

You can detect what kind of spaceball it is, by reading SpaceBall.Type.
You can also detect whether the SpaceBall exists by reading SpaceBall.exists.

If you want the angles in some other form besides Yaw, Pitch, and Roll, then you can use AxisAngle or a rotation matrix. For the rotation matrix, just use SpaceBall.RotMat. For AxisAngle just use SpaceBall.Axis to get the axis vector that the rotation is rotating around, and use SpaceBall.AxisAngle to get the angle of rotation around that axis.

NEW! PlayStation 3 SIXAXIS

The SIXAXIS, or PS3 Controller, is intended to be a wireless Bluetooth HID device, which can also connect via a USB charge cable.

Unfortunately it is NOT a valid Bluetooth device, so it can’t connect to the PC via Bluetooth without rewriting the operating system. Rewriting the operating system is only an option on Linux.

So you can only use it with GlovePIE while it is plugged into a USB port with a USB charge cable. So it effectively becomes a wired controller instead of a wireless one.

If you don’t own a PS3, you will need to buy a USB charge cable. I bought a MadCatz one.

Installation

True to form, it is also NOT a valid HID device, so the only way to read it from Windows is by using a special driver called LibUSB-win32. This driver allows it to communicate with USB devices directly without going through the normal windows HID layer.

You can download LibUSB-win32 from here:
http://sourceforge.net/project/showfiles.php?group_id=78138

There are two varieties of LibUSB-Win32. There is a "Filter Driver", which allows the program to talk to any USB device but also allows Windows to talk to it at the same time. This means you can use the SIXAXIS with GlovePIE and as a normal joystick at the same time.

The other variety is the the "Device Driver", which is a replacement driver for that particular device, and only allows GlovePIE and other libusb-win32 programs to talk to that hardware. Windows will no longer be able to talk to that device if you use the device driver. The "Device Driver" works fine with GlovePIE (you will need PPJoy to use it as a fake joystick) but won't work with anyone else's sixaxis driver, because they rely on windows being able to talk to it.

On Windows Vista, I couldn't get the Filter Driver to install successfully, so you will probably need to use the "Device Driver" if you have Vista. On my Windows XP computer I got the Filter Driver to install, but it crashes whenever I run GlovePIE or any of the SIXAXIS drivers made by other people. However it must work for some people, because all the other sixaxis drivers say to use the Filter Driver. So if you are not using Vista, try the Filter Driver first.

The filter driver is easy to install. So you won't need any help with that.

The device driver is much harder to install. It comes with a program called "inf-wizard" in the "bin" folder. You need to run this program. Then you need to plug in your SIXAXIS into a USB port that you DON'T want to use for the SIXAXIS. Because windows will detect it and install its own driver on that port, stopping that port from working with LibUSB. If windows asks you about installing a driver when you plug it in, say no. Then press "Next" in inf-wizard. Then choose the device which says "0x054C, 0x0268" (your SIXAXIS). Then click next. You don't need to change the manufacturer name or device name unless you want to, so click next. Then it will pop up a save dialog box. You need to save it in the same bin folder where you ran inf-wizard from. It doesn't matter what you call it, but I called it "sixaxis-libusb.inf". If User Account Control won't let you save it in the bin folder, save it somewhere you can find it, and then afterwards copy the ".inf" and ".cat" files into the bin folder manually. You now have a libusb driver for the sixaxis ready to install. You can't install it by right-clicking, so instead go into Control Panel, Add [New] Hardware. Click Next. Choose to install the hardware from a list, Show all devices, have disk. Then browse to the bin directory. Then your libusb device driver should be installed. Now you need to plug your SIXAXIS into a port that you haven't plugged it into before, and it should work. To use it on a port that you have plugged it into before, you will need to remove the existing HID driver installed by windows.

Once you have got the libusb installed, and your sixaxis plugged into a new usb port, you should use the testlibusb-win program to test it. It should include the Sony Playstation 3 controller in its list. If it doesn't, and the driver says version -1,-1,-1,-1 it means the filter driver didn't install correctly, so you may want to uninstall it and either try again, or use the device driver instead. On the other hand, if the driver version is right, but the Sony playstation 3 controller isn't listed, try plugging it into a different port and running testlibusb-win again. If it doesn't show up in testlib-usb then it won't work with GlovePIE.

Once you have libusb-win32 working, you can run GlovePIE.

Using SIXAXIS in GlovePIE

The SIXAXIS won't do anything until you switch it on by pressing the PS button.

There is a chance glovepie will freeze up when you try to use the sixaxis due to a bug in Libusb-win32. This happened to me on my WinXP computer. If this happens then you won't be able to end the task in task manager, and you have to reboot. Uninstall the filter driver if this is happening and try the device driver.

When you start your script, you should leave the SIXAXIS sitting still for a few seconds while it calibrates the rate gyro so it can calculate Yaw. The SIXAXIS accelerometers should be calibrated first from the CP-Settings menu for this to work properly.

To read the raw accelerations, use SixAxis.RawForceX, Sixaxis.RawForceY, and Sixaxis.RawForceZ. When the sixaxis is in free-fall all the forces will be 0. When you hold it up against gravity, the force of you holding it up will be included, along with any actual accelerations. X means towards the right of the sixaxis (in the direction of the circle button), Y means towards the top of the sixaxis, Z means towards the front of the sixaxis (where the USB cable is).

You should not use the raw accelerations in your scripts. Instead you should go to the CP-Settings menu and choose SIXAXIS calibration. Then follow the instructions to calibrate all your SIXAXES. Once you have saved the calibration you will be able to use SixAxis.Roll, SixAxis.Pitch, SixAxis.SmoothRoll, and SixAxis.SmoothPitch to get the SIXAXIS rotation. You will also be able to use SixAxis.gx, SixAxis.gy, and sixaxis.gz to get the raw accelerations (including gravity) measured in Gs. You can then use SixAxis.RelAccX, SixAxis.RelAccY, and SixAxis.RelAccZ.

To read the analog sticks use SixAxis.Joy1x, Joy1y, Joy2x, and Joy2y. They are between -1 and 1. You can also read DPadX and DPadY the same way.

Pushing vertically down on the analog sticks gives you the L3 and R3 buttons. They are digital and can only be true or false. The Select, Start, and PS buttons are the same.

The other buttons can all be read as either analog or digital. The analog version will be between 0 and 1, and end with "Analog". The digital versions are true or false.

Sixaxis.yaw tells you the yaw angle. Unlike the pitch and roll, the absolute yaw can never be measured. The SIXAXIS uses a rate-gyro to measure the speed of yaw rotation, and keeps track of the yaw value based on yaw speed. If you rotate the SIXAXIS too fast, the gyro sensor will max out, and the yaw value will become incorrect. Also if you are tilting the SIXAXIS while you yaw it, the yaw value will also become incorrect.

Unlike pitch and roll, your script can set Sixaxis.yaw. Normally you will want to set it to zero when the user presses a button. For example:

If sixaxis.circle then sixaxis.yaw = 0

To calibrate the SIXAXIS gyro, you can read sixaxis.RawGyro. You can then set sixaxis.RawGyroZero to the value that corresponds to not rotating at all. You should do this if your yaw keeps drifting. Eg.

If sixaxis.square then sixaxis.RawGyroZero = smooth(sixaxis.RawGyro)

You can also read or set sixaxis.DegreesPerRawGyro if turning the SIXAXIS 180 degrees doesn’t turn the yaw by 180 degrees.

The SIXAXIS has 4 player LEDs, like the Wiimote. Unlike the Wiimote, these LEDs are controlled by a timer chip and can be set to flash at any rate, in any pattern.

Sixaxis.Led1Frequency = 10Hz

You can also make an LED turn itself off after a specific duration:

Sixaxis.Led1Duration = 1 second

You can set it to infinity if you want it to stay on:

Sixaxis.Led1Duration = infinity
Bluetooth

You can read or set the BlueTooth MAC Address which is stored in the Sixaxis, by using Sixaxis.BlueToothMAC. On a new sixaxis it will be "00:00:00:00:00:00". You should set it to the address of the bluetooth adapter on your computer. Then your SIXAXIS will be able to connect to that Bluetooth adapter. You will need to go into your bluetooth stack to find the address of your bluetooth adapter. You could also try setting it to the bluetooth address of any other device you want to pair the SIXAXIS with. Here is an example of how to use it:

debug = sixaxis.BluetoothMAC
if pressed(sixaxis.PS) then
  sixaxis.BluetoothMAC = "00:10:C6:59:00:4A" // put your BT address here
end if

Once you have set the BluetoothMAC, you can make the SIXAXIS discoverable by pressing the PS button.

Unfortunately when I try to pair the SIXAXIS using Bluetooth it keeps connecting and then disconnecting. I have never successfully paired the SIXAXIS via bluetooth. If you do get the SIXAXIS to pair via bluetooth, let me know how you did it. But GlovePIE does not support SIXAXES connected via Bluetooth yet.

Sometimes it stops working

If your SIXAXIS stops working one day, you can fix the problem by pressing the Reset button on the back of your SIXAXIS. You will need a pin or skewer or something like that. The reset button will not reset the BluetoothMac. You can set the BluetoothMac back to its original value by setting it to "" or "00:00:00:00:00:00" in GlovePIE.

NEW! PlayStation 3 BDRemote

The BD Remote is the PlayStation 3's Blueray Disc remote. It is a Bluetooth remote control, like the Wii Remote is. You need to connect it using your Bluetooth software before you can use it in GlovePIE. You also need to use the correct setting for Bluetooth Fix in the troubleshooter menu. It should be off for BlueSoleil, and on for Microsoft.

The BD Remote has many buttons, they will be either true or false. You can assign them to keys like this:

Escape = BDRemote.Eject

Here is the complete list of buttons:

Eject, Num1, Num2, Num3, 
Audio, Num4, Num5, Num6,
Angle, Num7, Num8, Num9,
Subtitle, Clear, Num0, Time,
Blue, Red, Green, Yellow,
Display, TopMenu, Popup, Return,
Triangle, Circle
Up, Down, Left, Right, Enter
Square, Cross
L1, PS, R1,
L2, R2,
L3, Select, Start, R3,
Rewind, Play, FastForward,
Prev, Stop, Next,
StepRev, Pause, StepFwd

Some buttons can be read while you're holding down multiple buttons, and some buttons can only be read when you're only holding down a single button.

The buttons which are also on a SIXAXIS or normal playstation controller, plus the Enter button (which is not on a SIXAXIS) can always be read even when you hold down multiple buttons. Other buttons can't.

You can tell when the user is holding down too many buttons at the same time with: BDRemote.TooManyButtons. It is true or false.

You can also tell which button is currently down by reading: BDRemote.Button which is 0 for no button, or a number between 1 and 254 indicating which button is down, or -1 for too many buttons.

You can tell whether any button is pressed or not with BDRemote.AnyButton which is either true or false.

There is also BDRemote.Exists, and BDRemote.Count.

NEW! XBox360 Controller

The XBox360 controller is a Microsoft gamepad that is only partially compatible with Microsoft’s DirectInput. GlovePIE can read it both as a joystick, or as an XInput device. XInput is Microsoft’s new alternative to DirectInput that only works on Microsoft gamepads.

I don’t have an XBox360 controller, so I haven’t GlovePIE with it yet.

Unlike its competitors, the XBox360 controller has no motion sensing. It has two analog sticks (joy1, and joy2), and two analog triggers (LeftTrigger, RightTrigger). The rest of the buttons are digital. The gamepad can also vibrate.

GlovePIE supports a maximum of four XBox360 controllers. They will be called XInput1, XInput2, XInput3, and XInput4. If you need more than 4, then you can read them as joysticks instead.

You can’t control the LEDs in the “Ring Of Light”. They will be set automatically to whatever the player number is. You also can’t use the home button.

XInput1.A, XInput1.B, XInput1.X, and XInput1.Y are the main buttons. They are either true or false.

XInput1.Back and XInput1.Start are the Back and Start buttons on either side of the ring of light. They are either true or false.

XInput1.Up, XInput1.Down, XInput1.Left, and XInput1.Right are the DPad directions. They are also either true or false.

XInput1.LeftShoulder and XInput1.RightShoulder are the (digital) shoulder buttons, and are true or false.

XInput1.LeftTrigger and XInput1.RightTrigger are the analog trigger buttons under the shoulder buttons. They will be between 0 and 1.

XInput1.LeftThumb and XInput1.RightThumb are the buttons that you trigger by pushing in the two joysticks (with your thumb). They are the equivalent of L3 and R3 buttons on a PlayStation controller (But don’t try this on a Wii Classic Controller).

XInput1.Joy1X is the horizontal input of the left joystick. It is between -1 and 1, with 1 being to the right. Joy1Y is the vertical input of the left joystick. Positive means down. You can also access it as a vector [x, y], with just XInput1.Joy1.

XInput1.Joy2X, XInput1.Joy2Y, and XInput1.Joy2 are the right joystick.

XInput1.ExtraButton1, and XInput1.ExtraButton2 don’t exist yet. But XInput allows for future controllers to add those buttons.

XInput1.Vibration1, and XInput1.Vibration2 control the vibration. You can set them to a value between 0 and 1.

XInput1.Exists is true if that controller exists. XInput.count is the total number of XInput controllers connected (0 to 4).

Concept 2 Rowing Machine

If you have a Concept 2 rowing machine, also known as an ergo, you can connect it to the PC via a USB cable (which it should have come with). It can be a PM3 or PM4.

You must run GlovePIE.exe as an administrator if you are using Vista! Otherwise the rowing machine won’t work.

That allows you to use it with programs like GlovePIE, or to update the rowing machine’s firmware.

Updating the rowing machine’s firmware is a good idea, because it downloads the Fish Game onto your rowing machine. The fish game is really fun and works when it is not connected to the computer. You can update the firmware from here: http://www.concept2.com/us/support/software/firmware/

To use the rower in GlovePIE, the following are available:

Rower.Distance: The total distance rowed, in metres.
Rower.Distance2: Another version of the above. May be slightly different.

Rower.StrokeState: The part of the stroke you are currently in. 0 and 1 correspond to the wheel starting up. 2 means pulling. 3 means holding. 4 means releasing.
Rower.Pulling: True when doing the pulling part of the stroke
Rower.Holding: True when doing the holding part of the stroke
Rower.Releasing: True when doing the releasing part of the stroke

Rower.Power: How hard they were pulling during the stroke. In watts (Joules per second).

Rower.HeartRate: Beats per minutes (if you have a heart-rate monitor) in “per minute”.

Rower.Calories: Total calories burned so far.

Rower.Cadence: Strokes per minute.

Rower.Pace: How many seconds it takes to row a kilometre.

Rower.Time: Current session time. Divide calories or distance by this to get rates.
Rower.Time2: Another version of the above.

Rower.Exists: True if the rowing machine exists.
Rower.Count: Number of rowing machines (of the same type). 

Rower.Speed: Doesn’t really work that well. You need to use Smooth(Rower.Speed,30) for maximum smoothing. In metres per second.

Screen

You can get information about the screen, or screens, connected to the computer. Which may be important for controlling mouse pointers and stuff like that.

Use “Screen” to refer to the primary monitor, or use “Screen” followed by a number to refer to individual screens.
NEW! Orientation
In theory you can now set the screen orientation. It doesn’t work for me, but that might just be nvidia’s, or Vista’s fault. Use it like this:

Screen.Orientation = 90 degrees

You can only rotate the screen by a multiple of 90 degrees.
NEW! Scrolling the entire screen
Wallpaper must be switched off and set to a solid colour for this to work!

This is mostly used for Virtual Reality Head Mounted Displays, but it may also be useful for other purposes. It shifts the entire screen contents in any direction, exposing new desktop space. This allows you to create a much larger virtual desktop that you can pan around, and spread windows over.

It is buggy, but still very cool. With a HMD you could be surrounded by a 360 degree desktop. You could then drag windows all around you and place them at points in space.

Use Screen.ScrollX and Screen.ScrollY, they are measured in pixels. 

Size

Screen.Width is the width in pixels, but you can also get the width in real units by writing something like:

debug = Screen.Width in cm

The Physical width will only be right for a single Plug and Play monitor you have connected.

Screen.Height is the height in pixels. You can also get the real units.

Screen.PhysicalWidth is a better way of getting the screen width in physical units.
Screen.PhysicalHeight is the same for height.

Screen.ViewableSize is the actual viewable size of the monitor. If it is a CRT monitor then it will be less than the advertised size, because the advertised size is always the size of the tube itself rather than the viewable area. If it is an LCD monitor, then it will be about the right size.

Screen.PixelsPerInch is the number of dots per inch that your monitor has.

Screen.WorkAreaWidth and Screen.WorkAreaHeight is the size in pixels of the work-area, which is all of the screen that isn’t covered up with the task-bar and other bars.

Screen.DesktopWidth and Screen.DesktopHeight are the size in pixels of the Virtual Desktop, which stretches across all monitors in a multiple monitor setup.

Position

Screen.Left is the position of the left hand side of the screen in pixels, relative to the top left corner of the primary monitor. So for screen1 it will be 0, but for screen2 it may be something else.
Screen.Top is the position of the top of the screen in pixels, relative to the primary monitor.
Screen.Right is the position of the right hand side of the screen in pixels, relative to the primary monitor.
Screen.Bottom is the position of the bottom of the screen in pixels, relative to the primary monitor.

Screen.DesktopLeft is the position of the left hand side of the virtual desktop relative to the top left corner of the primary monitor.
etc.

Screen.WorkAreaLeft is the position of the left hand side of that screen’s work area (the parts not covered by the taskbar).
etc.

Plug & Play Monitor Stuff

These only work for a single Plug & Play monitor.

PlugAndPlayAvailable, ManufactureDate, EDIDVersion, EDIDRevision, PhysicalWidth, PhysicalHeight, VendorCode, ProductCode, VendorShortName, VendorLongName, SerialNumber, IsProjector, ViewableSize 

ScreenSaver stuff

ScreenSaverEnabled, ScreenSaverRunning, ScreenSaverTimeout

GlovePIE stuff

IsPieScreen, PieScreen

Other Stuff

There’s lots of other stuff in the Screen object, mostly control panel settings.

Window

The Window object gives you information about the currently active window. It is useful to find out which application is currently active, what size it is, and where it is.

The Window’s title can be read like this:

Window.Title

You can also read specific parts of the title:

Window.BeforeDash
Window.AfterDash
Window.AppName
Window.FileName

You can read the window class name like this:

Window.Class

You can read its size like this:

Window.Width
Window.Height
Window.ClientWidth
Window.ClientHeight

You can read its position like this:

Window.Left
Window.Top

 Many of the properties of the Window object are useless or don’t work. It is a work in progress.

FakeSpace Pinch Gloves

FakeSpace pinch gloves have two gloves with electrical contacts on each finger. So you can tell which gesture the user is doing by which fingers are touching each other.

They must be plugged into a serial, aka COM, aka RS232 port.

There is probably a switch on your pinch gloves control box that says which baud rate you want. If it is not set to 9600 then you need to add a line in your script like this:

Pinch.Baud115200 = true

Here is a list of supported baud rates: 1200, 2400, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 76800, 115200, 128000, 153600, 256000

You can then read any of the possible combinations of fingers to see if those two fingers are touching:

Eg. 
Key.Enter = Pinch.RightThumbRightIndex

You can use any combination of the following fingers:
LeftThumb, LeftIndex, LeftMiddle, LeftRing, LeftPinky, RightThumb, RightIndex, RightMiddle, RightRing, RightPinky

If you want to use a combination of 3 fingers touching you must do it like this:

Key.Enter = Pinch.RightThumbRightIndex and Pinch.RightThumbRightMiddle

There have been reports that GlovePIE has the right and left hands backwards. I don’t know because I can’t test it. Can someone check and let me know?

If you have multiple sets of pinch gloves, or it is plugged into a strange COM port, you can specify a COM port like this:

Key.Enter = Pinch.Com1.RightThumbRightIndex

5DT Data Glove

The 5DT Data Glove is a cheaper, but not consumer-priced VR glove. It is more expensive than the Essential Reality P5 Glove, but in many ways it has less features. It has no tracker, and no buttons.

I don’t have a 5DT Data Glove, so this is untested.

You can detect whether the FiveDT glove exists with: FiveDT.Exists

The DG5 model has just the five fingers. You can read their raw values like this:

FiveDT.AbsoluteThumb
FiveDT.AbsoluteIndex
FiveDT.AbsoluteMiddle
FiveDT.AbsoluteRing
FiveDT.AbsolutePinky

Or you can read their calibrated values like this:

FiveDT.Thumb, FiveDT.Index, FiveDT.Middle, FiveDT.Ring, and FiveDT.Pinky

To tell if it is a left-handed glove, you can read FiveDT.LeftHand, which is true or false.

You can tell which type of glove it is with FiveDT.Type, or FiveDT.TypeName.

The DG14 model has near (proximal) and far (medial) sensors for each finger. Although for the thumb it measures the medial and distal joints. The distal joints are the finger tips, which are only measured for the thumb.

FiveDT.AbsoluteThumbMedial
FiveDT.AbsoluteIndexProximal
FiveDT.AbsoluteMiddleProximal
FiveDT.AbsoluteRingProximal
FiveDT.AbsolutePinkyProximal
FiveDT.AbsoluteThumbDistal
FiveDT.AbsoluteIndexMedial
FiveDT.AbsoluteMiddleMedial
FiveDT.AbsoluteRingMedial
FiveDT.AbsolutePinkyMedial

You can read the calibrated values like this:

FiveDT.ThumbNear
FiveDT.ThumbFar
FiveDT.IndexNear
FiveDT.IndexFar
FiveDT.MiddleNear
FiveDT.MiddleFar
FiveDT.RingNear
FiveDT.RingFar
FiveDT.PinkyNear
FiveDT.PinkyFar

On the DG14, you can also read the gaps between the fingers:
FiveDT.AbsoluteGapThumbIndex
FiveDT.AbsoluteGapIndexMiddle
FiveDT.AbsoluteGapMiddleRing
FiveDT.AbsoluteGapRingPinky
FiveDT.AbsoluteGapThumbPalm

FiveDT.GapThumbIndex
FiveDT.GapIndexMiddle
FiveDT.GapMiddleRing
FiveDT.GapRingPinky
FiveDT.GapThumbPalm

There is also a wrist bend sensor:

FiveDT.AbsoluteWristBend
FiveDT.WristBend

Some gloves also have a rotation sensor:

FiveDT.RawPitch
FiveDT.RawRoll
FiveDT.ScaledPitch
FiveDT.ScaledRoll

You can read a number to identify a gesture like this:

FiveDT.Gesture

You can also recognise gestures the GlovePIE way, by using a 5-letter code representing the 5 fingers: thumb, index, middle, ring, pinky

Eg. FiveDT.xlnnn

The letters can be:
x: don’t care
n: fully bent
r: partly bent
l: straight

The gesture will be either true or false.

You can set FiveDT.minn and FiveDT.maxl (maxL) to specify the ranges that correspond to l and n.

If you want to calibrate the glove from GlovePIE, you can start calibration by setting
FiveDT.calibrating = true

And you can stop calibration by setting
FiveDT.calibrating = false

There is also a FiveDT.NewData value, but I don’t remember what it does.

Polhemus Fastrack and compatible trackers

You must set the Fastrack’s baud rate to 115200, otherwise it will not work with GlovePIE.
Other trackers may also be compatible, eg. The IsoTrak, Latus, or Patriot, or even some competing brands.

You can read the following values:

x, y, z: the position in inches by default
yaw, pitch, roll: the angles in degrees by default
exists: true if that sensor exists, false if it doesn’t

I can’t guarantee that the coordinates will be in the conventional GlovePIE coordinate system.

To read multiple sensors, use Fastrak1, Fastrak2, Fastrak3 and Fastrak4. eg. 

debug = Fastrak2.x

You can also read from different COM ports, and have more than one tracker system connected, like this:

Debug = Fastrak1.Com2.x + “, “ + Fastrak1.Com1.x

Ascension Flock of Birds

You can read from the Ascension Flock of Birds tracker almost exactly the same as the Polhemus tracker above, except you use Bird instead of Fastrak.

It must be set to 115200 baud.

You can read:
Bird1.x, Bird1,y, Bird1.z: position in inches
Bird1.yaw, Bird1.pitch, Bird1.roll: angles in degrees

You can change the 1 to other numbers to read multiple birds.

You can also choose which com port to use if the default isn’t working:

Debug = Bird1.com2.x

InterSense trackers

You can read InterSense trackers like this:

InterSense.Pos1, InterSense.Pos2, InterSense.Pos3: x, y, and z coordinates. I don’t know which axes the correspond to though, which is why they have the strange names.

InterSense.Angle1, InterSense.Angle2, InterSense.Angle3: some euler angles. I don’t know which are yaw, pitch, and roll.

InterSense.Button1 to InterSense.Button8: If you are using a tracked Wand with buttons on it, these will be the buttons. They are either true or false.

InterSense.JoyX and InterSense.JoyY are the joystick on the Wand.

InterSense.AuxInput1 to AuxInput4: Additional inputs. These are returned as a 1-byte number

InterSense.Analog3 to InterSense.Analog10: Additional analog inputs. Analog1 and Analog2 are the same as JoyX and JoyY.

InterSense.Exists: True if it exists, false if it doesn’t.

You can use multiple trackers by adding a number after InterSense, eg. InterSense2.JoyX

WorldViz PPT Tracker

The WorldViz Precision Position Tracker is an optical tracking system.

It has the following properties:
Exists,
x, y, z,
quat1, quat2, quat3, quat4,
XVelocity, YVelocity, ZVelocity,
HasPosition, HasOrientation, HasGoodPosition, HasGoodOrientation

You can track multiple targets with ppt1, ppt2, ppt3, etc.

You can also optionally specify the com port if you want, like this:
Debug = ppt1.com2.x

The orientations are in quat1, quat2, quat3, and quat4. But it is a quaternion. Sorry.