Add support for R.A.T.TE

@eyal0803 reported that his R.A.T mouse was not supported.

It looks like MadCatz is producing a whole lot of new mice, and the protocol might have changed a bit, so it needs to be investigated.

From the initial report (at #4 ), the IDs are:

{'vid': 0x0738, 'pid': 0x1704, 'name': 'R.A.T TE'}

However, an exception is raised in

measure = self.handle.controlRead(self.ctrl_request_type,
                                  self.ctrl_request,
                                  self.ctrl_value,
                                  self.ctrl_index,
                                  self.ctrl_length)

Which is later caught, but makes the function return some invalid data, that causes a crash.

Here is the crash backtrace:

Found one device: {'pid': 5892, 'name': 'R.A.T TE', 'vid': 1848}
Traceback (most recent call last):
  File "./ratctl.py", line 402, in <module>
    main()
  File "./ratctl.py", line 392, in main
    w = MainWindow()
  File "./ratctl.py", line 378, in __init__
    self.data = Data(self.pbar, self.tabs, self.dpi, self.com)
  File "./ratctl.py", line 227, in __init__
    self.pool()
  File "./ratctl.py", line 230, in pool
    self.dpiMode = self.com.getDpiMode()
  File "./ratctl.py", line 152, in getDpiMode
    return mode[0] / 16
TypeError: unsupported operand type(s) for /: 'NoneType' and 'int'

The problem is twofold here: we need to support the mouse, but also fix the subsequent crash, and provide a helpful message in case it happens.

@eyal0803, I have seen the same kind of error with the first version of the tool, when the driver didn't have the right permissions to access the device. It should now write an informative message; but could you check that this isn't a permission issue? (ie, did you write an udev rule or launch it with sudo)? Otherwise, the protocol probably changed. Would it be a possibility to capture new packets? A windows VM with the official software and Wireshark would be needed (it can also be performed directly on Windows). I can help you doing it, or I can perform it remotely if necessary.

We need to ensure that the protocol stayed the same, so we can either re-capture the packets, or try to send the old ones and see what sticks. THe former method is more complex, but that will be needed anyway if the protocol changed.

Writing a guide might not be a bad idea; as some people will want other functionality not yet in the driver: RGB LEDs, etc... And if they provide the protocol information themselves, that would speed things up.

@eyal0803, sure.

The protocol probably changed for reading the DPI, and maybe the Mode, and likely for writing as well. They may have changed it to allow for finer granularity, or for another reason.

From the amazon reviews, a couple people said that the DPI was only adjustable for both x and y, not independently, so that might be something that changed as well. Other than that, from the product description, it seems a pretty standard R.A.T 3 derivative (no horizontal scrollwheel, no battery, no revolutionary change like an embedded memory would be).

Required data

So, the data we need to gather, and when we can gather it with the windows program is:

Message requesting the current DPI setting, should be sent when starting the program
Message to set the DPI setting, is sent when applying the settings (might also be in real time when adjusting the slider, but I doubt it)
Message to get the current DPI mode the mouse is on (should be sent at startup, the program might pool it as well, so we could try to change it and see what changes)
Message to set the current DPI mode. This one is probably sent when changing tabs, if they didn't change the program design too much
Message to reset the mouse to its original settings. It is obviously sent when clicking on "reset" or default.

Capture protocol

I usually just use Virtual box with a windows guest and the control software installed on it (I personally use a XP image, but it should work the same regardless of the OS). You need to modprobe usbmon to use the usb monitor with Wireshark. The complicated part (for me, at least) is to select the right usb device. I usually just move the mouse and see which usb traffic graph goes up in the device selection screen. Once the capture is launched, I try not to interact with the mouse (or its sensor, at least -- you can cover it if you want), as it will generate a lot of noise in the packet dump. I recommend using a secondary mouse. Now, you need to send enough commands so that we can then reverse-engineer the protocol from the packets. I suggest writing everything down, including the timestamps relative to the capture start time (use a stopwatch if necessary, this makes it easier to filter the packets).

For example, you would like to pick a mode, write the lowest DPI possible, then another determined value, another, until the maximum is reached (8200 for your mouse, it seems). That's for setting the value.

A lot of different actions can be determined with the data the software exchanges when it starts up. You can change a few settings (mode, DPI), restart the software, and compare the exchanged data in the post-mortem. Of course, I suggest changing only one setting each time, and writing down which one :)

The reset sequence is probably the easiest one to guess, as it's unique, and should be exactly the same each time it is sent.

Analysis

Understanding the USB topology helps quite a bit, you can read the USB2 specification if you want, it's quite interesting, but can be quite long. Here, it is only useful to know that there are four (bulk, control, interupt, isochronous, IIRC) types of data transfers in the USB protocol. Ours will probably be control transfers (it's designed for this, and that's the way it was handled for the other models).

Here is what we want at the end: https://github.com/MayeulC/Saitek/wiki/R.A.T-9-USB-Documentation#usb-protocol

The next step is to write a tool for trying what we reverse-engineered. I personally did this in C at first, but python turned out to be a lot easier to work with.

import usb1
context = usb1.USBContext()
handle = context.openByVendorIDAndProductID(0x0738, 0x1704)
# and now, play around with it
# for example, check if the reset packet is the same:
bmRequestType = 0x40
bRequest = 145
wValue = 0x0000
wIndex = 115
data = b''
handle.controlWrite(bmRequestType, bRequest, wValue, wIndex, data)
# At this point, you should get an exception if the command is invalid, or it might just have worked

Note

Now that I think about it, it might be simpler to try what I wrote in the snippet first: with a bit of luck, only some commands will have changed. If you could try the commands from the previous protocol with your mouse, that might reduce the workload a lot. The code is pretty much self-explaining, from line 118.

So, this is pretty much the whole procedure, written down. The rest is up to you, your time and your willingness :)

MayeulC / Saitek