VDJPedia



 

Go back to German content

VERSION 8 Syntax - http://www.virtualdj.com/wiki/ControllerDefinitionHIDv8.html

ab Version 6.x

Controller Definition für HID - selbst gemacht
(Übersetzung aus dem Englischen von H. Jakovski)

Zum Ermitteln der notwendigen Daten am besten mal diese Tool hier downloaden: http://www.virtualdj.com/download/hidtrace.exe.

Die 'Definition' Datei für einen HID Controller ist eine XML Datei und liegt in 'Eigene Dateien/VirtualDJ/Devices/'. Sie hat folgenden Aufbau:

Das 'root' Element der XML Datei muss <device> heissen und hat folgende Werte:

- name: Eindeutiger Name welcher den Controller Identifiziert (Wird auch im Mapper Bereich verwendet).
- author: (Optional) Name des Authoren der XML Definition Datei.
- type: Muss in diesem Fall 'HID' sein.
- decks: Kann entweder "1" oder "2" sein, je nachdem ob der Controller nur für ein Deck oder eben für zwei Decks gleichzeitig ausgelegt ist.
- vid: HerstellerID des Controllers
- pid: ProductID des Controllers
- reportsize: Größe der Report Seite (Standard 32)
- outreportsize: (Optional) Größe der Output Seite (sofern unterschiedlich)

Beispiel:
<?xml version="1.0" encoding="UTF-8"?>
<device name="Mein Controller" author="Ich" type="HID" decks="2" vid="0x1234" pid="0x0100" reportsize="32">
<page type="in">
...
</page>
<page type="out">
...
</page>
</device>

Das '<device>' Element hat verschiedene '<page>' Elemente die folgende Parameter haben können:
- type: Kann eines der folgenden Schlüsselwörter sein "in", "out", "init", "wait" oder "exit"

Beispiel für den Dateinamen einer eigene Definition Datei: 'Herstelle Produkt definition.xml'.


Jeder Taster, Fader, Drehregler, LED, LCD, etc. wird durch ein sogenanntes 'child' Element innerhalb des <device> Elements definiert.
Alle dieser 'child' Elemente (mit Ausnahme von 'constant') können die folgenden Parameter beinhalten:

- name: Der Name des Elements - dieser wird später im Mapper angezeigt
- deck: (Optional) Das Deck (1/2) für welches dieses Element verwendet wird (sofern der Controller zwei Decks unterstützt) - z.B. für die 'PLAY' Taste. Für gleiche Elemente auf den
beiden Decks sollten IMMER die selben Namen verwendet werden, also z.B. für den Play Button 'PLAY' - die Unterscheidung ob linkes oder rechtes Deck erfolgt durch den
'deck' Parameter.

Alle Elemente haben Parameter die ihre Position ind Länge innerhalb des Seiten Reports definieren.
Die Position kann mittels einem der folgenden Parameter definiert werden:

- bit: Übergibt die Position in 'Bits', gezählt ab dem Anfang der Seite.
- byte: Übergibt die Position in 'Bytes', gezählt ab dem Anfang der Seite.
- word: Übergibt die Position in 'Words', gezählt ab dem Anfang der Seite.
- dword: Übergibt die Position in 'DWords', gezählt ab dem Anfang der Seite.

Wenn die Anzahl der 'Bits' die vom Element bearbeitet werden unterschiedlich zu der Größe ist die durch die aufrufende Funktion definiert wurde so kann die Größe durch einen der
folgenden Parameter definiert werden:

- nbbits: (Optional) Anzahl der 'Bits' die verwendet werden sollen.
- size: (Optional) Kann 'bit', 'byte', 'word' oder 'dword' sein.

(Der obige Satz klingt furchtbar kompliziert. Ist aber eigentlich ganz einfach. Wenn ich ein 'Bit' ansprechen will Addressiere ich die Position in 'Bits'. Möchte ich hingegen ein 'Byte'
oder ein 'Word' ansprechen Addressiere ich die Position entsprechend als 'Byte' oder 'Word'.)

Wenn die Größe der zu verwendenden Daten gleich oder größer als ein 'Word' ist kann der folgende Parameter angewendet werden:

- endian: (Optional) Kann 'little' oder 'big' sein (Standard ist 'big')



Eingabe Seite (Pages IN)
========================
Eingabe Seiten 'Pages IN' sind HID Report Seiten die vom Gerät an den HID Port gesendet werden. (Stellt Euch einfach eine A4 Seite mit allen verfügbaren Informationen vor und Ihr müsst jetzt jemandem erklären wo welche Textpassage steht. Ihr würdet bestimmt sowas in der Art sagen wie: 'Schau mal in Zeile 15, Wort 12, Buchstabe 4 bis 6'.)

Manche Geräte verwenden mehr als eine Reportseite um Daten mit dem Computer auszutauschen. Um diese Seiten unterscheiden zu können verwendet Ihr das '<constant>' Element.
Wenn VirtualDJ einen HID Report empfängt verwendet es die erste Seite, das erste '<page>' Element bei dem alle '<constant>' Elemente mit dem Inhalt des Reports übereinstimmen.


Konstanten:

Das '<constant>' Element kann einen der folgenden Parameter besitzen:

- text: Definiert den Inhalt der Konstanten als Text (String).
- buffer: Definiert den Inhalt der Konstanten als Hexadezimalwert (zum Beispiel "010203040A0B0C")
- value: Definiert den Inhalt der Konstanten mit einem festen Wert (z.B. '5')


Taster:

Ein Button wird durch ein '<button>' Element mit den folgenden Parametern definiert:

- value: (Optional) Definiert den Wert welchen das Element haben muss.
- inverted: (Optional) 'true' eintragen wenn das Bit 0 ist wenn der Taster gedrückt wurde und 'value' wenn der Taster losgelassen wurde.

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

Wenn der Taster im Report keinen Wert für betätigt/losgelassen hinterlegt sondern lediglich den Status abbildet mit an/aus kann das '<toggle>' Element mit folgenden Parametern verwendet werden:

- value: (Optional) Definiert den Wert welchen das Element haben muss.
- inverted: (Optional) 'true' eintragen wenn das Bit 0 ist wenn der Taster gedrückt wurde und 'value' wenn der Taster losgelassen wurde.


Fader:

Ein Fader wird durch das '<slider>' Element definiert. Es können folgende Parameter genutzt werden:
- min: Definiert den Wert für 0% (Standard: 0)
- max: Definiert den Wert für 100% (Standard: Der maximalwert wird auf 'nbbits' gesetzt. Siehe bei den allgemeinen Parametern: nbbits: Anzahl der 'Bits' die verwendet werden sollen)
- signed: (Optional) if "true", the value is a signed value (Da fällt mir leider im Moment die passende Übersetzung nicht ein ;-))
- inverted: (Optional) Auf 'true' setzen wenn der Slider auf dem Kopf steht / Seitenverkehrt eingebaut ist.
- vibration: (Optional) Definiert einen Tolleranzwert unter dem Änderungen nicht verarbeitet werden.
- zerorange: (Optional) Wenn der Wert näher als 'zerorange' an 50% ist, wird der Wert auf 50% gesetzt (z.B. für Pitchregler Mittelstellung)

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


Jogwheels:

Ein Jogwheel wird durch das '<jog>' Element mit folgenden Parametern definiert:

- full: Die Anzahl der Schritte für eine komplette Umdrehung des Jogs.
- min: (Optional) Definiert den kleinsten Wert.
- max: (Optional) Definiert den größten Wert den das Jog sendet bevor es wieder auf den Kleinsten Wert zurückspringt.
- inverted: (Optional) Auf 'true' setzen wenn das Jog genau falsch herum funktioniert wie es soll.
- vibration: (Optional) Definiert einen Tolleranzwert unter dem Änderungen nicht verarbeitet werden.

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


Endlos Drehregler:

Ein Endlosregler wird durch das '<encoder>' Element definiert. Es können folgende Parameter genutzt werden:

- min: (Optional) Definiert den kleinsten Wert.
- max: (Optional) Definiert den größten Wert den das Jog sendet bevor es wieder auf den Kleinsten Wert zurückspringt.
- inverted: (Optional) Auf 'true' setzen wenn der Drehregler genau falsch herum funktioniert wie er soll.
- vibration: (Optional) Definiert einen Tolleranzwert unter dem Änderungen nicht verarbeitet werden.


Aktionen:

You can put an <action> elements with the usual position, size and name properties.
The mapper for this name will be called every times the report page containing this <action> is received.
(Leider hab ich diesen Part bis jetzt noch nicht komplett verstanden. Deshalb auch noch nicht passend übersetzt.)


Ausgabe Seite (Pages OUT):

Ausgabe Seiten sind HID Report Seiten die von VDJ an den Controller auf dem HID Port gesendet werden.

Wenn die Report Seite spezifische Header Teile benötigt können diese mit dem '<constant>' Element, wie im Bereich 'Eingabe Seiten' beschrieben, definiert werden.

LEDs:

Eine LED wird durch das '<led>' Element mit folgenden Parametern definiert:

- value: (Optional) Der Wert auf den dieses Element gesetzt werden muß damit die LED an geht.
- default: (Optional) Der Name des korespondierenden Taster Elements. Sollte im Mapper KEINE Aktion für die LED definiert werden, wird hier automatisch der Status des Tasters mithilfe der LED angezeigt.

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


Zahlen (auf einem LCD d. Controllers)

Zahlen auf einer LCD Anzeige werden durch das '<digit>' Element mit folgenden Parametern definiert:

- enablebit: (Optional) Definiert die Position in Bits vom Seitenanfang für diesen Parameter. Auf '0' gesetzt wenn keine Anzeige erfolgen soll und auf '1' wenn eine Anzeige gemacht wird.
- enablebit2: (Optional) Definiert die Position in Bits vom Seitenanfang für diesen Parameter. Auf '0' gesetzt wenn keine Anzeige erfolgen soll und auf '1' wenn eine Anzeige gemacht wird. (Kann verwendet werden um LCD Symbole zu aktivieren die mit dieser Anzeige im Zusammenhang stehen).
- dotbit: (Optional) Definiert die Position in Bits vom Seitenanfang für diesen Parameter. '1' eintragen wenn der Wert der angezeigt wird KEIN Integer ist. Der Wert wird mit 10 multipliziert bevor er an die Anzeige gesendet wird.
- dotbit2: (Optional) Definiert die Position in Bits vom Seitenanfang für diesen Parameter. '1' eintragen wenn der Wert der angezeigt wird KEIN Integer ist. Der Wert wird mit 100 multipliziert bevor er an die Anzeige gesendet wird.
- plusbit: (Optional) Definiert die Position in Bits vom Seitenanfang für diesen Parameter. '1' eintragen wenn der Wert der angezeigt wird positiv ist.
- minusbit: (Optional) Definiert die Position in Bits vom Seitenanfang für diesen Parameter. '1' eintragen wenn der Wert der angezeigt wird negativ ist.
- min: (Optional) Setzt die Vorgabe für den Minimalwert.
- max: (Optional) Setzt die Vorgabe für den Maximalwert.


Text Displays:

Text Displays können mittels des '<text>' Elements und den folgenden Parametern definiert werden:

- nbchars: Die Anzahl der zu übertragenden Zeichen.
- enablebit: (Optional) Definiert die Position in Bits vom Seitenanfang für diesen Parameter. Auf '0' setzen wenn der Text leer ist, auf '1' wenn ein Text angezeigt werden soll.
- encoding: (Optional) Die Zeichenkodierung die verwendet werden soll ('urf8', 'iso-8859-1', 'ascii', etc.)
- scroll: Auf 'false' setzen um das Display vor dem Scrollen zu langer Texte zu schützen. (Standard ist 'true')


Progress bars und VU Meter:

Progress bars werden durch das '<bar>' Element, mit folgenden Parametern definiert:

- min: (Optional) Der Wert der 0% repräsentiert.
- max: (Optional) Der Wert der 100% repräsentiert.
- 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.

Alternativ kann ein Progressbar als eine Puffer definiert werden mithilfe des '<bar>' Elements. Folgende Parameter können definiert werden:
- type: Wenn 'bitfill' gesetzt ist wird der Puffer mir 1en gefüllt. Wenn 'bitmove' eingetragen wird wird eine einzelne '1' durch den Puffer geschoben.
- inverted: (optional) Wenn Ihr hier 'true' eintragt wird die Richtung des Puffers umgedreht.


Andere Seiten:

Seiten die mit dem '<init>' Element definiert werden schickt der Mapper an den Controller wenn dieser Initialisiert wird.
Die Seiten werden in der Reihenfolge an das Gerät geschickt in der sie in der XML Datei stehen.

Das '<constant>' Element kann genutzt werden (wie im Bereich 'Eingabe Seite' beschrieben) um die Seite zu füllen.

Wenn die Seite vom Typ 'wait' ist wird das Gerät erst nach Empfang der kompletten Seite / aller Init Seiten starten.

Seiten vom Typ 'exit' werden an das Gerät gesendet wenn das Gerät beendet wird.


(Übersetzung aus dem Englischen von H. Jakovski)

(Anmerkung des Übersetzers: Das Mapping von HID Controllern kann man aufgrund der techn. Funktion von HID schon als etwas kniffligeres Problem darstellen. Also nicht gleich verzweifeln wenn es auf anhieb nicht funktioniert.)


Go back to German content