NI Traktor Kontrol S2 Mk1: add controller mapping

[leifhelm]

This adds a controller mapping for the Traktor Kontrol S2 Mk1. It is based on the mapping from the Traktor Kontrol S2 Mk2.

Things to do before merge:

• [x] Add documentation to the manual (#412)

Please give feedback especially if something does not work (as expected).

[uklotzde]

As a First-time contributor we need your consent by formally signing the contributor agreement:

https://docs.google.com/forms/d/e/1FAIpQLScC9QG327sjLL0eWftmfGUasxFFLxg6LCXJ2xHDYRzFIRqyiw/viewform?formkey=dEpYN2NkVEFnWWQzbkFfM0ZYYUZ5X2c6MQ

[Be-ing]

I'm confused... I thought this wasn't an HID device?? Can you post the output of lsusb -v?

[leifhelm]

It is contains HID device according to lsusb -v. The protocol is very similar to the S2 Mk2. Just a few things got moved around and one message was added.

Output of lsusb -v

Bus 001 Device 003: ID 17cc:1101 Native Instruments Traktor Kontrol S2
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass          239 Miscellaneous Device
  bDeviceSubClass         2
  bDeviceProtocol         1 Interface Association
  bMaxPacketSize0        64
  idVendor           0x17cc Native Instruments
  idProduct          0x1101
  bcdDevice            0.1b
  iManufacturer          12 Native Instruments
  iProduct                7 Traktor Kontrol S2
  iSerial                13 55054651
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength       0x00d0
    bNumInterfaces          4
    bConfigurationValue     1
    iConfiguration          0
    bmAttributes         0x80
      (Bus Powered)
    MaxPower              480mA
    Interface Association:
      bLength                 8
      bDescriptorType        11
      bFirstInterface         0
      bInterfaceCount         2
      bFunctionClass          1 Audio
      bFunctionSubClass       0
      bFunctionProtocol      32
      iFunction               0
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           0
      bInterfaceClass         1 Audio
      bInterfaceSubClass      1 Control Device
      bInterfaceProtocol     32
      iInterface              7 Traktor Kontrol S2
      AudioControl Interface Descriptor:
        bLength                 9
        bDescriptorType        36
        bDescriptorSubtype      1 (HEADER)
        bcdADC               2.00
        bCategory               8
        wTotalLength       0x0048
        bmControls           0x00
      AudioControl Interface Descriptor:
        bLength                 8
        bDescriptorType        36
        bDescriptorSubtype     10 (CLOCK_SOURCE)
        bClockID               40
        bmAttributes            1 Internal fixed clock
        bmControls           0x07
          Clock Frequency Control (read/write)
          Clock Validity Control (read-only)
        bAssocTerminal          0
        iClockSource           26 Internal Clock
      AudioControl Interface Descriptor:
        bLength                17
        bDescriptorType        36
        bDescriptorSubtype      2 (INPUT_TERMINAL)
        bTerminalID             2
        wTerminalType      0x0101 USB Streaming
        bAssocTerminal          0
        bCSourceID             40
        bNrChannels             4
        bmChannelConfig    0x00000000
        iChannelNames          16 Main Left
        bmControls         0x0000
        iTerminal               2 Input
      AudioControl Interface Descriptor:
        bLength                26
        bDescriptorType        36
        bDescriptorSubtype      6 (FEATURE_UNIT)
        bUnitID                10
        bSourceID               2
        bmaControls(0)     0x00000000
        bmaControls(1)     0x00000000
        bmaControls(2)     0x00000000
        bmaControls(3)     0x00000000
        bmaControls(4)     0x00000000
        iFeature               15 Output Volume Control
      AudioControl Interface Descriptor:
        bLength                12
        bDescriptorType        36
        bDescriptorSubtype      3 (OUTPUT_TERMINAL)
        bTerminalID            20
        wTerminalType      0x0301 Speaker
        bAssocTerminal          0
        bSourceID              10
        bCSourceID             40
        bmControls         0x0000
        iTerminal               5 Audio Output Terminal
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        1
      bAlternateSetting       0
      bNumEndpoints           0
      bInterfaceClass         1 Audio
      bInterfaceSubClass      2 Streaming
      bInterfaceProtocol     32
      iInterface              8 Traktor Kontrol S2
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        1
      bAlternateSetting       1
      bNumEndpoints           2
      bInterfaceClass         1 Audio
      bInterfaceSubClass      2 Streaming
      bInterfaceProtocol     32
      iInterface              9 Audio Out Alt
      AudioStreaming Interface Descriptor:
        bLength                16
        bDescriptorType        36
        bDescriptorSubtype      1 (AS_GENERAL)
        bTerminalLink           2
        bmControls           0x00
        bFormatType             1
        bmFormats          0x00000001
          PCM
        bNrChannels             4
        bmChannelConfig    0x00000000
        iChannelNames          16 Main Left
      AudioStreaming Interface Descriptor:
        bLength                 6
        bDescriptorType        36
        bDescriptorSubtype      2 (FORMAT_TYPE)
        bFormatType             1 (FORMAT_TYPE_I)
        bSubslotSize            4
        bBitResolution         24
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x01  EP 1 OUT
        bmAttributes            5
          Transfer Type            Isochronous
          Synch Type               Asynchronous
          Usage Type               Data
        wMaxPacketSize     0x00f0  1x 240 bytes
        bInterval               1
        AudioStreaming Endpoint Descriptor:
          bLength                 8
          bDescriptorType        37
          bDescriptorSubtype      1 (EP_GENERAL)
          bmAttributes         0x00
          bmControls           0x00
          bLockDelayUnits         2 Decoded PCM samples
          wLockDelay         0x0008
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes           17
          Transfer Type            Isochronous
          Synch Type               None
          Usage Type               Feedback
        wMaxPacketSize     0x0004  1x 4 bytes
        bInterval               4
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        2
      bAlternateSetting       0
      bNumEndpoints           0
      bInterfaceClass       254 Application Specific Interface
      bInterfaceSubClass      1 Device Firmware Update
      bInterfaceProtocol      1
      iInterface              0
      Device Firmware Upgrade Interface Descriptor:
        bLength                             7
        bDescriptorType                    33
        bmAttributes                        7
          Will Not Detach
          Manifestation Tolerant
          Upload Supported
          Download Supported
        wDetachTimeout                    250 milliseconds
        wTransferSize                      64 bytes
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        3
      bAlternateSetting       0
      bNumEndpoints           2
      bInterfaceClass         3 Human Interface Device
      bInterfaceSubClass      0
      bInterfaceProtocol      0
      iInterface              0
        HID Device Descriptor:
          bLength                 9
          bDescriptorType        33
          bcdHID               1.10
          bCountryCode            0 Not supported
          bNumDescriptors         1
          bDescriptorType        34 Report
          wDescriptorLength     614
         Report Descriptors:
           ** UNAVAILABLE **
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x82  EP 2 IN
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0040  1x 64 bytes
        bInterval               1
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x02  EP 2 OUT
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0040  1x 64 bytes
        bInterval               1
Device Qualifier (for other device speed):
  bLength                10
  bDescriptorType         6
  bcdUSB               2.00
  bDeviceClass          239 Miscellaneous Device
  bDeviceSubClass         2
  bDeviceProtocol         1 Interface Association
  bMaxPacketSize0        64
  bNumConfigurations      1
can't get debug descriptor: Resource temporarily unavailable
Device Status:     0x0000
  (Bus Powered)

[Be-ing]

Ah, I think I was confusing this with the S4 Mk1. I think the S2 Mk1 may have been one of the first controllers where NI switched from a Vendor Defined Class for a Bulk endpoint to HID.

[leifhelm]

The manual states that it uses a proprietary protocol named NHL.

[Be-ing]

Ah, that explains my confusion. The manufacturer's documentation is incorrect.

[uklotzde]

• Contributor agreement has been signed
• Manual PR is linked and CI passes

@Be-ing @Holzhaus Include in 2.3.1?

[Be-ing]

Let's not delay 2.3.1 further for PRs that haven't started review and get to work reviewing the backlog of mapping PRs for 2.3.2.

[github-actions[bot]]

This PR is marked as stale because it has been open 90 days with no activity.

[daschuer]

Who is able and has interest to review this?

[nPrevail]

Does this need to be tested? I have a S4 MK1 available.

[shellkjell]

I'll give this a go and report back with results

[shellkjell]

I've been using this setup with the S2 "Mk1" for two days now without any issues I can attribute to the mappings themselves.

I'm running Mixxx 2.3.2 on a Raspberry Pi 4

[JoergAtGithub]

@leifhelm I would like to start with the code review of the S2 Mk1 HID mapping. But before I start, I would like to hear, if you are still available to address findings of the code review?

[leifhelm]

Yes :)

[leifhelm]

I do not like that I hard-coded the thresholds for the jog wheels. I had to adjust both values to get reliable jog wheel touch to work. Maybe it is more nice to measure the value when not pressed at startup. This is also not that nice. I do not know how Traktor solves this problem either.

[JoergAtGithub]

• Mapping code looks good for me
• A second user confirmed, that the mapping works for him too
• Manual is in place Let's try what happens, if I press the button Merge pull request which I never used before...

[JoergAtGithub]

@leifhelm Thank you for your contribution and your patience!