X-blox XBM-12 Trackball Module Data Report | Main Page
Note: The X-blox XBM-12 Trackball Module and the X-blox XBE-12 Trackball are the same product functionally, the only difference is the XBE-12 Trackball is in its own case. Please reference the XBM-12 Trackball Module folder for samples.
General Information
VID
|
05F3h
|
---|---|
XBM-12 Trackball Module PID #1
|
05D0h or 1488
|
XBM-12 Trackball Module PID #2
|
05D1h or 1489
|
XBM-12 Trackball Module PID #3
|
05D2h or 1490
|
XBM-12 Trackball Module PID #4
|
05D3h or 1491
|
XBM-12 Trackball Module PID #5 (Factory Default)
|
05D4h or 1492
|
XBM-12 Trackball Module PID #6
|
05D5h or 1493
|
XBM-12 Trackball Module PID #7
|
05D6h or 1494
|
XBM-12 Trackball Module PID #8 (KVM)
|
05D7h or 1495
|
Consumer Usage Page
|
1
|
Usage Page
|
000Ch or 12
|
PID #1 Endpoints: Consumer Usage Page Input and Output (Hid Usage Page
12, Hid Usage 1), Keyboard (Hid Usage Page 1, Hid Usage 6), Multimedia (Hid
Usage Page 12, Hid Usage 1 and Hid Usage Page 1, Hid Usage 128).
PID #2 Endpoints: Consumer Usage Page Input and Output (Hid Usage Page 12,
Hid Usage 1), Keyboard boot (Hid Usage Page 1, Hid Usage 6), Multimedia
(Hid Usage Page 12 and 1, Hid Usage 1 and 128).
PID #3 Endpoints: Consumer Usage Page Input and Output (Hid Usage Page 12,
Hid Usage 1), Keyboard (Hid Usage Page 1, Hid Usage 6), Joystick (Hid Usage
Page 1, Hid Usage 4).
PID #4 Endpoints: Consumer Usage Page Input and Output (Hid Usage Page 12,
Hid Usage 1), Joystick (Hid Usage Page 1, Hid Usage 4), Mouse (Hid Usage
Page 1, Hid Usage 2).
PID #5 Endpoints: Consumer Usage Page Input and Output (Hid Usage Page 12,
Hid Usage 1), Keyboard boot (Hid Usage Page 1, Hid Usage 6), Mouse (Hid
Usage Page 1, Hid Usage 2).
PID #6 Endpoints: Consumer Usage Page Input and Output (Hid Usage Page 12,
Hid Usage 1).
PID #7 Endpoints: Consumer Usage Page Input and Output (Hid Usage Page 12,
Hid Usage 1), Keyboard (Hid Usage Page 1, Hid Usage 6), Mouse (Hid Usage
Page 1, Hid Usage 2), Multimedia (Hid Usage Page 12 and 1, Hid Usage 1 and
128), Joystick (Hid Usage Page 1, Hid Usage 4).
PID #8 Endpoints: Keyboard boot (Hid Usage Page 1, Hid Usage 6) for use
with KVMs. Note: mouse will not work in this mode. To exit KVM mode on this
device unplug and replug the device while simultaneously holding down the
left trackball button.
In order for the trackball to work in native mouse mode there must be a
Mouse endpoint. A Mouse endpoint is available for PIDs #4, #5 (factory default),
and #7. Trackball X and Y data via a hid input report is available in all
PIDs except #8 (KVM) by enabling the Mouse Motion.
The XBM-12 Trackball Module is a standard USB HID device and is supported by P.I. Engineering's Macroworks 3.1, X-keys Basic Setup, and our many SDKs.
The XBM-12 Trackball Module has four GPIO pins which can be user configured for output (factory default), short to ground input, or drive high input. Table 1 shows the pins assignments for the GPIO port.
Pin
|
Description
|
---|---|
1
|
Pin 1 |
2
|
Pin 2 |
3
|
Pin 3 |
4
|
Pin 4 |
5
|
Ground |
Table 1: Pin assignments for the GPIO port
The XBM-12 Trackball Module has a UART port for serial communication. All features are accessible through the portInput reports can be read and output reports can be written through the UART port. See the X-blox UART Port Information section below for details on this specialized feature.
X-blox XBM-12 Trackball Module Input Report
Figure 1: X-blox XBM-12 Trackball Module
Report Length: 37 bytes
1. General Incoming Data
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 a Generate Data output report which is very useful for obtaining the initial state of the device immediately after enumeration. It is also sent when the user sends a Control Digital Input output report.
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-32
|
Bytes 33-36
|
Byte 37
|
Constant
|
Unit ID
|
Data Type
|
Keys
|
Keys
|
Keys
|
Keys, Right, & Left Buttons
|
NumLck, CapsLck, ScrLck, On Boot, GPIO Inputs
|
Virtual Digital Inputs
|
X Movement Low Byte
|
X Movement High Byte
|
Y Movement Low Byte
|
Y Movement High Byte
|
Reserved
|
Time Stamp
|
Reserved
|
0
|
<data>
|
DT
|
D1
|
D2
|
D3
|
D4
|
DS
|
DV
|
DELTA_X_L
|
DELTA_X_H
|
DELTA_Y_L
|
DELTA_Y_H
|
value
|
Time
|
value
|
DT: Data Type value of 0, 1, 2, or 3 indicates the following data
is a General Incoming Data report, DT is 2 if generated by the Generate
Data (output report 2). Any Data Type other than 0, 1, 2, or 3 is described
below
D1: For all bits 0 for open, 1 for closed. Bit 1=Key
0, bit 2=Key 1, bit 3=Key 2, bits 4-8=0
D2: For all bits 0 for open, 1 for closed. Bit 1=Key
3, bit 2=Key 4, bit 3=Key 5, bits 4-8=0
D3: For all bits 0 for open, 1 for closed. Bit 1=Key
6, bit 2=Key 7, bit 3=Key 8, bits 4-8=0
D4: For all bits 0 for open, 1 for closed. Bit 1=Key
9, bit 2=Key 10, bit 3=Key 11, bit 4=right trackball button, bit 5=left
trackball button
DS: For all bits 0 for open, 1 for closed. 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), bit 5=GPIO pin 1, bit 6=GPIO pin 2, bit 7=GPIO
pin 3, bit 8=GPIO pin 4
DV: Valid only when a Control Digital Input output report is sent
with a Virtual Button ID of 104-111. For all bits 0 for open, 1 for closed.
Bit 1=Virtual Digital Input 1 (Virtual Button ID = 104), bit 2=Virtual Digital
Input 2 (Virtual Button ID = 105), bit 3=Virtual Digital Input 3 (Virtual
Button ID = 106), bit 4=Virtual Digital Input 4 (Virtual Button ID = 107),
bit 5=Virtual Digital Input 5 (Virtual Button ID = 108), bit 6=Virtual Digital
Input 6 (Virtual Button ID = 109), bit 7=Virtual Digital Input 7 (Virtual
Button ID = 110), bit 8=Virtual Digital Input 8 (Virtual Button ID = 111)
DELTA_X_L: Lesat significant byte (LSB) of the X mouse motion, mouse
motion reporting must be enabled using the Enable Mouse Motion output report
in order to receive this data
DELTA_X_H: Most signficant byte (MSB) of the X mouse motion. X mouse
motion = 256*DELTA_X_H + DELTA_X_L, mouse motion reporting must be enabled
using the Enable Mouse Motion output report in order to receive this data
DELTA_Y_L: Lesat significant byte (LSB) of the Y mouse motion,
mouse motion reporting must be enabled using the Enable Mouse Motion output
report in order to receive this data
DELTA_Y_H: Most signficant byte (MSB) of the Y mouse motion. Y mouse
motion = 256*DELTA_Y_H + DELTA_Y_L, mouse motion reporting must be enabled
using the Enable Mouse Motion output report in order to receive this data
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 36 is the LSB or low byte and byte 33 is the MSB or high byte
2. Descriptor Data
This data is returned after a Get 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
|
Byte 15
|
Byte 16
|
Byte 17
|
Byte 18
|
Byte 19
|
Byte 20
|
Byte 21
|
Byte 22
|
Byte 23
|
Byte 24
|
Byte 25
|
Byte 26
|
Byte 27
|
Byte 28
|
Byte 29
|
Byte 30
|
Byte 31
|
Byte 32
|
Byte 33
|
Byte 34
|
Byte 35
|
Byte 36
|
Byte 37
|
Constant
|
Unit ID
|
Data Type
|
Mode
|
Key mapstart
|
Layer2 Offset
|
Constant
|
Constant
|
Max Columns
|
Max Rows
|
GPIO State
|
Version
|
PID Lo
|
PID Hi
|
Keymap start Hi
|
Max Macro Address Lo
|
Max Macro Address Hi
|
Bank 1 Dim Factor | Bank 2 Dim Factor | GPIO Configuration | GPIO Input Configuration |
UART Settings
|
Reserved
|
Start byte for Output Report Received Message
|
Stop byte for Output Report Received Message
|
Start byte for UART Custom Received Message
|
Stop byte for UART Custom Received Message
|
Native Mouse Enabled
|
Mouse Report Enabled
|
Reserved
|
General Incoming Data Enabled
|
Resolution
|
Rotate Unit
|
ClickLock Delay Low
|
ClickLock Delay High
|
Polling Interval
|
Reserved
|
0
|
<data>
|
214
|
Mode
|
160
|
128
|
255
|
255
|
4
|
8
|
GPIO
|
<data>
|
PIDL
|
PIDH
|
0
|
<data>
|
<data>
|
Dim1
|
Dim2
|
IOConfig
|
InputConfig
|
UART
|
value
|
4
|
5
|
2
|
3
|
NME
|
MRE
|
value
|
GIE
|
RES
|
ROT
|
CLL
|
CLH
|
CLH
|
value
|
Mode: 0 means device is in PID #1, 1 = PID #2, 2 = PID #3, 3 = PID
#4, 4=PID #5 (factory default), 5=PID #6, 6=PID #7
GPIO: This byte tells the current state of the four GPIO pins if
configured as outputs, bit 5= GPIO pin 1, bit 6=GPIO pin 2, bit 7=GPIO pin
3, bit 8=GPIO pin 4
PIDL: LSB of the Product Identification number or PID
PIDH: MSB of the Product Identification number or PID
Dim1: The stored Dim Factor for bank 1 (upper), 0-255 where 255 is
no dimming and 0 is 100% dim or LEDs off, factory default is 255, this may
differ from the current Dim Factor if user sent a Set
RGB Dim Factors output report and did not send a Save
Backlight State to EEPROM output report
Dim2: The stored Dim Factor for bank 2 (lower), 0-255 where 255 is
no dimming and 0 is 100% dim or LEDs off, factory default is 255, this may
differ from the current Dim Factor if user sent a Set
RGB Dim Factors output report and did not send a Save
Backlight State to EEPROM output report
IOConfig: For all bits, 0=output (factory default), 1=input where
bit 1=GPIO pin 1, bit 2=GPIO pin 2, bit 3=GPIO pin 3, bit 4=GPIO pin 4
InputConfig: If the GPIO pin is set to an input in IOConfig,
then the corresponding bit in this byte will determine the type of input,
0=Short to Ground (resistive pull up or triggers with ground), 1=Drive High
(resistive pull down or triggers with +3V to +5V)
UART: Users of UART port features only. Bit 1: 0=no UART PI Base64
Input Report Transmit Messages sent (factory default), 1=UART PI Base64
Input Report Transmit Message sent for selected input reports. See the Enable
UART PI Base64 Input Report Transmit Messages output report for details.
Bit 2: 0=no Incoming UART Data - Echo of UART Output
Report Received Message input report generated (factory default),
1=Incoming UART Data - Echo of UART Output Report Received
Message input report are generated when a UART Output Report Receive
Message received. See the Enable UART Echo output report for details. Bit
3: 0=Sleep of USB enabled (factory default), 1=Sleep of USB disabled. See
Disable Sleep of USB output report for details. Bit 4: 0=USB check enabled
(factory default), 1=USB check disabled. See Disable USB Check output report
for details.
NME: For all bits 0=disabled, 1=enabled (default). If disabled, then
no trackball motion
MRE: 0 if Mouse Motion Reporting is disabled (default) or 1 if enabled
GIE: 0 to disable the General Incoming Data Report, 1 (default) to
enable it
RES: Mouse resolution index of the trackball, 1=400 CPI, 2=600 CPI,
3=800 CPI, 4=1000 CPI, 5=1100 CPI (factory default), 6=1200 CPI, 7=1300
CPI, 8=1400 CPI, 9=1500 CPI, 10=1600 CPI
ROT: Describes orientation of unit, 0=0 degrees (default) trackball
on top, 1=90 degrees or trackball on right, 2=180 degrees or trackball on
bottom, 3=270 degrees or trackball on left
CLL: ClickLock delay low byte, where the ClickLock delay = 256*CLH+CLL.
Factory default ClickLock delay is 1200 ms.
CLH: ClickLock delay high byte, where the ClickLock delay = 256*CLH+CLL.
Factory default ClickLock delay is 1200 ms.
PI: the polling interval which is how often, in milliseconds, the
trackball is checked for motion, factory default is 4
3. Custom Data
This data is returned after a Generate Custom Data output report is sent.
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 37
|
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
5. RGB Backlight Values Data
This data is returned after an output report: Get RGB Backlight Values is sent. It returns the current state, R, G, and B, and flash state for both upper and lower LEDs of the requested key. It also returns the current Dim Factors and Flash Frequency.
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
|
Byte 15
|
Byte 16
|
Bytes 17 to 37
|
Constant | Unit ID | Data Type | Backlight Index |
R Value for Bank 1 LED |
G Value for Bank 1 LED | B Value for Bank 1 LED | R Value for Bank 2 LED | G Value for Bank 2 LED | B Value for Bank 2 LED | Flash State for Bank 1 LED | Flash State for Bank 2 LED | Reserved | Flash Frequency | Bank 1 Dim Factor | Bank 2 Dim Factor | Reserved |
0
|
<data>
|
167
|
BacklightIndex
|
value
|
value
|
value
|
value
|
value
|
value
|
Flash1
|
Flash2
|
value
|
value
|
Dim1
|
Dim2
|
value
|
BacklightIndex: Requested backlight, value shown on key in Figure
1
Flash1: Flash state for the bank 1 (upper) LED where 0=not flashing,
1=flashing
Flash2: Flash state for the bank 2 (lower) LED where 0=not flashing,
1=flashing
Dim1: Dim factor for bank 1 (upper), 0-255 where 255 is no dimming
and 0 is 100% dim or LEDs off, factory default is 255
Dim2: Dim factor for bank 2 (lower), 0-255 where 255 is no dimming
and 0 is 100% dim or LEDs off, factory default is 255
6. Unique ID Data
This data is returned after an output report: Request Unique ID is sent. It returns 8 bytes of the silicon generated unique ID of the device. This value is available also in the HID device descriptor as the string iSerialNumber.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Byte 7
|
Byte 8
|
Byte 9
|
Byte 10
|
Byte 11
|
Bytes 12 to 36
|
Constant | Unit ID | Data Type | Unique ID Byte 1 (MSB/Leftmost characters) | Unique ID Byte 2 | Unique ID Byte 3 | Unique ID Byte 4 | Unique ID Byte 5 | Unique ID Byte 6 | Unique ID Byte 7 | Unique ID Byte 8 (LSB/Rightmost characters) | Reserved |
0
|
<data>
|
157
|
B1
|
B2
|
B3
|
B4
|
B5
|
B6
|
B7
|
B8
|
value
|
B1-B8: The 8 bytes of the silicon generated unique ID of the device where B1 is the MSB and B8 is the LSB. Typically represented as a string of the hex values returned, for example if the 8 bytes returned were B1=70, B2=21, B3=48, B4=23, B5=22, B6=6, B7=43, and B8=0, the string for this would be 4615301716062B00
7. Incoming UART Data - Echo of UART Output Report Received Message
For users of the UART port only. If UART Echo is enabled, this report is generated when a UART Output Report Received Message is received on the module's UART RX. The module recognizes a UART Output Report Received Message by the start and stop bytes of 4 and 5, respectively. The data between the start and stop bytes in the UART Output Report Received Message is decoded from Base64 for this input report. For details on how to send a UART Output Report Receive Message to the module see the X-blox UART Port Information section below. This report can be enabled or disabled using the Enable Echo of UART Output Report Received Message output report. The current value can be read on the Descriptor as EchoEnabled. Note: regardless of this setting, when a UART Output Report Received Message is received it is executed.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Byte 7
|
Bytes 8 to x
|
Bytes x+1 to 37
|
Constant | Unit ID | Data Type | Number of bytes to follow | Command byte output report | Byte 1 of output report | Byte 2 of output report | Byte 3, 4, 5, ... of output report | Constant |
0
|
<data>
|
216
|
Count
|
BC
|
B1
|
B2
|
Bytes ...
|
0
|
Count: The number of bytes to follow
BC: The "Command" byte of the output report. For example,
if receiving an Index Based Set RGB Backlights output report then this value
would be 165
B1: The first byte of the required bytes for the output report. For
example, if receiving an Index Based Set RGB Backlights output report then
this value would be the Key Index
B2: The second byte of the required bytes of the output report. For
example, if receiving an Index Based Set RGB Backlights output report then
this value would be the Bank
Bytes: Additional bytes added until the required number of bytes
is reached. In the Index Based Set RGB Backlights example there would be
additionally B3=Red, B4=Green, B5=Blue, and B6= Flash and thus Count=7
8. Incoming UART Data - UART Custom Message
For users of the UART port only. This report is generated for messages received on the module's UART RX that have a start byte of 2 and a stop byte of 3. A single message may generate several of these reports. No decoding of data is performed.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Bytes 7 to x..
|
Bytes x+1
|
Bytes 34-37
|
Constant | Unit ID | Data Type | Start Byte | Byte 1 | Byte 2 | Byte 3 | Stop Byte | Constant |
0
|
<data>
|
216
|
2
|
B1
|
B2
|
Bytes ...
|
3
|
0
|
B1: The first byte of the custom message
B2: The second byte of the custom message
Bytes...: And so on, terminating with a stop byte of 3
The following is an example of an Incoming UART Data - UART Custom Message
that requires a total of 5 input reports to capture. This message is a UART
PI Base64 Input Report Transmit Message obtained from the following scenario:
- Connect the UART TX of X-blox module A to the UART RX of X-blox module
B
- On module A, enabled the Enable UART PI Base64 Input
Report Transmit Messages using the Enable UART PI Base64 Input Report Transmit
Messages output report
- Prepare module B for reading input reports
- Press a button on module A thus generating a General Incoming Data input
report on module A, simultaneously a UART PI Base64 Input Report Transmit
Messages is sent on module A's TX
- Module B receives the message on its UART RX and generates the Incoming
UART Data - UART Custom Message input reports, 4 of them in this case
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Bytes 7
|
Byte 8
|
Byte 9
|
Bytes 10
|
Byte 11
|
Byte 12
|
Bytes 13
|
Byte 14
|
Byte 15
|
Bytes 16
|
Byte 17
|
Byte 18
|
Byte 19
|
Bytes 20
|
Byte 21
|
Byte 22
|
Bytes 23
|
Byte 24
|
Byte 25
|
Bytes 26
|
Byte 27
|
Byte 28
|
Bytes 29
|
Byte 30
|
Byte 31
|
Bytes 32
|
Byte 33
|
Bytes 34-37
|
Constant | Unit ID | Data Type | Start Byte | Byte 1 { |
Byte 2 '' |
Byte 3 c |
Byte 4 m |
Byte 5 d |
Byte 6 " |
Byte 7 : |
Byte 8 " |
Byte 9 s |
Byte 10 e |
Byte 11 n |
Byte 12 d |
Byte 13 S |
Byte 14 p |
Byte 15 l |
Byte 16 a |
Byte 17 t |
Byte 18 " |
Byte 19 , |
Byte 20 " |
Byte 21 P |
Byte 22 I |
Byte 23 D |
Byte 24 " |
Byte 25 : |
Byte 26 " |
Byte 27 0-9 |
Byte 28 0-9 |
Byte 29 0-9 |
Constant |
0
|
<data>
|
216
|
2
|
123 (0x7b)
|
34 (0x22)
|
99 (0x63)
|
109 (0x6d)
|
100 (0x64)
|
34 (0x22)
|
58 (0x3a)
|
34 (0x22)
|
115 (0x73)
|
101 (0x65)
|
110 (0x6e)
|
100 (0x64)
|
83 (0x53)
|
112 (0x70)
|
108 (0x6c)
|
97 (0x61)
|
116 (0x74)
|
34 (0x22)
|
44 (0x2c)
|
34 (0x22)
|
80 (0x50)
|
73 (0x49)
|
68 (0x44)
|
34 (0x22)
|
58 (0x3a)
|
34 (0x22)
|
PID thousands
|
PID hundreds
|
PID tens
|
0
|
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Bytes 6
|
Byte 7
|
Byte 8
|
Bytes 9
|
Byte 10
|
Byte 11
|
Bytes 12
|
Byte 13
|
Byte 14
|
Bytes 15
|
Byte 16
|
Byte 17
|
Byte 18
|
Bytes 19
|
Byte 20
|
Byte 21
|
Bytes 22
|
Byte 23
|
Byte 24
|
Byte 25
|
Byte 26
|
Byte 27
|
Byte 28
|
Byte 29
|
Byte 30
|
Byte 31
|
Byte 32
|
Byte 33
|
Bytes 34-37
|
Constant | Unit ID | Data Type | Byte 30 0-9 |
Byte 31 " |
Byte 32 , |
Byte 33 " |
Byte 34 U |
Byte 35 I |
Byte 36 D |
Byte 37 " |
Byte 38 : |
Byte 39 " |
Byte 40 0-9 |
Byte 41 0-9 |
Byte 42 0-9 |
Byte 43 " |
Byte 44 , |
Byte 45 " |
Byte 46 S |
Byte 47 N |
Byte 48 " |
Byte 49 : |
Byte 50 " |
Byte 51 | Byte 52 | Byte 53 | Byte 54 | Byte 55 | Byte 56 | Byte 57 | Byte 58 | Byte 59 | Constant |
0
|
<data>
|
216
|
PID ones
|
34 (0x22)
|
44 (0x2c)
|
34 (0x22)
|
85 (0x55)
|
73 (0x49)
|
68 (0x44)
|
34 (0x22)
|
58 (0x3a)
|
34 (0x22)
|
UID hundreds
|
UID tens
|
UID ones
|
34 (0x22)
|
44 (0x2c)
|
34 (0x22)
|
83 (0x53)
|
78 (0x4E)
|
34 (0x22)
|
58 (0x3a)
|
34 (0x22)
|
Base64 SN 1
|
Base64 SN 2
|
Base64 SN 3
|
Base64 SN 4
|
Base64 SN 5
|
Base64 SN 6
|
Base64 SN 7
|
Base64 SN 8
|
Base64 SN 9
|
0
|
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Bytes 6
|
Byte 7
|
Byte 8
|
Bytes 9
|
Byte 10
|
Byte 11
|
Bytes 12
|
Byte 13
|
Byte 14
|
Bytes 15
|
Byte 16
|
Byte 17
|
Byte 18
|
Bytes 19
|
Byte 20
|
Byte 21
|
Bytes 22
|
Byte 23
|
Byte 24
|
Bytes 25
|
Byte 26
|
Byte 27
|
Bytes 28
|
Byte 29
|
Byte 30
|
Bytes 31
|
Byte 32
|
Byte 33
|
Bytes 34-37
|
Constant | Unit ID | Data Type | Byte 60 | Byte 61 | Byte 62 | Byte 63 " |
Byte 64 , |
Byte 65 " |
Byte 66 d |
Byte 67 a |
Byte 68 t |
Byte 69 a |
Byte 70 " |
Byte 71 : |
Byte 72 " |
Byte 73 | Byte 74 | Byte 75 | Byte 76 | Byte 77 | Byte 78 | Byte 79 | Byte 80 | Byte 81 | Byte 82 | Byte 83 | Byte 84 | Byte 85 | Byte 86 | Byte 87 | Byte 88 | Byte 89 | Constant |
0
|
<data>
|
216
|
Base64 SN 10
|
Base64 SN 11
|
Base64 SN 12
|
34 (0x22)
|
44 (0x2c)
|
34 (0x22)
|
34 (0x22)
|
97 (0x61)
|
116 (0x74)
|
97 (0x61)
|
34 (0x22)
|
58 (0x3a)
|
34 (0x22)
|
Base64 1
|
Base64 2
|
Base64 3
|
Base64 4
|
Base64 5
|
Base64 6
|
Base64 7
|
Base64 8
|
Base64 9
|
Base64 10
|
Base64 11
|
Base64 12
|
Base64 13
|
Base64 14
|
Base64 15
|
Base64 16
|
Base64 17
|
0
|
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Bytes 6
|
Byte 7
|
Byte 8
|
Bytes 9
|
Byte 10
|
Byte 11
|
Bytes 12
|
Byte 13
|
Byte 14
|
Bytes 15
|
Byte 16
|
Byte 17
|
Byte 18
|
Bytes 19
|
Byte 20
|
Byte 21
|
Bytes 22
|
Byte 23
|
Byte 24
|
Bytes 25
|
Byte 26
|
Byte 27
|
Bytes 28
|
Byte 29
|
Byte 30
|
Bytes 31
|
Byte 32
|
Byte 33
|
Bytes 34-37
|
Constant | Unit ID | Data Type | Byte 90 | Byte 91 | Byte 92 | Byte 93 | Byte 94 | Byte 95 | Byte 96 | Byte 97 | Byte 98 | Byte 99 | Byte 100 | Byte 101 | Byte 102 | Byte 103 | Byte 104 | Byte 105 | Byte 106 | Byte 107 | Byte 108 | Byte 109 | Byte 110 | Byte 111 | Byte 112 | Byte 113 | Byte 114 | Byte 115 | Byte 116 | Byte 117 | Byte 118 | Byte 119 | Constant |
0
|
<data>
|
216
|
Base64 18
|
Base64 19
|
Base64 20
|
Base64 21
|
Base64 22
|
Base64 23
|
Base64 24
|
Base64 25
|
Base64 26
|
Base64 27
|
Base64 28
|
Base64 29
|
Base64 30
|
Base64 31
|
Base64 32
|
Base64 33
|
Base64 34
|
Base64 35
|
Base64 36
|
Base64 37
|
Base64 38
|
Base64 39
|
Base64 40
|
Base64 41
|
Base64 42
|
Base64 43
|
Base64 44
|
Base64 45
|
Base64 46
|
Base64 47
|
0
|
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Bytes 15
|
Byte 16
|
Byte 17
|
Bytes 18-37
|
Constant | Unit ID | Data Type | Byte 120 | Byte 121 | Byte 122 | Stop Byte | Constant |
0
|
<data>
|
216
|
Base64 48
|
34 (0x22)
|
125 (0x7d)
|
3
|
0
|
Base64 SN1-12: Base64 encoded bytes of the Unique ID or "Serial
Number"
Base64 1-Base64 48: Base64 encoded bytes of the input report, excluding
the leading 0
9. ClickLock Delay Reached Data
This data is returned once the Left ClickLock button has been held down long enough to enter the ClickLock state and also when it releases from ClickLock state. It is valid only for buttons programmed as Left ClickLock. The desired amount of time needed for the button to be pressed before entering the ClickLock state (CLL and CLH) is 1200 ms by factory default but can be changed by sending a Set ClickLock Delay output report.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Byte 7
|
Bytes 8 to 36
|
Constant | Unit ID | Data Type | Actual ClickLock Delay LSB | Actual ClickLock Delay MSB | ClickLock Desired Delay LSB | ClickLock Desired Delay MSB | Reserved |
0
|
<data>
|
162
|
ACLL
|
ACLH
|
CLL
|
CLH
|
value
|
ACLL: Actual ClickLock delay low byte, where the actual ClickLock
delay = 256*ACLH+ACLL. This is the actual time the button
was held down before entering the ClickLock state, ACLL and ACLH both=0
for ClickLock release
ACLH: Actual ClickLock delay high byte, where the actual ClickLock
delay = 256*ACLH+ACLL. This is the actual time the button
was held down before entering the ClickLock state, ACLL and ACLH both=0
for ClickLock release
CLL: ClickLock delay low byte, where the ClickLock delay = 256*CLH+CLL.
Factory default ClickLock delay is 1200 ms. This is the desired amount of
time needed to hold the button down in order to enter the ClickLock state
CLH: ClickLock delay high byte, where the ClickLock delay = 256*CLH+CLL.
Factory default ClickLock delay is 1200 ms. This is the desired amount of
time needed to hold the button down in order to enter the ClickKock state
*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.
X-blox XBM-12 Trackball Module Output Report
The following types of output reports are shown in the summary below. 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, 186, PinState, 0... | Set GPIO Outputs |
2
|
0, 179, PinIndex, State, 0... | Index Based Set GPIO Outputs |
3
|
0, 189, UnitID, 0... | Set Unit IDe |
4
|
0, 214, 0... | Get 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, 165, BacklightIndex, Bank, R, G, B, Flash, 0... | Index Based Set RGB Backlights |
9
|
0, 166, Bank, R, G, B, 0... | Set Entire Bank of RGB Backlights |
10
|
0, 164, Bank 1 Dim Factor, Bank 2 Dim Factor, 0... | Set RGB Dim Factors |
11
|
0, 167, BacklightIndex, 0... | Get RGB Backlight Values |
12
|
0, 181, LBacklightIndex, State, 0... | Legacy Index Based Set Backlights (Flash) |
13
|
0, 182, Bank, OnOff, 0... | Legacy Turn On/Off Rows of Backlights |
14
|
0, 187, Bank 1 Intensity, Bank 2 Intensity, 0... | Legacy Set Backlight Intensity |
15
|
0, 184, 0... | Toggle Backlights |
16
|
0, 180, Freq, 0... | Set Frequency of Flash |
17
|
0, 199, Save, 0... | Save Backlight State to EEPROMe |
18
|
0, 204, Mode, 0... | Change PIDe |
19
|
0, 196, Change, 0... | Reboot Mode |
20
|
0, 201, Modifier, 0, HC1, HC2, HC3, HC4, HC5, HC6, 0... | Keyboard Reflector (keyboard endpoint required) |
21
|
0, 203, Buttons, Mouse X, Mouse Y, Wheel Y, 0... | Mouse Reflector (mouse endpoint required) |
22
|
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 (joystick endpoint required) |
23
|
0, 225, Usage ID LSB, Usage ID MSB, 0... | Multimedia Reflector (multimedia endpoint required) |
24
|
0, 147, IOConfig, InputConfig, 0... | Set GPIO Configuration |
25
|
0, 148, 0... | Save GPIO Configuatione |
26
|
0, 195, Version LSB, Version MSB, 0... | Set Version Numbere |
27
|
0, 238, 0... | Reboot Device |
28
|
0, 192, K0, K1, K2, K3, 0... | Set Dongle Keye |
29
|
0, 193, N0, N1, N2, N3, 0... | Check Dongle Key |
30
|
0, 162, ClickLock Delay Low, ClickLock Delay High, 0... | Set ClickLock Delaye |
31
|
0, 161, Rotation, 0... | Rotate Unite |
32
|
0, 168, Resolution, 0... | Set Mouse Resolutione |
33
|
0, 171, Mouse Report Enabled, 0... | Enable Mouse Motion Reportinge |
34
|
0, 173, Native Mouse Enabled, 0... | Disable Native Mousee |
35
|
0, 163, General Incoming Data Enabled, 0... | Enable General Incoming Datae |
36
|
0, 157, 0... | Request Unique ID |
37
|
0, 220, KeyIndex or Virtual Button ID, State, 0... | Control Digital Input |
38
|
0, 215, Enable, 0... | Enable UART PI Base64 Input Report Transmit Messagese |
39
|
0, 216, Count, B1, B2, B3..., 0... | Transmit to UART |
40
|
0, 217, Enable, 0... | Enable Echo of UART Output Report Received Messagee |
41
|
0, 175, Polling Interval, 0... | Set Polling Intervale |
42
|
0, 218, SleepDisable, 0... | Disable Sleep of USBe |
43
|
0, 143, USBCheckDisable, 0... | Disable USB Check |
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. Set GPIO Outputs
One of two methods for controlling the GPIO outputs. This command is recommended only if all four GPIO pins are configured as outputs, otherwise use Index Based Set GPIO Outputs.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant | Command | GPIO Control | Constant |
0
|
186
|
PinState
|
0
|
PinState: Bit 1=GPIO pin 1, bit 2=GPIO pin 2, bit 3=GPIO pin 3, bit 4=GPIO pin 4. Bit is 0 for off, 1 for on. For example a value of 5 (0101) turns on GPIO pin 1 and GPIO pin 3 and turns off GPIO pin 2 and GPIO pin 4.
2. Index Based Set GPIO Outputs
One of two methods for controlling the GPIO outputs. If flashing of output is desired this method must be used.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Bytes 5-36
|
Constant | Command | Pin Index | State | Constant |
0
|
179
|
PinIndex
|
PinState
|
0
|
PinIndex: 1=GPIO pin 1, 2=GPIO pin 2, 3=GPIO pin 3, 4=GPIO pin 4
PinState: 0=off, 1=on and 2=flash. Set the frequency of the flash
with output report 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. Get Descriptor
After sending this output report a Descriptor Data 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 (see General Incoming Data). 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 Custom 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. Index Based Set RGB Backlights
Control of individual backlights. For each key shown in Figure 1 there are 2 RGB backlight LEDs, one above the key and one below. The LEDs above the key are said to be on "bank 1" and those below the key are said to be on "bank 2".
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Byte 7
|
Byte 8
|
Bytes 9-36
|
Constant | Command | Backlight Index | Bank | Red | Green | Blue | Flash | Constant |
0
|
165
|
BacklightIndex
|
Bank
|
R
|
G
|
B
|
Flash
|
0
|
BacklightIndex: Desired backlight, value shown on key in Figure
1
Bank: 0 for bank 1(upper) LEDs, 1 for bank 2 (lower) LEDs
R: 0 = no red, 1-255 for red component of desired color
G: 0 = no green, 1-255 for green component of desired color
B: 0 = no blue, 1-255 for blue component of desired color
Flash: 0 = no flash, 1 = flash, set the frequency of the flash using
the Set Frequency of Flash command
Both color and intensity are controlled with the R, G, and B values. For
example the brightest red is 255, 0, 0 and a dimmest red 1, 0, 0. To vary
the intensity of a color the ratios of R, G, B must be maintained. For example,
a bright yellow is 255, 128, 0 and a dimmer yellow is 128, 64, 0. Below
is a list of the R, G, B values for commonly used colors.
Off - 0, 0, 0
White - 255, 255, 255
Pink - 255, 8, 40
Red - 255, 0, 0
Orange - 255, 20, 0
Yellow - 255, 128, 0
Green - 0, 255, 0
Turquoise - 0, 255, 129
Blue - 0, 0, 255
Purple - 150, 0, 255
9. Set Entire Bank of RGB Backlights
Send this output report to turn on or off all of the LEDs on a given bank.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Bytes 7-36
|
Constant | Command | Bank | Red | Green | Blue | Constant |
0
|
166
|
Bank
|
R
|
G
|
B
|
0
|
Bank: 0 for bank 1(upper) LEDs, 1 for bank 2 (lower) LEDs
R: 0 = no red, 1-255 for red component of desired color
G: 0 = no green, 1-255 for green component of desired color
B: 0 = no blue, 1-255 for blue component of desired color
10. Set RGB Dim Factors
This output report is meant to be used after setting up the entire unit's RGB LEDs using the above output reports 8. and 9. It will apply a bank-wide dim factor where 255 is the equivalent of no dimming at all and 0 is 100% dimming which will result in all LEDs for the bank being off. Factory default is 255. Use caution if set a dim factor to 0, LEDs will be off and will not be able to be turned on without changing the dim factor to a non-0 value.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Bytes 5-36
|
Constant | Command | Bank 1 Dim Factor | Bank 2 Dim Factor | Constant |
0
|
164
|
Dim1
|
Dim2
|
0
|
Dim1: Dim factor for bank 1 (upper), 0-255 where 255 is no dimming
and 0 is 100% dim or LEDs off, factory default is 255
Dim2: Dim factor for bank 2 (lower), 0-255 where 255 is no dimming
and 0 is 100% dim or LEDs off, factory default is 255
11. Get RGB Backlight Values
After sending this output report an RGB Backlight Values Data input report will be returned giving the three RGB values and flash state for bank 1 (upper) and bank 2 (lower) LEDs of the requested key. Also returned is the flash frequency.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant | Command | Backlight Index | Constant |
0
|
167
|
BacklightIndex
|
0
|
BacklightIndex: Desired backlight, value shown on key in Figure 1
12. Legacy Index Based Set Backlights
This a legacy command meant to behave the same as the Index Based Set Backlights command on non-RGB LED X-keys which have only blue on bank 1 (upper) and red on bank 2 (lower). It works in conjunction with the Legacy Set Backlights Intensity command and the Legacy Turn On/Off Rows of Backlights. Control of individual backlights with top backlight LED only blue and bottom backlight LED only red.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Bytes 5-36
|
Constant | Command | Legacy Backlight Index | State | Constant |
0
|
181
|
LBacklightIndex
|
State
|
0
|
LBacklightIndex: For bank 1 (upper) LEDs, value shown in Figure
1. For bank 2 (lower) LEDs add 12 to the value shown in Figure 1. For example
to control the top left key bank 1 index=0, the corresponding bank 2 is
index=12
State: 0 = off, 1 = on and 2 = flash. Set the frequency of the flash
with output report Set Frequency of Flash
13. Legacy Turn On/Off Rows of Backlights
This a legacy command meant to behave the same as the Turn On/Off Rows of Backlights command on non-RGB LED X-keys which have only blue on bank 1 (upper) and red on bank 2 (lower). It works in conjunction with the Legacy Set Backlights Intensity command and the Legacy Index Based Set Backlights. Send this output report to either turn on or off rows of the backlights. This command is most useful for turning on or off all of the LEDs on a given bank.
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. Set
to 0 to turn all of the LEDs on the selected bank off, and set to 255 to
turn them all on.
14. Legacy Set Backlight Intensity
This a legacy command meant to behave the same as the Set Intensity command on non-RGB LED X-keys. It works in conjunction with the Legacy Index Based Set Backlights command and the Legacy Turn On/Off Rows of Backlights.
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
15. Toggle Backlights
Byte 1*
|
Byte 2
|
Bytes 3-36
|
Constant | Command | Constant |
0
|
184
|
0
|
16. 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
17. 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 which includes all LED R, G, B values and Dim Factors, to the EEPROM so when the device is replugged it will display this 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
18. Change PID
Send this output report to change between PIDs.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant | Command | Mode | Constant |
0
|
204
|
Mode
|
0
|
Mode: 0 for PID #1, 1 for PID #2, 2 for PID #3 and 3 for PID #4, 4 for PID #5, 5 for PID #6, 6 for PID #7, and 7 for PID #8 (KVM). Note if change to PID #8 (KVM) input and output reports will not be available, and the trackball will not function. To convert back to PID #1 from PID #8, immediately after plugging the device in, toggle the Scroll Lock key on the keyboard 5-10 times. Use the Reboot Mode command to either have the unit always revert to PID #8 (KVM) on reboot or not.
19. Reboot Mode
Send this output report to determine if the device will automatically return to PID #8 (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: Enter 0 to have the device not return to PID #8 (KVM) on reboot and 7 to have it always return to PID #8 (KVM) on reboot
To setup a device for KVM use first program the hardware keyboard macros into it using either P.I. Engineering Macroworks 3.1 or X-keys Basic Setup while it is in the factory default PID #1. Test the macros to make sure they are as desired. After programming send the Reboot Mode command with Change=7, then either reboot device or send the Change PID command with Mode=7.
To return a device previously setup for KVM use, press and release the
Scroll Lock key 10 times immediately after plugging in the device. The device
will return to the factory default PID #1. Now it is important to send the
Reboot Mode command with Change=0. The device will now be back to factory
default. User may or may not wish to clear the hardware keyboard macros
at this point.
20. Keyboard Reflector
Sends native keyboard messages. Must have the device set to a PID with a keyboard endpoint; PID #1, #2, #3, #5, #7, or #8 (KVM mode).
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
21. Mouse Reflector
Sends native mouse messages. Must have the device set to a PID with a mouse endpoint; PID #4, #5, or #7.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6
|
Bytes 7-36
|
Constant | Command | Buttons | Mouse X | Mouse Y | Wheel Y | Constant |
0
|
203
|
Buttons
|
X
|
Y
|
WY
|
0
|
Buttons: Bit 1=Left, bit 2=Right, bit 3=Middle, bit 4=XButton1,
bit 5=XButton2
X=Mouse X motion. 0 no motion, 1-127 is right, 255-129=left, finest
inc (1 and 255) to coarsest (127 and 129)
Y=Mouse Y motion. 0 no motion, 1-127 is down, 255-129=up, finest
inc (1 and 255) to coarsest (127 and 129)
WY=Wheel Y. 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
22. Joystick Reflector
Sends native joystick messages. Must have the device set to a PID with a joystick endpoint; PID #3, #4, or #7.
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
23. Multimedia Reflector
Sends 2 byte multimedia messages. Must have the device set to a PID with a multimedia endpoint; PID #1, #2, or #3. When in this PID there is no input data report available thus users of this feature will not be able to read any data, only write output reports. If desiring this feature users are instructed to use MacroWorks 3.1 programming utility for programming of the buttons and converting to a multimedia PID. This command must be followed with an "up" command with ULo and UHi =0.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Bytes 8-36
|
Constant | Command | Usage ID Lo | Usage ID Hi | Constant |
0
|
225
|
ULo
|
UHi
|
0
|
ULo=Usage ID low byte see hut1_12.pdf, pages 75-85 Consumer Page
UHi=Usage ID high byte see hut1_12.pdf, pages 75-85 Consumer Page
Example: My Computer - 0, 225, 94, 01, 0... and send report using WriteData. Then 0, 225, 0, 0, 0... and send report using WriteData. In this example 0194 is the Usage ID for My Computer.
24. Set GPIO Configuration
Send this output report to configure the four GPIO pins to be outputs or inputs and if configured as inputs, the input configuration. The GPIO pins are set to outputs by factory default. In order to make the GPIO configuration permanent, the Save GPIO Configuration command must be called, otherwise the unit will return to the last saved configuration.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Bytes 5-36
|
Constant | Command | IO Configuration | Input Configuration | Constant |
0
|
147
|
IOConfig
|
InputConfig
|
0
|
IOConfig: For all bits, 0=output, 1=input where bit 1=GPIO pin 1,
bit 2=GPIO pin 2, bit 3=GPIO pin 3, bit 4=GPIO pin 4
InputConfig: If the GPIO pin is set to an input in IOConfig,
then the corresponding bit in this byte will determine the type of input,
0=Short to Ground (resistive pull up or triggers with ground), 1=Drive High
(resistive pull down or triggers with +3V to +5V)
25. Save GPIO Configuration
Send this output report to save the GPIO configuration set using the Set GPIO Configuration to memory.
Byte 1*
|
Byte 2
|
Bytes 3-36
|
Constant | Command | Constant |
0
|
148
|
0
|
26. 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
|
27. 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
|
28. 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
29. 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
|
193
|
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
30. Set ClickLock Delay
Use this output report to change the ClickLock delay which is the amount of time a ClickLock button must be held down before the ClickLock is engaged. Factory default is 1200 ms. Current value can be read in the Descriptor Data input report. Note if using this feature, do not also activate the operating system's ClickLock feature.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Bytes 5-36
|
Constant
|
Command
|
ClickLock Delay Low
|
ClickLock Delay High
|
Constant
|
0
|
162
|
CLL
|
CLH
|
0
|
CLL: ClickLock delay low byte, where the ClickLock delay = 256*CLH+CLL.
Factory default ClickLock delay is 1200 ms. This is the desired amount of
time needed to hold the button down in order to enter the ClickLock state
CLH: ClickLock delay high byte, where the ClickLock delay = 256*CLH+CLL.
Factory default ClickLock delay is 1200 ms. This is the desired amount of
time needed to hold the button down in order to enter the ClickLock state
31. Rotate Unit
Use this output report if the unit will be rotated, it will adjust the X and Y trackball motion accordingly such that rolling the trackball to the right results in mouse cursor motion to the right, rolling the trackball to the left results in mouse cursor motion to the left, rolling the trackball up or away from the user results in the mouse cursor motion up, and rolling the trackball down or towards the user results in mouse cursor motion down. Current value can be read in the Descriptor.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
Rotation
|
Constant
|
0
|
161
|
ROT
|
0
|
ROT: 0=0 degree rotation or trackball on bottom as shown in Figure 1 (factory default), 1=90 degree rotation or trackball on left, 2=180 degree rotation or trackball on top, 3=270 degree rotation or trackball on right
32. Set Mouse Resolution
Use this output report to set the mouse resolution or mouse cpi. Current value can be read in the Descriptor.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
Resolution Index
|
Constant
|
0
|
168
|
CPI
|
0
|
CPI: The index corrresponding to desired cpi 1=400, 2=600, 3=800, 4=1000, 5=1100 (factory default), 6=1200, 7=1300, 8=1400, 9=1500, 10=1600
33. Enable Mouse Motion Reporting
Use this output report to enable or disable the reporting of the Mouse Motion bytes in the General Incoming Data input report. If enabled differences in X and Y mouse motion caused by trackball movement will generate a new General Data input report, regardless of whether native mouse features are enabled or not. Current value can be read in the Descriptor.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
Mouse Report Enable
|
Constant
|
0
|
171
|
MRE
|
0
|
MRE: 0=off (factory default), 1=on
34. Disable Native Mouse
Use this output report to disable or enable the native mouse. If disabled there is no trackball motion. It is intended for developers who wish to use the trackball for other purposes other than a mouse. The trackball motion can be read by enabling the Mouse Message Report, a new report will be generated when motion is detected. Note: PIDs #1, #2, #3, and #6 do not have a Mouse endpoint thus putting the XBA-Trackball into one of these PIDs using the Change PID command would have the same effect as disabling the native mouse. Current value can be read in the Descriptor.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
Enable
|
Constant
|
0
|
173
|
NME
|
0
|
NME: 1=enabled (factory default) and 0=disabled. If disabled then no trackball motion
35. Enable General Incoming Data
Use this output report to disable or enable the General Incoming Data Input Report. Disabling this report will not affect the mouse button functions, factory default macros, or other hardware mode programmed macros. Current value can be read in the Descriptor.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
General Incoming Data Enable
|
Constant
|
0
|
163
|
GIE
|
0
|
GIE: 1=enabled (factory default) and 0=disabled
36. Request Unique ID
After sending a Request Unique ID output report, a Request Unique ID Data input report will be generated with the 8 bytes of the silicon generated unique ID of the device. This value is available also in the HID device descriptor as the string iSerialNumber.
Byte 1*
|
Byte 2
|
Bytes 3-36
|
Constant | Command | Constant |
0
|
157
|
0
|
37. Control Digital Input
Use this output report to virtually press or release a physical button or to press or release a Virtual Button.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 5
|
Bytes 4-36
|
Constant
|
Command
|
Key Index or Virtual Button ID
|
State
|
Constant
|
0
|
220
|
ID
|
State
|
0
|
ID: To control one of the physical buttons use the Key Index of
the button as shown in Figure 1. To control the GPIOs (if configured as
inputs) ID=100, 101, 102, 103. There 8 digital Virtual Buttons provided
on the device. Controlling these Virtual Buttons will cause a General Incoming
Data input report with the Virtual Digital Inputs byte modified. ID= 104
to 111 correspond to the lowest to highest bit. A special ID=255 is provided
to clear all buttons pressed virtually.
State: 2=press, 1=release
38. Enable UART PI Base64 Input Report Transmit Messages
For users of the UART port only. Send this output report to disable or enable the UART PI Base64 Input Report Transmit Messages. If enabled, a UART PI Base64 Input Report Transmit Message will be transmitted via the module's UART TX whenever certain input reports are generated, see the X-blox UART Port Information section for additional details. Factory default is disabled. Current value can be read in the Descriptor as PIEnabled.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
Enable
|
Constant
|
0
|
215
|
Enable
|
0
|
Enable: 0=disabled (factory default), 1=enabled
39. Transmit to UART
For users of the UART port only. Puts bytes on the module's UART TX for transmission. The number of bytes sent at one time is limited by the output report length and is 33.
Byte 1*
|
Byte 2
|
Byte 3
|
Byte 4
|
Byte 5
|
Byte 6...
|
Bytes (Count+4) to 36
|
Constant
|
Command
|
Count of bytes to follow
|
Byte 1
|
Byte 2
|
Byte 3...
|
Constant
|
0
|
216
|
Count
|
B1
|
B2
|
B3...
|
0
|
Count: Number of bytes to follow
B1: 1st byte
B2: 2nd byte
B3: 3rd byte and so on for as many bytes as specified in Count
40. Enable Echo of UART Output Report Received Message
For users of the UART port only. Send this output report to disable or enable the Incoming UART Data - Echo of UART Output Report Received Message input reports generated when UART Output Report Received Messages are received via the module's UART RX. Current value can be read in the Descriptor as EchoEnabled. Note: regardless of this setting, when a UART Output Report Received Message is received, the corresponding output report is executed.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
Enable
|
Constant
|
0
|
217
|
Enable
|
0
|
Enable: 0=disabled (factory default), 1=enabled
41. Set Polling Interval
Send this output report to change the polling interval which is how often, in milliseconds, the trackball is checked for motion. Factory default is 4. Current value can be read in the Descriptor Data input report.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant | Command | Polling Interval | Constant |
0
|
175
|
PI
|
0
|
PI: Polling Interval in milliseconds
43. Disable Sleep of USB
By factory default the X-keys device is designed to turn off its LEDs and any GPIO pins configured as outputs when a USB suspend condition occurs. To override this behavior send this report with SleepDisable=1.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
Sleep Disable
|
Constant
|
0
|
218
|
SleepDisable
|
0
|
SleepDisable: 0=enabled (factory default), 1=disabled
44. Disable Check of USB
For users of UART port only operating without USB connection. X-keys devices with UART capability are designed to operate without a USB connection. In this configuration the USB cord is used for power only. When no USB is detected and USBCheckDisable=0, the X-keys device will check for the presence of a USB connection periodically. Normally this presents no problems but to suppress this periodic check send this report with a value of 1.
Byte 1*
|
Byte 2
|
Byte 3
|
Bytes 4-36
|
Constant
|
Command
|
USB Check Disable
|
Constant
|
0
|
143
|
USBCheckDisable
|
0
|
USBCheckDisable: 0=enabled (factory default), 1=disabled
*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.
X-blox UART Port Information
For users of UART port only. This X-blox module comes equipped with a UART port for serial communication options. Pin assignments for the UART port are shown in Table 2. Baud rate is 115200 (actual baud rate 114286), Data bits 8, Parity non, Stop bits 1.
Pin
|
Description
|
---|---|
1
|
RX |
2
|
TX |
3
|
- |
4
|
- |
5
|
Ground |
Table 2: Pin assignments for the UART port
Messages Received
Two types of messages received on the module's UART RX are recognized;
UART Output Report Received Messages to control features like the RGB LEDs,
set Unit ID, etc. and UART Custom Received Messages. Each is described below.
1. UART Output Report Received Message
Every output report described in the above Output Report section can be
sent via the UART. UART Output Report Received Message requires a start
byte of 4, encoding into Base64 of the 2 digit hexidecimal byte values required
for the output report, and a stop byte of 5. This example demonstrates turning
the bank 1 RGB LED corresponding to KeyIndex 0 (first button in top left)
to red. Consulting the Index Based Set RGB Backlights output report from
above, we need to send a total of 7 bytes; 165, KeyIndex,
Bank, R, G, B, Flash. Note for this method we ignore the first 0
and the trailing 0s. Convert each byte to 2 digit hexidecimal strings and
store in a string array called stringbytes:
stringbytes[0]="A5"; //Command
stringbytes[1]="00"; //KeyIndex
stringbytes[2]="00"; //bank 1
stringbytes[3]="FF"; //r
stringbytes[4]="00"; //g
stringbytes[5]="00"; //b
stringbytes[6]="00"; //flash
Next convert stringbytes to Base64, this example uses Visual Studio C# Convert
call:
int baseType = 16; //data coming in hex
byte[] dataArray = new byte[stringbytes.Length];
for (int i = 0; i < stringbytes.Length; i++)
{
dataArray[i] = Convert.ToByte(stringbytes[i], baseType);
// baseType can be 16 for Hex or 10 for Dec
}
string bytesBase64 = Convert.ToBase64String(dataArray);
The resulting encoded string is pQAA/wAAAA==
Once the Base64 encoded string is obtained user can send it to the module's UART RX using a start byte of 4 and a stop byte of 5. The following is the complete message:
Byte 1=4 start byte
Byte 2=0x70 p
Byte 3=0x51 Q
Byte 4=0x41 A
Byte 5=0x41 A
Byte 6=0x2F /
Byte 7=0x77 w
Byte 8=0x41 A
Byte 9=0x41 A
Byte 10=0x41 A
Byte 11=0x41 A
Byte 12=0x3D =
Byte 13=0x3D =
Byte 14=5 stop byte
Sending this message will result in setting the top left bank 1 RGB LED
to red and, if the UART Echo is enabled, an Incoming UART Data - UART Echo
input report to be generated.
2. UART Custom Received Messages
A message received on the module's RX with a start byte of 2, up to 255
bytes of user defined data, and a stop byte of 3. For example:
Byte 1=0x02 start byte
Byte 2=0x75 first byte
Byte 3=0x41 second byte
Byte 4=0x3D third byte
Byte 5=0x3D fourth byte
Byte 6=0x03 stop byte
When this message is received on the module's UART RX, an Incoming UART
Data - UART Custom Received Message input report is generated. Messages
without the required start and stop bytes are ignored.
Messages Transmitted
Two types of messages are transmitted from the module's UART TX; UART PI Base64 Input Report Transmit Message and UART Custom Transmit Message.
UART PI Base64 Input Report Transmit Message
These messages are only sent if UART PI Base64 Input Report Transmit Messages are enabled, see Enable UART PI Base64 Input Report Transmit Messages output report. If enabled whenever General Incoming Data, Descriptor Data, Custom Data, Check Dongle Key, RGB Backlight Values Data, or Unique ID Data input report is generated a corresponding UART PI Base64 Input Report Transmit Message will also be transmitted on the module's UART TX. The message is a total of 104 bytes consisting of a start byte of 2, header text, Product ID, Unit ID, the Base64 encoded input report (excluding the leading 0), and a stop byte of 3 as follows:
0x02 start byte
0x7b {
0x22 "
0x63 c
0x6d m
0x64 d
0x22 "
0x3a :
0x22 "
0x73 s
0x65 e
0x6e n
0x64 d
0x53 S
0x70 p
0x6c l
0x61 a
0x74 t
0x22 "
0x2c ,
0x22 "
0x50 U
0x49 I
0x44 D
0x22 "
0x3A :
0x22 "
Ascii code for the thousands place of the Product ID
Ascii code for the hundreds place of the Product ID
Ascii code for the tens place of the Product ID
Ascii code for the ones place of the Product ID
0x22 "
0x2c ,
0x22 "
0x55 U
0x49 I
0x44 D
0x22 "
0x3a :
0x22 "
Ascii code for hundreds place of the Unit ID
Ascii code for the tens place of the Unit ID
Ascii code for the ones place of the Unit ID
0x22 "
0x2c ,
0x22 "
0x53 S
0x4E N
0x22 "
0x3A :
0x22 "
<SN Data> Base64 encoded Unique ID or "Serial Number", this
is 12 bytes
0x22 "
0x2C ,
0x22 "
0x64 d
0x61 a
0x74 t
0x61 a
0x22 "
0x3a :
0x22 "
<Input Report Data> Base64 encoded input report, this is 48 bytes
and does not include the leading 0 which is appended by Windows.
0x22 "
0x7d }
0x03 stop byte
UART Custom Transmit Message
Sending the Transmit to UART output report will place on the module's UART TX any bytes the user desires, up to 33 bytes per message