/doc/hidpp10.md

https://github.com/cvuchener/g500 · Markdown · 215 lines · 159 code · 56 blank · 0 comment · 0 complexity · 37339d40c33ee3800d5b2d3896274421 MD5 · raw file 

    

  1. HID++ 1.0
    2. 

  2. =========
    3. 

  3. 

  4. Short and long reports are use the same way. The long report is used when the data does not fit in the short one. Every HID++ 1.0 report use the same header:
    5. 

  5. 

  6. | Bytes | Type       | Content            | Comment                  |
    7. 

  7. | ----- | ---------- | ------------------ | ------------------------ |
    8. 

  8. | 0     | byte       | HID report ID      | 0x10 for short report, 0x11 for long report |
    9. 

  9. | 1     | byte       | Device index       | -1 (0xff) for Unifying receivers, 0 for wired devices, 1–6 for Unifying devices |
    10. 

  10. | 2     | byte       | Sub ID             |                          |
    11. 

  11. | 3–…   |            |                    | Depends on the *Sub ID*  |
    12. 

  12. 

  13. 

  14. Known Sub IDs are:
    15. 

  15.  - 0x00–0x0F: Device notifications
    16. 

  16.  - 0x40–0x4F: Unifying receiver notifications
    17. 

  17.  - 0x50: Memory writing notifications
    18. 

  18.  - 0x80–0x8F: Register access
    19. 

  19.  - 0x90–0x93: Writing data to memory
    20. 

  20. 

  21. 

  22. Register access
    23. 

  23. ---------------
    24. 

  24. 

  25. A register size may vary, if it is too big to fit in a short report, the long report is used. Every register command is answered with a input report using the same Sub ID or an error message.
    26. 

  26. 

  27. | Sub ID | Description          | Output | Input |
    28. 

  28. | ------ | -------------------- | ------ | ----- |
    29. 

  29. | 0x80   | Write short register | short  | short |
    30. 

  30. | 0x81   | Read short register  | short  | short |
    31. 

  31. | 0x82   | Write long register  | long   | short |
    32. 

  32. | 0x83   | Read short register  | short  | long  |
    33. 

  33. | 0x8F   | Error message        | N/A    | short |
    34. 

  34. 

  35. ### Accessing registers
    36. 

  36. 

  37. The format for report with Sub IDs 0x80 to 0x83 is:
    38. 

  38. 

  39. | Bytes | Type       | Content            | Comment                  |
    40. 

  40. | ----- | ---------- | ------------------ | ------------------------ |
    41. 

  41. | 0     | byte       | HID report ID      | 0x10 for short report, 0x11 for long report |
    42. 

  42. | 1     | byte       | Device index       |                          |
    43. 

  43. | 2     | byte       | Sub ID             | 0x80–0x83                |
    44. 

  44. | 3     | byte       | Register index     | See below                |
    45. 

  45. | 4–…   |            |                    | Register data            |
    46. 

  46. 

  47. #### 0x00–0x0F: General registers
    48. 

  48. 

  49. | Register | Description                                           | R/W | UR    | G5    | G500(s) | G700s |
    50. 

  50. | -------- | ----------------------------------------------------- | --- | ----- | ----- | ------- | ----- |
    51. 

  51. | 0x00     | Enable notifications                                  | R/W | short | short |         | short |
    52. 

  52. | 0x01     | [Individual features](commands/01-features.md)        | R/W |       | short | short   | short |
    53. 

  53. | 0x02     | Connection state                                      | R/W | short |       |         |       |
    54. 

  54. | 0x07     | [Battery status](commands/07-battery-status.md)       | R/? |       |       |         | short |
    55. 

  55. | 0x09     | ? (bit 8: keyboard Fn swap flag)                      | R/W |       |       |         |       |
    56. 

  56. | 0x0D     | [Battery mileage](commands/0d-battery-mileage.md)     | R   |       |       |         |       |
    57. 

  57. | 0x0F     | [Profile related queries](commands/0f-profile.md)     | R/W |       |       | short   | short |
    58. 

  58. 

  59. #### 0x10–0x1F: ?
    60. 

  60. 

  61. | Register | Description                                           | R/W |
    62. 

  62. | -------- | ----------------------------------------------------- | --- |
    63. 

  63. | 0x17     | Keyboard illumination                                 | ?   |
    64. 

  64. 

  65. #### 0x50–0x5F: LED registers
    66. 

  66. 

  67. | Register | Description                                           | R/W | G5    | G500(s) | G700s |
    68. 

  68. | -------- | ----------------------------------------------------- | --- | ----- | ------- | ----- |
    69. 

  69. | 0x51     | [LED status](commands/51-leds.md)                     | R/W | short | short   | short |
    70. 

  70. | 0x54     | [LED intensity](commands/54-led-intensity.md)         | R/W |       |         |       |
    71. 

  71. | 0x57     | LED color                                             | R/W |       | short   |       |
    72. 

  72. 

  73. #### 0x60–0x6F: Mouse sensor registers
    74. 

  74. 

  75. | Register | Description                                           | R/W | G5    | G500(s) | G700s |
    76. 

  76. | -------- | ----------------------------------------------------- | --- | ----- | ------- | ----- |
    77. 

  77. | 0x61     | [Optical sensor settings](commands/61-sensor.md)      | R/W |       | short   | short |
    78. 

  78. | 0x63     | [Current resolution](commands/63-resolution.md)       | R/W | short | long    | long  |
    79. 

  79. | 0x64     | [USB refresh rate](commands/64-usbrate.md)            | R/W | short | short   | short |
    80. 

  80. 

  81. #### 0x70–0x7F: ?
    82. 

  82. 

  83. | Register | Description                                           | R/W | G500(s) |
    84. 

  84. | -------- | ----------------------------------------------------- | --- | ------- |
    85. 

  85. | 0x78     | ?                                                     | R   | short   |
    86. 

  86. 

  87. #### 0xA0–0xAF: Memory registers
    88. 

  88. 

  89. | Register | Description                                           | R/W | G500(s) | G700s |
    90. 

  90. | -------- | ----------------------------------------------------- | --- | ------- | ----- |
    91. 

  91. | 0xA0     | [Internal memory operations](commands/a0-memop.md)    | W   | long    | ?     |
    92. 

  92. | 0xA1     | [Resetting the sequence number](commands/a1-seqnum.md)| W   | short   | ?     |
    93. 

  93. | 0xA2     | [Internal memory reading](commands/a2-memread.md)     | R   | long    | long  |
    94. 

  94. 

  95. #### 0xB0–0xBF: Unifying connections
    96. 

  96. 

  97. | Register | Description                                           | R/W | UR    |
    98. 

  98. | -------- | ----------------------------------------------------- | --- | ----- |
    99. 

  99. | 0xB2     | Device Connection (Pairing)                           | W   | short |
    100. 

  100. | 0xB3     | Device Activity                                       | R   | long  |
    101. 

  101. | 0xB5     | Device Pairing information                            | R/W | long  |
    102. 

  102. 

  103. #### 0xD0–0xDF: ?
    104. 

  104. 

  105. | Register | Description                                           | R/W | G5    | G500(s) | G700s |
    106. 

  106. | -------- | ----------------------------------------------------- | --- | ----- | ------- | ----- |
    107. 

  107. | 0xD0     | ?                                                     | R/W | short | short   | short |
    108. 

  108. | 0xD2     | ? (write unavailable on G5)                           | R   | short | short   |       |
    109. 

  109. | 0xD3     | ? (error: unavailable)                                | R/? |       |         | long  |
    110. 

  110. | 0xD5     | ? (error: unavailable)                                | R/? |       |         | long  |
    111. 

  111. | 0xDA     | ? (error: unavailable)                                | R/W | short | short   |       |
    112. 

  112. | 0xDB     | ? (error: unavailable)                                | R   | long  | long    |       |
    113. 

  113. | 0xDE     | ? (error: unavailable)                                | R/W | short | short   |       |
    114. 

  114. 

  115. #### 0xF0–0xFF: Firmware registers?
    116. 

  116. 

  117. | Register | Description                                           | R/W | G5    | G500(s) | G700s |
    118. 

  118. | -------- | ----------------------------------------------------- | --- | ----- | ------- | ----- |
    119. 

  119. | 0xF0     | ?                                                     | W   | short | short   | ?     |
    120. 

  120. | 0xF1     | [Firmware infos](commands/f1-fwinfos.md)              | R   | short | short   | ?     |
    121. 

  121. 

  122. 

  123. ### Error messages
    124. 

  124. 

  125. | Bytes | Type       | Content            | Comment                  |
    126. 

  126. | ----- | ---------- | ------------------ | ------------------------ |
    127. 

  127. | 0     | byte       | HID report ID      | Short report: 0x10       |
    128. 

  128. | 1     | byte       | Device index       |                          |
    129. 

  129. | 2     | byte       | Sub ID             | 0x8F                     |
    130. 

  130. | 3     | byte       | Original Sub ID    | From the output report generating the error |
    131. 

  131. | 4     | byte       | Register index     | From the output report generating the error |
    132. 

  132. | 5     | byte       | Error code         | See table below          |
    133. 

  133. | 6     |            |                    | *unused*                 |
    134. 

  134. 

  135. Error codes are:
    136. 

  136. 

  137. | Value | Name                    | Description                           |
    138. 

  138. | ----- | ----------------------- | ------------------------------------- |
    139. 

  139. | 0x00  | ERR_SUCCESS             |                                       |
    140. 

  140. | 0x01  | ERR_INVALID_SUBID       | Invalid report type or message length |
    141. 

  141. | 0x02  | ERR_INVALID_ADDRESS     | Invalid query type                    |
    142. 

  142. | 0x03  | ERR_INVALID_VALUE       |                                       |
    143. 

  143. | 0x04  | ERR_CONNECT_FAIL        | Unifying Receiver error               |
    144. 

  144. | 0x05  | ERR_TOO_MANY_DEVICES    | Unifying Receiver error               |
    145. 

  145. | 0x06  | ERR_ALREADY_EXISTS      | Unifying Receiver error               |
    146. 

  146. | 0x07  | ERR_BUSY                | Unifying Receiver error               |
    147. 

  147. | 0x08  | ERR_UNKNOWN_DEVICE      | Unifying Receiver error               |
    148. 

  148. | 0x09  | ERR_RESOURCE_ERROR      | Unifying Receiver error               |
    149. 

  149. | 0x0A  | ERR_REQUEST_UNAVAILABLE |                                       |
    150. 

  150. | 0x0B  | ERR_INVALID_PARAM_VALUE |                                       |
    151. 

  151. | 0x0C  | ERR_WRONG_PIN_CODE      |                                       |
    152. 

  152. 

  153. For invalid parameters some devices use ERR_INVALID_VALUE instead of ERR_INVALID_PARAM_VALUE.
    154. 

  154. 

  155. 

  156. Sending data to the internal memory
    157. 

  157. -----------------------------------
    158. 

  158. 

  159. Data is sent in blocks to the internal memory. Values are replaced in the temporary memory (page 0) but is AND’ed in the permanent memory.
    160. 

  160. 

  161. Each block is transmitted in several messages, the first message contains a 9-byte-long header describing the block being sent. All reports are long, thus each report contains 16 bytes of data, except the first which contains only 7 bytes because of the header.
    162. 

  162. 

  163. The structure of each message is:
    164. 

  164. 

  165. | Bytes | Type       | Content            | Comment                  |
    166. 

  166. | ----- | ---------- | ------------------ | ------------------------ |
    167. 

  167. | 0     | byte       | Report ID          | Long report: 0x11        |
    168. 

  168. | 1     | byte       | Device index       |                          |
    169. 

  169. | 2     | byte       | Sub ID             | 0x90–0x93                |
    170. 

  170. | 3     | byte       | Sequence number    |                          |
    171. 

  171. | 4–19  | byte array | 16 bytes of data   | Payload or header with smaller payload |
    172. 

  172. 

  173. ### Sub IDs
    174. 

  174. 

  175. Sub IDs identify if the report is the first for a block or if acknowledgment message (input report with Sub ID = 0x50) are needed.
    176. 

  176. 

  177. |                         | Begin sending | Continue sending |
    178. 

  178. | ----------------------- | ------------- | ---------------- |
    179. 

  179. | Without acknowledgement | 0x90          | 0x91             |
    180. 

  180. | With acknowledgement    | 0x92          | 0x93             |
    181. 

  181. 

  182. 

  183. ### Sequence number
    184. 

  184. 

  185. Each message contains a sequence number that must be incremented each time. The next sequence number to send can be reset by writing [register 0xA1](commands/a1-seqnum.md).
    186. 

  186. 

  187. When using acknowledgement message, the sequence number is repeated in the input report.
    188. 

  188. 

  189. ### Acknowledgement messages
    190. 

  190. 

  191. The structure of the acknowledgement messages is:
    192. 

  192. 

  193. | Bytes | Type       | Content                | Comment                  |
    194. 

  194. | ----- | ---------- | ---------------------- | ------------------------ |
    195. 

  195. | 0     | byte       | Report ID              | Short report: 0x10       |
    196. 

  196. | 1     | byte       | Device index           |                          |
    197. 

  197. | 2     | byte       | Sub ID                 | 0x50                     |
    198. 

  198. | 3     | byte       | Acknowledgement status | 0x01 if there is no error, otherwise an error code |
    199. 

  199. | 4     | byte       | Sequence number        | if there was no error    |
    200. 

  200. | 5–6   |            |                        | *unused*                 |
    201. 

  201. 

  202. 

  203. ### Header
    204. 

  204. 

  205. The structure of the header sent in the first message is:
    206. 

  206. 

  207. | Bytes | Type       | Content            | Comment                  |
    208. 

  208. | ----- | ---------- | ------------------ | ------------------------ |
    209. 

  209. | 0     | byte       | ?                  | 0x01                     |
    210. 

  210. | 1     | byte       | destination page   |                          |
    211. 

  211. | 2     | byte       | destination offset |                          |
    212. 

  212. | 3–4   | byte       | ?                  |                          |
    213. 

  213. | 5–6   | int16 be   | block length       |                          |
    214. 

  214. | 7–8   | byte       | ?                  |                          |
    215.