# P.I. Engineering SDK Help

## X-keys XK-12/XK-3 Switch Interface KVM Data Report

### General Information

VID | 05f3h
XK-3 Switch Interface KVM PID #1 | 0514h or 1300
XK-3 Switch Interface KVM PID #2 | 0515h or 1301
XK-12 Switch Interface KVM PID #1 | 0516h or 1302
XK-12 Switch Interface KVM PID #2 | 0517h or 1303
Consumer Usage Page | 1
Usage Page | 000Ch or 12

The XK-12/XK-3 Switch Interface KVM is a special X-keys device designed to work specifically with KVMs. In PID #2 the XK-12/XK-3 Switch Interface KVM is only a keyboard, no input or output reports are available thus making it compatible with KVM units. The information below is relevant only to PID #1 which does contain an input and output endpoint. Please note that the XK-12/XK-3 Switch Interface KVM in PID #1 will NOT be compatible with most KVMs, it must operate in PID #2 to be compatible. To convert the device to PID #1 when it is currently in PID #2 unplug the device then replug it in and press the Scroll Lock key repeatingly 10-15 times. The device gives 10 seconds after reboot to detect the Scroll Lock toggles. If it is not done quick enough, hotplug and try again. This procedure requires a regular keyboard to be attached to the computer for the Scroll Lock key. The device will revert back to PID #2 (KVM mode) on reboot unless Reboot Mode (see output reports) was changed.

XK-12/XK-3 Switch Interface KVM is supported by P.I. Engineering Macroworks 3.1, X-key Basic Setup for PC users , P.I. Engineering SDK samples for Microsoft C# Express, VB 2010, (Microsoft C++ 2010 available upon request) and Linux.

### X-keys XK-12/XK-3 Switch Interface KVM Input Report

Figure 1a: X-keys XK-12 Switch Interface.

Figure 1b: X-keys XK-3 Switch Interface.

Report Length: 37 bytes

1a. General Incoming Data for XK-12 Switch Interface KVM

This data is returned when new data is detected such as button presses or unit id change. This report can be manually stimulated by sending an output report: Generate Data which is very useful for obtaining the initial state of the device immediately after enumeration. This report is available only in PID #1.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Bytes 6-7 | Byte 8 | Bytes 9-32 | Bytes 33-36 | Byte 37
Constant | Unit ID | Data Type | Jacks 1-4 | Jacks 5-6 | Reserved | NumLck, CapsLck, ScrLck | Reserved | Time Stamp | # of times rebooted
0 | <data> | DT | D1 | D2 | value | D3 | value | Time | Reboot

DT: Data Type value of 0 or 2 indicates the following data is a General Incoming Data report, 2 if generated by the output report: Generate Data. Data Type value of 214 indicates a Descriptor Data Report, see below. Data Type value of 224 indicates a Custom Data Report, see below.
D1: If using a splitter to read both L and R then for all bits 0 for switch open, 1 for switch closed. If plugging in only one switch to the jack then the corresponding R will always be closed for that jack. Bit 1=1R, bit 2=1L, bit 3=2R, bit 4=2L, bit 5=3R, bit 6=3L, bit 7=4R, bit 8=4L.
D2: If using a splitter to read both L and R then for all bits 0 for switch open, 1 for switch closed. If plugging in only one switch to the jack then the corresponding R will always be closed for that jack. Bit 1=5R, bit 2=5L, bit 3=6R, bit 4=6L, bits 5-8=na.
D3: Bit 1=NumLock, bit 2=CapsLock, bit 3=ScrLock, bit 4=On Boot (sets the bit when device is booted up by the usb then sets it back to 0) .
Time: If enabled using output report: Enable Time Stamp gives a time in ms starting from when the device was plugged into a port in 4 bytes where byte 36 is the LSB or low byte and byte 33 is the MSB or high byte.
Reboot: This is a number that indicates how many times the device has been rebooted by the USB.

1b. General Incoming Data for XK-3 Switch Interface KVM

This data is returned when new data is detected such as button presses or unit id change. This report can be manually stimulated by sending an output report: Generate Data which is very useful for obtaining the initial state of the device immediately after enumeration. This report is available only in PID #1.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Bytes 6-7 | Byte 8 | Bytes 9-32 | Bytes 33-36 | Byte 37
Constant | Unit ID | Data Type | SW1-3 | Reserved | Reserved | NumLck, CapsLck, ScrLck | Reserved | Time Stamp | # of times rebooted
0 | <data> | DT | D1 | value | value | D3 | value | Time | Reboot

DT: Data Type value of 0 or 2 indicates the following data is a General Incoming Data report, 2 if generated by the output report: Generate Data. Data Type value of 214 indicates a Descriptor Data Report, see below. Data Type value of 224 indicates a Custom Data Report, see below.
D1: Bit 1=SW2, bit 2= SW1, bits 3 is unset if nothing is plugged in and set if anything is plugged in, bit 4=undefined, bit 5=SW3.
D3: Bit 1=NumLock, bit 2=CapsLock, bit 3=ScrLock, bit 4=On Boot (sets the bit when device is booted up by the usb then sets it back to 0) .
Time: If enabled using output report: Enable Time Stamp gives a time in ms starting from when the device was plugged into a port in 4 bytes where byte 36 is the LSB or low byte and byte 33 is the MSB or high byte.
Reboot: This is a number that indicates how many times the device has been rebooted by the USB.

2. Descriptor Data

This data is returned after an output report: Request for Descriptor is sent. This report is available only in PID #1.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 | Byte 8 | Byte 9 | Byte 10 | Byte 11 | Byte 12 | Byte 13 | Byte 14 | Bytes 15-37
Constant | Unit ID | Data Type | Mode | Key mapstart | Layer2 Offset | Constant | Constant | Max Columns | Max Rows | LED State | Version | PID Low | PID Hi | Reserved
0 | <data> | 214 | Mode | 32 | 208 | 192 | 14 | Cols | Rows | LEDs | <data> | PIDL | PIDH | Value

Mode: 0 means device is in PID #1, 1 = PID #2.
Cols: 1 for XK-3 Switch Interface KVM, 2 for XK-12 Switch Interface KVM.
Rows: 5 for XK-3 Switch Interface KVM, 8 for XK-12 Switch Interface KVM.
LEDs: Bit 7 set means Green LED is on, bit 8 set means Red LED is on.
PIDL: LSB of the Product Identification number or PID.
PIDH: MSB of the Product Identification number or PID.

3. Custom Data

This data is returned after an output report: Generate Custom Data is sent. This report is available only in PID #1 and PID #4.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 | Bytes Count+5 to 36 | Byte 37
Constant | Unit ID | Data Type | Count of custom bytes to follow | Custom byte 1 | Custom byte 2 | Custom byte 3... | Reserved | Increment
0 | <data> | 224 | Count | B1 | B2 | B3... | value | Increment

Count: Number of custom bytes to follow.
B1: 1st custom byte.
B2: 2nd custom byte.
B3: 3rd custom byte and so on for as many bytes as specified in Count.
Increment: This byte is incremented each time a Custom Data report is sent thus even if 2 identical reports are sent they will both come in even if SuppressDuplicate reports is on.

4. Check Dongle Key

This is received immediately following a Check Dongle Key output report is sent. The four values R0-R3 are required to continue the check. See Dongle Implementation for further details.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 | Bytes 8 to 36
Constant | Unit ID | Data Type | 1st byte returned from hash | 2nd byte returned from hash | 3rd byte returned from hash | 4th byte returned from hash | Reserved
0 | <data> | 193 | R0 | R1 | R2 | R3 | value

R0: Value need for comparison to check for correct dongle key.
R1: Value need for comparison to check for correct dongle key.
R2: Value need for comparison to check for correct dongle key.
R3: Value need for comparison to check for correct dongle key.

### X-keys XK-12/XK-3 Switch Interface KVM Output Report

The following types of output reports are shown in the summary below. Available for all PIDs. Please be aware that several of these commands result in writing to the device's eeprom which has a limit to the number of writes allowed before it is "burnt out". The manufacturer's specification is 50,000 eeprom writes. Because of this we recommend the commands designated with e be executed rarely and not within timing loops. Note, the first byte listed in this documentation is 0 and represents the report ID. This is not present on some non-PC operating systems. So when sending an output report on Android for example, eliminate this byte.

Report | Format | Description
--- | --- | ---
1 | 0, 179, LEDIndex, State, 0... | Index Based Set LED (Flash)
2 | 0, 189, UnitID, 0... | Set Unit IDe
3 | 0, 180, Freq, 0... | Set Frequency of Flash
4 | 0, 214, 0... | Request Descriptor
5 | 0, 210, Enable, 0... | Enable Time Stamp
6 | 0, 177, 0... | Generate Data
7 | 0, 224, Count, B1, B2, B3..., 0... | Generate Custom Data
8 | 0, 204, Mode, 0... | Change PIDe
9 | 0, 201, Modifier, 0, HC1, HC2, HC3, HC4, HC5, HC6, 0... | Keyboard Reflector (PID #2 and #4 only)
10 | 0, 203, Buttons, Mouse X, Mouse Y, 0, Wheel Y, 0... | Mouse Reflector
11 | 0, 196, RebootMode, 0... | Reboot Modee
12 | 0, 195, Version LSB, Version MSB, 0... | Set Version Numbere
13 | 0, 238, 0... | Reboot Device
14 | 0, 192, K0, K1, K2, K3, 0... | Set Dongle Keye
15 | 0, 193, N0, N1, N2, N3, 0... | Check Dongle Key

eCommand writes to EEPROM, do not perform this command excessively, do not exceed 50,000 writes to EEPROM.

Endpoint: Vendor Defined Usage Page.

Report Length: 36 bytes.

1. Index Based Set LED (Flash)

Send this output report to control the LEDs and the 2 additional digial outputs.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Bytes 5-36
Constant | Command | LED Index | LED State | Constant
0 | 179 | LEDIndex | LEDState | 0

LEDIndex: 0=Out 1, 1=Out 2, 6 = Green LED, 7 = Red LED.
LEDState: 0 = off, 1 = on and 2 = flash. Set the frequency of the flash with output report: Set Frequency of Flash.

2. Set Unit ID

Send this output report to set the Unit ID of the device. This is useful if connecting more than one of the same device to the a computer.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | Unit ID (0-255) | Constant
0 | 189 | value | 0

3. Set Frequency of Flash

Send this output report to control the frequency of the flashing of the indicator LEDs.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | Frequency | Constant
0 | 180 | Freq | 0

Freq: 1-255 where 1 is the fastest flash and 255 is the slowest. 255 is approximately 4 seconds between flashes.

4. Request Descriptor

After sending this output report a Descriptor input report will be generated.

Byte 1* | Byte 2 | Bytes 3-36
Constant | Command | Constant
0 | 214 | 0

5. Enable Time Stamp

By default the Time Stamp feature is enabled. To turn off send this command with Byte 3=0.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | Enable | Constant
0 | 210 | 0=off, 1=on | 0

6. Generate Data

After sending this output report a General Incoming Data input report will be generated with bit 2 of Byte 3 set. This is useful in determining the initial state of the device before any data has changed.

Byte 1* | Byte 2 | Bytes 3-36
Constant | Command | Constant
0 | 177 | 0

7. Generate Cutom Data

After sending this output report a Custom Data input report will be generated with Byte 3 set to 224 and the count and custom bytes following.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6... | Bytes (Count+4) to 36
Constant | Command | Count of custom bytes to follow | Custom byte 1 | Custom byte 2 | Custom byte 3... | Constant
0 | 224 | Count | B1 | B2 | B3... | 0

Count: Number of custom bytes to follow.
B1: 1st custom byte.
B2: 2nd custom byte.
B3: 3rd custom byte and so on for as many bytes as specified in Count.

8. Change PID

Send this output report to change from PID #1 which is the programming mode to PID #2 which is the KVM operating mode. To change from PID #2 (KVM PID) to PID #1 unplug the device, replug and tap the main keyboard's Scroll Lock key 10-15 times within 10 seconds of replugging it. IMPORTANT: after converting to PID #1 the user must manually convert back to PID #2, it will not automatically revert on reboot.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | Mode | Constant
0 | 204 | Mode | 0

Mode: 1 for PID #2 (KVM mode).
PID #1 Endpoints: Endpoints: Consumer Usge Page Input and Output (Hid Usage Page 12, Hid Usage 1), Boot Mouse (Hid Usage Page 1, Hid Usage 2), Boot Keyboard (Hid Usage Page 1, Hid Usage 6).
PID #2 Endpoints: Boot Keyboard (Hid Usage Page 1, Hid Usage 6).

9. Keyboard Reflector

Sends native keyboard messages. Must have the device set to a PID with a keyboard endpoint; PID #4 or PID #2.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 | Byte 8 | Byte 9 | Byte 10 | Bytes 11-36
Constant | Command | Modifier | Constant | Hid Code 1 | Hid Code 2 | Hid Code 3 | Hid Code 4 | Hid Code 5 | Hid Code 6 | Constant
0 | 201 | Modifier | 0 | HC1 | HC2 | HC3 | HC4 | HC5 | HC6 | 0

Modifier: Bit 1=Left Ctrl, bit 2=Left Shift, bit 3=Left Alt, bit 4=Left Gui, bit 5=Right Ctrl, bit 6=Right Shift, bit 7=Right Alt, bit 8=Right Gui.
HC1=Hid Code for 1st key down, or 0 to release previous key press in this byte position.
HC2=Hid Code for 2nd key down, or 0 to release previous key press in this byte position.
HC3=Hid Code for 3rd key down, or 0 to release previous key press in this byte position.
HC4=Hid Code for 4th key down, or 0 to release previous key press in this byte position.
HC5=Hid Code for 5th key down, or 0 to release previous key press in this byte position.
HC6=Hid Code for 6th key down, or 0 to release previous key press in this byte position.

10. Mouse Reflector

Sends native mouse messages.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 | Bytes 8-36
Constant | Command | Buttons | Mouse X | Mouse Y | Constant | Wheel Y | Constant
0 | 203 | Buttons | X | Y | 0 | WY | 0

Buttons: Bit 1=Left, bit 2=Right, bit 3=Center, bit 4=XButton1, bit 5=XButton2.
X=Mouse X motion. 128=0 no motion, 1-127 is right, 255-129=left, finest inc (1 and 255) to coarsest (127 and 129).
Y=Mouse Y motion. 128=0 no motion, 1-127 is down, 255-129=up, finest inc (1 and 255) to coarsest (127 and 129).
WY=Wheel Y. 128=0 no motion, 1-127 is up, 255-129=down, finest inc (1 and 255) to coarsest (127 and 129).
Example 1: Move mouse 1 mickey, the finest increment.
x+: 0, 203, 0, 1, 0, 0, 0
x-: 0, 203, 0, 255, 0, 0, 0
y+: 0, 203, 0, 0, 1, 0, 0
y-: 0, 203, 0, 0, 255, 0, 0
Example 2: Wheel Y with increment of 5.
+ motion: 0, 203, 0, 0, 0, 0, 5
- motion: 0, 203, 0, 0, 0, 0, 250 where 250=255-5
Example 3: Left button click.
left button down: 0, 203, 1, 0, 0, 0, 0
left button up: 0, 203, 0, 0, 0, 0, 0
Example 4: Left button down and drag
with mouse at starting position: 0, 203, 1, 0, 0, 0, 0
move mouse with button down: 0, 203, 1, 30, 30, 0, 0
release button: 0, 203, 0, 0, 0, 0, 0

11. Reboot Mode

Send this output report to determine if the device will automatically return to PID #2 (KVM) on each reboot or if it will remain in the current PID between reboots.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | Change | Constant
0 | 196 | Change | 0

Change: 0 to have device remain in its current PID between reboots, 1 to have the device always revert to PID #2 at every reboot.

12. Set Version Number

Send this output report to set the Version of the device. This is not the firmware version given in the descriptor but a 2 byte number available on enumeration. The value is "remembered" so if it is changed, using this report, the device must be rebooted. The device can be rebooted by replugging it or by sending the output report : Reboot Device. The device is also rebooted when changing pids using output report: Change PID.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Bytes 5-36
Constant | Command | Version LB (0-255) | Version HB (0-255) | Constant
0 | 195 | value | value | 0

13. Reboot Device

Send this output report to reboot the device without having to unplug it. After sending this report the device must be re-enumerated.

Byte 1* | Byte 2 | Bytes 3-36
Constant | Command | Constant
0 | 238 | 0

14. Set Dongle Key

Sets the user entered key. Remember these numbers as they are required to check for the key. This is intented to be done once by the developer prior to sale. See Dongle Implemenation for more details.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Bytes 7-36
Constant | Command | 1st byte of key | 2nd byte of key | 3rd byte of key | 4th byte of key | Constant
0 | 192 | K0 | K1 | K2 | K3 | 0

K0: 1st byte of user determined dongle key, any number 1-254.
K1: 2nd byte of user determined dongle key, any number 1-254.
K2: 3rd byte of user determined dongle key, any number 1-254.
K3: 4th byte of user determined dongle key, any number 1-254.

15. Check Dongle Key

Checks the key that was entered in Set Dongle Key. This is intented to be done by the developer within their own software to determine if the connected X-keys device is the one they sold to the customer. 4 random bytes along with the actual key are entered into the DongleCheck2() hash function of the Piehid32.dll/PieHid32Net.dll which returns 4 bytes. Then after sending this output report a Check Dongle Key input report will be received containing the same 4 bytes returned from the hash if the key matches. See Dongle Implemenation for more details.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Bytes 7-36
Constant | Command | Random number | Random number | Random number | Random number | Constant
0 | 192 | N0 | N1 | N2 | N3 | 0

K0: 1st byte of a random number that was used in the hash, any number 1-254.
K1: 2nd byte of a random number that was used in the hash, any number 1-254.
K2: 3rd byte of a random number that was used in the hash, any number 1-254.
K3: 4th byte of a random number that was used in the hash, any number 1-254.

*This first byte may be omitted on some non-PC operating systems. On these systems the read and write lengths will be 1 byte smaller.

Back to top