Stealth Z-Mouse (and Hand Wheel)
Developer Guide
USB Identifiers:
VID/PID: 0403/6001
Vendor ID: ABC-SD
Mouse Product ID: Stealth Z-Mouse V01
Hand Wheel Product ID: Stealth HW V01
Important Change:
As of Feb 2015, the VID/PID was changed from 0403/DBB8 to 0403/6001 in order to comply with Microsoft Windows 8 Driver requirements. Instructions for converting earlier mice to the new VID/PID can be found at www.stealth3dmouse.com/Drivers.
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.
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.
|
Stealth U-Mouse (our original USB mouse) |
Stealth Z-Mouse |
|
Requires serial port |
Requires USB port |
|
Requires separate power supply |
Powered by USB port * |
|
Multiplexes the buttons |
All 10 buttons are independent |
|
Two buttons are shift buttons only |
Button programming is unrestricted |
* The Z-Mouse draws up to 350 mA.This is well within the range of USB, but be aware that it is the total of all USB devices cannot exceed 500 mA.If a Hub is used, it should be self-powered.
The communication protocol is compatible with our Stealth S-Mouse.It sends data up to 100 times per second.
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 |
|
All buttons released |
0 |
|
Multiple |
Add the codes for each button pressed |
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 uses standard FDTI drivers since Febuary 2015. Before that it used a proprietary driver, and the VID/PID was 0403/DBB8. Instructions for changing the VID/PID can be found on our web site www.stealth3dmouse.com/Drivers.
Plug the Z-Mouse into your computer, download the driver from our web site www.stealth3dmouse.com or from FTDIchip.com. Be sure to also get the file FTD2XX.DLL.
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. Opening Device Port and Reading Data
The document "D2XX Programmer Guide", is available at FTDIchip.com, 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/6001.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.
All Stealth Z-Type mice have the serial number PR000001, and all hand wheel kits have the serial number PR000002.
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.
Note: You must move the mouse to produce data, except for response to the Attention command.
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.
4. Hand Wheels
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 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.
5. Z-Type Protocol
The Z-Type mouse has a very simple protocol. It will automatically transmit the following when the mouse is moved:
Sssss (S1, S64, S65, etc.)
Xxxx (X1, X-2, X11, etc.)
Yyyy (Y1, Y-2, Y-11, etc.)
Zzzz (Z-1, Z12, etc.)
Putting all together, you could have S1<CR>or X1Y-2<CR>or even S1024X1Y1Z1<CR>.
Commands sent to Z-Mouse.
<CR> - A carriage return will reply with Vxx<CR>where xx is the version number. The version number for this project will be 34.
O<CR>Change baud rate to 9600. This is the default.
P<CR>Change baud rate to 115200. Be careful, if the application ends without changing the baud rate back to the default, then the next application to be run will likely fail to connect. It will then be necessary to cycle the power on the mouse to return to the default.
6.0 Programming Shift Buttons
We have shown that there are no dedicated shift buttons, so what if you want to have one, two or more shift buttons as on the mouse?
You simply have to ignore the shift button(s) 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.
So, if the user wants to use Right Shift + button 2, the value 130 will be received. Process button 130 as you would any other button.
Note that just like the shift
key on a keyboard, it is necessary to press the Shift first, then the other
button, then release the other button, and finally release the Shift. So the
application will receive the following data in the example above:
S128 (press right shift, ignore)
S130 (press button 2, process button 130)
S128 (release button 2, ignore right shift)
S0 (release right shift, finished)
Free function: The Shift buttons can also do double-duty as a clutch. Just ignore any XY motion that is received while a shift button is pressed.
7.0 Developer "Requirements"
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.
Thank you.
Timothy Roberts
Stealth International, LLC