Ergodex DX1 Open Source Drivers

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**Work In Progress**

====== Ergodex DX1 protocol ======

Written By Dominic Clifton (C) 2007

===== Overview =====


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 I've found out the following information (which is incomplete, please


===== Commands =====

16 bytes per command.

 * Byte 1:     Command Code

 * Bytes 2-16: Command Data

Command data is different for each command.





==== Set Device ====

__Usage__

Send when device is idle.

__Command Code__

0x02

__Command Data__

The 15 byes of command data is made up as follows:

  * Byte 1: unknown, use 0x00

  * Byte 2: unknown (seen values 0x00 and 0x01, use 0x00 for now)

<code>
0x01 - enable "Test" mode.  
</code>

When the device is in this mode will cause a "Control" device "Key Test" event to be raised when pressing or releasing any key.

<code>
0x00 - normal mode
</code>

  * Byte 3: set leds - bitmask

<code>
0x00 - 00000000 - all led's off
0x01 - 00000001 - green led on, red led off
0x02 - 00000010 - green led off, red led on
0x03 - 00000011 - green led on, red led on
</code>  

  * Byte 4: unknown use 0x00

  * Byte 5: This byte seems to control whether the main keys on the erogodex send back any data when pressed

<code>
0x00 - enable keymap, all programmed keys will now send back data when pressed
0x01 - 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" commands, if left set at 0x00 the device appears to work as expected.

  * Byte 7: 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.


Examples:

  * Sent by erogdex software each time it changes the keyboard layout, before the "Program Keys" commands

  00 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

  00 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 01 01 00 01 01 01 00 00 00 00 00 00 00 00

Contents unknown at present.




==== Program Keys ====

__Usage__

Program up to 4 keys per command

__Command Code__

0x03

__Command Data__

3 bytes per key (below)
If a key is not to be programmed then pad the command with 0x00's

Then for each key that has a single key macro assigned to it sends 3 bytes

  * Byte 1: key number in hex (corresponds to the number on the physical key itself) 0x01 for Key 1, etc
  * Byte 2: "Key Type"

Key types:

  0x01 - "Single Key"
  0x02 - "Modifier Key"
  0x03 - "Macro"

  * Byte 3: different depending on "Key Type"

When key is:

  * "Single Key"

Byte 3: Set to a valid Keyboard Scan Code

See Keyboard Scan Code Specification [References 1,2] Appendix C: USB Keyboard/Keypad Page (0x07)

  * "Modifier Key"

Byte 3: Set as follows

  0x01 LEFT CTRL
  0x02 LEFT SHIFT
  0x04 LEFT ALT
  0x08 LEFT WIN KEY (Left GUI Key)
  0x10 RIGHT CTRL
  0x20 RIGHT SHIFT
  0x40 RIGHT ALT
  0x80 RIGHT WIN KEY (Right GUI Key)

  * "Macro Key"

Byte 3: Empty Value (0x00)

When keys are assigned "Single" or "Modifer" keys data is received by the HID interface for key up and key down events (8 bytes per event, see below)

When keys are assigned "Macro" keys data is received by the "control" interface for key up and key down events (16 bytes per event)

Example of data sent when switching to an application that has a profile enabled for it.

  000003: Bulk or Interrupt Transfer (UP), 06.02.2007 14:50:42.4375000 +5.0312500
  Pipe Handle: 0x88094694 (Endpoint Address: 0x2)
  Send 0x10 bytes to the device:
   02 00 00 01 00 01 01 01 00 00 00 00 00 00 00 00   ................
  
  
  000004: Bulk or Interrupt Transfer (UP), 06.02.2007 14:50:42.4843750 +0.0468750
  Pipe Handle: 0x88094694 (Endpoint Address: 0x2)
  Send 0x30 bytes to the device:
   03 01 02 02 02 03 00 03 03 00 04 03 00 0E 03 00   ................
   03 12 03 00 18 03 00 1B 03 00 29 03 00 2C 03 00   ..........)..,..
   02 00 00 01 00 00 01 01 00 00 00 00 00 00 00 00   ................




==== Get Device Status ====

__Usage__

Sent when device is idle.

__Command Code__

0x0A

__Command Data__

Fill with 0x00's

Command Response:

16 bytes

  * Byte 1: 0x0A
  * 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)
  * Bytes 12-16: unknown (seen value 0x0000000000 only)

===== Event 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 ====

The HID interface receives the following events:

  * Key pressed and released events for keys assigned to "Single Key" or "Modifier Key" by the "Program Keys" command.

Each HID event causes the device to send 8 bytes of data.

If a key assigned to a "Modifier Key" is pressed at the same time as one or more keys assigned to "Modifier Key" or a single key assigned to "Single Key" then only one event is received and the data is combined.
e.g. if you assign keys 1-Shift, 2-Control, 3-A, 4-B and press 1 2 and 3 at the same time you'll get one event, if you press keys 1-4 you'll get two events. (TODO: double check)

There's not much point going into further detail regarding the HID event data as it should be the same as any other standard USB keyboard.

One thing to note is if you program keys 1-3 with ctrl and alt and shift and press them all at the same time you receive the following data

  07 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:

  * 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.

Each HID event causes the device to send 16 bytes of data.

The first byte indicates the "Event Type" number

  * 0x01 - Status Changed
  * 0x02 - A key assigned to "Macro key" pressed or released
  * 0x03 - Any key on the device was pressed or released (only sent when device is in "Test" mode)

The next 15 bytes are different depending on the "event type" number

=== Event Types ===

__Status Changed__

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 3: status of something (seen values 0x00 and 0x01) - might be of led or whether keys are active?
  * Byte 4: bit-mapped button status.

The last two bits indicate the current status of the buttons

  0x00 - 00 - both buttons pressed
  0x01 - 01 - record button pressed
  0x02 - 10 - hand button pressed
  0x03 - 11 - no buttons pressed

  * Byte 5: status of something (seen values 0x00 and 0x01) - might be of led or whether keys are active?
  
It looks like byte 5 is set as follows:
  
  0x01 - keys are enabled
  0x00 - keys are enabled

TODO: verify this
  
  * Bytes 6-15: unknown (only seen filled with 0x00's)
  

__Macro Key Pressed__

The remaining 15 bytes of data is made up as follows

  * Byte 1: unknown (seen value 0x01)
  * Byte 2: unknown (seen value 0x01)
  * Bytes 3-8: 
  
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 will contain the number of the key that was pressed first, byte 4 will contain the number of the key that was subsequently pressed, bytes 5-8 will contain 0x00

and so on, up to 6 keys.

  * Bytes 9-15: unknown (only seen filled with 0x00's)
    
__Test__

The data for this command appears to be the same as the event "Macro Key Pressed"


===== References =====

- Key Support, Keyboard Scan Codes, and Windows

 http://www.microsoft.com/whdc/device/input/Scancode.mspx

- Keyboard Scan Code Specification

 http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/scancode.doc
Ergodex DX1 Open Source Drivers

User Tools

Site Tools

Page Tools
