This paper is intended to provide a starting point for developers who wish to integrate the Stealth Z-Mouse with their software. The Z-version of the Stealth mouse utilizes a USB interface, but is actually a serial device, compatible with the Stealth S-version mouse.

Why did we make a new mouse with a different interface? Several developers indicated that they would like a USB mouse that was not also a system mouse. We already had a serial mouse that could be easily converted to USB, so we decided to use that protocol to build a new USB mouse. Besides, it is not really a new mouse, since it is compatible with our S-Mouse.

Stealth Hand Wheels are identical in function to the mouse, with fewer buttons. However, different resolution, and possibly counting direction, will be used for hand wheels. Developers are encouraged to provide support for both mouse and hand wheels simultaneously, and with different resolution settings.

The communication protocol is compatible with our Stealth S-Mouse. However, it has an added transmission rate commands (see section 5.2).

1. The Stealth Z-Mouse

The device is an ergonomic, two-handed mouse with 10 key switches and a Z-wheel. It has an optical XY motion sensor, and a high-resolution Z-wheel.

The Stealth 3D Mouse buttons are arranged like this: 



 

Button	Mouse Code
1	1
2	2
3	4
4	8
5	16
6	32
7	64
8	128
9	256
10	512

 

2. Mouse Driver Software

The Stealth Z-Mouse is interfaced to the host computer with a FTDI FT232BM Serial conversion chip (www.ftdichip.com). This chip communicates with the host computer via USB, and with the device controller via serial interface, hence the designation "serial conversion chip."



FTDI has provided a D2XX driver with Application Extension (Library) interface, FTD2XX.DLL.

NOTE: The Z-Mouse does not use standard FDTI drivers. You must use the drivers provided by ABC Software Developers. These are Microsoft certified drivers, but the .inf files have been modified slightly to work with the USB VID/PID of the Stealth Z-Mouse (0403/DBB8).

Plug the Z-Mouse into your computer and use the enclosed CD to install the driver.

With the FTD2XX.DLL, you will have to program the interface before you can test the mouse. The interface is described in the FTDI DLL.PDF file.

WARNING: Do not use any of the EE modification functions, or bit-banging functions. This could damage the Z-Mouse.

3. Reading Data

3.1 Opening the Device

The document "D2XX Programmer Guide", a Pdf file, found on the Developer CD, explains the use of the DLL to open the device. It is possible to open by product name or serial number, so it is easy to find and open both the "Stealth Z-Mouse V01" product and the "Stealth HW V01" Product using the VID/PID of 0403/DBB8. Even though the VID/PID are the same for both devices, you will get a different handle for each when opening by product name or serial number.

Early units (the first 10 or so) have unique serial numbers. This means that most developers have units with unique numbers. Following that, all mice have the serial number PR000001, and all hand wheel kits have the serial number PR000002. The reason for the change is that the drivers will not need to be reloaded when connecting a different mouse, or hand wheel kit. This is to make it easier for the end user. The disadvantage is that only one mouse and one hand wheel kit can be connected to one computer, but that should not be a problem for the end user.

You must provide serial (RS232C) type parameters when opening, because the USB chip is communicating with the mouse over a serial interface. The parameters are 9600 baud, No parity, 8 data bits, 1 stop bit, and no handshaking. If these parameters are incorrect, no data, or possibly corrupted data, will be received.

Use the FT_List Devices to find out how many devices are present, and use FT_Open or FT_OpenEx function to open them. Be sure to look for both Stealth Mouse and Stealth Hand Wheel Kit.

Set the baud rate to 9600 using FT_SetBaudRate, and use FT_SetDataCharacteristics to No parity, 8 bits and 1 Stop bit. Set the flow control with FT_SetFlowControl to the value FT_FLOW_NONE.

Once the device is open, reading produces a string of characters only when the mouse is moved, Z-Wheel is moved, or buttons are pressed or released. The data is a very simple string of data with a trailing <CR> character. It looks like this:

SssssXxxxxxxYyyyyyyZzzzzzz<CR>.

No data is sent if there is no change, so typically you might have:

"X-2<CR>" or "S1<CR>" or "S0Y1<CR>". Note that there are no leading zeros. Only changes are sent, but when switches are changed, the entire current switch value is sent, so pressing button1, pressing button 2, releasing button 1, and releasing button 2 will produce: "S1<CR>", "S3<CR>", "S2<CR>", "S0<CR>". Together with these, or in between these, there might be any number of additional records containing X, Y, Z data, of course.

All values are in decimal format.

To read the data, use FT_Read, reading 62 bytes (the USB buffer size.) You will not receive 62 bytes if you follow the recommendation to the Event Character (see section 3.3 below), because the maximum record length is 21 bytes.

Please read the Application notes found in AN232B-04_DataLatflow.pdf. These notes explain the interaction of the various USB parameters in respect to reading the data.

It is suggested to use the Event Character (FT_SetChars function) to end the read. Setting the Event Character to <CR> will end each read after a record is received, thus eliminating the need to read one character at a time while looking for the <CR> character.

It is NOT RECOMMENDED to read one character at a time. This can lead to lengthy delays in reading data.

Setting the USB input buffer size to 62 bytes is recommended. USB data packets are 62 bytes in size, so setting it to a lower value will not have an effect. This is done with the FT_SetUSBParameters.

The Stealth Hand Wheels (two hand wheels, one foot disk and three foot switches), work like the Stealth Z-Mouse, but with the following variations:

• The Product ID string is "Stealth HW V01"
• The Attention Command produces a version number of 50 or greater
• The resolution is 6,000 counts per revolution, producing up to +/- 2,000 counts per record
• There are only three switches (optionally 4). These are equivalent to Z-Mouse buttons 4, 5, 6 (and optionally 7), respectively. These can be easily changed before delivery by user request.
• X and Y wheels count positive when turned clockwise
• Z foot disk counts positive when turned counter-clockwise
• The Stealth Z-Mouse driver is used, so the end user will see the device name "Stealth Z-Mouse" in the System list of USB devices. However, under the Stealth Z-Mouse Properties, the product name "Stealth HW V01" is shown under Location.

There are two commands accepted by the mouse, the attention command, and the transmission rate commands.

The attention command is a single <CR> character. In response to this character, the mouse will send "Vxx<CR>". Xx is always the two-character version number of the firmware. Any other character (except those mentioned in sectin 5.2 below) received by the mouse is ignored. It is therefore permissible to send "Attn<CR><LF>", for example.

The Stealth Z-Mouse default transmission rate is 25 records per second (25 Hz). This rate can be changed by sending a one character transmission rate code.

The possible transmission rates are (Hz): 100, 66, 50, 40, 33, 28, 25, 22, 20.

The code for these rates, respectively are (Hex): 32, 33, 34, 35, 36, 37, 38, 39, 3A.

This will immediately change the transmission rate. Please note that if the value is followed by a <CR> the Stealth Z-Mouse will interpret this as an Attention Command and respond with the version number as shown in section 5.1 above.

We have shown that there are no dedicated shift buttons, so what if you want to have two shift buttons as on the Stealth 3D Mouse, for example?

You simply have to ignore the shift buttons when they are pressed on their own. For example, designate button 1 and button 8 as Left Shift and Right Shift. Then a switch value of 1, 128, or 129 will be ignored. Only when another button is pressed, giving a value of 130, for example, will you process the button combination (Right Shift + button 2.)

All developers, in order to provide the best experience for the end user, please consider the following:

• Provide for both Stealth Z-Mouse and Stealth Hand Wheel input. When calling FTD2XX.DLL, find out if there are both mouse and handwheels attached. The VID/PID are the same, as is the data format, but the product names and serial numbers are different. The product name for the mouse is "Stealth Z-Mouse V01", and the product name for the handwheels is "Stealth HW V01".
• Use the FT_OpenEx function to open both mouse and hand wheels. Note that you can open by product name or serial number. All Stealth products have a unique serial number.
• Make sure to provide user controlled resolution and direction separately for both devices. This is necessary, because some users prefer to use hand wheels for fine motion, and the mouse for fast motion.
• Deliver and install the file FTD2XX.DLL with your software to avoid user confusion, even if you do not plan to sell or deliver the Stealth Z-Mouse or Hand Wheels on a regular basis. Otherwise, if the customer has this mouse, or obtains one at a later date, there could be frustration and delay on the user's part.
• Report to Tim Roberts, Tim@Stealth3Dmouse.com, the location for installing the DLL file, so that if customers contact us, we will be able to help them.

Thank you.

ABC Software Developers