Differences

This shows you the differences between two versions of the page.

--- usb_protocol_information [2007/02/07 20:39]
hydra
+++ usb_protocol_information [2010/05/10 19:05] (current)
@@ Line 7: / Line 7: @@
 ===== Overview =====
+Data is transferred to and from the Ergodex DX1's second interface in multiple of 16 bytes.  We refer this second interface as the "Control" interface.  The first interface is a HID USB Keyboard.
-Data is transferred two and from the Ergodex DX1's second interface (the first interface is a HID USB Keyboard) in multiple of 16 bytes.
+After snooping the USB communications between the host machine and the Ergodex DX1 the following information has been compiled.
-After snooping the USB communications between the host machine and the Ergodex DX1 I've found out the following information (which is incomplete, please
+We split up the information into requests and responses
+===== Control Requests =====
-===== Commands =====
+bytes per request.
-bytes per command.
+ * Byte 1:     Request Code
- * Byte 1:     Command Code
+ * Bytes 2-16: Request Data
- * Bytes 2-16: Command Data
+Request data is different for each request.
-Command data is different for each command.
@@ Line 32: / Line 32: @@
 Send when device is idle.
-__Command Code__
+__Request Code__
 x02
-__Command Data__
+__Request Data__
-The 15 byes of command data is made up as follows:
+The 15 byes of request data is made up as follows:
- * Byte 1: unknown, use 0x00
+  * Byte 1: unknown, use 0x00
- * Byte 2: unknown (seen values 0x00 and 0x01, use 0x00 for now)
+  * Byte 2: unknown (seen values 0x00 and 0x01, use 0x00 for now)
-x01 - enable "Test" mode.
+<code>
+x01 - enable "Test" mode.
+</code>
-When the device is in this mode will cause a "Control" device "Test" event to be raised when pressing or releasing any key.
+When the device is in this mode will cause a "Control" device "Key Test" event to be raised when pressing or releasing any key.  There is something rather odd about test mode though.  If the RED LED is OFF you will receive up to 6 keypresses in the "Key Test" reponse.   However, if the RED LED is ON and you press and hold one key and then press and hold another key you'll get a "Key Test" event with no key press information.  Thus, you'll never be able to check for more than one key pressed at a time when in "Test" mode and the RED LED is ON.  Weird.
-x00 - normal mode
+<code>
+x00 - normal mode
+</code>
- * Byte 3: set leds - bitmask
+  * Byte 3: set leds - bitmask
-x00 - 00000000 - all led's off
+<code>
-x01 - 00000001 - green led on, red led off
+x00 - 00000000 - all led's off
-x02 - 00000010 - green led off, red led on
+x01 - 00000001 - green led on, red led off
-x03 - 00000011 - green led on, red led on
+x02 - 00000010 - green led off, red led on
+x03 - 00000011 - green led on, red led on
- * Byte 4: unknown use 0x00
+</code>
- * Byte 5: This byte seems to control whether the main keys on the erogodex send back any data when pressed
+  * Byte 4: unknown use 0x00
-x00 - enable keymap, all programmed keys will now send back data when pressed
-x01 - clear keymap, all previously programmed keys are cleared from the device's memory.
- * Byte 5: unknown, ergodex and ryan's drivers set this to 0x01 before and after sending one or more "Program Keys" commands, if left set at 0x00 the device appears to work as expected.
- * Byte 6: unknown, ergodex and ryan's drivers set this to 0x01 before and after sending one or more "Program Keys" commands, if left set at 0x00 the device appears to work as expected.
+  * Byte 5: This byte seems to control whether the main keys on the erogodex send back any data when pressed
+<code>
+x00 - enable keymap, all programmed keys will now send back data when pressed
+x01 - clear keymap, all previously programmed keys are cleared from the device's memory.
+</code>
+  * Byte 6: unknown, ergodex and ryan's drivers set this to 0x01 before and after sending one or more "Program Keys" requests
+If the pad has been previously sent a set device command with this set to 0x01 sending subsequently setting this to 0x00 has no apparent effect.
+If it's never set to 0x01 the pad does not seem to send any data back.  TODO: investigate more.
+  * Byte 7: unknown, ergodex and ryan's drivers set this to 0x01 before and after sending one or more "Program Keys" requests, if left set at 0x00 the device appears to work as expected.
+If the pad has been previously sent a set device command with this set to 0x01 sending subsequently setting this to 0x00 has no apparent effect.
+If it's never set to 0x01 the pad does not seem to send any data back.  TODO: investigate more.
 Examples:
- * Sent by erogdex software each time it changes the keyboard layout, before the "Program Keys" commands
+  * Sent by erogdex software each time it changes the keyboard layout, before the "Program Keys" requests
 00 01 00 01 01 01 00 00 00 00 00 00 00 00
- * Sent by erogdex software each time it changes the keyboard layout, after the "Program Keys" commands
+  * Sent by erogdex software each time it changes the keyboard layout, after the "Program Keys" requests
+00 01 00 00 01 01 00 00 00 00 00 00 00 00
+  * Sent by erogdex software when you focus the ergodex manager window
-00 00 01 00 00 01 01 00 00 00 00 00 00 00 00
+ 01 01 00 01 01 01 00 00 00 00 00 00 00 00
 Contents unknown at present.
@@ Line 88: / Line 105: @@
 __Usage__
-Program up to 4 keys per command
+Program up to 5 keys per requests
-__Command Code__
+__Request Code__
 x03
-__Command Data__
+__Request Data__
 bytes per key (below)
-If a key is not to be programmed then pad the command with 0x00's
+If a key is not to be programmed then pad the request with 0x00's
 Then for each key that has a single key macro assigned to it sends 3 bytes
@@ Line 147: / Line 164: @@
   Send 0x10 bytes to the device:
 00 00 01 00 01 01 01 00 00 00 00 00 00 00 00   ................
 : Bulk or Interrupt Transfer (UP), 06.02.2007 14:50:42.4843750 +0.0468750
   Pipe Handle: 0x88094694 (Endpoint Address: 0x2)
@@ Line 156: / Line 173: @@
 00 00 01 00 00 01 01 00 00 00 00 00 00 00 00   ................
+==== Status Inquiry ====
+__Usage__
+Sent when device is idle.
+__Request Code__
+x01
+__Request Data__
+Fill with 0x00's
+==== Get Device Information ====
-==== Get Device Status ====
+Use to request a "Device Information" response.
 __Usage__
@@ Line 165: / Line 196: @@
 Sent when device is idle.
-__Command Code__
+__Request Code__
 x0A
-__Command Data__
+__Request Data__
 Fill with 0x00's
-Command Response:
+==== Unknown Command 1 ====
-bytes
+The Ergodex software sends this command when recording macros.  It has the effect of momentarily turning of the red LED.  The green LED remains on.  The command it sent once a second and the red led blinks off once a second.
-  * Byte 1: 0x0A
+__Usage__
-  * Bytes 2-9: PCB serial number? - appears to always be different from serial number printed underneath each ergodex.  The numbers seem to bear no relation, but this number always uniquely identifies a DX1 pad.
-  * Bytes 10-11: binary status flags? pcb and or firmware revision numbers? (seen value 0x0101 only)
+Only seen being sent when the device is in "Test" mode.
-  * Bytes 12-16: unknown (seen value 0x0000000000 only)
+__Request Code__
+x08
+__Request Data__
+Unknown.
+Here's what the ergodex software sends (complete request, including command code).
+<code>
+00 00 00 00 00 01 01 00 00 00 00 00 00 00 00
+</code>
-===== Event Data =====
+===== Event and Response Data =====
-Events are triggered by the device when keys are pressed on it.  Which events you receive depend upon the device's status.
+HID Events are triggered by the device when keys are pressed on it.  Which events you receive depend upon the device's status.
 ==== HID Events ====
@@ Line 202: / Line 246: @@
 00 00 00 00 00 00 00
 This indicates the values are additive, it has been reported it's possible to assign a key to "Modifier Key" and use the value 0x07 which simulates pressing all the keys together.
-==== Control Events ====
-The control interface receives the following events:
+==== Control Responses ====
+The ergodex pad sends the sends data to the control interface when:
   * Hand button pressed or released
   * Record button pressed or released
-  * Key pressed and released events for keys assigned to "Macro Key" by the "Program Keys" command.
+  * Key pressed or released for keys assigned to "Macro Key" by a "Program Keys" request.
+  * Key pressed or released when the pad is in "Test" mode.
+  * Status Requested
+  * Serial Number Requested
+Data is set to the control interface in 16 byte blocks.
-Each HID event causes the device to send 16 bytes of data.
+  * Byte 1: "Event Type" code.
+  * Bytes 2-16: 15 bytes which is different for each response.
-The first byte indicates the event type
+=== Status Changed ===
-  * 0x01 - Status Changed
+Sent in response to a status inquiry request or because the device's status changed due to the "Hand" or "Record" buttons being pressed.
-  * 0x02 - A key assigned to "Macro key" pressed or released
-The next 15 bytes are different depending on the event type
+__Event Type Code__
-=== Event Types ===
+x01
-__Status Changed__
+__Data__
 The remaining 15 bytes of data is made up as follows
   * Byte 1: unknown (seen value 0x04 only)
-  * Byte 2: status of something (seen values 0x00 and 0x01) - might be of led or whether keys are active?
+  * Byte 2: status of something (seen values 0x00 and 0x01) - whether keys are active?
-  * Byte 3: status of something (seen values 0x00 and 0x01) - might be of led or whether keys are active?
+  * Byte 3: status of leds, the bitmask is the same as for the setting LED's using the "Set Device" request
   * Byte 4: bit-mapped button status.
-The last two bits indicate the current status of the buttons
+The first two bits indicate the current status of the buttons
 x00 - 00 - both buttons pressed
@@ Line 240: / Line 296: @@
 x03 - 11 - no buttons pressed
-  * Byte 5: status of something (seen values 0x00 and 0x01) - might be of led or whether keys are active?
+When these two bits are inverted they make up a bitmask of the button status.  When inverted the first bit (lsb) is 1 when the hand button is pressed and the second bit is 1 when the record button is pressed.
+example:
+<code>
+#define PRES_EROGODEXDX1_OFFSET_STATUS_BUTTONS 0x04
+#define PRES_EROGDEXDX1_BITMASK_BUTTON_HAND    ( 1 << 0 )
+#define PRES_EROGDEXDX1_BITMASK_BUTTON_RECORD  ( 1 << 1 )
+BOOL bRecordButtonPressed = !(*(pResponseData + PRES_EROGODEXDX1_OFFSET_STATUS_BUTTONS) & PRES_EROGDEXDX1_BITMASK_BUTTON_RECORD);
+BOOL bHandButtonPressed = !(*(pResponseData + PRES_EROGODEXDX1_OFFSET_STATUS_BUTTONS) & PRES_EROGDEXDX1_BITMASK_BUTTON_HAND);
+</code>
+  * Byte 5: keymap status
 It looks like byte 5 is set as follows:
 x01 - keys are enabled
-x00 - keys are enabled
+x00 - keys are disabled
-TODO: verify this
   * Bytes 6-15: unknown (only seen filled with 0x00's)
-__Macro Key Pressed__
+=== Macro Key Pressed ===
+Sent as soon as a key assigned to "Macro Key" is pressed or released.
+__Event Type Code__
+x02
+__Data__
 The remaining 15 bytes of data is made up as follows
@@ Line 258: / Line 333: @@
   * Byte 1: unknown (seen value 0x01)
   * Byte 2: unknown (seen value 0x01)
-  * Byte 3:
+  * Bytes 3-8:
-when a key is pressed the value corresponds to number printed on the physical keys
-x00 when no keys assigned to "Macro Key" are pressed.
+When a key is pressed the values corresponds to number printed on the physical keys
+If one key is pressed then byte 3 will be the number of the key pressed, bytes 4-8 will contain 0x00
+If two keys are pressed then byte 3 and 4 will contain the numbers of the key that are currently pressed in random order, bytes 5-8 will contain 0x00
+... and so on, up to 6 keys.
+When all keys are released bytes 3-8 will be filled with 0x00.
+  * Bytes 9-15: unknown (only seen filled with 0x00's)
+=== Test ===
+Sent as soon as a key is pressed or released when the device is in "Test" mode.
+__Event Type Code__
+x03
+__Data__
+The data for this response appears to be the same as the "Macro Key Pressed" response, except that you will only ever receive information about 1 key being pressed instead of up to 6 when the RED LED is ON.  If two keys are pressed Bytes 3-8 will be filled with 0x00.  If the RED LED is OFF you'll receive information about multiple keys in bytes 3-8.  See "Set Device", above.
+=== Device Information ===
+Sent in response to a "Get Device Information" request
+__Event Type Code__
+x0A
+__Data__
+The remaining 15 bytes of data is made up as follows
-TODO: try creating a few "Macro Key" assignments and try various combinations of pressing and releasing.
+  * Bytes 1-8: PCB serial number? - appears to always be different from serial number printed underneath each ergodex.  The numbers seem to bear no relation, but this number always uniquely identifies a DX1 pad.
+  * Bytes 9-10: binary status flags? pcb and or firmware revision numbers? (seen value 0x0101 only)
+  * Bytes 11-15: unknown (seen value 0x0000000000 only)
-  * Bytes 4-15: unknown (only seen filled with 0x00's)
 ===== References =====

Ergodex DX1 Open Source Drivers

User Tools

Site Tools

Differences

Page Tools