(WIP) Mapping for the Traktor Kontrol Z2 #3038

JoergAtGithub · 2020-08-23T11:25:55Z

New HID mapping for the Native Instrument Kontrol Z2 mixer.

Note: This mapping requires features from 2.4 or Main branch and can not work with 2.2 or 2.3 builds!

The Documentation PR is mixxxdj/manual#236
Link to the Preview of the Z2 Mapping-Manual: https://deploy-preview-236--mixxx-manual.netlify.app/hardware/controllers/native_instruments_traktor_kontrol_z2.html

ywwg · 2020-08-23T16:28:43Z

cool thanks for basing this on my refactored js :). hopefully it's easier to maintain and debug.

JoergAtGithub · 2020-08-23T16:37:33Z

It's my first HID mapping, therfore I can't compare. It was easy to get all the knobs and buttons to work, but the LED lights do not show reproduceable behaviour yet.

ywwg · 2020-08-23T16:56:51Z

on the s3, I found that the outgoing HID messages have to be exactly the right length for them to work. I used usblyzer to sniff the outgoing packets from traktor.

JoergAtGithub · 2020-08-23T21:22:15Z

I could get nearly all LEDs to work, except the last one (an LED in a 7segment display). I'ts byte 95 of a packet of 95 bytes. I get always the following error message (German windows settings):

Debug [Controller]: HID TraktorZ2: debugLights
Debug [Controller]: HID 2

Debug [Controller]: HID i 0 70,70,70,70,70,00,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,FF,00,00,FF,00,00,00,00,00,00,00,00,34,34,34,00,
00,34,00,FF,00,00,00,34,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,70,
Debug [Controller]: HID 95

Debug [Controller]: HID 128 95

Warning [Controller]: Unable to send data to "Traktor Kontrol Z2 13EA_4" serial # "C86013EA" : "Der angegebene Benutzerpuffer ist für den angeforderten Vorgang
nicht zulässig."
Debug [Controller]: HID i 1 FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF,FF
Debug [Controller]: HID 41

Debug [Controller]: HID 129 41

Debug [Controller]: 95 bytes sent to Traktor Kontrol Z2 13EA_4 serial # C86013EA (including report ID of 129 )
Debug [Controller]: HID TraktorZ2: Init done!

If I reduce the size to 94 bytes, the other LEDs can be controlled

ywwg · 2020-08-24T00:16:54Z

res/controllers/Traktor.Kontrol-Z2-hid-scripts.js

+TraktorZ2.shutdown = function() {
+    // Deactivate all LEDs
+    var dataStrings = [
+        "      00 00  00 00 00 00  00 00 00 00  00 00 00 00 " +


there is a bug in this code (that was in my code too-- if you have leading spaces, the first item in the list is an empty string so that byte does get set

the fix is to eliminate leading spaces in your strings

Thank's for poiting to this! This is the shutdown code, which I've to rework anyway. Currently I'm working on debugLights.

The shutdown code for the Z2 will be tricky anyway, because of the concept of seamless switching between internal and external mixing mode. The idea is:
-At the end of your DJ set, switch one channel from internal to external mixing mode and play an analog vinyl
-DJ1 disconnects his laptop -> Shutdown code must not interfere the music
-DJ2 connects his laptop -> Init code must not interfere the music
-Switch the deck with the analog vinyl back to internal mixing mode

Therefore I will have to decide LED by LED if the shutdown code should reset it, or if the LED represents a still active state.

ywwg · 2020-08-24T00:17:06Z

res/controllers/Traktor.Kontrol-Z2-hid-scripts.js

+        data[i].length = splitted.length;
+        for (var j = 0; j < splitted.length; j++) {
+            var byteStr = splitted[j];
+            if (byteStr.length === 0) {


this line will get activated

ywwg · 2020-08-24T00:18:33Z

res/controllers/Traktor.Kontrol-Z2-hid-scripts.js

+        HIDDebug(splitted.length + "\n");
+        for (var j = 0; j < splitted.length; j++) {
+            var byteStr = splitted[j];
+            if (byteStr.length === 0) {


Add hiddebug here to make sure this isn't happening

ywwg · 2020-08-24T00:18:59Z

looks like a low-level HID error message. I'm not sure why the 95th byte makes it blow up.

JoergAtGithub · 2020-08-27T20:11:39Z

Cross-Reference to related Zulip-Chat: https://mixxx.zulipchat.com/#narrow/stream/113295-controller-mapping/topic/Traktor.20Kontrol.20Z2

vbatts · 2020-08-30T17:49:00Z

Related work (by the op) for the LEDs on this same board: #3051

JoergAtGithub · 2020-09-14T10:51:51Z

This will not go into 2.3, because this mapping can't work without #3051, which is targeted for 2.4.

Holzhaus

Thank you.

There are code-style issues. Please click the "Details" link for Travis CI below this PR and check the output of the pre-commit job.

Also, starting with Mixxx 2.3, all controller mappings are now supposed to be documented in the Manual. This is necessary so that other users know how to use this mapping. We also need it to review it properly and check if the mapping makes sense and if the code matches the documentation.

Please fork the mixxxdj/manual repository, check out the manual-2.3.x branch and add documentation to the source/hardware/controllers directory. Open the pull request and add the link to the PR description.

Here's an example how such documentation could look like: https://manual.mixxx.org/2.3/en/hardware/controllers/roland_dj_505.html (If you don't have schematic images and don't want to draw them yourself, just use the same numbering as in the controller's manual and document the buttons like that).

res/controllers/Traktor Kontrol Z2.hid.xml

Holzhaus · 2020-10-13T12:56:09Z

res/controllers/Traktor Kontrol Z2.hid.xml

+        <name>Traktor Kontrol Z2</name>
+        <author>Jörg Wartenberg (based on the Traktor S3 mapping by Owen Williams)</author>
+        <description>HID Mapping for Traktor Kontrol Z2</description>
+        <wiki>http://mixxx.org/wiki/doku.php/traktor_z2</wiki>


Please use a github wiki link

1.) I removed the link to the non-existing wiki page at all.
2.) I added a link to the manual, and it points to the 2.3 manual, but this PR is rebased to master.

Holzhaus · 2020-10-16T18:52:51Z

Pre-commit issues:

codespell................................................................Failed
- hook id: codespell
- exit code: 1
res/controllers/Traktor-Kontrol-Z2-hid-scripts.js:829: inbetween ==> between, in between
res/controllers/Traktor-Kontrol-Z2-hid-scripts.js:1155: swiched ==> switched
eslint...................................................................Failed
- hook id: eslint
- exit code: 1
/home/travis/build/mixxxdj/mixxx/res/controllers/Traktor-Kontrol-Z2-hid-scripts.js
  12:1  error  Parsing error: The keyword 'const' is reserved
✖ 1 problem (1 error, 0 warnings)

Tim19801 · 2020-10-22T12:14:39Z

Hi, thanks for the mapping. I've tried the setting under Mixxx 2.3 and older versions under Ubuntu. I didn't have luck so far. Mixxx sees the controller and I can indicate which channels I want to use (so it mus recognize my soundcard under the Kontrol Z2 in some sort of way) but it only sends audio over the master output.

I can't control anything either. Maybe I can also check the template under Windows.
In the manual it says the Kontrol Z2 is USB compliant and automatically recognized in Linux but I don't have any luck with it.

Could someone please point me in the right direction? Thanks! Tim

JoergAtGithub · 2020-10-22T19:29:51Z

The soundcard is independent from this mapping for Buttons, Knobs, Faders and LEDs.
If you can select Traktor Z2 as Audio source, than the operating system has recognized the soundcard. The soundcard settings should be:

JoergAtGithub · 2020-10-22T19:37:47Z

Mixxx 2.3.0 is not sufficient for this mapping. To use this mapping, you need a recent build of the Master tree containing the PR #3051 .

The controller mapping must be selected manually:

JoergAtGithub · 2020-10-22T19:39:36Z

Please continue general discussions about Mixxx and the Traktor Z2 here: https://mixxx.zulipchat.com/#narrow/stream/113295-controller-mapping/topic/Traktor.20Kontrol.20Z2

Tim19801 · 2020-10-26T07:52:44Z

Please continue general discussions about Mixxx and the Traktor Z2 here: https://mixxx.zulipchat.com/#narrow/stream/113295-controller-mapping/topic/Traktor.20Kontrol.20Z2

Thank you for the help so far. Sorry for the late responseI think I'll try to get the controller to work in Windows first with the suggested mapping. Will report back on the above link if it also Worked under Linux. I also need to read a tutorial on how to pull the pr in Mixxx. Don't have experience with that so need to sort that out first ;-)

JoergAtGithub · 2020-10-27T18:15:39Z

You don't need to build Mixxx yourself, to test this. The CI systems build this automatically for each PR.
To get a Windows download of any PR, click on the continuous-integration/appveyor/pr Details-Link at the bottom of the PR -> Visual Studio 2017... -> Artifacts
In general, this controller mapping contains nothing platform specific. It should run on Linux, MacOS and Windows. The only important thing is, that you use a recent build of the Main development tree.

Tim19801 · 2020-11-01T22:14:55Z

You don't need to build Mixxx yourself, to test this. The CI systems build this automatically for each PR.
To get a Windows download of any PR, click on the continuous-integration/appveyor/pr Details-Link at the bottom of the PR -> Visual Studio 2017... -> Artifacts
In general, this controller mapping contains nothing platform specific. It should run on Linux, MacOS and Windows. The only important thing is, that you use a recent build of the Main development tree.

Hi Joerg,

Thanks for your time to help me out. Sorry for my late responses. Very busy lately. I'm on Linux right now and not Windows. What I tried to do is clone everything and install it. But it indicates there's no makefile. Can imagine cause I don't think it's complete. I'm absolutely not experienced with GIT. I'll try to sort this out when I'm back on Windows. Or I'll just patiently wait for a new version of Mixxx where the Kontrol Z2 is integrated and will learn a thing or two about GIT in the mean time. I'm not sure I follow your explanation; To get a Windows download of any PR, click on the continuous-integration/appveyor/pr Details-Link at the bottom of the PR -> Visual Studio 2017... -> Artifacts but will check it out when I reinstalled Windows on my laptop. Will let you know if I make progress and have tested this. The Z2 seems a very difficult card on Linux. Didn't have luck with it either on xwax so far and it must be USB compliant. Anyway.. thanks. Tim

Holzhaus · 2020-11-01T22:47:41Z

Please open a thread on Zulip chat. We can help you with git and compiling on Linux. The PR discussion is not the right place for that.

Tim19801 · 2020-11-02T13:58:49Z

Sorry for that. Will pay attention to it from now on.

ywwg reviewed Aug 24, 2020

View reviewed changes

uklotzde added this to the 2.3.0 milestone Aug 27, 2020

JoergAtGithub changed the base branch from 2.3 to master September 14, 2020 12:14

Holzhaus added the controller mappings label Oct 13, 2020

Holzhaus requested changes Oct 13, 2020

View reviewed changes

JoergAtGithub mentioned this pull request Oct 20, 2020

(WIP) Initial manual page for the NI Traktor Kontrol Z2 mixxxdj/manual#236

Draft

Be-ing changed the base branch from master to main October 23, 2020 23:11

JoergAtGithub force-pushed the Traktor-Z2-2.3 branch from 7e1a451 to ca64657 Compare October 26, 2020 18:04

JoergAtGithub force-pushed the Traktor-Z2-2.3 branch 2 times, most recently from cce8330 to fd485b0 Compare November 1, 2020 20:55

github-actions bot added soundio cmake serato search controller backend labels Jan 12, 2025

daschuer removed skins effects library engine ui build autodj code quality preferences scanner waveform vinylcontrol itunes soundsource browse sync broadcast Bugs pertaining to streaming radio broadcaster use-case analyzer packaging soundio cmake serato search controller backend labels Jan 25, 2025

daschuer changed the base branch from 2.4 to 2.5 January 25, 2025 22:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(WIP) Mapping for the Traktor Kontrol Z2 #3038

(WIP) Mapping for the Traktor Kontrol Z2 #3038

JoergAtGithub commented Aug 23, 2020 •

edited

Loading

ywwg commented Aug 23, 2020

JoergAtGithub commented Aug 23, 2020

ywwg commented Aug 23, 2020

JoergAtGithub commented Aug 23, 2020

ywwg Aug 24, 2020

ywwg Aug 24, 2020

JoergAtGithub Aug 24, 2020

ywwg Aug 24, 2020

ywwg Aug 24, 2020

ywwg commented Aug 24, 2020

JoergAtGithub commented Aug 27, 2020

vbatts commented Aug 30, 2020

JoergAtGithub commented Sep 14, 2020

Holzhaus left a comment

Holzhaus Oct 13, 2020

JoergAtGithub Oct 16, 2020

Holzhaus commented Oct 16, 2020

Tim19801 commented Oct 22, 2020

JoergAtGithub commented Oct 22, 2020

JoergAtGithub commented Oct 22, 2020

JoergAtGithub commented Oct 22, 2020

Tim19801 commented Oct 26, 2020

JoergAtGithub commented Oct 27, 2020

Tim19801 commented Nov 1, 2020

Holzhaus commented Nov 1, 2020 •

edited

Loading

Tim19801 commented Nov 2, 2020

(WIP) Mapping for the Traktor Kontrol Z2 #3038

Are you sure you want to change the base?

(WIP) Mapping for the Traktor Kontrol Z2 #3038

Conversation

JoergAtGithub commented Aug 23, 2020 • edited Loading

ywwg commented Aug 23, 2020

JoergAtGithub commented Aug 23, 2020

ywwg commented Aug 23, 2020

JoergAtGithub commented Aug 23, 2020

ywwg Aug 24, 2020

Choose a reason for hiding this comment

ywwg Aug 24, 2020

Choose a reason for hiding this comment

JoergAtGithub Aug 24, 2020

Choose a reason for hiding this comment

ywwg Aug 24, 2020

Choose a reason for hiding this comment

ywwg Aug 24, 2020

Choose a reason for hiding this comment

ywwg commented Aug 24, 2020

JoergAtGithub commented Aug 27, 2020

vbatts commented Aug 30, 2020

JoergAtGithub commented Sep 14, 2020

Holzhaus left a comment

Choose a reason for hiding this comment

Holzhaus Oct 13, 2020

Choose a reason for hiding this comment

JoergAtGithub Oct 16, 2020

Choose a reason for hiding this comment

Holzhaus commented Oct 16, 2020

Tim19801 commented Oct 22, 2020

JoergAtGithub commented Oct 22, 2020

JoergAtGithub commented Oct 22, 2020

JoergAtGithub commented Oct 22, 2020

Tim19801 commented Oct 26, 2020

JoergAtGithub commented Oct 27, 2020

Tim19801 commented Nov 1, 2020

Holzhaus commented Nov 1, 2020 • edited Loading

Tim19801 commented Nov 2, 2020

JoergAtGithub commented Aug 23, 2020 •

edited

Loading

Holzhaus commented Nov 1, 2020 •

edited

Loading