1. x36usb20d4.zip Driver
2. Profile.txt File Contents

Profile.txt Driver File Contents (x36usb20d4.zip)

Dhauzimmer's X36 USB filter driver v2.0gamma1
PROFILE.TXT
07/22/2001
----------------------------------------

Background:

Filter driver version 2.0+ now requires a loader program to load profiles into the driver.  The 2.x series uses a new set of memory structures, to reflect the capabilites of the new interface.

Each button/switch position on the X36 is assigned one entry in a table of frobbables.  Each frobbable, at any given moment, may be in one of two positions: pressed or released.  A script of key or button presses may be triggered on the transition between each state.  The frobbables are, in order by number in the Frob Table text file.  All of the hat switches are handled as 8-ways.  When scripting for hat switches, remember that the release script for a direction will be processed before the press script for the new direction.

--------

Command Scripts


Scripts are constructed largely the same way as for the 1.x series of drivers, with one exception:  data is now a 2-byte short integer.  This current build allows for up to 65536 different scripts to be loaded in the driver at any one time.  A script entry is constructed as follows:

Script number:  1-65536 (2-byte unsigned short integer)
Number of events: 0-256 (1-byte unsigned char)
	Event 1 Opcode: 1-byte unsigned char
	Event 1 Data: 2-byte unsigned short integer
	Event 1 Time delay: 4-byte unsigned long
	Event 2 Opcode: 1-byte unsigned char
	Event 2 Data: 2-byte unsigned short integer
	Event 2 Time delay: 4-byte unsigned long
	...
	
Currently defined opcodes are:
	0x00	-	Press keyboard key with HID code specified in data field.
	0x01	-	Release keyboard key with HID code specified in data field.
	0x02	- 	Press DirectX button specified in data field.
	0x03	-	Release DirectX button specified in data field.
	0x04	- 	Set the Windows Hat direction to the value specified in the data field.  0 = centered, 1 = up, clockwise to 8 = up-left.
	0x05	-	Load configuration specified in the data field.
	0x08	-	Press mouse button in the data field.  Valid values are 1-3.
	0x09	-	Release mouse button in the data field.  Valid values are 1-3.
	0x0A	-	Set mouse X axis velocity.  Value in data field is signed short int (negative is left, positive right.)
	0x0B	-	Set mouse Y axis velocity.  Value in data field is signed short int (negative is up, positive down.)
	
The time delay field specifies a delay in milliseconds past the previous event.  Eg if the first entry had a delay of 5, and the second entry had a delay of 10, the second entry would fire at time 15ms.

-------

Configuration Scripts and Mode Switching

Build 2.0beta1 contains a completely new technique for switching modes.  You may define up to 256 'configurations' which contain a list of frobbables and the command to be assigned to each one.  To enable a configuration, place an event with opcode 0x05 and with the configuration number as the data field in a command.

Here's how a configuration script works in the profile:

Configuration Number	-	unsigned char	-	The number assigned to this configuration.
Entry Count				-	unsigned char	- 	The number of frobbables modified by this configuration.
	First Frobbable Number - unsigned char	-   First frobbable.
	First New Command	-	unsigned int	-	New command to fire on first frobbable
	Second Frobbable Number
	Second New Command
	etc.
	
	
Confused?  Here's an example.

Command 1	-	0x03 0x0001 0x0000000	- Release DX Button 1
Command 2	-	0x02 0x0001 0x0000000	- Press DX Button 1
Command 3 	-	0x01 0x0004 0x0000000	- Release key 'a'
Command 4	-	0x00 0x0004 0x0000000	- Press key 'a'
Command 5	-	0x05 0x0001 0x0000000	- Load configuration 1
Command 6	-	0x05 0x0002 0x0000000	- Load configuration 2

Configuration 1:
	0x00 0x0001		// Attach command 1 to release of trigger
	0x01 0x0002		// Attach command 2 to press of trigger
	
Configuration 2:
	0x00 0x0003		// Attach command 3 to release of trigger
	0x01 0x0004		// Attach command 4 to press of trigger
	
Starting configuration (frobbable table in profile):
	Trigger Release	-	Command 1
	Trigger Press	-	Command 2
	Pinkie Release	-	Command 5
	Pinkie Press	-	Command 6
	
This setup causes the trigger to send an 'a' key when the pinkie shift is pressed, and send DirectX button 1 when the shift is released.

-------

So how do we put all this together to create a profile?

The driver expects binary profiles to follow a certain format.  ints are assumed to be 2 bytes, chars 1, longs 4.  The format is as follows:

Version Byte 		- unsigned char	- Profile format version.  0x01 = without configurations, 0x02 = with confiugrations.

Profile Byte Count  - unsigned long	- Number of bytes in profile.

Frobbable Table		- 64x2xunsigned int - Table of initial script values for each frobbable.  Two entries for each frobbable: release then press.  (ie: trigger release, trigger press, fire A release, fire A press, etc. etc.)

Command Script Count - unsigned int - Number of command scripts following.

	First Command Script - uses script format discussed above.
	Second Command Script.. etc.
	
Configuration Count - unsigned char - Number of configuration scripts following.
	First Config Script
	Second Config Script.. etc
	
Footer Byte			- unsigned char - Must be 0x00.


-------

Profiles are to be stored in binary format, one profile per file.  You will need a hex editor to create these files.  I'm planning on a text script processor, but I intend to get the majority of the driver features finished first.  Once you've stored your profile, you can use 'query profilename.bpf' to load the profile into the driver.

Two example profiles are included in with the driver package - one that emulates the 26-button stick that you get when you plug the X36 in without any drivers, and one that does the same but with the middle positions of the two switches masked off.

-------

Error codes.

So your profile won't load?  Here's a list of the error codes that might be helpful.

Error 02 - Profile below minimum size.  Is frobbable table complete?
Error 03 - Incorrect profile version.
Error 04 - Length field does not match bytes sent.  Check length field in profile.
Error 05 - Number of commands to load exceeds maximum number of commands supported by system.
Error 06 - Data sent too small to contain next command.  Check number of commands field in profile.
Error 07 - Data sent too small to contain size of script.  Check number of script entries in profile.
Error 08 - Unable to allocate memory for script.
Error 09 - unassigned.
Error 10 - Footer position exceeds number of bytes sent.  Check footer is present.
Error 11 - Footer byte does not match.  Check footer is present, check number of comands/script entries.
Error 12 - Command number exceeds maximum.  Check byte counts and command numbering.

BE AWARE THAT THIS DRIVER DOES MINIMAL ERROR CHECKING AND THAT A FAULTY PROFILE COULD DESTABILIZE YOUR SYSTEM.  CHECK YOUR PROFILES THOROUGHLY BEFORE LOADING!

------

Any questions?  Drop me an e-mail at dhauzimmer@geocities.com, ICQ me at 2978767, or post on Ron's message boards (www.saitekhelp.com) and we'll see what we can do.

  Dhauzimmer