Crowdsourcing the deciphering of the init handshake

[chmod222]

I'm opening this up because I've been busy trying to get ISO/ANSI layout autodetection to work and would need more outside data for this. I now know that both the ISO and ANSI versions of the same revision of the MK Pro L share 003b as the product ID, so this cannot be used to figure out the layout.

So my suspicion is the 40 20 (handshake part 2) packet.

I have added a new test binary that can be compiled using: make cmmk-debug. It's used the same way as cmmk-test, so the same LD_LIBRARY_PATH and permission things apply.

It simply connects to the keyboard and dumps out the initial exchange performed by the official binaries.

This is the output for my MasterKeys Pro L ISO:

Attaching to 2516:003b...
Firmware version: 2.2.1
Hexdump of handshake #1:
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: 05 00 00 00 32 2e 32 2e 31 00 00 00 ff ff ff ff  ....2.2.1.......
000010: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
000020: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
000030: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F

Hexdump of handshake #2:
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: 40 20 00 00 05 14 04 0c 12 01 20 00 00 00 00 00  @ ........ .....
000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F

If anyone wants to help out, please feel free to run this binary on your keyboard and attach its output along with the model / layout to this issue.

[RedFantom]

Here is the output for my MasterKeys Pro L ANSI RGB:

Attaching to 2516:003b...
Firmware version: 1.2.1
Hexdump of handshake #1:
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: 05 00 00 00 31 2e 32 2e 31 00 00 00 ff ff ff ff  ....1.2.1.......
000010: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
000020: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
000030: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F

Hexdump of handshake #2: (identical to the one above)
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: 40 20 00 00 05 14 04 0c 12 01 20 00 00 00 00 00  @ ........ .....
000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F

The only differing byte is 0x04. In your protocol file this is described as the major of the firmware version number, ASCII encoded. I last updated my keyboard in July, and the software (run in a VM with the keyboard attached) claims no updates are available. Could the version number actually be in the format layout.major.minor? In that case, it would match the enum in the official SDK header file:

enum LAYOUT_KEYBOARD {LAYOUT_UNINIT = 0, LAYOUT_US = 1, LAYOUT_EU = 2, LAYOUT_JP = 3};

[chmod222]

Hey, many thanks for the data. This is really interesting, as my firmware also claims to be up to date and I can not remember having updated it once since I bought it over 2 years ago.

So either A) the firmware version depends on the layout as they are using different branches that are versioned independently, B) the software uses some other way to query the layout and looks for specific firmware versions that way, or C) they really do encode the layout inside this version.

Whatever option is true, if I receive more samples and this stays consistent, I think this is a good enough property to use to determine the layout!

[Holzhaus]

Masterkeys MK750 keyboard ISO/German:
MK750GKCM1DE

$ cmmk-debug
Attaching to 2516:0067...
Layout detected as: 5
Firmware version:
Hexdump of handshake #1:
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: ff aa 00 00 01 02 00 00 00 00 00 00 00 00 00 00  ................
000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
Hexdump of handshake #2:
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: 40 20 00 00 05 14 04 0b 12 04 20 00 01 00 00 00  @ ........ .....
000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
Effect enabled: 254
Effect enabled: 0
Effect enabled: 4
Effect enabled: 7
Effect enabled: 3
Effect enabled: 176
Effect enabled: 9
Effect enabled: 8
Effect enabled: 2
Effect enabled: 1

[puddyput]

Masterkeys Pro S
SGK-6030-KKCM1-US

$ sudo LD_LIBRARY_PATH=dist/lib64 dist/bin/cmmk-debug 
Attaching to 2516:003c...
Layout detected as: 0
Firmware version: 1.2.1
Hexdump of handshake #1:
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: 05 00 00 00 31 2e 32 2e 31 00 00 00 ff ff ff ff  ....1.2.1.......
000010: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
000020: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
000030: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F

Hexdump of handshake #2:
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
000000: 40 20 00 00 05 14 04 0c 12 01 20 00 00 00 00 00  @ ........ .....
000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
        0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
Effect enabled: 0
Effect enabled: 4
Effect enabled: 8
Effect enabled: 2
Effect enabled: 5

[chmod222]

Welp, that's a curve ball on the MK750, using a different-ish protocol with no firmware response (ff aa is some sort of error, or "unknown command" response) is going to break the current autodetect. The slightly different 40 20 response doesn't really form a coherent picture either. At least the pattern seems to hold for the Pro L and Pro S models across various layouts.

Any way you could grab a couple of USB captures of the init process of the official software on the MK750? I found the free Win 7 VMs that Microsoft publishes + Wireshark/usbmon to be very useful.

[Holzhaus]

@chmod222 To use CM Portal, I had to update the firmware on my MK750 from V1.00.13 (factory) to V1.05.02. Now It seems like they changed the protocol or something like that. If I run cmmk-debug, It hangs:

$ cmmk-debug
Attaching to 2516:0067...
Layout detected as: 5
^C

cmmk_ctrl does not seem to work anymore, either.

Anyway, I managed to capture the official software USB traffic. I Just started it, then applied some changes and closed it. Here's the dump:
http://homepage.rub.de/Jan.Holthuis/downloads/mk750.pcapng

[chmod222]

Hm, yes it does.

The protocol communication is still fundamentally the same exchange over the same USB interface endpoints, but the commands are mostly different now and more complex. It returns the firmware in 12 20 as UTF-16 for some reason, the fundamental 41 x mode change and 5x profile changes remain the same, but there are a few new 52 query commands and it seems to use a different-enough set of packets for effects control.

I'm sorry for causing you to make your device unusuable with the lib for the time being, this is something that's going to be difficult for me to support without actually owning an MK750. The new protocol itself looks fairly harmless, but it's not someting I can decipher non-interactively.

I had to reverse the protocol on mine by setting a bunch of parameters to known and distinct values, which are then easy to find in the protocol dumps, or watching which packets the software sends when I, for example, change an effect or effect setting in the configurator.

[Holzhaus]

I'm sorry for causing you to make your device unusuable with the lib for the time being, this is something that's going to be difficult for me to support without actually owning an MK750.

That's not your fault. Nobody could reasonably expect them to change their protocol that much tbh. I also have a bunch of new effects, so it's not that bad ;-)

I made another capture using the CM Portal software and just went through all effects that are available:
https://homepage.rub.de/Jan.Holthuis/downloads/mk750-documented.pcapng
I also added package comments for the first package that is transmitted when selecting a new effect (use frame.comment filter in wireshark to only see packages with comments, then select a package and press Ctrl+Alt+c). I look into it further when I find the time. Just uploading it for now in case someone else want to have a look, too.

[Holzhaus]

I experimented a bit and found out how to activate some of the effects. However, this is quite a bit of work and I don't know when I'll find enough spare time to finish it. I uploaded some of my notes here, but it's nowhere near a mergeable state (or even a cherry-pickable one, for that matter).
Just in case someone else with a MK750 who wants to have a look and does not need to start from scratch.

[VirtualValence]

The SDK has been released on the coolermaster website, have you checked it out?