gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2025-03-01 02:33:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix xap docs gen + clarify some broadcast messages

Browse Source
This commit is contained in:
zvecr 2023-08-29 02:37:23 +01:00
parent 87fd4b42f5
commit 980699f3cf
12 changed files with 78 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
data/templates/xap/docs/broadcast_messages.md.j2
View File

@ -1,4 +1,4 @@
{%- for id, message in xap.broadcast_messages.messages | dictsort %}
{% for id, message in xap.broadcast_messages.messages | dictsort %}
### {{ message.name }} - `{{ id }}`
{{ message.description }}
{%- endfor %}
{% endfor %}

8
data/templates/xap/docs/docs.md.j2
View File

@ -1,9 +1,11 @@
{{ constants.GPL2_HEADER_XML_LIKE }}
{{ constants.GENERATED_HEADER_XML_LIKE }}
{%- for item in xap.documentation.order -%}
{%- if not item[0:1] == '!' -%}
{%- for item in xap.documentation.order %}
{% if not item[0:1] == '!' %}
{{ xap.documentation.get(item) }}
{% else %}
{%- include item[1:] %}
{% include item[1:] %}
{% endif %}
{% endfor %}

9
data/templates/xap/docs/response_flags.md.j2
View File

@ -1,9 +1,12 @@
|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} Bit {{ bitnum }} |{% endfor %}
|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} -- |{% endfor %}
|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} `{{ bitinfo.define }}` |{%- endfor %}
|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} `{{ bitinfo.define }}` |{% endfor %}
{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %}
{%- if bitinfo.define != "-" -%}
{% if bitinfo.define != "-" -%}
* Bit {{ bitnum }} (`{{ bitinfo.define }}`): {{ bitinfo.description }}
{% endif %}
{%- endfor %}
{% endfor %}

27
data/templates/xap/docs/routes.md.j2
View File

@ -17,20 +17,20 @@ __{{ name }}:__ `{{ type }}`
{% if 'secure' == route.permissions %}__Secure__{% endif %}
{%- endmacro -%}
{%- for id, route in xap.routes | dictsort %}
{% for id, route in xap.routes | dictsort %}
### {{ route.name }} - `{{ id }}`
{{ route.description }}
{% if route.routes %}
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
{%- for subid, subroute in route.routes | dictsort %}
{%- if not subroute.routes %}
{% for subid, subroute in route.routes | dictsort %}
{% if not subroute.routes %}
| {{ subroute.name }} | `{{ id }} {{ subid }}` | {{ gen_tags(subroute) }} | {{ gen_payloads(subroute) }} | {{ subroute.description | newline_to_br }}|
{%- endif %}
{%- endfor %}
{% endif %}
{% endfor %}
{%- for subid, subroute in route.routes | dictsort %}
{% for subid, subroute in route.routes | dictsort %}
{%- if subroute.routes %}
#### {{ subroute.name }} - `{{ id }} {{ subid }}`
@ -38,12 +38,13 @@ __{{ name }}:__ `{{ type }}`
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
{%- for subsubid, subsubroute in subroute.routes | dictsort %}
{%- if not subsubroute.routes %}
{% for subsubid, subsubroute in subroute.routes | dictsort %}
{% if not subsubroute.routes %}
| {{ subsubroute.name }} | `{{ id }} {{ subid }} {{ subsubid }}` | {{ gen_tags(subsubroute) }} | {{ gen_payloads(subsubroute) }} | {{ subsubroute.description | newline_to_br }}|
{%- endif %}
{%- endfor %}
{%- endif %}
{%- endfor %}
{% endif %}
{%- endfor %}
{% endfor %}
{% endif %}
{% endfor %}
{% endif %}
{% endfor %}

8
data/templates/xap/docs/term_definitions.md.j2
View File

@ -1,8 +1,8 @@
| Name | Definition |
| -- | -- |
{%- for type, definition in xap.term_definitions | dictsort %}
{% for type, definition in xap.term_definitions | dictsort %}
| _{{ type }}_ | {{ definition }} |
{%- endfor %}
{%- for type, definition in xap.type_definitions | dictsort %}
{% endfor %}
{% for type, definition in xap.type_definitions | dictsort %}
| _{{ definition.name }}_ | {{ definition.description }}{% if 'struct' == definition.type %} Takes the format:{% for item in definition.struct_members %}<br>`{{ item.type }}` - {{ item.name }}{%- endfor %}{% endif %} |
{%- endfor %}
{% endfor %}

4
data/templates/xap/docs/type_docs.md.j2
View File

@ -1,5 +1,5 @@
| Name | Definition |
| -- | -- |
{%- for type, definition in xap.type_docs | dictsort %}
{% for type, definition in xap.type_docs | dictsort %}
| _{{ type }}_ | {{ definition }} |
{%- endfor %}
{% endfor %}

12
data/xap/xap_0.1.0.hjson
View File

@ -20,7 +20,7 @@
'''
## Broadcast messages
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, with corresponding _payload_.
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, then the response _payload_ length, and finally the corresponding _payload_.
'''
}
@ -100,7 +100,7 @@
'''
Replicates and replaces the same functionality as if using the standard QMK `CONSOLE_ENABLE = yes` in `rules.mk`. Normal prints within the firmware will manifest as log messages broadcast to the host. `hid_listen` will not be functional with XAP enabled.
Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
Log message payloads include `u8[Length]` containing the text, where the length of the text is the _broadcast_header.length_ field.
**Example Log Broadcast** -- log message "Hello QMK!"
@ -119,10 +119,10 @@
**Example Secure Status Broadcast** -- secure "Unlocking"
| Byte | 0 | 1 | 2 | 3 |
| --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` |
| Byte | 0 | 1 | 2 | 3 | 4 |
| --- | --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Length | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` | `0x01` |
'''
return_type: u8
}

5
docs/xap_0.0.1.md
View File

@ -1,4 +1,4 @@
<!--- Copyright 2022 QMK --->
<!--- Copyright 2023 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
@ -77,7 +77,6 @@ Response messages will always be prefixed by the originating request _token_, di
* Bit 0 (`SUCCESS`): When this bit is set, the request was successfully handled. If not set, all payload data should be disregarded, and the request retried if appropriate (with a new token).
### Example "conversation":
**Request** -- version query:
@ -99,11 +98,9 @@ Response messages will always be prefixed by the originating request _token_, di
Subsystem validity should be queried through the “Enabled-in-firmware subsystem query” under the QMK subsystem (route=0x00,0x01).
This is the primary method for determining if a subsystem has been enabled in the running firmware.
### XAP - `0x00`
This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Version Query | `0x00 0x00` | | __Response:__ `u32` | XAP protocol version query.<br><br>* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`<br> * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|

22
docs/xap_0.1.0.md
View File

@ -1,4 +1,4 @@
<!--- Copyright 2022 QMK --->
<!--- Copyright 2023 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
@ -34,6 +34,7 @@ This document describes the requirements of the QMK XAP ("extensible application
| Name | Definition |
| -- | -- |
| _bool_ | Data type that contains values 0 and 1. Implemented as an alias of `u8`. |
| _struct{}_ | A structure of data, packing different objects together. Data is "compacted" -- there are no padding bytes between fields. Equivalent to a packed C-style `struct`. The order in which they're defined matches the order of the data in the response packet. |
| _type[n]_ | An array of `type`, with array extent of `N` -- e.g. `u8[2]` signifies two consecutive octets. |
| _u16_ | An unsigned 16-bit integral, commonly seen as `uint16_t` from _stdint.h_. |
@ -88,7 +89,6 @@ Response messages will always be prefixed by the originating request _token_, di
* Bit 1 (`SECURE_FAILURE`): When this bit is set, the requested _route_ was marked _secure_ but an _unlock sequence_ has not completed.
* Bit 0 (`SUCCESS`): When this bit is set, the request was successfully handled. If not set, all payload data should be disregarded, and the request retried if appropriate (with a new token).
### Example "conversation":
**Request** -- version query:
@ -110,11 +110,9 @@ Response messages will always be prefixed by the originating request _token_, di
Subsystem validity should be queried through the “Enabled-in-firmware subsystem query” under the QMK subsystem (route=0x00,0x01).
This is the primary method for determining if a subsystem has been enabled in the running firmware.
### XAP - `0x00`
This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Version Query | `0x00 0x00` | | __Response:__ `u32` | XAP protocol version query.<br><br>* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`<br> * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|
@ -127,7 +125,6 @@ This subsystem is always present, and provides the ability to query information
### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Version Query | `0x01 0x00` | | __Response:__ `u32` | QMK protocol version query.<br><br>* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`<br> * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|
@ -144,21 +141,18 @@ This subsystem is always present, and provides the ability to address QMK-specif
### Keyboard - `0x02`
This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.
### User - `0x03`
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
## Broadcast messages
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, with corresponding _payload_.
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, then the response _payload_ length, and finally the corresponding _payload_.
### Log message - `0x00`
Replicates and replaces the same functionality as if using the standard QMK `CONSOLE_ENABLE = yes` in `rules.mk`. Normal prints within the firmware will manifest as log messages broadcast to the host. `hid_listen` will not be functional with XAP enabled.
Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
Log message payloads include `u8[Length]` containing the text, where the length of the text is the _broadcast_header.length_ field.
**Example Log Broadcast** -- log message "Hello QMK!"
@ -171,10 +165,10 @@ Secure status has changed. Payloads include a `u8` matching a 'Secure Status' re
**Example Secure Status Broadcast** -- secure "Unlocking"
| Byte | 0 | 1 | 2 | 3 |
| --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` |
| Byte | 0 | 1 | 2 | 3 | 4 |
| --- | --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Length | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` | `0x01` |
### Keyboard - `0x02`
Reserved for vendor-specific functionality. No messages are defined by XAP.
### User - `0x03`

25
docs/xap_0.2.0.md
View File

@ -1,4 +1,4 @@
<!--- Copyright 2022 QMK --->
<!--- Copyright 2023 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
@ -34,6 +34,7 @@ This document describes the requirements of the QMK XAP ("extensible application
| Name | Definition |
| -- | -- |
| _bool_ | Data type that contains values 0 and 1. Implemented as an alias of `u8`. |
| _struct{}_ | A structure of data, packing different objects together. Data is "compacted" -- there are no padding bytes between fields. Equivalent to a packed C-style `struct`. The order in which they're defined matches the order of the data in the response packet. |
| _type[n]_ | An array of `type`, with array extent of `N` -- e.g. `u8[2]` signifies two consecutive octets. |
| _u16_ | An unsigned 16-bit integral, commonly seen as `uint16_t` from _stdint.h_. |
@ -88,7 +89,6 @@ Response messages will always be prefixed by the originating request _token_, di
* Bit 1 (`SECURE_FAILURE`): When this bit is set, the requested _route_ was marked _secure_ but an _unlock sequence_ has not completed.
* Bit 0 (`SUCCESS`): When this bit is set, the request was successfully handled. If not set, all payload data should be disregarded, and the request retried if appropriate (with a new token).
### Example "conversation":
**Request** -- version query:
@ -110,11 +110,9 @@ Response messages will always be prefixed by the originating request _token_, di
Subsystem validity should be queried through the “Enabled-in-firmware subsystem query” under the QMK subsystem (route=0x00,0x01).
This is the primary method for determining if a subsystem has been enabled in the running firmware.
### XAP - `0x00`
This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Version Query | `0x00 0x00` | | __Response:__ `u32` | XAP protocol version query.<br><br>* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`<br> * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|
@ -127,7 +125,6 @@ This subsystem is always present, and provides the ability to query information
### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Version Query | `0x01 0x00` | | __Response:__ `u32` | QMK protocol version query.<br><br>* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`<br> * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|
@ -144,15 +141,12 @@ This subsystem is always present, and provides the ability to address QMK-specif
### Keyboard - `0x02`
This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.
### User - `0x03`
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
### Keymap - `0x04`
This subsystem allows for query of currently configured keycodes.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Capabilities Query | `0x04 0x01` | | __Response:__ `u32` | Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
@ -163,7 +157,6 @@ This subsystem allows for query of currently configured keycodes.
### Remapping - `0x05`
This subsystem allows for live reassignment of keycodes without rebuilding the firmware.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Capabilities Query | `0x05 0x01` | | __Response:__ `u32` | Remapping subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
@ -174,7 +167,6 @@ This subsystem allows for live reassignment of keycodes without rebuilding the f
### Lighting - `0x06`
This subsystem allows for control over the lighting subsystem.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Capabilities Query | `0x06 0x01` | | __Response:__ `u32` | Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
@ -182,13 +174,12 @@ This subsystem allows for control over the lighting subsystem.
## Broadcast messages
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, with corresponding _payload_.
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, then the response _payload_ length, and finally the corresponding _payload_.
### Log message - `0x00`
Replicates and replaces the same functionality as if using the standard QMK `CONSOLE_ENABLE = yes` in `rules.mk`. Normal prints within the firmware will manifest as log messages broadcast to the host. `hid_listen` will not be functional with XAP enabled.
Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
Log message payloads include `u8[Length]` containing the text, where the length of the text is the _broadcast_header.length_ field.
**Example Log Broadcast** -- log message "Hello QMK!"
@ -201,10 +192,10 @@ Secure status has changed. Payloads include a `u8` matching a 'Secure Status' re
**Example Secure Status Broadcast** -- secure "Unlocking"
| Byte | 0 | 1 | 2 | 3 |
| --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` |
| Byte | 0 | 1 | 2 | 3 | 4 |
| --- | --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Length | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` | `0x01` |
### Keyboard - `0x02`
Reserved for vendor-specific functionality. No messages are defined by XAP.
### User - `0x03`

38
docs/xap_0.3.0.md
View File

@ -1,4 +1,4 @@
<!--- Copyright 2022 QMK --->
<!--- Copyright 2023 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
@ -34,6 +34,7 @@ This document describes the requirements of the QMK XAP ("extensible application
| Name | Definition |
| -- | -- |
| _bool_ | Data type that contains values 0 and 1. Implemented as an alias of `u8`. |
| _struct{}_ | A structure of data, packing different objects together. Data is "compacted" -- there are no padding bytes between fields. Equivalent to a packed C-style `struct`. The order in which they're defined matches the order of the data in the response packet. |
| _type[n]_ | An array of `type`, with array extent of `N` -- e.g. `u8[2]` signifies two consecutive octets. |
| _u16_ | An unsigned 16-bit integral, commonly seen as `uint16_t` from _stdint.h_. |
@ -88,7 +89,6 @@ Response messages will always be prefixed by the originating request _token_, di
* Bit 1 (`SECURE_FAILURE`): When this bit is set, the requested _route_ was marked _secure_ but an _unlock sequence_ has not completed.
* Bit 0 (`SUCCESS`): When this bit is set, the request was successfully handled. If not set, all payload data should be disregarded, and the request retried if appropriate (with a new token).
### Example "conversation":
**Request** -- version query:
@ -110,11 +110,9 @@ Response messages will always be prefixed by the originating request _token_, di
Subsystem validity should be queried through the “Enabled-in-firmware subsystem query” under the QMK subsystem (route=0x00,0x01).
This is the primary method for determining if a subsystem has been enabled in the running firmware.
### XAP - `0x00`
This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Version Query | `0x00 0x00` | | __Response:__ `u32` | XAP protocol version query.<br><br>* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`<br> * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|
@ -127,7 +125,6 @@ This subsystem is always present, and provides the ability to query information
### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Version Query | `0x01 0x00` | | __Response:__ `u32` | QMK protocol version query.<br><br>* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`<br> * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|
@ -144,15 +141,12 @@ This subsystem is always present, and provides the ability to address QMK-specif
### Keyboard - `0x02`
This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.
### User - `0x03`
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
### Keymap - `0x04`
This subsystem allows for query of currently configured keycodes.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Capabilities Query | `0x04 0x01` | | __Response:__ `u32` | Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
@ -163,7 +157,6 @@ This subsystem allows for query of currently configured keycodes.
### Remapping - `0x05`
This subsystem allows for live reassignment of keycodes without rebuilding the firmware.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Capabilities Query | `0x05 0x01` | | __Response:__ `u32` | Remapping subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
@ -174,11 +167,11 @@ This subsystem allows for live reassignment of keycodes without rebuilding the f
### Lighting - `0x06`
This subsystem allows for control over the lighting subsystem.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Capabilities Query | `0x06 0x01` | | __Response:__ `u32` | Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
#### backlight - `0x06 0x02`
This subsystem allows for control over the backlight subsystem.
@ -190,6 +183,7 @@ This subsystem allows for control over the backlight subsystem.
| Set Config | `0x06 0x02 0x04` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* enable: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* mode: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* val: `u8` | Set the current config.|
| Save Config | `0x06 0x02 0x05` | | | Save the current config.|
#### rgblight - `0x06 0x03`
This subsystem allows for control over the rgblight subsystem.
@ -201,6 +195,7 @@ This subsystem allows for control over the rgblight subsystem.
| Set Config | `0x06 0x03 0x04` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* enable: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* mode: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* hue: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* sat: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* val: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* speed: `u8` | Set the current config.|
| Save Config | `0x06 0x03 0x05` | | | Save the current config.|
#### rgbmatrix - `0x06 0x04`
This subsystem allows for control over the rgb matrix subsystem.
@ -212,16 +207,25 @@ This subsystem allows for control over the rgb matrix subsystem.
| Set Config | `0x06 0x04 0x04` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* enable: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* mode: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* hue: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* sat: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* val: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* speed: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* flags: `u8` | Set the current config.|
| Save Config | `0x06 0x04 0x05` | | | Save the current config.|
### Audio - `0x07`
This subsystem allows for control over the audio subsystem.
| Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- |
| Capabilities Query | `0x07 0x01` | | __Response:__ `u32` | Audio subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Config | `0x07 0x03` | | __Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* enable: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* clicky_enable: `u8` | Query the current config.|
| Set Config | `0x07 0x04` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* enable: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* clicky_enable: `u8` | Set the current config.|
| Save Config | `0x07 0x05` | | | Save the current config.|
## Broadcast messages
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, with corresponding _payload_.
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, then the response _payload_ length, and finally the corresponding _payload_.
### Log message - `0x00`
Replicates and replaces the same functionality as if using the standard QMK `CONSOLE_ENABLE = yes` in `rules.mk`. Normal prints within the firmware will manifest as log messages broadcast to the host. `hid_listen` will not be functional with XAP enabled.
Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
Log message payloads include `u8[Length]` containing the text, where the length of the text is the _broadcast_header.length_ field.
**Example Log Broadcast** -- log message "Hello QMK!"
@ -234,10 +238,10 @@ Secure status has changed. Payloads include a `u8` matching a 'Secure Status' re
**Example Secure Status Broadcast** -- secure "Unlocking"
| Byte | 0 | 1 | 2 | 3 |
| --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` |
| Byte | 0 | 1 | 2 | 3 | 4 |
| --- | --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Length | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` | `0x01` |
### Keyboard - `0x02`
Reserved for vendor-specific functionality. No messages are defined by XAP.
### User - `0x03`

2
docs/xap_protocol.md
View File

@ -1,4 +1,4 @@
<!--- Copyright 2022 QMK --->
<!--- Copyright 2023 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---