Contents |
[edit] ZWDA - General Mouse - How to add compatibility for a mouse
This tutorial will try to explain how to configure ZWDA to use your mouse with it.
The screenshots are taken under Windows XP but the procedure is the same for Vista and Seven. I you are afraid to break your computer, you can use a virtual machine (I use VMware).
This tutorial is quite new, so if you have any comments don't hesitate to post on the message boards.
I'll be using a Logitech VX Nano.
[edit] Step 1 - Edit the inf file
[edit] Identify your device
Find your mouse in the device manager of windows and open its properties.
Under the tab named "Details", you should find its identifier.
Note the values of VID, PID, and MI
| VID | 046D |
| PID | C521 |
| MI | 00 |
You can also find this information using different methods, as explained here: http://www.freelabs.com/~whitis/USB_VID_PID.xhtml
[edit] Edit the inf file
Go to \drivers\GeneralMouse\driver\[Your OS/Architecture] and edit the file named zwda_general_mouse.inf.
Find the place where devices are declared and add yours, using the values previously found.
%LogitechMX1000% = ZWDAHIDMOUSE,HID\VID_046D&PID_C50E
%LogitechMXRevolution% = ZWDAHIDMOUSE,HID\VID_046D&PID_C525&Mi_00
%LogitechVXNano% = ZWDAHIDMOUSE,HID\VID_046D&PID_C521&Mi_00
In the strings section at the end of the file, add the displayed name of your mouse
LogitechMX1000 = "ZWDA - Logitech MX 1000"
LogitechMXRevolution = "ZWDA - Logitech MX Revolution"
LogitechVXNano = "ZWDA - Logitech VX Nano"
[edit] Step 2 - Load the driver
[edit] Get the driver
You need a debug version of the driver known as a Checked Build (see this link for details.
You can either build it yourself (the sources are here), or use a prebuilt version:
http://fzwte.net/content/zwda/checked_builds/
Be sure to have the right version in the driver folder of Windows: %windir%\system32\drivers\zwda_gm_lowerfilter.sys (compare the dates and the size of the file). Sometimes the inf file will replace it on its own.
[edit] Load the driver
Install and load the driver normally.
See ZWDA_GeneralMouseHelp for details (especially if you are running 7.x64).
Your mouse should now be labeled correctly.
The driver should be loaded.
Also, you should see a symbolic link to the control device, using WinObj. This is the device that the ZWDA application will connect to. If you don't see it, you should try rebooting your computer.
[edit] Check the output of the driver
Download and launch DebugView.
Be sure to select "Capture Kernel" in the menus (you might need to run it as an Administrator).
Now, if you disable and enable your mouse in the device manager, you should see information from the driver.
[edit] Step 3 - Create a device XML file
In this section, we will identify the information from the bytes of the read events of the mouse.
[edit] Identify the information
If you move or click to the buttons of your mouse, you should see information printing in DebugView.
When a read event is triggered, the driver will output the data. Then, it will apply its filters. Then, it will output the data sent to the next driver. The data is displayed in binary.
The next screenshot show the data received (red) and the data sent (green). In this case, the data is not modified.
[edit] Identifying buttons
Press and unpress a button of your mouse (try not to move it at the same time). I'll click the left button.
You can see that the driver triggered two read events. The first one is when the button is pressed (red) and the second for when the button is unpressed (green).
You can notice that during this operation, one bit changed: the bit number 0 of the byte number 1. This bit describes the button left click.
The bytes and bits are ordered as follow:
Another example: this is when I press the button next.
You can see that this button is located on byte 1 and bit 4.
You should now be able to identify all the buttons of the mouse:
| Button | Byte | Bit |
|---|---|---|
| Left Click | 1 | 0 |
| Right Click | 1 | 1 |
| Top Button | 1 | 2 |
| Next Button | 1 | 4 |
| Previous Button | 1 | 3 |
[edit] Identifying wheels
Wheels are slightly different. Since they don't have two states (pressed, unpressed), they only need one read event. On the next screenshot, I scrolled up once (red) and scrolled down once (green). The information of a wheel take a full byte and is represented as a signed number (1 = up, -1 = down).
You can then identify the wheels of the mouse. On the VX Nano, the buttons wheel right and wheel left are represented as a wheel and not as a button.
| Wheel | Byte |
|---|---|
| Scroll Wheel | 6 |
| Wheel left & Wheel right | 7 |
[edit] Creating a XML file
The main application of ZWDA uses a XML file to determine where the information is stored, and then it communicates with the driver to get informed when this information changes.
A XML file is divided into 3 parts:
[edit] Part 1 - Device description
This part contains information about the device, such as:
- Its name
- Its image file
- Its icon file (16x16 pixels)
The paths for the images are relative to the folder \drivers\GeneralMouse.
Exemple section:
<icon>images\LogitechVXNano\1616.jpg</icon> <image>images\LogitechVXNano\0.jpg</image> <name>Logitech VX Nano</name>
[edit] Part 2 - Buttons and Combos
This part lists the buttons of the mouse, and the possible combos.
<buttons> <button filterable="yes" name="left_click" caption="Left-Click" image="images\LogitechVXNano\1.jpg"/> <button filterable="yes" name="right_click" caption="Right-Click" image="images\LogitechVXNano\2.jpg"/> <button filterable="yes" name="next" caption="Next Button" image="images\LogitechVXNano\4.jpg"/> <button filterable="yes" name="previous" caption="Previous Button" image="images\LogitechVXNano\5.jpg"/> <button filterable="yes" name="top" caption="Top Button" image="images\LogitechVXNano\6.jpg"/> <button filterable="yes" name="wheel_left" caption="Wheel Left" image="images\LogitechVXNano\7.jpg"/> <button filterable="yes" name="wheel_right" caption="Wheel Right" image="images\LogitechVXNano\8.jpg"/> <button filterable="yes" name="scroll_up" caption="Scroll Up" image="images\LogitechVXNano\3.jpg"/> <button filterable="yes" name="scroll_down" caption="Scroll Down" image="images\LogitechVXNano\3.jpg"/> </buttons>
If you know XSLT, you will find a style sheet which create the combo section automatically in the sources folder of ZWDA (create_combo_section.xsl).
<combos> <combo name1="left_click" name2="middle_click"/> <combo name1="left_click" name2="cruise_up"/> <combo name1="left_click" name2="cruise_down"/> <combo name1="left_click" name2="left_middle_button"/> <combo name1="left_click" name2="left_top_button"/> <combo name1="left_click" name2="left_bottom_button"/> <combo name1="left_click" name2="wheel_up"/> <combo name1="left_click" name2="wheel_down"/> ... </combos>
[edit] Part 3 - Driver mapping
In this part, you will enter the information you got earlier. The format of this part will change in the future versions.
<driver_information> <hardware_ids> <hardware_id vid="046d" pid="c521" mi="00"/> </hardware_ids> <driver name="main_device" link="standard"> <events> <event location="on_read" information_type="bit" position="8" maptype="button" mapto="left_click" mapstyle="standard"/> <event location="on_read" information_type="bit" position="9" maptype="button" mapto="right_click" mapstyle="standard"/> <event location="on_read" information_type="bit" position="10" maptype="button" mapto="top" mapstyle="standard"/> <event location="on_read" information_type="bit" position="11" maptype="button" mapto="previous" mapstyle="standard"/> <event location="on_read" information_type="bit" position="12" maptype="button" mapto="next" mapstyle="standard"/> <event location="on_read" information_type="char_positive_negative" position="6" maptype="scroll_wheel" mapto_up="scroll_up" mapto_down="scroll_down" mapstyle="standard"/> <event location="on_read" information_type="char_positive_negative" position="7" maptype="scroll_wheel" mapto_up="wheel_left" mapto_down="wheel_right" mapstyle="standard"/> </events> </driver> </driver_information>
- Enter the hardware identifiers (VID, PID, MI) in the section hardware_id.
- Add an event for each data entry from earlier.
- For wheels, enter the position of the byte and the id of the corresponding two buttons.
- For buttons, enter the position of the bit and the id of the corresponding button.
- For buttons that generate both buttons and wheel events (Like the cruise buttons of the Logitech MX1000), use the maptype cruise_button (see the mx1000 file for details).
The position of the bits is calculated the following way:
position = [position of the byte] * 8 + [position of the bit]
Exemple: for the top button: position = 8 * 1 + 2 = 10.
When you are done, save the file and put it in the folder \drivers\GeneralMouse\devices.
[edit] Step 4 - Use your mouse with ZWDA
Start ZWDA and start the General Mouse driver. Under the device tab, you should normally see your device.
When you start the device, DebugView should output more debug information.
You can now try to bind actions to the buttons and wheel and test them; and try to filter buttons. You can watch the data in DebugView to check if everything is working correctly.
In the following screenshot, you can see that the left click is correctly filtered and that an event is sent to the main application:
That's it. If everything went well, your mouse is now supported by the General Mouse driver of ZWDA.
[edit] Problems you might encounter
[edit] I don't see anything in DebugView
If you can see the symbolic link in WinObj but nothing in DebugView:
- Be sure that you are using the checked build of zwda_gm_lowerfilter.sys.
- Be sure that you selected Capture kernel in the menu.
[edit] There are buttons missing in DebugView
Problem: in DebugView you can see most of the buttons, but some are missing.
This problem is known with the search button of the MX Revolution for exemple.
This is because the device is a composite device and so the missing data is handled in an other subdevice. The General Mouse driver does not handle these cases in its current version.