gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2025-04-22 23:21:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Align client/docs gen with recent changes

Browse Source
This commit is contained in:
zvecr 2022-10-16 20:24:37 +01:00
parent e8f40517a8
commit 9fcab705a9
22 changed files with 309 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
data/templates/xap/client/python/constants.py.j2
View File

@ -1,14 +1,17 @@
{{ constants.GPL2_HEADER_SH_LIKE }}
{{ constants.GENERATED_HEADER_SH_LIKE }}
from enum import IntEnum from enum import IntEnum
# version: 0.0.1 # version: 0.0.1
class RgblightModes(IntEnum): class RgblightModes(IntEnum):
{%- for id, effect in constants.rgblight.effects | dictsort %} {%- for id, effect in specs.rgblight.effects | dictsort %}
{{ effect.key }} = {{ id }} {{ effect.key }} = {{ id }}
{%- endfor %} {%- endfor %}
# version: 0.0.1
class RgbMatrixModes(IntEnum): class RgbMatrixModes(IntEnum):
{%- for id, effect in constants.rgb_matrix.effects | dictsort %} {%- for id, effect in specs.rgb_matrix.effects | dictsort %}
{{ effect.key }} = {{ id }} {{ effect.key }} = {{ id }}
{%- endfor %} {%- endfor %}

3
data/templates/xap/client/python/routes.py.j2
View File

@ -1,4 +1,5 @@
{{ constants.GPL2_HEADER_SH_LIKE }}
{{ constants.GENERATED_HEADER_SH_LIKE }}
class XAPRouteError(Exception): class XAPRouteError(Exception):
pass pass

2
data/templates/xap/client/python/types.py.j2
View File

@ -1,3 +1,5 @@
{{ constants.GPL2_HEADER_SH_LIKE }}
{{ constants.GENERATED_HEADER_SH_LIKE }}
from collections import namedtuple from collections import namedtuple
from enum import IntFlag, IntEnum from enum import IntFlag, IntEnum
from struct import Struct from struct import Struct

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

@ -1,3 +1,5 @@
{{ constants.GPL2_HEADER_XML_LIKE }}
{{ constants.GENERATED_HEADER_XML_LIKE }}
{%- for item in xap.documentation.order -%} {%- for item in xap.documentation.order -%}
{%- if not item[0:1] == '!' -%} {%- if not item[0:1] == '!' -%}
{{ xap.documentation.get(item) }} {{ xap.documentation.get(item) }}

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

@ -1,8 +0,0 @@
{%- if route.request_type == 'struct' -%}
__Request:__
{%- for member in route.request_struct_members -%}
<br>{{ "&nbsp;"|safe*4 }}* {{ member.name }}: `{{ member.type }}`
{%- endfor -%}
{%- elif route.request_type -%}
__Request:__ `{{ route.request_type }}`
{%- endif -%}

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

@ -1,8 +0,0 @@
{%- if route.return_type == 'struct' -%}
__Response:__
{%- for member in route.return_struct_members -%}
<br>{{ "&nbsp;"|safe*4 }}* {{ member.name }}: `{{ member.type }}`
{%- endfor -%}
{%- elif route.return_type -%}
__Response:__ `{{ route.return_type }}`
{%- endif -%}

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

@ -1,3 +1,22 @@
{%- macro gen_payload(name, type, members) -%}
{%- if type == 'struct' -%}
__{{ name }}:__
{%- for member in members -%}
<br>{{ "&nbsp;"|safe*4 }}* {{ member.name }}: `{{ member.type }}`
{%- endfor -%}
{%- elif type -%}
__{{ name }}:__ `{{ type }}`
{%- endif -%}
{%- endmacro -%}
{%- macro gen_payloads(route) -%}
{{ gen_payload('Request', route.request_type, route.request_struct_members) }}{%- if route.return_type and route.request_type -%}<br><br>{% endif %}{{ gen_payload('Response', route.return_type, route.return_struct_members) }}
{%- endmacro -%}
{%- macro gen_tags(route) -%}
{% 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.name }} - `{{ id }}`
{{ route.description }} {{ route.description }}
@ -7,9 +26,7 @@
| -- | -- | -- | -- | -- | | -- | -- | -- | -- | -- |
{%- for subid, subroute in route.routes | dictsort %} {%- for subid, subroute in route.routes | dictsort %}
{%- if not subroute.routes %} {%- if not subroute.routes %}
{%- with route=subroute %} | {{ subroute.name }} | `{{ id }} {{ subid }}` | {{ gen_tags(subroute) }} | {{ gen_payloads(subroute) }} | {{ subroute.description | newline_to_br }}|
| {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure__{% endif %} | {%- include 'route_request.md.j2' -%}{%- if subroute.return_type and subroute.request_type -%}<br><br>{% endif %}{%- include 'route_response.md.j2' -%} | {{ subroute.description.replace('\n', '<br>') }}|
{%- endwith %}
{%- endif %} {%- endif %}
{%- endfor %} {%- endfor %}
@ -23,9 +40,7 @@
| -- | -- | -- | -- | -- | | -- | -- | -- | -- | -- |
{%- for subsubid, subsubroute in subroute.routes | dictsort %} {%- for subsubid, subsubroute in subroute.routes | dictsort %}
{%- if not subsubroute.routes %} {%- if not subsubroute.routes %}
{%- with route=subsubroute %} | {{ subsubroute.name }} | `{{ id }} {{ subid }} {{ subsubid }}` | {{ gen_tags(subsubroute) }} | {{ gen_payloads(subsubroute) }} | {{ subsubroute.description | newline_to_br }}|
| {{ subsubroute.name }} | `{{ id }} {{ subid }} {{ subsubid }}` | {% if 'secure' == subsubroute.permissions %}__Secure__{% endif %} | {%- include 'route_request.md.j2' -%}{%- if subsubroute.return_type and subsubroute.request_type -%}<br><br>{% endif %}{%- include 'route_response.md.j2' -%} | {{ subsubroute.description.replace('\n', '<br>') }}|
{%- endwith %}
{%- endif %} {%- endif %}
{%- endfor %} {%- endfor %}
{%- endif %} {%- endif %}

6
data/templates/xap/docs/versions.md.j2 Normal file
View File

@ -0,0 +1,6 @@
{{ constants.GPL2_HEADER_XML_LIKE }}
{{ constants.GENERATED_HEADER_XML_LIKE }}
{%- for ver in versions | reverse -%}
* [XAP Version {{ ver }}](xap_{{ ver }}.md)
{% endfor %}

4
data/templates/xap/firmware/xap_generated.h.j2
View File

@ -1,5 +1,5 @@
{{ GPL2_HEADER_C_LIKE }} {{ constants.GPL2_HEADER_C_LIKE }}
{{ GENERATED_HEADER_C_LIKE }} {{ constants.GENERATED_HEADER_C_LIKE }}
#pragma once #pragma once
#include <stdint.h> #include <stdint.h>

4
data/templates/xap/firmware/xap_generated.inl.j2
View File

@ -1,5 +1,5 @@
{{ GPL2_HEADER_C_LIKE }} {{ constants.GPL2_HEADER_C_LIKE }}
{{ GENERATED_HEADER_C_LIKE }} {{ constants.GENERATED_HEADER_C_LIKE }}
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// Full XAP {{ xap.version }} definitions // Full XAP {{ xap.version }} definitions

28
docs/xap_0.0.1.md
View File

@ -1,3 +1,29 @@
<!--- Copyright 2022 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
*******************************************************************************
88888888888 888 d8b .d888 d8b 888 d8b
888 888 Y8P d88P" Y8P 888 Y8P
888 888 888 888
888 88888b. 888 .d8888b 888888 888 888 .d88b. 888 .d8888b
888 888 "88b 888 88K 888 888 888 d8P Y8b 888 88K
888 888 888 888 "Y8888b. 888 888 888 88888888 888 "Y8888b.
888 888 888 888 X88 888 888 888 Y8b. 888 X88
888 888 888 888 88888P' 888 888 888 "Y8888 888 88888P'
888 888
888 888
888 888
.d88b. .d88b. 88888b. .d88b. 888d888 8888b. 888888 .d88b. .d88888
d88P"88b d8P Y8b 888 "88b d8P Y8b 888P" "88b 888 d8P Y8b d88" 888
888 888 88888888 888 888 88888888 888 .d888888 888 88888888 888 888
Y88b 888 Y8b. 888 888 Y8b. 888 888 888 Y88b. Y8b. Y88b 888
"Y88888 "Y8888 888 888 "Y8888 888 "Y888888 "Y888 "Y8888 "Y88888
888
Y8b d88P
"Y88P"
*******************************************************************************
--->
# QMK Firmware XAP Specs # QMK Firmware XAP Specs
This document describes the requirements of the QMK XAP ("extensible application protocol") API. This document describes the requirements of the QMK XAP ("extensible application protocol") API.
@ -80,6 +106,6 @@ This subsystem is always present, and provides the ability to query information
| Name | Route | Tags | Payloads | Description | | 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}.| | 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}.|

58
docs/xap_0.1.0.md
View File

@ -1,3 +1,29 @@
<!--- Copyright 2022 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
*******************************************************************************
88888888888 888 d8b .d888 d8b 888 d8b
888 888 Y8P d88P" Y8P 888 Y8P
888 888 888 888
888 88888b. 888 .d8888b 888888 888 888 .d88b. 888 .d8888b
888 888 "88b 888 88K 888 888 888 d8P Y8b 888 88K
888 888 888 888 "Y8888b. 888 888 888 88888888 888 "Y8888b.
888 888 888 888 X88 888 888 888 Y8b. 888 X88
888 888 888 888 88888P' 888 888 888 "Y8888 888 88888P'
888 888
888 888
888 888
.d88b. .d88b. 88888b. .d88b. 888d888 8888b. 888888 .d88b. .d88888
d88P"88b d8P Y8b 888 "88b d8P Y8b 888P" "88b 888 d8P Y8b d88" 888
888 888 88888888 888 888 88888888 888 .d888888 888 88888888 888 888
Y88b 888 Y8b. 888 888 Y8b. 888 888 888 Y88b. Y8b. Y88b 888
"Y88888 "Y8888 888 888 "Y8888 888 "Y888888 "Y888 "Y8888 "Y88888
888
Y8b d88P
"Y88P"
*******************************************************************************
--->
# QMK Firmware XAP Specs # QMK Firmware XAP Specs
This document describes the requirements of the QMK XAP ("extensible application protocol") API. This document describes the requirements of the QMK XAP ("extensible application protocol") API.
@ -91,12 +117,12 @@ This subsystem is always present, and provides the ability to query information
| Name | Route | Tags | Payloads | Description | | 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}.| | 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}.|
| Capabilities Query | `0x00 0x01` | |__Response:__ `u32`| XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x00 0x01` | | __Response:__ `u32` | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Enabled subsystem query | `0x00 0x02` | |__Response:__ `u32`| XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.| | Enabled subsystem query | `0x00 0x02` | | __Response:__ `u32` | XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.|
| Secure Status | `0x00 0x03` | |__Response:__ `u8`| Query secure route status<br><br>* 0 means secure routes are disabled<br>* 1 means unlock sequence initiated but incomplete<br>* 2 means secure routes are allowed<br>* any other value should be interpreted as disabled| | Secure Status | `0x00 0x03` | | __Response:__ `u8` | Query secure route status<br><br>* 0 means secure routes are disabled<br>* 1 means unlock sequence initiated but incomplete<br>* 2 means secure routes are allowed<br>* any other value should be interpreted as disabled|
| Secure Unlock | `0x00 0x04` | || Initiate secure route unlock sequence| | Secure Unlock | `0x00 0x04` | | | Initiate secure route unlock sequence|
| Secure Lock | `0x00 0x05` | || Disable secure routes| | Secure Lock | `0x00 0x05` | | | Disable secure routes|
### QMK - `0x01` ### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality. This subsystem is always present, and provides the ability to address QMK-specific functionality.
@ -104,16 +130,16 @@ This subsystem is always present, and provides the ability to address QMK-specif
| Name | Route | Tags | Payloads | Description | | 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}.| | 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}.|
| Capabilities Query | `0x01 0x01` | |__Response:__ `u32`| QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x01 0x01` | | __Response:__ `u32` | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Board identifiers | `0x01 0x02` | |__Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Vendor ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product Version: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* QMK Unique Identifier: `u32`| Retrieves the set of identifying information for the board.| | Board identifiers | `0x01 0x02` | | __Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Vendor ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product Version: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* QMK Unique Identifier: `u32` | Retrieves the set of identifying information for the board.|
| Board Manufacturer | `0x01 0x03` | |__Response:__ `string`| Retrieves the name of the manufacturer| | Board Manufacturer | `0x01 0x03` | | __Response:__ `string` | Retrieves the name of the manufacturer|
| Product Name | `0x01 0x04` | |__Response:__ `string`| Retrieves the product name| | Product Name | `0x01 0x04` | | __Response:__ `string` | Retrieves the product name|
| Config Blob Length | `0x01 0x05` | |__Response:__ `u16`| Retrieves the length of the configuration data bundled within the firmware| | Config Blob Length | `0x01 0x05` | | __Response:__ `u16` | Retrieves the length of the configuration data bundled within the firmware|
| Config Blob Chunk | `0x01 0x06` | |__Request:__ `u16`<br><br>__Response:__ `u8[32]`| Retrieves a chunk of the configuration data bundled within the firmware| | Config Blob Chunk | `0x01 0x06` | | __Request:__ `u16`<br><br>__Response:__ `u8[32]` | Retrieves a chunk of the configuration data bundled within the firmware|
| Jump to bootloader | `0x01 0x07` | __Secure__ |__Response:__ `u8`| Jump to bootloader<br><br>May not be present - if QMK capabilities query returns “true”, then jump to bootloader is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will jump to bootloader| | Jump to bootloader | `0x01 0x07` | __Secure__ | __Response:__ `u8` | Jump to bootloader<br><br>May not be present - if QMK capabilities query returns “true”, then jump to bootloader is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will jump to bootloader|
| Hardware Identifier | `0x01 0x08` | |__Response:__ `u32[4]`| Retrieves a unique identifier for the board.| | Hardware Identifier | `0x01 0x08` | | __Response:__ `u32[4]` | Retrieves a unique identifier for the board.|
| Reinitialize EEPROM | `0x01 0x09` | __Secure__ |__Response:__ `u8`| Reinitializes the keyboard's EEPROM (persistent memory)<br><br>May not be present - if QMK capabilities query returns “true”, then reinitialize is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will reinitialize and then reboot| | Reinitialize EEPROM | `0x01 0x09` | __Secure__ | __Response:__ `u8` | Reinitializes the keyboard's EEPROM (persistent memory)<br><br>May not be present - if QMK capabilities query returns “true”, then reinitialize is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will reinitialize and then reboot|
### Keyboard - `0x02` ### Keyboard - `0x02`
This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP. This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.

76
docs/xap_0.2.0.md
View File

@ -1,3 +1,29 @@
<!--- Copyright 2022 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
*******************************************************************************
88888888888 888 d8b .d888 d8b 888 d8b
888 888 Y8P d88P" Y8P 888 Y8P
888 888 888 888
888 88888b. 888 .d8888b 888888 888 888 .d88b. 888 .d8888b
888 888 "88b 888 88K 888 888 888 d8P Y8b 888 88K
888 888 888 888 "Y8888b. 888 888 888 88888888 888 "Y8888b.
888 888 888 888 X88 888 888 888 Y8b. 888 X88
888 888 888 888 88888P' 888 888 888 "Y8888 888 88888P'
888 888
888 888
888 888
.d88b. .d88b. 88888b. .d88b. 888d888 8888b. 888888 .d88b. .d88888
d88P"88b d8P Y8b 888 "88b d8P Y8b 888P" "88b 888 d8P Y8b d88" 888
888 888 88888888 888 888 88888888 888 .d888888 888 88888888 888 888
Y88b 888 Y8b. 888 888 Y8b. 888 888 888 Y88b. Y8b. Y88b 888
"Y88888 "Y8888 888 888 "Y8888 888 "Y888888 "Y888 "Y8888 "Y88888
888
Y8b d88P
"Y88P"
*******************************************************************************
--->
# QMK Firmware XAP Specs # QMK Firmware XAP Specs
This document describes the requirements of the QMK XAP ("extensible application protocol") API. This document describes the requirements of the QMK XAP ("extensible application protocol") API.
@ -91,12 +117,12 @@ This subsystem is always present, and provides the ability to query information
| Name | Route | Tags | Payloads | Description | | 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}.| | 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}.|
| Capabilities Query | `0x00 0x01` | |__Response:__ `u32`| XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x00 0x01` | | __Response:__ `u32` | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Enabled subsystem query | `0x00 0x02` | |__Response:__ `u32`| XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.| | Enabled subsystem query | `0x00 0x02` | | __Response:__ `u32` | XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.|
| Secure Status | `0x00 0x03` | |__Response:__ `u8`| Query secure route status<br><br>* 0 means secure routes are disabled<br>* 1 means unlock sequence initiated but incomplete<br>* 2 means secure routes are allowed<br>* any other value should be interpreted as disabled| | Secure Status | `0x00 0x03` | | __Response:__ `u8` | Query secure route status<br><br>* 0 means secure routes are disabled<br>* 1 means unlock sequence initiated but incomplete<br>* 2 means secure routes are allowed<br>* any other value should be interpreted as disabled|
| Secure Unlock | `0x00 0x04` | || Initiate secure route unlock sequence| | Secure Unlock | `0x00 0x04` | | | Initiate secure route unlock sequence|
| Secure Lock | `0x00 0x05` | || Disable secure routes| | Secure Lock | `0x00 0x05` | | | Disable secure routes|
### QMK - `0x01` ### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality. This subsystem is always present, and provides the ability to address QMK-specific functionality.
@ -104,16 +130,16 @@ This subsystem is always present, and provides the ability to address QMK-specif
| Name | Route | Tags | Payloads | Description | | 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}.| | 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}.|
| Capabilities Query | `0x01 0x01` | |__Response:__ `u32`| QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x01 0x01` | | __Response:__ `u32` | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Board identifiers | `0x01 0x02` | |__Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Vendor ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product Version: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* QMK Unique Identifier: `u32`| Retrieves the set of identifying information for the board.| | Board identifiers | `0x01 0x02` | | __Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Vendor ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product Version: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* QMK Unique Identifier: `u32` | Retrieves the set of identifying information for the board.|
| Board Manufacturer | `0x01 0x03` | |__Response:__ `string`| Retrieves the name of the manufacturer| | Board Manufacturer | `0x01 0x03` | | __Response:__ `string` | Retrieves the name of the manufacturer|
| Product Name | `0x01 0x04` | |__Response:__ `string`| Retrieves the product name| | Product Name | `0x01 0x04` | | __Response:__ `string` | Retrieves the product name|
| Config Blob Length | `0x01 0x05` | |__Response:__ `u16`| Retrieves the length of the configuration data bundled within the firmware| | Config Blob Length | `0x01 0x05` | | __Response:__ `u16` | Retrieves the length of the configuration data bundled within the firmware|
| Config Blob Chunk | `0x01 0x06` | |__Request:__ `u16`<br><br>__Response:__ `u8[32]`| Retrieves a chunk of the configuration data bundled within the firmware| | Config Blob Chunk | `0x01 0x06` | | __Request:__ `u16`<br><br>__Response:__ `u8[32]` | Retrieves a chunk of the configuration data bundled within the firmware|
| Jump to bootloader | `0x01 0x07` | __Secure__ |__Response:__ `u8`| Jump to bootloader<br><br>May not be present - if QMK capabilities query returns “true”, then jump to bootloader is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will jump to bootloader| | Jump to bootloader | `0x01 0x07` | __Secure__ | __Response:__ `u8` | Jump to bootloader<br><br>May not be present - if QMK capabilities query returns “true”, then jump to bootloader is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will jump to bootloader|
| Hardware Identifier | `0x01 0x08` | |__Response:__ `u32[4]`| Retrieves a unique identifier for the board.| | Hardware Identifier | `0x01 0x08` | | __Response:__ `u32[4]` | Retrieves a unique identifier for the board.|
| Reinitialize EEPROM | `0x01 0x09` | __Secure__ |__Response:__ `u8`| Reinitializes the keyboard's EEPROM (persistent memory)<br><br>May not be present - if QMK capabilities query returns “true”, then reinitialize is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will reinitialize and then reboot| | Reinitialize EEPROM | `0x01 0x09` | __Secure__ | __Response:__ `u8` | Reinitializes the keyboard's EEPROM (persistent memory)<br><br>May not be present - if QMK capabilities query returns “true”, then reinitialize is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will reinitialize and then reboot|
### Keyboard - `0x02` ### Keyboard - `0x02`
This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP. This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.
@ -129,10 +155,10 @@ This subsystem allows for query of currently configured keycodes.
| Name | Route | Tags | Payloads | Description | | 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.| | Capabilities Query | `0x04 0x01` | | __Response:__ `u32` | Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Layer Count | `0x04 0x02` | |__Response:__ `u8`| Query maximum number of layers that can be addressed within the keymap.| | Get Layer Count | `0x04 0x02` | | __Response:__ `u8` | Query maximum number of layers that can be addressed within the keymap.|
| Get Keycode | `0x04 0x03` | |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br><br>__Response:__ `u16`| Query the Keycode at the requested location.| | Get Keycode | `0x04 0x03` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br><br>__Response:__ `u16` | Query the Keycode at the requested location.|
| Get Encoder Keycode | `0x04 0x04` | |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br><br>__Response:__ `u16`| Query the Keycode at the requested location.| | Get Encoder Keycode | `0x04 0x04` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br><br>__Response:__ `u16` | Query the Keycode at the requested location.|
### Remapping - `0x05` ### Remapping - `0x05`
This subsystem allows for live reassignment of keycodes without rebuilding the firmware. This subsystem allows for live reassignment of keycodes without rebuilding the firmware.
@ -140,10 +166,10 @@ This subsystem allows for live reassignment of keycodes without rebuilding the f
| Name | Route | Tags | Payloads | Description | | 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.| | Capabilities Query | `0x05 0x01` | | __Response:__ `u32` | Remapping subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Layer Count | `0x05 0x02` | |__Response:__ `u8`| Query maximum number of layers that can be addressed within the keymap.| | Get Layer Count | `0x05 0x02` | | __Response:__ `u8` | Query maximum number of layers that can be addressed within the keymap.|
| Set Keycode | `0x05 0x03` | __Secure__ |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16`| Modify the Keycode at the requested location.| | Set Keycode | `0x05 0x03` | __Secure__ | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16` | Modify the Keycode at the requested location.|
| Set Encoder Keycode | `0x05 0x04` | __Secure__ |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16`| Modify the Keycode at the requested location.| | Set Encoder Keycode | `0x05 0x04` | __Secure__ | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16` | Modify the Keycode at the requested location.|
### Lighting - `0x06` ### Lighting - `0x06`
This subsystem allows for control over the lighting subsystem. This subsystem allows for control over the lighting subsystem.
@ -151,7 +177,7 @@ This subsystem allows for control over the lighting subsystem.
| Name | Route | Tags | Payloads | Description | | 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.| | Capabilities Query | `0x06 0x01` | | __Response:__ `u32` | Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
## Broadcast messages ## Broadcast messages

106
docs/xap_0.3.0.md
View File

@ -1,3 +1,29 @@
<!--- Copyright 2022 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
*******************************************************************************
88888888888 888 d8b .d888 d8b 888 d8b
888 888 Y8P d88P" Y8P 888 Y8P
888 888 888 888
888 88888b. 888 .d8888b 888888 888 888 .d88b. 888 .d8888b
888 888 "88b 888 88K 888 888 888 d8P Y8b 888 88K
888 888 888 888 "Y8888b. 888 888 888 88888888 888 "Y8888b.
888 888 888 888 X88 888 888 888 Y8b. 888 X88
888 888 888 888 88888P' 888 888 888 "Y8888 888 88888P'
888 888
888 888
888 888
.d88b. .d88b. 88888b. .d88b. 888d888 8888b. 888888 .d88b. .d88888
d88P"88b d8P Y8b 888 "88b d8P Y8b 888P" "88b 888 d8P Y8b d88" 888
888 888 88888888 888 888 88888888 888 .d888888 888 88888888 888 888
Y88b 888 Y8b. 888 888 Y8b. 888 888 888 Y88b. Y8b. Y88b 888
"Y88888 "Y8888 888 888 "Y8888 888 "Y888888 "Y888 "Y8888 "Y88888
888
Y8b d88P
"Y88P"
*******************************************************************************
--->
# QMK Firmware XAP Specs # QMK Firmware XAP Specs
This document describes the requirements of the QMK XAP ("extensible application protocol") API. This document describes the requirements of the QMK XAP ("extensible application protocol") API.
@ -91,12 +117,12 @@ This subsystem is always present, and provides the ability to query information
| Name | Route | Tags | Payloads | Description | | 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}.| | 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}.|
| Capabilities Query | `0x00 0x01` | |__Response:__ `u32`| XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x00 0x01` | | __Response:__ `u32` | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Enabled subsystem query | `0x00 0x02` | |__Response:__ `u32`| XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.| | Enabled subsystem query | `0x00 0x02` | | __Response:__ `u32` | XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.|
| Secure Status | `0x00 0x03` | |__Response:__ `u8`| Query secure route status<br><br>* 0 means secure routes are disabled<br>* 1 means unlock sequence initiated but incomplete<br>* 2 means secure routes are allowed<br>* any other value should be interpreted as disabled| | Secure Status | `0x00 0x03` | | __Response:__ `u8` | Query secure route status<br><br>* 0 means secure routes are disabled<br>* 1 means unlock sequence initiated but incomplete<br>* 2 means secure routes are allowed<br>* any other value should be interpreted as disabled|
| Secure Unlock | `0x00 0x04` | || Initiate secure route unlock sequence| | Secure Unlock | `0x00 0x04` | | | Initiate secure route unlock sequence|
| Secure Lock | `0x00 0x05` | || Disable secure routes| | Secure Lock | `0x00 0x05` | | | Disable secure routes|
### QMK - `0x01` ### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality. This subsystem is always present, and provides the ability to address QMK-specific functionality.
@ -104,16 +130,16 @@ This subsystem is always present, and provides the ability to address QMK-specif
| Name | Route | Tags | Payloads | Description | | 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}.| | 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}.|
| Capabilities Query | `0x01 0x01` | |__Response:__ `u32`| QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x01 0x01` | | __Response:__ `u32` | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Board identifiers | `0x01 0x02` | |__Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Vendor ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product Version: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* QMK Unique Identifier: `u32`| Retrieves the set of identifying information for the board.| | Board identifiers | `0x01 0x02` | | __Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Vendor ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product ID: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Product Version: `u16`<br>&nbsp;&nbsp;&nbsp;&nbsp;* QMK Unique Identifier: `u32` | Retrieves the set of identifying information for the board.|
| Board Manufacturer | `0x01 0x03` | |__Response:__ `string`| Retrieves the name of the manufacturer| | Board Manufacturer | `0x01 0x03` | | __Response:__ `string` | Retrieves the name of the manufacturer|
| Product Name | `0x01 0x04` | |__Response:__ `string`| Retrieves the product name| | Product Name | `0x01 0x04` | | __Response:__ `string` | Retrieves the product name|
| Config Blob Length | `0x01 0x05` | |__Response:__ `u16`| Retrieves the length of the configuration data bundled within the firmware| | Config Blob Length | `0x01 0x05` | | __Response:__ `u16` | Retrieves the length of the configuration data bundled within the firmware|
| Config Blob Chunk | `0x01 0x06` | |__Request:__ `u16`<br><br>__Response:__ `u8[32]`| Retrieves a chunk of the configuration data bundled within the firmware| | Config Blob Chunk | `0x01 0x06` | | __Request:__ `u16`<br><br>__Response:__ `u8[32]` | Retrieves a chunk of the configuration data bundled within the firmware|
| Jump to bootloader | `0x01 0x07` | __Secure__ |__Response:__ `u8`| Jump to bootloader<br><br>May not be present - if QMK capabilities query returns “true”, then jump to bootloader is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will jump to bootloader| | Jump to bootloader | `0x01 0x07` | __Secure__ | __Response:__ `u8` | Jump to bootloader<br><br>May not be present - if QMK capabilities query returns “true”, then jump to bootloader is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will jump to bootloader|
| Hardware Identifier | `0x01 0x08` | |__Response:__ `u32[4]`| Retrieves a unique identifier for the board.| | Hardware Identifier | `0x01 0x08` | | __Response:__ `u32[4]` | Retrieves a unique identifier for the board.|
| Reinitialize EEPROM | `0x01 0x09` | __Secure__ |__Response:__ `u8`| Reinitializes the keyboard's EEPROM (persistent memory)<br><br>May not be present - if QMK capabilities query returns “true”, then reinitialize is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will reinitialize and then reboot| | Reinitialize EEPROM | `0x01 0x09` | __Secure__ | __Response:__ `u8` | Reinitializes the keyboard's EEPROM (persistent memory)<br><br>May not be present - if QMK capabilities query returns “true”, then reinitialize is supported<br><br>* 0 means secure routes are disabled, and should be considered as a failure<br>* 1 means successful, board will reinitialize and then reboot|
### Keyboard - `0x02` ### Keyboard - `0x02`
This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP. This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.
@ -129,10 +155,10 @@ This subsystem allows for query of currently configured keycodes.
| Name | Route | Tags | Payloads | Description | | 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.| | Capabilities Query | `0x04 0x01` | | __Response:__ `u32` | Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Layer Count | `0x04 0x02` | |__Response:__ `u8`| Query maximum number of layers that can be addressed within the keymap.| | Get Layer Count | `0x04 0x02` | | __Response:__ `u8` | Query maximum number of layers that can be addressed within the keymap.|
| Get Keycode | `0x04 0x03` | |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br><br>__Response:__ `u16`| Query the Keycode at the requested location.| | Get Keycode | `0x04 0x03` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br><br>__Response:__ `u16` | Query the Keycode at the requested location.|
| Get Encoder Keycode | `0x04 0x04` | |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br><br>__Response:__ `u16`| Query the Keycode at the requested location.| | Get Encoder Keycode | `0x04 0x04` | | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br><br>__Response:__ `u16` | Query the Keycode at the requested location.|
### Remapping - `0x05` ### Remapping - `0x05`
This subsystem allows for live reassignment of keycodes without rebuilding the firmware. This subsystem allows for live reassignment of keycodes without rebuilding the firmware.
@ -140,10 +166,10 @@ This subsystem allows for live reassignment of keycodes without rebuilding the f
| Name | Route | Tags | Payloads | Description | | 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.| | Capabilities Query | `0x05 0x01` | | __Response:__ `u32` | Remapping subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Layer Count | `0x05 0x02` | |__Response:__ `u8`| Query maximum number of layers that can be addressed within the keymap.| | Get Layer Count | `0x05 0x02` | | __Response:__ `u8` | Query maximum number of layers that can be addressed within the keymap.|
| Set Keycode | `0x05 0x03` | __Secure__ |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16`| Modify the Keycode at the requested location.| | Set Keycode | `0x05 0x03` | __Secure__ | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16` | Modify the Keycode at the requested location.|
| Set Encoder Keycode | `0x05 0x04` | __Secure__ |__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16`| Modify the Keycode at the requested location.| | Set Encoder Keycode | `0x05 0x04` | __Secure__ | __Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Keycode: `u16` | Modify the Keycode at the requested location.|
### Lighting - `0x06` ### Lighting - `0x06`
This subsystem allows for control over the lighting subsystem. This subsystem allows for control over the lighting subsystem.
@ -151,40 +177,40 @@ This subsystem allows for control over the lighting subsystem.
| Name | Route | Tags | Payloads | Description | | 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.| | 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` #### backlight - `0x06 0x02`
This subsystem allows for control over the backlight subsystem. This subsystem allows for control over the backlight subsystem.
| Name | Route | Tags | Payloads | Description | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Capabilities Query | `0x06 0x02 0x01` | |__Response:__ `u32`| backlight subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x06 0x02 0x01` | | __Response:__ `u32` | backlight subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Enabled Effects | `0x06 0x02 0x02` | |__Response:__ `u8`| Each bit should be considered as a "usable" effect id| | Get Enabled Effects | `0x06 0x02 0x02` | | __Response:__ `u8` | Each bit should be considered as a "usable" effect id|
| Get Config | `0x06 0x02 0x03` | |__Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* enable: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* mode: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* val: `u8`| Query the current config.| | Get Config | `0x06 0x02 0x03` | | __Response:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* enable: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* mode: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* val: `u8` | Query the current config.|
| 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.| | 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.| | Save Config | `0x06 0x02 0x05` | | | Save the current config.|
#### rgblight - `0x06 0x03` #### rgblight - `0x06 0x03`
This subsystem allows for control over the rgblight subsystem. This subsystem allows for control over the rgblight subsystem.
| Name | Route | Tags | Payloads | Description | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Capabilities Query | `0x06 0x03 0x01` | |__Response:__ `u32`| rgblight subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x06 0x03 0x01` | | __Response:__ `u32` | rgblight subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Enabled Effects | `0x06 0x03 0x02` | |__Response:__ `u64`| Each bit should be considered as a "usable" effect id| | Get Enabled Effects | `0x06 0x03 0x02` | | __Response:__ `u64` | Each bit should be considered as a "usable" effect id|
| Get Config | `0x06 0x03 0x03` | |__Response:__<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`| Query the current config.| | Get Config | `0x06 0x03 0x03` | | __Response:__<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` | Query the current config.|
| 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.| | 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.| | Save Config | `0x06 0x03 0x05` | | | Save the current config.|
#### rgbmatrix - `0x06 0x04` #### rgbmatrix - `0x06 0x04`
This subsystem allows for control over the rgb matrix subsystem. This subsystem allows for control over the rgb matrix subsystem.
| Name | Route | Tags | Payloads | Description | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Capabilities Query | `0x06 0x04 0x01` | |__Response:__ `u32`| rgb matrix subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.| | Capabilities Query | `0x06 0x04 0x01` | | __Response:__ `u32` | rgb matrix subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Enabled Effects | `0x06 0x04 0x02` | |__Response:__ `u64`| Each bit should be considered as a "usable" effect id| | Get Enabled Effects | `0x06 0x04 0x02` | | __Response:__ `u64` | Each bit should be considered as a "usable" effect id|
| Get Config | `0x06 0x04 0x03` | |__Response:__<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`| Query the current config.| | Get Config | `0x06 0x04 0x03` | | __Response:__<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` | Query the current config.|
| 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.| | 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.| | Save Config | `0x06 0x04 0x05` | | | Save the current config.|
## Broadcast messages ## Broadcast messages

27
docs/xap_protocol.md
View File

@ -1,4 +1,29 @@
<!-- This file is generated --> <!--- Copyright 2022 QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
<!---
*******************************************************************************
88888888888 888 d8b .d888 d8b 888 d8b
888 888 Y8P d88P" Y8P 888 Y8P
888 888 888 888
888 88888b. 888 .d8888b 888888 888 888 .d88b. 888 .d8888b
888 888 "88b 888 88K 888 888 888 d8P Y8b 888 88K
888 888 888 888 "Y8888b. 888 888 888 88888888 888 "Y8888b.
888 888 888 888 X88 888 888 888 Y8b. 888 X88
888 888 888 888 88888P' 888 888 888 "Y8888 888 88888P'
888 888
888 888
888 888
.d88b. .d88b. 88888b. .d88b. 888d888 8888b. 888888 .d88b. .d88888
d88P"88b d8P Y8b 888 "88b d8P Y8b 888P" "88b 888 d8P Y8b d88" 888
888 888 88888888 888 888 88888888 888 .d888888 888 88888888 888 888
Y88b 888 Y8b. 888 888 Y8b. 888 888 888 Y88b. Y8b. Y88b 888
"Y88888 "Y8888 888 888 "Y8888 888 "Y888888 "Y888 "Y8888 "Y88888
888
Y8b d88P
"Y88P"
*******************************************************************************
--->
* [XAP Version 0.3.0](xap_0.3.0.md) * [XAP Version 0.3.0](xap_0.3.0.md)
* [XAP Version 0.2.0](xap_0.2.0.md) * [XAP Version 0.2.0](xap_0.2.0.md)
* [XAP Version 0.1.0](xap_0.1.0.md) * [XAP Version 0.1.0](xap_0.1.0.md)

17
lib/python/qmk/cli/xap/generate_docs.py
View File

@ -1,16 +1,18 @@
"""This script generates the XAP protocol documentation. """This script generates the XAP protocol documentation.
""" """
import hjson import hjson
from milc import cli
from qmk.constants import QMK_FIRMWARE from qmk.constants import QMK_FIRMWARE
from qmk.xap.common import get_xap_definition_files, update_xap_definitions, render_xap_output from qmk.xap.common import get_xap_definition_files, update_xap_definitions, render_xap_output
from milc import cli
@cli.subcommand('Generates the XAP protocol documentation.', hidden=False if cli.config.user.developer else True) @cli.subcommand('Generates the XAP protocol documentation.', hidden=False if cli.config.user.developer else True)
def xap_generate_docs(cli): def xap_generate_docs(cli):
"""Generates the XAP protocol documentation by merging the definitions files, and producing the corresponding Markdown document under `/docs/`. """Generates the XAP protocol documentation by merging the definitions files, and producing the corresponding Markdown document under `/docs/`.
""" """
docs_list = [] versions = []
overall = None overall = None
for file in get_xap_definition_files(): for file in get_xap_definition_files():
@ -22,17 +24,12 @@ def xap_generate_docs(cli):
overall['response_flags']['bits'][str(n)] = {'name': '', 'description': '', 'define': '-'} overall['response_flags']['bits'][str(n)] = {'name': '', 'description': '', 'define': '-'}
output_doc = QMK_FIRMWARE / "docs" / f"{file.stem}.md" output_doc = QMK_FIRMWARE / "docs" / f"{file.stem}.md"
docs_list.append(output_doc) versions.append(overall['version'])
output = render_xap_output('docs', 'docs.md.j2', overall) output = render_xap_output('docs', 'docs.md.j2', overall)
with open(output_doc, "w", encoding='utf-8') as out_file: with open(output_doc, "w", encoding='utf-8') as out_file:
out_file.write(output) out_file.write(output)
output_doc = QMK_FIRMWARE / "docs" / "xap_protocol.md" output_doc = QMK_FIRMWARE / "docs" / "xap_protocol.md"
output = render_xap_output('docs', 'versions.md.j2', overall, versions=versions)
with open(output_doc, "w", encoding='utf-8') as out_file: with open(output_doc, "w", encoding='utf-8') as out_file:
out_file.write('''\ out_file.write(output)
<!-- This file is generated -->
''')
for file in reversed(sorted(docs_list)):
ver = file.stem[4:]
out_file.write(f'* [XAP Version {ver}]({file.name})\n')

13
lib/python/qmk/cli/xap/generate_python.py
View File

@ -1,12 +1,11 @@
"""This script generates the python XAP client. """This script generates the python XAP client.
""" """
from qmk.constants import QMK_FIRMWARE, GPL2_HEADER_SH_LIKE, GENERATED_HEADER_SH_LIKE
from qmk.xap.common import latest_xap_defs, render_xap_output
from qmk.commands import dump_lines
from milc import cli from milc import cli
from qmk.commands import dump_lines
from qmk.constants import QMK_FIRMWARE
from qmk.xap.common import latest_xap_defs, render_xap_output
@cli.subcommand('Generates the python XAP client.', hidden=False if cli.config.user.developer else True) @cli.subcommand('Generates the python XAP client.', hidden=False if cli.config.user.developer else True)
def xap_generate_python(cli): def xap_generate_python(cli):
@ -14,9 +13,7 @@ def xap_generate_python(cli):
parent = QMK_FIRMWARE / 'lib' / 'python' / 'xap_client' parent = QMK_FIRMWARE / 'lib' / 'python' / 'xap_client'
for name in ['types.py', 'routes.py', 'constants.py']: for name in ['types.py', 'routes.py', 'constants.py']:
lines = [GPL2_HEADER_SH_LIKE, GENERATED_HEADER_SH_LIKE]
output = render_xap_output('client/python', f'{name}.j2', defs) output = render_xap_output('client/python', f'{name}.j2', defs)
lines += output.split('\n') lines = output.split('\n')
dump_lines(parent / name, lines) dump_lines(parent / name, lines)

31
lib/python/qmk/constants.py
View File

@ -136,6 +136,11 @@ GPL2_HEADER_SH_LIKE = f'''\
# SPDX-License-Identifier: GPL-2.0-or-later # SPDX-License-Identifier: GPL-2.0-or-later
''' '''
GPL2_HEADER_XML_LIKE = f'''\
<!--- Copyright {date.today().year} QMK --->
<!--- SPDX-License-Identifier: GPL-2.0-or-later --->
'''
GENERATED_HEADER_C_LIKE = '''\ GENERATED_HEADER_C_LIKE = '''\
/******************************************************************************* /*******************************************************************************
88888888888 888 d8b .d888 d8b 888 d8b 88888888888 888 d8b .d888 d8b 888 d8b
@ -186,3 +191,29 @@ GENERATED_HEADER_SH_LIKE = '''\
# #
################################################################################ ################################################################################
''' '''
GENERATED_HEADER_XML_LIKE = '''\
<!---
*******************************************************************************
88888888888 888 d8b .d888 d8b 888 d8b
888 888 Y8P d88P" Y8P 888 Y8P
888 888 888 888
888 88888b. 888 .d8888b 888888 888 888 .d88b. 888 .d8888b
888 888 "88b 888 88K 888 888 888 d8P Y8b 888 88K
888 888 888 888 "Y8888b. 888 888 888 88888888 888 "Y8888b.
888 888 888 888 X88 888 888 888 Y8b. 888 X88
888 888 888 888 88888P' 888 888 888 "Y8888 888 88888P'
888 888
888 888
888 888
.d88b. .d88b. 88888b. .d88b. 888d888 8888b. 888888 .d88b. .d88888
d88P"88b d8P Y8b 888 "88b d8P Y8b 888P" "88b 888 d8P Y8b d88" 888
888 888 88888888 888 888 88888888 888 .d888888 888 88888888 888 888
Y88b 888 Y8b. 888 888 Y8b. 888 888 888 Y88b. Y8b. Y88b 888
"Y88888 "Y8888 888 888 "Y8888 888 "Y888888 "Y888 "Y8888 "Y88888
888
Y8b d88P
"Y88P"
*******************************************************************************
--->
'''

12
lib/python/qmk/xap/common.py
View File

@ -8,7 +8,7 @@ from pathlib import Path
from typing import OrderedDict from typing import OrderedDict
from jinja2 import Environment, FileSystemLoader, select_autoescape from jinja2 import Environment, FileSystemLoader, select_autoescape
from qmk.constants import QMK_FIRMWARE, GPL2_HEADER_C_LIKE, GENERATED_HEADER_C_LIKE import qmk.constants
from qmk.git import git_get_version from qmk.git import git_get_version
from qmk.json_schema import json_load, validate from qmk.json_schema import json_load, validate
from qmk.decorators import lru_cache from qmk.decorators import lru_cache
@ -53,7 +53,7 @@ def load_lighting_spec(feature, version='latest'):
def _get_jinja2_env(data_templates_xap_subdir: str): def _get_jinja2_env(data_templates_xap_subdir: str):
templates_dir = os.path.join(QMK_FIRMWARE, 'data', 'templates', 'xap', data_templates_xap_subdir) templates_dir = os.path.join(qmk.constants.QMK_FIRMWARE, 'data', 'templates', 'xap', data_templates_xap_subdir)
j2 = Environment(loader=FileSystemLoader(templates_dir), autoescape=select_autoescape()) j2 = Environment(loader=FileSystemLoader(templates_dir), autoescape=select_autoescape())
return j2 return j2
@ -65,11 +65,11 @@ def render_xap_output(data_templates_xap_subdir, file_to_render, defs=None, **kw
attach_filters(j2) attach_filters(j2)
constants = {} specs = {}
for feature in ['rgblight', 'rgb_matrix', 'led_matrix']: for feature in ['rgblight', 'rgb_matrix', 'led_matrix']:
constants[feature] = load_lighting_spec(feature) specs[feature] = load_lighting_spec(feature)
return j2.get_template(file_to_render).render(xap=defs, qmk_version=git_get_version(), xap_str=hjson.dumps(defs), constants=constants, GPL2_HEADER_C_LIKE=GPL2_HEADER_C_LIKE, GENERATED_HEADER_C_LIKE=GENERATED_HEADER_C_LIKE, **kwargs) return j2.get_template(file_to_render).render(xap=defs, qmk_version=git_get_version(), xap_str=hjson.dumps(defs), specs=specs, constants=qmk.constants, **kwargs)
def _find_kb_spec(kb): def _find_kb_spec(kb):
@ -130,7 +130,7 @@ def _merge_ordered_dicts(dicts):
def get_xap_definition_files(): def get_xap_definition_files():
"""Get the sorted list of XAP definition files, from <QMK>/data/xap. """Get the sorted list of XAP definition files, from <QMK>/data/xap.
""" """
xap_defs = QMK_FIRMWARE / "data" / "xap" xap_defs = qmk.constants.QMK_FIRMWARE / "data" / "xap"
return list(sorted(xap_defs.glob('**/xap_*.hjson'))) return list(sorted(xap_defs.glob('**/xap_*.hjson')))

5
lib/python/qmk/xap/jinja2_filters.py
View File

@ -61,8 +61,13 @@ def _triplet_to_bcd(value: str):
return f'0x{int(m.group(1)):02d}{int(m.group(2)):02d}{int(m.group(3)):04d}' return f'0x{int(m.group(1)):02d}{int(m.group(2)):02d}{int(m.group(3)):04d}'
def _newline_to_br(value: str):
return value.replace('\n', '<br>')
def attach_filters(j2: Environment): def attach_filters(j2: Environment):
j2.filters['to_snake'] = to_snake j2.filters['to_snake'] = to_snake
j2.filters['newline_to_br'] = _newline_to_br
j2.filters['triplet_to_bcd'] = _triplet_to_bcd j2.filters['triplet_to_bcd'] = _triplet_to_bcd
j2.filters['fnv1a_32'] = _fnv1a_32 j2.filters['fnv1a_32'] = _fnv1a_32
j2.filters['type_to_c'] = _xap_type_to_c j2.filters['type_to_c'] = _xap_type_to_c

1
lib/python/xap_client/constants.py
View File

@ -75,6 +75,7 @@ class RgblightModes(IntEnum):
TWINKLE_6 = 0x29 TWINKLE_6 = 0x29
# version: 0.0.1
class RgbMatrixModes(IntEnum): class RgbMatrixModes(IntEnum):
SOLID_COLOR = 0x00 SOLID_COLOR = 0x00
ALPHAS_MODS = 0x01 ALPHAS_MODS = 0x01

1
lib/python/xap_client/routes.py
View File

@ -26,7 +26,6 @@
# #
################################################################################ ################################################################################
class XAPRouteError(Exception): class XAPRouteError(Exception):
pass pass