# P.I. Engineering SDK Help

## X-keys XK-24 KVM Data Report

### General Information

VID | 05f3h or 1523
PID #1 | 04D3h or 1235
PID #2 (KVM) | 04D4h or 1236
Consumer Usage Page | 1
Usage Page | 000Ch or 12

The XK-24 KVM is a special X-keys device designed to work specifically with KVMs. In PID #2 the XK-24 KVM is only a keyboard, no input or output reports are available. The information below is relevant only to PID #1 which does contain an input and output endpoint. Please note that the XK-24 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 hold and press the programming switch located at the top of the device while plugging it into the usb port. By default the XK-24 KVM will return to PID #2 which is the desired PID for use with KVMs after each reboot however this can be changed using the Reboot Mode output report (described below).

XK-24 KVM is supported by P.I. Engineering Macroworks 3.1, X-keys Basic Setup for PC users , P.I. Engineering SDK samples for Microsoft C# Express, VB Express, Microsoft C++ 2010 and Linux.

### X-keys XK-24 KVM Input Report

Figure 1: X-keys XK-24 KVM key reference.

Endpoint: 3, Consumer Usage Page.

PID #1 Additional Endpoints: 1, Keyboard (Hid Usage Page 1, Hid Usage 6) and 2, Joystick (Hid Usage Page 1, Hid Usage 4).
PID #2 Additional Endpoints: 1, Keyboard (Hid Usage Page 1, Hid Usage 6) only for use with KVM. In this PID the only way to return to PID #1 is to press and hold the programming switch down while plugging the device into the usb port.

Report Length: 33 bytes.

1. General Incoming Data

This data is returned when new data is detected such as button presses, unit id change. This report can be manually stimulated by sending a Generate Data output report which is very useful for obtaining the initial state of the device immediately after enumeration.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 | Bytes 8-11 | Bytes 12-33
Constant | Unit ID | Data Type | Keys | Keys | Keys | Keys | Time Stamp | Reserved
0 | <data> | PS | D1 | D2 | D3 | D4 | Time | value

PS: Program Switch, 0 if unset 1 if set.
D1: For all bits 0 for key up, 1 for key down. Bit 1=Key 0, bit 2=Key 1, bit 3=Key 2, bit 4=Key 3, bit 5=Key 4, bit 6=Key 5, bits 7-8=0 always.
D2: For all bits 0 for key up, 1 for key down. Bit 1=Key 8, bit 2=Key 9, bit 3=Key 10, bit 4=Key 11, bit 5=Key 12, bit 6=Key 13, bits 7-8=0 always.
D3: For all bits 0 for key up, 1 for key down. Bit 1=Key 16, Bit 2=Key 17, bit 3=Key 18, bit 4=Key 19, bit 5=Key 20, bit 6=Key 21, bits 7-8=0 always.
D4: For all bits 0 for key up, 1 for key down. Bit 1=Key 24, Bit 2=Key 25, bit 3=Key 26, bit 4=Key 27, bit 5=Key 28, bit 6=Key 29, bits 7-8=0 always.
Time: If enabled using Enable Time Stamp output report gives a time in ms starting from when the device was plugged into a port in 4 bytes where byte 8 is the MSB and byte 11 is the LSB.

2. Descriptor Data

This data is returned after a Request for Descriptor output report is sent.

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 13-33
Constant | Unit ID | Data Type | Reserved | Key mapstart | Layer2 Offset | Write Report Length-1 | Read Report Length-1 | Max Columns | Max Rows | LED State | Version | PID Low | PID Hi | Reserved
0 | <data> | 214 | value | 32 | 128 | 35 | 32 | 4 | 6 | LEDs | <data> | PIDL | PIDH | value

LEDs: Bit 7=1 for Green LED on, 0 for Green LED off, bit 8=1 for Red LED on, bit 8=0 for Red LED off.
PIDL: LSB of the Product Identification number or PID.
PIDH: MSB of the Product Identification number or PID.

### X-keys XK-24 KVM Output Report

The following types of output reports are shown in the summary below. These reports on only applicable when the device is in PID #1. 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.

Report | Format | Description
--- | --- | ---
1 | 0, 186, LEDs, 0... | Set LEDs
2 | 0, 179, LEDIndex, State, 0... | Index Based Set LED (Flash)
3 | 0, 189, UnitID, 0... | Set Unit IDe
4 | 0, 214, 0... | Request Descriptor
5 | 0, 210, Enable, 0... | Enable Time Stamp
6 | 0, 177, 0... | Generate Data
7 | 0, 187, Bank 1 Intensity, Bank 2 Intensity, 0... | Set Backlight Intensity
8 | 0, 184, 0... | Toggle Backlights
9 | 0, 183, ScrLk, 0... | Enable Scroll Lock to Toggle Backlights
10 | 0, 182, Bank, OnOff, 0... | Turn On/Off Rows of Backlights
11 | 0, 181, Index, State, 0... | Index Based Set Backlights (Flash)
12 | 0, 180, Freq, 0... | Set Frequency of Flash
13 | 0, 199, Save, 0... | Save Backlight State to EEPROMe
14 | 0, 204, Mode, 0... | Change PIDe
15 | 0, 196, Change, 0... | Reboot Mode
16 | 0, 201, Modifier, 0, HC1, HC2, HC3, HC4, HC5, HC6, 0... | Keyboard Reflector
17 | 0, 202, Joystick X, Joystick Y, Joystick Z rot., Joystick Z, Joystick Slider, Game Buttons 1, Game Buttons 2, Game Buttons 3, Game Buttons 4, 0, Point of View Hat, 0... | Joystick Reflector
18 | 0, 195, Version LSB, Version MSB, 0... | Set Version Numbere
19 | 0, 238, 0... | Reboot Device

eCommand writes to EEPROM, do not perform this command excessively, do not exceed 50,000 writes to EEPROM.
Endpoint: 4, Vendor Defined Usage Page.

Report Length: 36 bytes.

1. Set LEDs

One of two methods for controlling the LEDs.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | LED Control | Constant
0 | 186 | LEDs | 0

LEDs: Bits 1-6=0, bit 7=1 to turn on Green LED or 0 to turn off Green LED, bit 8=1 to turn on Red LED or 0 to turn off Red LED.

2. Index Based Set LED (Flash)

One of two methods for controlling the LEDs. If flashing of LEDs is desired this method must be used.

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

LEDIndex: 6 = green, 7 = red.
LEDState: 0 = off, 1 = on and 2 = flash. Set the frequency of the flash with output report 12. Set Frequency of Flash.

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

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 PS 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. Set Backlight Intensity

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Bytes 5-36
Constant | Command | Bank 1 Intensity | Bank 2 Intensity | Constant
0 | 187 | Intensity | Intensity | 0

Intensity: 0-255 where 0 is no intensity for that color or off, and 255 is the brightest.

8. Toggle Backlights

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

9. Enable Scroll Lock to Enable Backlights

Send this output report with ScrLk=128 to enable the standard keyboard's ScrLk key to toggle the backlights.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | Save | Constant
0 | 183 | ScrLk | 0

ScrLk: 0 to disable Scroll Lock, 128 to enable Scroll Lock to toggle backlighting.

10. Turn On/Off Rows of Backlights

Send this output report to either turn on or off rows of the backlights.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Bytes 5-36
Constant | Command | Bank # | State | Constant
0 | 182 | Bank | OnOff | 0

Bank: 0 = bank 1, 1 = bank 2.
OnOff: For all bits 0 for no backlighting, 1 for backlighting. Bit 0 = 1st row, bit 1=2nd row, bit 2=3rd row, bit 3=4th row, bit 4=5th row, bit 5=6th row. Note the intensities are not affected by this command.

11. Index Based Set Backlights (Flash)

Control of individual backlights.

Byte 1* | Byte 2 | Byte 3 | Byte 4 | Bytes 5-36
Constant | Command | Key Index | State | Constant
0 | 181 | Index | State | 0

Index: For bank 1 equals the index given in Figure 1. For bank 2 add 32 to the index given in Figure 1. For example to control the lower left key bank 1 index=5, the corresponding bank 2 is index=37.
State: 0 = off, 1 = on and 2 = flash. Set the frequency of the flash with output report 12. Set Frequency of Flash.

12. Set Frequency of Flash

Use this output report to control the frequency of the flashing of both the indicator LEDs and the backlights, same frequency is used for both.

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.

13. Save Backlight State to EEPROM

Send this output report to change the default backlighting on startup of device to the current backlight state, ie, what ever backlights are on or off at the time this report is sent will be the new default.

Byte 1* | Byte 2 | Byte 3 | Bytes 4-36
Constant | Command | Save | Constant
0 | 199 | Save | 0

Save: Any value other than 0 will save the current backlight state to the EEPROM so when the device is replugged it will display this save backlighting. Note because there is a limited number of times the EEProm can be written to, it is not a good idea to do this often.

14. Change PID

Send this output report to change between the two PIDs.

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

Mode: 0 for PID #1, reporting to the USB as a Splat device (IN and OUT), a joystick, and a boot keyboard and 1 for PID #2, reporting as a boot keyboard.

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

16. Keyboard Reflector

Sends native keyboard messages.

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.

17. Joystick Reflector

Sends native joystick messages (PID #2 only).

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 | Bytes 14-36
Constant | Command | Joystick X | Joystick Y | Joystick Z rot. | Joystick Z | Joystick Slider | Game Buttons | Game Buttons | Game Buttons | Game Buttons | Constant | Point of View Hat | Constant
0 | 202 | X | Y | Z rot. | Z | Slider | GB1 | GB2 | GB3 | GB4 | 0 | Hat | 0

X: Joystick X, 0-127 is from center to full right, 255-128 is from center to full left.
Y: Joystick Y, 0-127 is from center to bottom, 255-128 is from center to top.
Z rot.: Joystick Z rot., 0-127 is from center to bottom, 255-128 is from center to top.
Z.: Joystick Z, 0-127 is from center to bottom, 255-128 is from center to top.
Slider: Joystick Slider, 0-127 is from center to bottom, 255-128 is from center to top.
GB1: Game buttons 1-8, bit 1= game button 1, bit 2=game button 2, etc.
GB2: Game buttons 9-16, bit 1= game button 9, bit 2=game button 10, etc.
GB3: Game buttons 17-24, bit 1= game button 17, bit 2=game button 18, etc.
GB4: Game buttons 25-32, bit 1= game button 25, bit 2=game button 26, etc.
Hat: 0 to 7 clockwise, 8 is no hat.

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

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

*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