[WIP] Support for Maschine MK3

[Drachenkaetzchen]

This issue documents my findings about the Maschine MK3.

Basic Information from usb-devices

T:  Bus=02 Lev=02 Prnt=02 Port=05 Cnt=03 Dev#= 11 Spd=480 MxCh= 0
D:  Ver= 2.00 Cls=ef(misc ) Sub=02 Prot=01 MxPS=64 #Cfgs=  1
P:  Vendor=17cc ProdID=1600 Rev=01.41
S:  Manufacturer=Native Instruments
S:  Product=Maschine MK3
S:  SerialNumber=REMOVED
C:  #Ifs= 7 Cfg#= 1 Atr=80 MxPwr=480mA
I:  If#= 0 Alt= 0 #EPs= 0 Cls=01(audio) Sub=01 Prot=20 Driver=snd-usb-audio
I:  If#= 1 Alt= 1 #EPs= 1 Cls=01(audio) Sub=02 Prot=20 Driver=snd-usb-audio
I:  If#= 2 Alt= 0 #EPs= 0 Cls=01(audio) Sub=02 Prot=20 Driver=snd-usb-audio
I:  If#= 3 Alt= 0 #EPs= 2 Cls=01(audio) Sub=03 Prot=00 Driver=snd-usb-audio
I:  If#= 4 Alt= 0 #EPs= 2 Cls=03(HID  ) Sub=00 Prot=00 Driver=(none)
I:  If#= 5 Alt= 0 #EPs= 1 Cls=ff(vend.) Sub=bd Prot=00 Driver=(none)
I:  If#= 6 Alt= 0 #EPs= 0 Cls=fe(app. ) Sub=01 Prot=01 Driver=(none)

if#=5 is bulk data, maybe for the displays?
if#=6 seems to be for the firmware update.

[Drachenkaetzchen]

A bit of success: I can now make device-test to turn on the Mute/Choke button as well as 4 LEDs around the encoder button. No inputs are recognized yet, but well, at least it's connecting ;)

[Drachenkaetzchen]

Okay, I got the buttons working (partially). My c++ is very rusty, so I need to figure out how the mapping in cabl works. I added debug outputs to both the DeviceTest (which outputs the button) as well as the device implementation method processButtons to display the button ID of the device.

I now have a partial map of buttons, some buttons didn't output anything, so I guess the index list is wrong.

I also tried to modify the button list in MaschineMK3::Button however it's not clear how it works. I assume the position in the list defines which button is which. For example, NoteRepeat is button number 20, so I assume that NoteRepeat must be at position 20 in the list, right?

[shaduzlabs]

That's good news, I didn't really have time so far to work on the Mk3 support :)
You're right, the position in the list is the actual position of the corresponding bit in the HID report, let me know if I can help you any further!
The display is going to be a bit tricky: like Maschine Studio and Komplete Kontrol Mk2, the new Maschine controller uses a proprietary compression algorithm to send display frames and I didn't try to reverse-engineer it so far.

[Drachenkaetzchen]

I'm on to the display support. I've captured frames via Wireshark and usbpcap.

What I know so far is documented in this google doc:

https://docs.google.com/document/d/1xdWTY4XAMPFj8dKzvZJnUyJy-SxdZiPVdcSUw1nVl8A/edit?usp=sharing

Feel free to read and comment if you find something interesting ;)

[Drachenkaetzchen]

Okay, that was way easier than expected.

[shaduzlabs]

Great job @FELICITUS, that was really quick :)
Are you also able to send partial updates?

[Drachenkaetzchen]

@shaduzlabs not yet. Right now I only have a PHP script to convert a 480x272 image to a data file and a python script to send the raw data to the interface. If you want both the python and the PHP script tell me :)

There's more to the protocol, but right now I just send the raw pixel data using command code 1 to the device. Command code 2 supports pixel repetition, maybe there are other command codes. I also gotta clean up the documentation

[Drachenkaetzchen]

I can finally watch anime on the Maschine MK3 ;)

https://www.youtube.com/watch?v=3qieMM4V1SU

[Drachenkaetzchen]

A few words on the protocol:

It's basically a bunch of commands being sent to the display. Format is RGB565. Right now I found two commands:

first 16 bytes: Header, which includes the display to address as well as X/Y start position and the width/height of the transmission.

After that commands are following. Each command header is 4 bytes long. The first of that 4 bytes is the command code and the next 3 are parameters.

Command Code 00: Sends the next two pixel values to the display. Parameters are all zero. Data is two pixels with 2 bytes each
Command Code 01: Repeats two given pixel values n times. Parameters are the number of repetitions. Data is two pixels with 2 bytes each.
Command Code 03: Unknown yet, but required to display things on the display. Parameters are all zero. No data.
Command Code 04: End of Transmission. Parameters are all zero. No data

[Drachenkaetzchen]

Documentation for the display protocoll can now be found here:

https://github.com/Drachenkaetzchen/cabl/tree/develop/doc/hardware/maschine-mk3

Will send a PR as soon as I got the code working.

[Drachenkaetzchen]

I just added documentation for the HID protocol, including touch strip, touch sense knobs and all LEDs.

Fun fact: The Maschine MK3 even knows the physical state of the volume knobs on the back.

[Drachenkaetzchen]

I now have a preliminary version in my repository. However, currently it's very unlikely that I'll finish support, since my C++ isn't that strong anymore and my holiday is almost over.

There are a few things to consider:

• Right now, the USB Driver claims interface #0 hardcoded, whilst the NI Maschine MK3 uses interface case-sensitive CoreMIDI error in DeviceTest #5
• The bulk transfer, for some reason, doesn't allow me to push the display data for one display at once; instead, I have a workaround where I transmit every line individually. This is pretty slow. When I try to transmit the full display data (262208 bytes), I see in wireshark that only around 62kb are transmitted.
• I believe the Macro M_REGISTER_DEVICE_CLASS must be rewritten to allow for the same device with the same USB vendor and product ID to exist in the registry; however, I didn't research this for too long.

[shaduzlabs]

Wow! Kudos for this seriously impressive work :)

Now I'll be able to add support for Komplete Kontrol MK2 and Maschine Studio as well since they use the same display protocol.
I'll do some refactoring taking into account your input and will investigate the display transfer issue further.
Also, in the next weeks I'm going to replace the gfx subsystem with a separate library, so there will be a few more changes to the display handling code.

[mstaack]

@shaduzlabs have there been any updates?

[mstaack]

@Drachenkaetzchen amazing work with that documentation regarding the mk3!!