Fix xap docs gen + clarify some broadcast messages

data/templates/xap/docs/broadcast_messages.md.j2

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

data/templates/xap/docs/docs.md.j2

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

data/templates/xap/docs/response_flags.md.j2

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

data/templates/xap/docs/routes.md.j2

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

data/templates/xap/docs/term_definitions.md.j2

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

data/templates/xap/docs/type_docs.md.j2

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

data/xap/xap_0.1.0.hjson

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

docs/xap_0.0.1.md

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

docs/xap_0.1.0.md

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

docs/xap_0.2.0.md

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