darkkirb/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Render request/response in XAP docs

Browse source
This commit is contained in:
zvecr 2022-05-26 18:22:54 +01:00
parent 32404cbb77
commit f727692fd1
9 changed files with 79 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
data/templates/xap/docs/route_request.md.j2 Normal file
View file

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

8
data/templates/xap/docs/route_response.md.j2 Normal file
View file

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

6
data/templates/xap/docs/routes.md.j2
View file

@ -3,10 +3,10 @@
{{ route.description }} {{ route.description }}
{% if route.routes %} {% if route.routes %}
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
{%- for subid, subroute in route.routes | dictsort %} {%- for subid, subroute in route.routes | dictsort %}
| {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure__{% endif %} | {{ subroute.description.replace('\n', '<br>') }} | | {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure__{% endif %} | {%- include 'route_request.md.j2' -%}{%- include 'route_response.md.j2' -%} | {{ subroute.description.replace('\n', '<br>') }}|
{%- endfor %} {%- endfor %}
{% endif %} {% endif %}
{%- endfor %} {%- endfor %}

2
data/xap/xap_0.0.1.hjson
View file

@ -223,8 +223,6 @@
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ` * 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}. * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
* Response:
* `u32` value.
''' '''
return_type: u32 return_type: u32
return_purpose: bcd-version return_purpose: bcd-version

2
data/xap/xap_0.1.0.hjson
View file

@ -226,8 +226,6 @@
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ` * 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}. * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
* Response:
* `u32` value.
''' '''
return_type: u32 return_type: u32
return_purpose: bcd-version return_purpose: bcd-version

10
data/xap/xap_0.2.0.hjson
View file

@ -28,7 +28,7 @@
type: command type: command
name: Get Layer Count name: Get Layer Count
define: 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_type: u8
return_constant: DYNAMIC_KEYMAP_LAYER_COUNT return_constant: DYNAMIC_KEYMAP_LAYER_COUNT
} }
@ -36,7 +36,7 @@
type: command type: command
name: Get Keycode name: Get Keycode
define: GET_KEYMAP_KEYCODE define: GET_KEYMAP_KEYCODE
description: TODO description: Query the Keycode at the requested location.
request_type: struct request_type: struct
request_struct_length: 3 request_struct_length: 3
request_struct_members: [ request_struct_members: [
@ -60,7 +60,7 @@
type: command type: command
name: Set Keycode name: Set Keycode
define: SET_KEYMAP_KEYCODE define: SET_KEYMAP_KEYCODE
description: TODO description: Modify the Keycode at the requested location.
permissions: secure permissions: secure
request_type: struct request_type: struct
request_struct_length: 5 request_struct_length: 5
@ -113,7 +113,7 @@
type: command type: command
name: Get Keycode name: Get Keycode
define: GET_ENCODER_KEYCODE define: GET_ENCODER_KEYCODE
description: TODO description: Query the Keycode at the requested location.
request_type: struct request_type: struct
request_struct_length: 3 request_struct_length: 3
request_struct_members: [ request_struct_members: [
@ -138,7 +138,7 @@
name: Set Keycode name: Set Keycode
define: SET_ENCODER_KEYCODE define: SET_ENCODER_KEYCODE
permissions: secure permissions: secure
description: TODO description: Modify the Keycode at the requested location.
request_type: struct request_type: struct
request_struct_length: 5 request_struct_length: 5
request_struct_members: [ request_struct_members: [

6
docs/xap_0.0.1.md
View file

@ -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. This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Version Query | `0x00 0x00` | | 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}.<br>* Response:<br> * `u32` value. | | Version Query | `0x00 0x00` | |<br>__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}.|

38
docs/xap_0.1.0.md
View file

@ -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. This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Version Query | `0x00 0x00` | | 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}.<br>* Response:<br> * `u32` value. | | Version Query | `0x00 0x00` | |<br>__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` | | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | | Capabilities Query | `0x00 0x01` | |<br>__Response:__ `u32`| 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. | | Enabled subsystem query | `0x00 0x02` | |<br>__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` | | 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` | |<br>__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.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Version Query | `0x01 0x00` | | 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}.<br>* Response:<br> * `u32` value. | | Version Query | `0x01 0x00` | |<br>__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` | | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | | Capabilities Query | `0x01 0x01` | |<br>__Response:__ `u32`| 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 identifiers | `0x01 0x02` | |<br>__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` | | Retrieves the name of the manufacturer | | Board Manufacturer | `0x01 0x03` | |<br>__Response:__ `string`| Retrieves the name of the manufacturer|
| Product Name | `0x01 0x04` | | Retrieves the product name | | Product Name | `0x01 0x04` | |<br>__Response:__ `string`| Retrieves the product name|
| info.json length | `0x01 0x05` | | Retrieves the length of info.json | | info.json length | `0x01 0x05` | |<br>__Response:__ `u32`| Retrieves the length of info.json|
| info.json | `0x01 0x06` | | Retrieves a chunk of info.json | | info.json | `0x01 0x06` | |<br>__Request:__ `u16`<br>__Response:__ `u8[32]`| Retrieves a chunk of info.json|
| Jump to bootloader | `0x01 0x07` | __Secure__ | 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__ |<br>__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|
| info.json | `0x01 0x08` | | Retrieves a unique identifier for the board. | | info.json | `0x01 0x08` | |<br>__Response:__ `u32[4]`| Retrieves a unique identifier for the board.|
### Keyboard - `0x02` ### Keyboard - `0x02`
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP. This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.

66
docs/xap_0.2.0.md
View file

@ -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. This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Version Query | `0x00 0x00` | | 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}.<br>* Response:<br> * `u32` value. | | Version Query | `0x00 0x00` | |<br>__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` | | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | | Capabilities Query | `0x00 0x01` | |<br>__Response:__ `u32`| 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. | | Enabled subsystem query | `0x00 0x02` | |<br>__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` | | 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` | |<br>__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.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Version Query | `0x01 0x00` | | 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}.<br>* Response:<br> * `u32` value. | | Version Query | `0x01 0x00` | |<br>__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` | | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | | Capabilities Query | `0x01 0x01` | |<br>__Response:__ `u32`| 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 identifiers | `0x01 0x02` | |<br>__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` | | Retrieves the name of the manufacturer | | Board Manufacturer | `0x01 0x03` | |<br>__Response:__ `string`| Retrieves the name of the manufacturer|
| Product Name | `0x01 0x04` | | Retrieves the product name | | Product Name | `0x01 0x04` | |<br>__Response:__ `string`| Retrieves the product name|
| info.json length | `0x01 0x05` | | Retrieves the length of info.json | | info.json length | `0x01 0x05` | |<br>__Response:__ `u32`| Retrieves the length of info.json|
| info.json | `0x01 0x06` | | Retrieves a chunk of info.json | | info.json | `0x01 0x06` | |<br>__Request:__ `u16`<br>__Response:__ `u8[32]`| Retrieves a chunk of info.json|
| Jump to bootloader | `0x01 0x07` | __Secure__ | 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__ |<br>__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|
| info.json | `0x01 0x08` | | Retrieves a unique identifier for the board. | | info.json | `0x01 0x08` | |<br>__Response:__ `u32[4]`| Retrieves a unique identifier for the board.|
### Keyboard - `0x02` ### Keyboard - `0x02`
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP. 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. This subsystem allows for live modifications of the keymap, allowing keys to be reassigned without rebuilding the firmware.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Capabilities Query | `0x04 0x00` | | Dynamic Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | | Capabilities Query | `0x04 0x00` | |<br>__Response:__ `u32`| Dynamic Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Layer Count | `0x04 0x01` | | TODO | | Get Layer Count | `0x04 0x01` | |<br>__Response:__ `u8`| Query maximum number of layers that can be addressed within the keymap.|
| Get Keycode | `0x04 0x02` | | TODO | | Get Keycode | `0x04 0x02` | |<br>__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Row: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Column: `u8`<br>__Response:__ `u16`| Query the Keycode at the requested location.|
| Set Keycode | `0x04 0x03` | __Secure__ | TODO | | Set Keycode | `0x04 0x03` | __Secure__ |<br>__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.|
### Dynamic Encoders - `0x05` ### Dynamic Encoders - `0x05`
This subsystem allows for live modifications of the keymap, allowing encoder functionality to be reassigned without rebuilding the firmware. This subsystem allows for live modifications of the keymap, allowing encoder functionality to be reassigned without rebuilding the firmware.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Capabilities Query | `0x05 0x00` | | Dynamic Encoders subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | | Capabilities Query | `0x05 0x00` | |<br>__Response:__ `u32`| Dynamic Encoders subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
| Get Keycode | `0x05 0x02` | | TODO | | Get Keycode | `0x05 0x02` | |<br>__Request:__<br>&nbsp;&nbsp;&nbsp;&nbsp;* Layer: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Encoder: `u8`<br>&nbsp;&nbsp;&nbsp;&nbsp;* Clockwise: `u8`<br>__Response:__ `u16`| Query the Keycode at the requested location.|
| Set Keycode | `0x05 0x03` | __Secure__ | TODO | | Set Keycode | `0x05 0x03` | __Secure__ |<br>__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.
| Name | Route | Tags | Definition | | Name | Route | Tags | Payloads | Description |
| -- | -- | -- | -- | | -- | -- | -- | -- | -- |
| Capabilities Query | `0x06 0x00` | | Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | | Capabilities Query | `0x06 0x00` | |<br>__Response:__ `u32`| Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.|
## Broadcast messages ## Broadcast messages