Controlling the Hidsporb Driver

To keep the core of the hidsporb driver support as simple as possible, all control to the orb is done via a command-line interface, orbcontrol.exe. I chose a command-line interface for many reasons, chief among them being simplicity of the underlying code as well as a stark loyalty to command-line interfaces; it is a philosophical choice as much as anything (for an amusing read on the subject, see Neal Stephenson's essay "In the Beginning, there was the Command Line", freely available at http://www.cryptonomicon.com/beginning.html) While third-party utilities promise to make this process much more user-friendly and elegant, it still behooves the hidsporb user to understand the concepts involved in basic orb control.

To use orbcontrol, the orbcontrol.exe must be in your path or current directory.

Executing the orbcontrol command without any arguments will show the current status of the orb.

Basic control

Setting the orb facing

With so many users of the SpaceOrb, the question of "how to hold the orb" has coalesced into two camps: the vertical mode and the horizontal mode. In the vertical mode, picture the device held with the ball "pointed at the ceiling"; pressing the ball away from you (perpendicular to the plane of the controller) will result in forward motion. By contrast, the "horizontal" mode pictures the device held with the ball pointing horizontally; squeezing the ball away from the user results in forward motion.

The vertical (default) orb facing

Figure 23. Vertical facing for the SpaceOrb

The horizontal orb facing

Figure 24. Horizontal facing for the SpaceOrb

To set the facing of the orb using orbcontrol.exe, use the --set-facing (vertical | horizontal) command:

Example 1. Setting the orb facing to vertical using orbcontrol

C:> orbcontrol --set-facing vertical

The --set-facing command accepts either "horizontal" or "vertical" as its argument, and sets the facing appropriately.

Chording

One of the largest drawbacks of the original SpaceOrb was that the device only had six buttons. While this was enough for very basic functionality in many games, users invariably had to use the keyboard quite frequently (usually frustrating, but not always terrible; my wife and I have very fond memories of playing half-life with myself on the orb and her on the keyboard as weapons control; it provided unending hours of amusement as I would round a corner and begin shouting in a panicked voice "AAAH! SHOTGUN! SHOTGUN!" Needless to say, she laughed at me a great deal.)

While the device has only six physical buttons, it is possible to simulate more logical buttons by using chording--pressing keys in combination. While this could be extremely confusing, the hidsporb driver uses the physical layout of the orb to divide its buttons into page selectors (buttons A and B, on the "edge" of the orb) and button selectors (buttons C, D, E, and F, on the "face" of the orb). The following table summarizes button usages when chording is on (note: Internally, and as far as DirectInput goes, buttons begin numbering from 0; in the game controller control panel, they are numbered starting from 1. I refer to the buttons as 0-15 in this table):

Table 1. Button assignment with chording on

If page selector "A" is......and page selector "B" is......and this physical button is pressed...The computer will see this logical button as pressed.
offoffC0
offoffD1
offoffE2
offoffF3
onoffC4
onoffD5
onoffE6
onoffF7
offonC8
offonD9
offonE10
offonF11
ononC12
ononD13
ononE14
ononF15

With chording off, the physical buttons A-F match directly to the logical buttons 0-5. The "reset" button (button 6) on the bottom of the orb is actually reported as a DirectInput button, but since pressing it will re-zero the axis control, I cannot recommend this for in-game use.

To control chording with orbcontrol, use the command --set-chording (on|off); for example:

Example 2. Turning chording on with orbcontrol

C:> orbcontrol --set-chording on

Restoring default settings

It could be that during the course of changing your orb's behaviour that you put the orb in a bad state. To recover, and set the orb to default settings, use the --set-defaults command:

Example 3. Restarting the orb to default settings

C:> orbcontrol --set-defaults

The default orb settings are:

Table 2. Default hidsporb settings

FacingVertical
Chordingon
Sensitivity4 on all axes (this closely resembles the classic SpaceOrb response curve)
Gain50 on all axes
Polarity+ on all axes
Null region65
Precision sensitivity0
Precision gain50
Precision buttonnone

Intermediate control

Setting the axis map

The --set-facing command is really just shorthand for redefining the axis map to a preset. For more fine-grained control, any logical axis can be mapped to any physical axis.

A logical axis represents what the computer sees; the hidsporb.sys driver supports the following six axes:

Table 3. Logical axes supported by hidsporb.sys

0XMovement in the X axis (left/right)
1YMovement in the Y axis (forward/backward)
2ZMovement in the Z axis (up/down)
3RxRotation about the X axis (pitch up/down)
4RyRotation about the Y axis (roll left/right)
5RzRotation about the Z axis (yaw left/right)

In the standard vertical mode, each physical axis maps to the appropriate logical axis (in other words, moving the orb left-to-right (physical axis 0) modifies logical axis 0 (your on-screen character moves left-to-right)). When thinking about physical axes, always view the orb from the "vertical" position.

To change the axis map on the orb, use the orbcontrol command --set-axis (logical-axis) (physical-axis); this maps the logical axis named in the first argument to the physical (orb) axis named in the second argument. For example:

Example 4. Setting logical axis 1 to physical axis 0

C:> orbcontrol --set-axis 1 0

After issuing this command, if the user held the orb in the vertical position and moved the orb left/right (physical axis zero), the on-screen character would move forward/backward (logical axis 1).

In general, most users will stick with either vertical or horizontal facing.

Axis polarity

While the hidsporb driver complies with the standard HID guidelines regarding which physical motion maps to which logical motion, users may find that they need to "invert" axes. To invert a given logical axis, use the --set-polarity (axis) (- | 0 | +). Positive polarity is the default; negative polarity reverses an axis. The '0' polarity setting causes that axis to always send a "midpoint" value--effectively making that axis unresponsive.

Example 5. Setting the polarity of axis 0 to negative

C:> orbcontrol --set-polarity 0 -

Now, if the user moves the orb to the right, his on-screen character will move left. You may have to change polarity if a given game reacts strangely and does not provide in-game configurability.

Axis gain

Beginning users of the orb will probably find, as the get used to the orb's motion, that they no longer want to move the orb to its maximum travel--in other words, they would like the orb to be more responsive to their touch. There are two aspects to this: gain and sensitivity. Gain represents how much the orb "amplifies" your motion, and is designated by a number between 0 and 100. At the default value of 50, the orb has a one-to-one relationship between physical motion and logical motion. At higher values of gain, the orb will be more responsive, reaching maximum values earlier; at lower values of gain, the orb will feel more "mushy" and will not reach maximum values (to see why this is useful, see the "precision" features, later). The scale is such that at a gain value of 0, the orb will be one-fifth as responsive as usual, and at a gain value of 100, the orb will be five times as responsive. Many users find that a value of 75 (three times as responsive) feels quite comfortable.

To set the gain of an axis, use the --set-gain (axis) (gain) command; to set the gain of all axes, use the --set-master-gain (gain) command:

Example 6. Setting the gain of axis 0 to 25 (one-third as responsive)

C:> orbcontrol --set-gain 0 25

Example 7. Setting the gain of all axes to 75 (three times as responsive)

C:> orbcontrol --set-master-gain 75

Axis sensitivity

Gain represents one part of the orb's "feel"; sensitivity is another. The hidsporb driver supports up to six "sensitivity curves" that represent different ways the orb can respond to physical motion.

The default sensitivity curve (curve zero) is a linear curve; in other words, users get the same response all across the orb's range of motion. The other default curves (1-5) are curves which get progressively steeper near the edges and flatter near the center. What this means is that, for example, using default sensitivity curve 5, the orb will be much more unresponsive near the center and much more responsive near the edges. This can be used to provide precise aiming with small motions and rapid turns with large motions, roughly comparable to the "acceleration" setting in many mouse drivers. For much more advanced control of sensitivity curves, see the section on uploading and downloading sensitivity curves later in the documentation.

The six default sensitivity curves of the orb. Curve 0 represents a very linear motion; curve 5 represents very accelerated motion. The curve which matches the old vendor SpaceOrb drivers is curve 4

Figure 25. The default sensitivity curves of the orb

To set the sensitivity curve on a given axis, use the --set-sensitivity (axis) (curve number) command; to set it on all axes, use the --set-master-sensitivity command:

Example 8. Setting the sensitivity of axis 0 to curve 5

C:> orbcontrol --set-sensitivity 0 5

Example 9. Setting the sensitivity of all axes to curve 3

C:> orbcontrol --set-master-sensitivity 3

The null region

The sensor used by the orb is remarkably sensitive; even the weight of the orb pressing on the sensor results in some motion signals. To prevent this from becoming too irritating, the orb itself implements a "null region" near the center of motion. This represents a number below which no messages will be sent to the computer, and can be set to any value in the range [0..127], with 0 representing no null region and 127 representing a fairly large null region.

To set the null region, use the command --set-null-region (new region)

Example 10. Setting the null region to zero

C:> orbcontrol --set-null-region 0

Precision

What is 'precision'?

The gain and sensitivity commands allow the user to control the orb's motion to a great degree. However, there are some situations in certain games where it might be advantageous to temporarily change the orb's gain and sensitivity in order to move more precisely. For example, in Half-Life Team Fortress Classic, the "sniper" character can zoom in to a great degree, but control is far too jumpy using the regular orb settings to be controllable.

In recent months, joystick manufacturers have begun producing game devices which have a "precision" button which temporarily "dampens" the joystick's motion (Gravis's "Precision Pro" line of controllers is the most widely-known example). The hidsporb driver provides this functionality through the "precision" commands, which allow the user to select the gain and sensitivity of the orb when the precision button is pressed, and to select which button will be used as the "precision" button.

Setting precision gain

To set the gain of all orb axes when the precision button is being pressed, use the --set-precision-gain (gain) command:

Example 11. Setting the precision-mode gain to 20

C:> orbcontrol --set-precision-gain 20

Setting precision sensitivity

To set the sensitivity of all axes when the precision button is being pressed, use the --set-precision-sensitivity (sensitivity) command:

Example 12. Setting the precision-mode sensitivity to curve 0

C:> orbcontrol --set-precision-sensitivity 0

Setting the precision button

In order for the precision function to work at all, some button must be selected as the "precision button"; when this button is pressed, the orb will immediately go into precision mode, where the precision gain and sensitivity is applied to all axes. The button you choose can either be a physical button or a logical button, and you should think carefully about how this will work (for example, if you choose physical button 0 with chording on, you will be putting the orb into precision mode every time you choose logical button page 1 or 3). Even so, I have found that using physical button 0 works quite smoothly (in Half-Life TFC, I have chosen physical button 0 as precision-mode and set physical button D to "+attack" on pages 0 and 1, and the combination is quite satisfactory).

To choose a precision button, use the command --set-precision-button (logical | physical | none) (button index). The second argument (button index) deserves some explanation; if you choose "logical" for the first argument, you may choose any button in the range [0..15]; if you choose "physical", this must be in the range [0..6]. Finally, if you choose "none" (disabling precision mode), you should omit the second argument entirely.

Example 13. Setting the precision-mode button to physical button 0

C:> orbcontrol --set-precision-button physical 0

Example 14. Disabling precision mode

C:> orbcontrol --set-precision-button none

"Batch Files" for orbcontrol

It would certainly get tiresome having to type in lists of orbcontrol commands every time you start a game. To simplify things somewhat, orbcontrol supports "batch files" of commands. Simply create a file containing the orbcontrol commands you would ordinarily type in at the command line and use the -f or --from-file commands to load that into orbcontrol

Example 15. Creating and running a batch file

Suppose I had a standard orb configuration for Half-Life TFC. I want the master sensitivity to 3, the master gain to 75, precision sensitivity and gain to 0 and 20, and precision button to physical button 0. First, I would make a file named "halflife.orb" with the following contents:

--set-defaults
--set-master-sensitivity 3
--set-master-gain 75
--set-precision-sensitivity 0
--set-precision-gain 20
--set-precision-button physical 0

I would then load this into the orb by typing:

C:> orbcontrol -f halflife.orb

I recommend that you use the suffix ".orb" to denote orb configuration files and that you also include --set-defaults as the first line in every configuration file unless you nest files.

Note that all orbcontrol commands are available from within batch files including -f and --from-file. It is therefore possible to "link" .orb files into complex configurations. The orbcontrol program will not protect you from infinite loops, though, so use some caution in creating complex configurations.

Advanced control

What is a sensitivity curve?

In general, users of the SpaceOrb demand a great deal of control over their input devices and demand as much configurability as possible. One high-end input device, the upcoming Thrustmaster HOTAS Cougar (a $300 part!), offers the ability to modify the sensitivity curves used by the device to translate physical motion into logical response. The hidsporb driver allows the user the same functionality.

The orb generates values ranging from -512 to +512; these values are converted internally to hidsporb through the given gain and polarity settings to a value between 0 and 1023. The resultant number is then looked up in a table to return a number between 0 and 1023 to get the value sent to Windows and the DirectInput system.

The default curve 0 simply uses a linear table--in other words, entry 0 is the value 0, entry 512 is the value 512, and so on. The next default curves (1-5) are simply built to follow a function that increasingly steepens the curve near the edges and flattens it near the center.

By creating a text file containing 1024 numbers, each ranging from 0 to 1023, a user can replace one of these sensitivity curves with a custom curve. For example, a custom curve which consisted of 1024 repetitions of the number 0 would cause any axis assigned to that curve to always produce minimum values. The orbcontrol program provides three commands for manipulating these curves. I suggest you use the extension .crv for sensitivity curves.

Downloading sensitivity curves

To download a curve that the driver is already using, use the --download-sensitivity-curve (curve number) (filename) command. This will create a text file containing all the numbers used by the existing curve.

Example 16. Downloading the default curve 0 from the driver

C:> orbcontrol --download-sensitivity-curve 0 default0.crv

Creating and uploading custom sensitivity curves

Creating a .crv file is straightforward; simply create a text file consisting of nothing but numbers ranging from 0 to 1023. Make sure you have included 1024 entries, at least, then upload the curve to the orb using the --upload-sensitivity-curve (curve number) (filename):

Example 17. Sending a custom curve to the orb

Suppose I want absolute boolean control of a given axis--either the character is at rest, or they are moving to the limits of their abilities. I would then create a text file named "boolean.crv" and fill it with contents similar to this:

0
0
0
0
.
.
.
(about 410 times)
512
512
512
.
.
.
(about 204 times)
1023
1023
1023
.
.
.
(about 412 times, bringing us up to 1024 entries)

I would then upload the curve to the orb using the command

C:> orbcontrol --upload-sensitivity-curve 5 boolean.crv

...but my work is not yet done. In order to assign all axes to this curve, I must still use the command

C:> orbcontrol --set-master-sensitivity 5

Note that the gain commands will still work in conjunction with custom sensitivity curves.

Resetting sensitivity curves

It is certainly possible to upload a curve that does not match what you really want; if you want to return to the default curves provided by the driver, either disable and re-enable the driver, reboot the system, or use the much simpler --reset-sensitivity-curve:

Example 18. Resetting curve 0 to driver defaults

C:> orbcontrol --reset-sensitivity-curve 0

Notes on sensitivity curves

Unlike most orb settings, which affect only the particular orb, the sensitivity curves apply to the driver as a whole and thus affect all orbs connected to a system. This does not matter right now (since hidsporb only accepts one orb at the moment), but will matter in the future when multiple-orb support is added.

Setting custom sensitivity curves represents the ultimate in user-configurable control. Indeed, it is possible to use custom curves instead of the usual gain, sensitivity, and polarity settings. But it should be noted that gain and polarity are still in effect when using a custom sensitivity curve, so be aware of this when creating your own curves.