CDJ HID Protocol

Background

Historically, DJ controllers (meaning hardware whose purpose is to communicate with digital DJ Software) have been using MIDI over USB. With increasing complexity, the protocol became a bottleneck for certain applications, causing Hardware-manufacturers to start transmitting data via HID. This allows for comparatively simple mechanisms such as simply serializing the status of controls on the controller into a buffer of fixed format but also creating complex proprietary binary protocols involving data fragmented over multiple HID packets, handshakes, variable-length data, etc.

The PioneerDJ CDJ-2000NXS2 has many different ways to communicate with other devices such as other CDJs or Mixers. One if these methods is using a custom Network Protocol called ProDJLink whose reverse engineering efforts have inspired this project as well.

Protocol primitives

Simple header

Every Packet being sent and received to and from the CDJs shares this common header:

0123456789abcdefdecktype001020Packet rest according to type (padded with 00)30

The first byte "deck" uses the more significant nibble to indicate the source/destination deck. It uses 0 for controllers which only have/represent a single deck such as a CDJ and 1-based deck numbers for controllers with multiple decks such as the XDJ-XZ. The "type" byte indicates the type of message being transmitted. This format limits the maximum amount of data transmitted to 62 Bytes which is not sufficient for transmitting larger strings or other binary data such as images. For these purposes, the protocol uses an extended header

Extended Header

Packets with an extended header are able to transmit Bytes (~3.8MB) of data.

0123456789abcdefdecktypeIL001020Packet rest according to type (padded with 00)30

L denotes the number of packets the data following takes up while I indicates the index of the packet fragment in the current stream. Both ushorts encoded in little-endian byte order.

TLV Structure

Some parts of the Protocol utilize a TLV structure:

TL

These TLV structures can occur nested (for example in the handshakes TODO hyperlink) It seems T only indirectly describes the actual type of data in the buffer. Instead T indicates what the data is actually used for, which in turn describes the actual type of the data.

Thanks

An enormous thanks to James Elliot (@brunchboy) from Deep Symmetry for not only creating bytefield-svg which allowed me to create these awesome bytefield diagrams but also for all of his previous research into the ProDJLink Protocol as well as helping me in the setup of this wiki, using bytefield-svg and supplying me with some USB-Captures of the XDJ-XZ. Also thanks to Ard van Breemen for helping out with his in-depth knowledge of the USB protocol.