-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
HID Mapping
Mixxx doesn't currently have a semantic mapping format for HID or USB
bulk-transfer mode controllers, so they must be handled entirely in
script. That said, the procedure to do so is exactly the same as for
MIDI controllers that use scripting, but you also add
an incomingData
function to handle all input from the controller.
The steps are:
- Create your script file. The same function and file naming conventions as well as init and shutdown function requirements apply as with MIDI scripting.
- The script file must also contain a function called
incomingData
. This will receive all data packets from the controller and is responsible for parsing them and taking appropriate actions based on which bytes change. It has the same signature as the inboundSysex function in MIDI scripting. - Create an XML file that tells Mixxx the name of the controller and
which script file(s) to load, just like with MIDI
scripting
but make sure to end the file name with
.hid.xml
or.bulk.xml
as appropriate.
Read on for more details.
Here is an example file containing the required elements:
var SuperCool = {};
SuperCool.init = function (ID,debugging) {
// Do setup here
if (debugging) print("SuperCool "+ID+" initialized!");
}
SuperCool.shutdown = function () {
// Do shutdown steps here, like turning off all LEDs
}
SuperCool.incomingData = function(data,length) {
// Parse packet data here & call relevant functions
}
There is no standard HID packet arrangement/structure. The length and
contents (and even
endianness) are completely
up to the manufacturer. For input packets, you can watch the incoming
packets in Mixxx's console output when running Mixxx with the
--controllerDebug
command line option. For output, you can examine the
USB descriptors of the HID device to figure out what packets to send. On
Linux you can use the
usbhid-dump and
hidrd-convert tools to show these
descriptors in a human readable format. First, identify the USB product
and vendor ID of your device with lsusb:
$ lsusb
Bus 001 Device 004: ID 046d:c52b Logitech, Inc. Unifying Receiver
Here the vendor ID is 046d and the product ID is c52b. Use these with usbhid-dump:
usbhid-dump -dVENDORID:PRODUCTID | grep -v : | xxd -r -p | hidrd-convert -o spec
Refer to this tutorial for how to interpret the information from hidrd-convert.
Once you know what data you want to send, simply call
controller.send()
with:
- An array of data bytes to send,
- null (the second parameter is required for backwards compatibility, but it is actually ignored by Mixxx)
- The HID report ID. If the controller only supports a single report packet, set this as 0.
var byteArray = [ byte1, byte2, byte3, ..., byteN ];
controller.send(byteArray, null, reportID);
Here is an example containing everything you need. Just copy and change the appropriate parts:
<?xml version="1.0" encoding="utf-8"?>
<MixxxControllerPreset schemaVersion="1" mixxxVersion="1.11+">
<info>
<name>SuperCool HID Controller</name>
<author>Your Name Here</author>
<description>HID mapping for the SuperCool controller</description>
<devices> <!-- Optional section that Mixxx can use to auto-load presets on matching devices -->
<!-- Get the vendor and product IDs for the controller from your operating system -->
<product protocol="hid" vendor_id="0x1111" product_id="0x100" />
</devices>
</info>
<controller id="SuperCoolHID">
<scriptfiles>
<file filename="SuperCool-Controller.js" functionprefix="SuperCool"/>
</scriptfiles>
</controller>
</MixxxControllerPreset>
There is also an HID Packet Parser JS
script in the res/controllers
directory you can examine for parsing
hints. (If you would like to try using it directly, simply add it to the
top of the scriptfiles
list in your XML file:)
<file filename="common-hid-packet-parser.js" functionprefix=""/>
However, the structure of this library's code is messy and it may cause as many hassles to use it as it solves.
Familiarise yourself with HID scripting by reading the previous sections and looking into existing HID mappings. Basic programming knowledge is required.
Run mixxx --controllerDebug
and see which bytes change when you toy
around with the controls. Map these bytes to the mixxx controls.
Go into Windows and download software which natively supports this controller (e.g. you can use the demo of Traktor Pro for Traktor Controllers). Get USBlyzer (it has a free demo) and watch which signals the software sends and what that changes on the controller. Then try to send something to these in your mapping script via an output package and see if you are right. If yes, proceed mapping them to the correct values.
For any controller mapping, we need a manual page as well. A good example for such a manual page, is the page for the Traktor Kontrol Z1 The manual page is created by a seperate PR in our manual repository: https://github.com/mixxxdj/manual
Mixxx is a free and open-source DJ software.
Manual
Hardware Compatibility
Reporting Bugs
Getting Involved
Contribution Guidelines
Coding Guidelines
Using Git
Developer Guide
Creating Skins
Contributing Mappings
Mixxx Controls
MIDI Scripting
Components JS
HID Scripting