diff --git a/data/templates/xap/docs/route_request.md.j2 b/data/templates/xap/docs/route_request.md.j2
new file mode 100644
index 0000000000..e0148c9d15
--- /dev/null
+++ b/data/templates/xap/docs/route_request.md.j2
@@ -0,0 +1,8 @@
+{%- if subroute.request_type == 'struct' -%}
+
__Request:__
+{%- for member in subroute.request_struct_members -%}
+
{{ " "|safe*4 }}* {{ member.name }}: `{{ member.type }}`
+{%- endfor -%}
+{%- elif subroute.request_type -%}
+
__Request:__ `{{ subroute.request_type }}`
+{%- endif -%}
\ No newline at end of file
diff --git a/data/templates/xap/docs/route_response.md.j2 b/data/templates/xap/docs/route_response.md.j2
new file mode 100644
index 0000000000..a36099937a
--- /dev/null
+++ b/data/templates/xap/docs/route_response.md.j2
@@ -0,0 +1,8 @@
+{%- if subroute.return_type == 'struct' -%}
+
__Response:__
+{%- for member in subroute.return_struct_members -%}
+
{{ " "|safe*4 }}* {{ member.name }}: `{{ member.type }}`
+{%- endfor -%}
+{%- elif subroute.return_type -%}
+
__Response:__ `{{ subroute.return_type }}`
+{%- endif -%}
\ No newline at end of file
diff --git a/data/templates/xap/docs/routes.md.j2 b/data/templates/xap/docs/routes.md.j2
index c740ae2f5e..1c1e61bd51 100644
--- a/data/templates/xap/docs/routes.md.j2
+++ b/data/templates/xap/docs/routes.md.j2
@@ -3,10 +3,10 @@
{{ route.description }}
{% if route.routes %}
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
{%- for subid, subroute in route.routes | dictsort %}
-| {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure__{% endif %} | {{ subroute.description.replace('\n', '
') }} |
+| {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure__{% endif %} | {%- include 'route_request.md.j2' -%}{%- include 'route_response.md.j2' -%} | {{ subroute.description.replace('\n', '
') }}|
{%- endfor %}
{% endif %}
{%- endfor %}
diff --git a/data/xap/xap_0.0.1.hjson b/data/xap/xap_0.0.1.hjson
index d22c542864..2b6def0ff1 100755
--- a/data/xap/xap_0.0.1.hjson
+++ b/data/xap/xap_0.0.1.hjson
@@ -223,8 +223,6 @@
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
- * Response:
- * `u32` value.
'''
return_type: u32
return_purpose: bcd-version
diff --git a/data/xap/xap_0.1.0.hjson b/data/xap/xap_0.1.0.hjson
index aea6584346..361a37461e 100755
--- a/data/xap/xap_0.1.0.hjson
+++ b/data/xap/xap_0.1.0.hjson
@@ -226,8 +226,6 @@
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
- * Response:
- * `u32` value.
'''
return_type: u32
return_purpose: bcd-version
diff --git a/data/xap/xap_0.2.0.hjson b/data/xap/xap_0.2.0.hjson
index 822e5190a0..6c791ffd42 100755
--- a/data/xap/xap_0.2.0.hjson
+++ b/data/xap/xap_0.2.0.hjson
@@ -28,7 +28,7 @@
type: command
name: Get Layer Count
define: GET_LAYER_COUNT
- description: TODO
+ description: Query maximum number of layers that can be addressed within the keymap.
return_type: u8
return_constant: DYNAMIC_KEYMAP_LAYER_COUNT
}
@@ -36,7 +36,7 @@
type: command
name: Get Keycode
define: GET_KEYMAP_KEYCODE
- description: TODO
+ description: Query the Keycode at the requested location.
request_type: struct
request_struct_length: 3
request_struct_members: [
@@ -60,7 +60,7 @@
type: command
name: Set Keycode
define: SET_KEYMAP_KEYCODE
- description: TODO
+ description: Modify the Keycode at the requested location.
permissions: secure
request_type: struct
request_struct_length: 5
@@ -113,7 +113,7 @@
type: command
name: Get Keycode
define: GET_ENCODER_KEYCODE
- description: TODO
+ description: Query the Keycode at the requested location.
request_type: struct
request_struct_length: 3
request_struct_members: [
@@ -138,7 +138,7 @@
name: Set Keycode
define: SET_ENCODER_KEYCODE
permissions: secure
- description: TODO
+ description: Modify the Keycode at the requested location.
request_type: struct
request_struct_length: 5
request_struct_members: [
diff --git a/docs/xap_0.0.1.md b/docs/xap_0.0.1.md
index 20e6115a7c..fe85fddb48 100644
--- a/docs/xap_0.0.1.md
+++ b/docs/xap_0.0.1.md
@@ -75,8 +75,8 @@ This is the primary method for determining if a subsystem has been enabled in th
This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Version Query | `0x00 0x00` | | XAP protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
* Response:
* `u32` value. |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Version Query | `0x00 0x00` | |
__Response:__ `u32`| XAP protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.|
diff --git a/docs/xap_0.1.0.md b/docs/xap_0.1.0.md
index de21009a9c..cd9036cff1 100644
--- a/docs/xap_0.1.0.md
+++ b/docs/xap_0.1.0.md
@@ -88,30 +88,30 @@ This is the primary method for determining if a subsystem has been enabled in th
This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Version Query | `0x00 0x00` | | XAP protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
* Response:
* `u32` value. |
-| Capabilities Query | `0x00 0x01` | | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. |
-| Enabled subsystem query | `0x00 0x02` | | 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` | | Query secure route status
* 0 means secure routes are disabled
* 1 means unlock sequence initiated but incomplete
* 2 means secure routes are allowed
* any other value should be interpreted as disabled |
-| Secure Unlock | `0x00 0x04` | | Initiate secure route unlock sequence |
-| Secure Lock | `0x00 0x05` | | Disable secure routes |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Version Query | `0x00 0x00` | |
__Response:__ `u32`| XAP protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* 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.|
+| 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
* 0 means secure routes are disabled
* 1 means unlock sequence initiated but incomplete
* 2 means secure routes are allowed
* any other value should be interpreted as disabled|
+| Secure Unlock | `0x00 0x04` | || Initiate secure route unlock sequence|
+| Secure Lock | `0x00 0x05` | || Disable secure routes|
### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Version Query | `0x01 0x00` | | QMK protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
* Response:
* `u32` value. |
-| Capabilities Query | `0x01 0x01` | | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. |
-| Board identifiers | `0x01 0x02` | | Retrieves the set of identifying information for the board. |
-| Board Manufacturer | `0x01 0x03` | | Retrieves the name of the manufacturer |
-| Product Name | `0x01 0x04` | | Retrieves the product name |
-| info.json length | `0x01 0x05` | | Retrieves the length of info.json |
-| info.json | `0x01 0x06` | | Retrieves a chunk of info.json |
-| Jump to bootloader | `0x01 0x07` | __Secure__ | Jump to bootloader
May not be present – if QMK capabilities query returns “true”, then jump to bootloader is supported
* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will jump to bootloader |
-| info.json | `0x01 0x08` | | Retrieves a unique identifier for the board. |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Version Query | `0x01 0x00` | |
__Response:__ `u32`| QMK protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* 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.|
+| Board identifiers | `0x01 0x02` | |
__Response:__
* Vendor ID: `u16`
* Product ID: `u16`
* Product Version: `u16`
* 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|
+| Product Name | `0x01 0x04` | |
__Response:__ `string`| Retrieves the product name|
+| info.json length | `0x01 0x05` | |
__Response:__ `u32`| Retrieves the length of info.json|
+| info.json | `0x01 0x06` | |
__Request:__ `u16`
__Response:__ `u8[32]`| Retrieves a chunk of info.json|
+| Jump to bootloader | `0x01 0x07` | __Secure__ |
__Response:__ `u8`| Jump to bootloader
May not be present – if QMK capabilities query returns “true”, then jump to bootloader is supported
* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will jump to bootloader|
+| info.json | `0x01 0x08` | |
__Response:__ `u32[4]`| Retrieves a unique identifier for the board.|
### Keyboard - `0x02`
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
diff --git a/docs/xap_0.2.0.md b/docs/xap_0.2.0.md
index fc8afa4ebf..ed2130e34f 100644
--- a/docs/xap_0.2.0.md
+++ b/docs/xap_0.2.0.md
@@ -88,30 +88,30 @@ This is the primary method for determining if a subsystem has been enabled in th
This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Version Query | `0x00 0x00` | | XAP protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
* Response:
* `u32` value. |
-| Capabilities Query | `0x00 0x01` | | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. |
-| Enabled subsystem query | `0x00 0x02` | | 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` | | Query secure route status
* 0 means secure routes are disabled
* 1 means unlock sequence initiated but incomplete
* 2 means secure routes are allowed
* any other value should be interpreted as disabled |
-| Secure Unlock | `0x00 0x04` | | Initiate secure route unlock sequence |
-| Secure Lock | `0x00 0x05` | | Disable secure routes |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Version Query | `0x00 0x00` | |
__Response:__ `u32`| XAP protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* 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.|
+| 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
* 0 means secure routes are disabled
* 1 means unlock sequence initiated but incomplete
* 2 means secure routes are allowed
* any other value should be interpreted as disabled|
+| Secure Unlock | `0x00 0x04` | || Initiate secure route unlock sequence|
+| Secure Lock | `0x00 0x05` | || Disable secure routes|
### QMK - `0x01`
This subsystem is always present, and provides the ability to address QMK-specific functionality.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Version Query | `0x01 0x00` | | QMK protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
* Response:
* `u32` value. |
-| Capabilities Query | `0x01 0x01` | | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. |
-| Board identifiers | `0x01 0x02` | | Retrieves the set of identifying information for the board. |
-| Board Manufacturer | `0x01 0x03` | | Retrieves the name of the manufacturer |
-| Product Name | `0x01 0x04` | | Retrieves the product name |
-| info.json length | `0x01 0x05` | | Retrieves the length of info.json |
-| info.json | `0x01 0x06` | | Retrieves a chunk of info.json |
-| Jump to bootloader | `0x01 0x07` | __Secure__ | Jump to bootloader
May not be present – if QMK capabilities query returns “true”, then jump to bootloader is supported
* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will jump to bootloader |
-| info.json | `0x01 0x08` | | Retrieves a unique identifier for the board. |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Version Query | `0x01 0x00` | |
__Response:__ `u32`| QMK protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* 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.|
+| Board identifiers | `0x01 0x02` | |
__Response:__
* Vendor ID: `u16`
* Product ID: `u16`
* Product Version: `u16`
* 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|
+| Product Name | `0x01 0x04` | |
__Response:__ `string`| Retrieves the product name|
+| info.json length | `0x01 0x05` | |
__Response:__ `u32`| Retrieves the length of info.json|
+| info.json | `0x01 0x06` | |
__Request:__ `u16`
__Response:__ `u8[32]`| Retrieves a chunk of info.json|
+| Jump to bootloader | `0x01 0x07` | __Secure__ |
__Response:__ `u8`| Jump to bootloader
May not be present – if QMK capabilities query returns “true”, then jump to bootloader is supported
* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will jump to bootloader|
+| info.json | `0x01 0x08` | |
__Response:__ `u32[4]`| Retrieves a unique identifier for the board.|
### Keyboard - `0x02`
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
@@ -125,30 +125,30 @@ This subsystem is always present, and reserved for user-specific functionality.
This subsystem allows for live modifications of the keymap, allowing keys to be reassigned without rebuilding the firmware.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Capabilities Query | `0x04 0x00` | | Dynamic Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. |
-| Get Layer Count | `0x04 0x01` | | TODO |
-| Get Keycode | `0x04 0x02` | | TODO |
-| Set Keycode | `0x04 0x03` | __Secure__ | TODO |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Capabilities Query | `0x04 0x00` | |
__Response:__ `u32`| Dynamic Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
+| Get Layer Count | `0x04 0x01` | |
__Response:__ `u8`| Query maximum number of layers that can be addressed within the keymap.|
+| Get Keycode | `0x04 0x02` | |
__Request:__
* Layer: `u8`
* Row: `u8`
* Column: `u8`
__Response:__ `u16`| Query the Keycode at the requested location.|
+| Set Keycode | `0x04 0x03` | __Secure__ |
__Request:__
* Layer: `u8`
* Row: `u8`
* Column: `u8`
* Keycode: `u16`| Modify the Keycode at the requested location.|
### Dynamic Encoders - `0x05`
This subsystem allows for live modifications of the keymap, allowing encoder functionality to be reassigned without rebuilding the firmware.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Capabilities Query | `0x05 0x00` | | Dynamic Encoders subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. |
-| Get Keycode | `0x05 0x02` | | TODO |
-| Set Keycode | `0x05 0x03` | __Secure__ | TODO |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Capabilities Query | `0x05 0x00` | |
__Response:__ `u32`| Dynamic Encoders subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
+| Get Keycode | `0x05 0x02` | |
__Request:__
* Layer: `u8`
* Encoder: `u8`
* Clockwise: `u8`
__Response:__ `u16`| Query the Keycode at the requested location.|
+| Set Keycode | `0x05 0x03` | __Secure__ |
__Request:__
* Layer: `u8`
* Encoder: `u8`
* Clockwise: `u8`
* Keycode: `u16`| Modify the Keycode at the requested location.|
### Lighting - `0x06`
This subsystem allows for control over the lighting subsystem.
-| Name | Route | Tags | Definition |
-| -- | -- | -- | -- |
-| Capabilities Query | `0x06 0x00` | | Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. |
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+| Capabilities Query | `0x06 0x00` | |
__Response:__ `u32`| Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
## Broadcast messages