VDJPedia



 ControllerDefinitionHIDv8

Back to Controllers Developing Wiki HOME

Definition file for a HID Controller in Version 8



The Definition File for a HID controller is a XML file installed in Documents\VirtualDJ\Devices\ folder and has the following form.
<device ...><audio ... /><page>definition of HID elements</page></device>
Example :
<?xml version="1.0" encoding="UTF-8"?>
<device name="XDJAERO" author="Atomix Productions" version="800" description="Pioneer XDJ-AERO" type="HID" vid="0x08E4" pid="0x0172" reportsize="16" outreportsize="32" decks="4">
<audio description="PIONEER XDJ-AERO" vid="0x08E4" pid="0x0172" asio="PIONEER XDJ-AERO ASIO" input="0" output="2" mic="no" mixer="yes" />
<page type="in">
<constant byte="0" value="0x01" />
<constant byte="2" value="0x80" />
<!-- Buttons -->
<button name="PLAY_PAUSE" bit="0x20" deck="1" />
...
<!-- Encoders -->
<encoder name="BROWSE" word="4" endian="little" min="0" max="65536" />
...
<!-- Sliders -->
<slider name="PITCH" word="5" endian="little" signed="true" min="-1000" max="+1000" deck="1" />
...
</page>
<page type="out">
<constant byte="0" value="0x01" />
<led name="LED_PLAY" bit="0x20" deck="1" />
...
<bar name="VU_METER" byte="5" enablebit="0x28" max="256" deck="1" />
...
<digit word="6" name="DIGIT_BPM" endian="little" dotbit="0x3B" deck="1" />
...
</page>
</device>

* The <!-- --> are optional comments, not executable.
  • <device>
    The <device> line holds all the identifiers that will secure the unique and proper detection of a controller, and has the following parameters.

      • name - Provide a unique short name for the device, which will be used in the mapping file as well. The name will not be visible anywhere else. (E.g. name="XDJAERO")
      • type - must be "HID"
      • description - Provide a description. This will be visible in the Controllers tab of Config. (E.g. description="Pioneer XDJ-AERO"). In v8 it is preferred to give this name in the definition instead of the mapping file because a single device can have multiple mappers.
      • version - VDJ version this definition was created for. E.g. version="800"
      • decks - Number of decks that can be controlled with this controller. E.g. decks="2" for a 2-sides controller, or decks="1" for a single-deck controller, or decks="4" for a 2-sides controller which offers additional layers for each deck per side.
      • singledeck - Set to "yes" if it is a single-deck controller (decks="1") with a switch button to toggle to a second deck. When 1 controller is connected it will switch between 1 and 2, but when 2 controllers are connected, they will switch between 1 and 3, and 2 and 4. Can be used for 2-deck controller that can control 4 decks as well.
      • padColumns padRows padSides - (Optional) Define the matrix that the controller provides to control the Sampler. If the controller has sampler pads, provide the number of horizontal pads in one sampler area, the number of vertical pads in one sampler area and the number of the sides. If the controller has a sampler area on each side, the padSides should be 2, if there is only one sampler area on the controller it should be 1.
      • platform="pc|mac" (Optional). Most of the time this shouldn't be needed, but if a controller has a different driver or firmware for mac or pc, use this to have the definition loaded only on the specified platform. In this case, use 2 definition files for the device, one with platform pc and one with platform mac.

    • Unique Identifiers
      • vid - VendorID of the device.
      • pid - ProductID of the device.
      • reportsize - size of the report pages in bytes (default 32)
      • outreportsize - (optional) if different, size of the output pages in bytes

    • How to get the Unique Identifiers :
      VirtualDJ 8 provides an implemented tool to get all the information that your Audio, MIDI and HID devices offer. Open VirtualDJ 8, goto the Options tab of the Config and set the setting CreateMidiLog to Yes from the Advanced Options. Close VirtualDJ 8 and make sure your device is properly connected and its drivers are installed. Launch VirtualDJ 8 and then close right after. Open the generated Log Report.txt file you will find in /Documents/VirtualDJ folder to get all the reported data.
    • How to get the reportsize value :
      Download Hidtrace tool from here. In this tool, select your device from the drop down menu on the left, and click any button on your controller. you should be able to see the device properites on the right side of the window now, among with a matrix of the reported values of the current page.

  • <audio>
    The <audio> line is optional. If the controller has a built-in sound card, then define its properties using this line, in order a special button in the Audio tab of Config to be offered with a pre-defined audio configuration.
      • description - Provide a name that will be shown in the "special" button in the Audio tab of Config. It is possible to use \n if the name would be too long to fit properly on one line.
      • image - (Optional) Name of the Image shown in the audio configuration for this controller. E.g. image="mycontroller.png". It will look for a .png file with this name in the /Devices folder. If not provided, it will look for a png file with the same filename as the definition file.
        Alternatively, the image can be base64 encoded and embedded in the xml by using image="embedded://base64encodedstring"
      • input Provide the number of (stereo) inputs available for this device.
      • output - Provide the number of (stereo) outputs available for this device
      • mic - [Yes/No] Define, if this device has a microphone input that should be configured (default is No)
      • linein - Define the number of line inputs that should be configured for this device. E.g. linein="2" will auto create linein1 and linein2 in the audio configuration of this unit.
      • timecode - Define the number of time code inputs that should be configured for this device
      • mixer - [Yes/No/Internal] If set to yes, master and headphones output will be created. If set to no, deck 1, deck 2 outputs will be created. If set to internal, deck 1 and deck 2 outputs will be created and its used when the device mixes the channels instead of the computer (fake mixer)
      • asio - Name of the ASIO driver for this device. E.g. asio="Pioneer DDJ-SX ASIO"
      • coreAudio - Name of the mac core audio name of the device. Only required if the name is different from the midi name, and the device is not found without.
      • vid pid mid - vid/pid of this devices sound card (for wasapi when asio is not available and for detecting if the device is connected or not)
        vid/pid are required for any sound config
        optionally, some devices may also require mid (usually not)
      • vid2 pid2 mid2 - When the different output channels are shown as separate sound cards, sometimes they get a different pid and/or mid
      • identifier - Optional, for some devices, the pid/vid cannot be found in the device instance id. In this case, use a unique string inside the device instance id as identifier. The vid/pid can be copied from the midi part in this case. E.g. ideintifier=" #NUMARKV7AUDIOADAPTER#"
      • asioOnly - If a sound card doesn't show up as a usbAudio on windows, set this to "Yes", so that the vid/pid listed should be looked for in the USB MEDIA class, instead of usbAudio devices
      • controllerIdentifier - If no vid/pid's or other identifiers are available, this can be used to say that the audio device is available if the controller with name NAME is available (the name="" entry of the device description above)
      • outputChannels - Optional when using default order. Use this to re-order the Output channels. E.g. in case Channels 3,4 should be used first for master out, and Channels 1,2 for headphones have outputChannels="3,4,1,2" (default is 1,2,3,4).
      • inputChannels - Optional when using default order. Use this to re-order the Input channels. E.g. in case Channels 3,4 should be used first for Linein 1 or Timecode 1, and Channels 1,2 for Linein 2 or Timecode 2 have inputChannels="3,4,1,2" (default is 1,2,3,4).

      The <audio> definition can be used as a stand-alone definition file to offer a pre-defined audio configuration when the defined sound card is connected. The audio definition follows the above structure, with the difference that a name="" needs to be provided.
      Example:
      <audio name="TRAKTORAUDIO2" description="Traktor Audio 2" vid="0x17cc" pid="0x041d" identifier="#nita2_avs#" asio="Traktor Audio 2" mixer="no" output="2" >
      </audio>

  • <page>
    The <device> element has child elements <page>, with these properties:
      • type can be "in", "out", "packets", "init", "wait" or "exit"
      • pagesize (optional) if different, report page size in bytes

    • Pages IN
      Pages "IN" are HID report pages sent by the device on the HID port.
      If your device sends more than one report page, you must differentiate the pages using a <constant> element.
      When VirtualDJ receives the HID report, it will use the first <page> element where all <constant> elements match the content of the report.
    • Pages OUT
      Pages "OUT" are HID report pages that the application can send to the device on the HID port.
      If the report page needs to have some specific headers to identify the page, you can use <constant> elements, as described in the Pages IN section.
      (for Hercules DJConsole RMX, Hercules DJControl MP3 where ReportID equals 1, please use <constant byte="-1" value="0x01"/>)
    • Other Pages
      Pages defined with the type "init" will be sent to the HID port when the device is initialized.
      The pages will be sent in the order they appear in the XML.
      You can use <constant> elements to fill the page, as defined in Pages IN.
      If a page has the type "wait", the device will not start until this page has been received, after all the "init" pages have been sent.
      Pages defined with the type "exit" will be sent when the device is exited.
    • Constants
      The <constant> element can have one of these properties:
      • text: specifies the content of the constant with a text string.
      • buffer: specifies the content of the constant with an hexadecimal buffer (like "010203040A0B0C")
      • value: specifies the content of the constant with a value

  • HID elements
    Each button, slider, knob, LED, LCD, etc, will be defined by a child item of a <page> element.
      All elements (except <constant>) can implement these properties:
      • name: the name of this element, as will be used in the mapper
      • deck: (optional) the deck on which this element apply, if the device controls two decks

      All elements also have properties that defines their position and length inside the page report.
      The position can be defined by one of these properties:
      • bit: gives the position in number of bits since the beginning of the page (1 bit = 0 or 1)
      • byte: gives the position in number of bytes since the beginning of the page (1 byte = 8 bits)
      • word: gives the position in number of words since the beginning of the page (1 word = 2 bytes = 16 bits)
      • dword: gives the position in number of dwords since the beginning of the page (1 dword = 2 words = 4 bytes = 32 bits)

      If the number of bits taken by the element in the report is different than the size implied by the method used to give the position, you can specify the size by one of these properties:
      • nbbits: (optional) specifically gives the number of bits
      • size: (optional) can be "bit", "byte", "word", "dword"

      If the size is greater or equal to "word", you can specify this property:
      • endian: (optional) can be "little" or "big" (default is "big")

    • Buttons
      A button is defined by a <button> element, with the following properties:
      • value: (optional) specify the value the element should match
      • inverted: (optional) set to "true" if the bit is 0 when pressed and "value" when released

      example:
      <button bit="42" name="PLAY" />

      If the button does not change the report value on pushed/released, but on on/off, you can use a <toggle> element with the following properties:
      • value: (optional) specify the value the element should match
      • inverted: (optional) set to "true" if the bit is 0 when activated and "value" when deactivated

    • Sliders
      A slider is defined by a <slider> element, with the following properties:
      • min: defines the value for 0% (default: 0)
      • max: defines the value for 100% (default: maximum allowed by nbbits)
      • zero: value that the controller sends when the slider is 0 (for pitch sliders the center value)
      • signed: (optional) if "true", the value is a signed value
      • inverted: (optional) set to "true" if the slider is bottom-up
      • vibration: (optional) defines a delta value under which changes are not reported
      • zerorange: (optional) if value is closer than zerorange from 50%, it will be set to 50%
      • ignoretouchrelease: (optional) set to yes for touch-sensitive strips that send a '0' when released

      example:
      <slider word="2" endian="little" max="1000" name="VOLUME" />

    • Jog Wheels
      A jog wheel is defined by a <jog> element, with the following properties:
      • full: gives the number of steps to perform a full rotation
      • min: (optional) defines the minimum value
      • max: (optional) defines the maximum value, just before it wraps back to the minimum value
      • inverted: (optional) set to "true" if the jogwheel is inverted
      • vibration: (optional) defines a delta value under which changes are not reported

      example:
      <jog byte="19" size="word" full="300" name="JOGWHEEL" deck="1" />

    • Encoders
      An encoder is defined by a <encoder> element, with the following properties:
      • min: (optional) defines the minimum value
      • max: (optional) defines the maximum value, just before it wraps back to the minimum value
      • inverted: (optional) set to "true" if the encoder is inverted
      • vibration: (optional) defines a delta value under which changes are not reported

      example:
      <encoder word="4" endian="little" min="0" max="65536" name="BROWSE" />

    • Actions
      You can put <action> elements with the usual position, size and name properties.
      The VDJ Script action for this name will be called every time the report page containing this <action> is received.
    • LEDs
      a LED is defined by a <led> element, with the following properties:
      • value: (optional) the value to set this element to when the LED is on
      • zero: (optional) the value to set this element to when the LED is off (it can also be used to set a LED on dimmed state)
      • default: (optional) gives the name of the corresponding <button> element. If the mapper doesn't specifically provide an action for this LED, the action of the button will automatically be used to get the state of the LED.

      example:
      <led bit="0x42" name="LED_PLAY" default="PLAY" deck="1" />

    • RGB LEDs
      a LED that offers different colors is defined by a <color> element, with the following properties
      • bitspercolor: (optional) use when less than nbbits/3 bits are used. (For example R at byte 0, G at byte 1, B at byte 2, but each with a range of 0 to 127 would mean 7 bits used)
      • values: (optional) define a value for each color in a comma-separated list. Colors can be names or HTML hex colors.

      example:
      <color byte="0x00" nbbits="24" bitspercolor="7" name="LED_PAD1" default="PAD1" deck="1" />
      <color byte="0x03" values="0x01=red,0x02=#112233" name="LED_MODE" default="MODE" deck="1" />

    • Digits
      Digits on a LCD are defined by a <digit> element, with the following properties:
      • enablebit: (optional) specify the position in bits from the beginning of the page of a bit to set to 0 when there is no digits to display and 1 when there is.
      • enablebit2: (optional) specify the position in bits from the beginning of the page of another bit to set to 0 when there is no digits to display and 1 when there is (can be used to activate LCD sign related to these digits).
      • dotbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is not an integer. The value will be multiplied by 10 before being sent to the digit.
      • dotbit2: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is not an integer. The value will be multiplied by 100 before being sent to the digit.
      • plusbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is positive.
      • minusbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is negative.
      • min: (optional) set a minimum for the value.
      • max: (optional) set a maximum for the value.

    • Text displays
      Text displays are defined by a <text> element, with the following properties:
      • nbchars: the number of characters
      • enablebit: (optional) specify the position in bits from the beginning of the page of a bit to set to 0 when the text is empty and to 1 when it's not.
      • encoding: (optional) the encoding to use (can be "utf8", "utf16", "iso-8859-1", "ascii", etc)
      • scroll: set to "false" to prevent the display from scrolling too long strings (default is "yes")

    • Progress bars and VUE meters
      Progress bars are defined by a <bar> element, with the following properties:
      • min: (optional) value to write for 0%
      • max: (optional) value to write for 100%
      • enablebit: (optional) specify the position in bits from the beginning of the page of a bit to set to 0 when the bar is empty and to 1 when it's not.
      • enablebit2: (optional) specify the position in bits from the beginning of the page of another bit to set to 0 when the bar is empty and to 1 when it's not.
      • minusbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 when the value is negative and 0 when it's positive.

      Alternatively, progress bars can be defined as a buffer of binary bits.
      For this, use a <bar> element with the following properties:
      • type: if set to "bitfill" the buffer will progressively fill with 1s. If set to "bitmove", the buffer will have only one 1 moving through the buffer.
      • inverted: (optional) invert the direction of the buffer.




Navigation:

Back to Controllers Developing Wiki HOME