mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-05-02 03:51:29 +00:00
stub out route and broadcast_message docs
This commit is contained in:
parent
d9b045a6fe
commit
a9468f385e
4
data/templates/xap/docs/broadcast_messages.md.j2
Normal file
4
data/templates/xap/docs/broadcast_messages.md.j2
Normal file
@ -0,0 +1,4 @@
|
||||
{%- for id, message in xap.broadcast_messages.messages | dictsort %}
|
||||
### {{ message.name }} - `{{ id }}`
|
||||
{{ message.description }}
|
||||
{%- endfor %}
|
12
data/templates/xap/docs/routes.md.j2
Normal file
12
data/templates/xap/docs/routes.md.j2
Normal file
@ -0,0 +1,12 @@
|
||||
{%- for id, route in xap.routes | dictsort %}
|
||||
### {{ route.name }} - `{{ id }}`
|
||||
{{ route.description }}
|
||||
|
||||
{% if route.routes %}
|
||||
| Name | Route | Definition |
|
||||
| -- | -- | -- |
|
||||
{%- for subid, subroute in route.routes | dictsort %}
|
||||
| {{ subroute.name }} | `{{ id }} {{ subid }}` | {{ subroute.description.split('\n')[0] }} |
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{%- endfor %}
|
@ -17,6 +17,8 @@
|
||||
response_flags
|
||||
!response_flags.md.j2
|
||||
example_conversation
|
||||
routes
|
||||
!routes.md.j2
|
||||
]
|
||||
|
||||
page_header:
|
||||
@ -64,17 +66,27 @@
|
||||
### Example "conversation":
|
||||
|
||||
**Request** -- version query:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Payload Length | Route | Route |
|
||||
| **Value** | `0x43` | `0x2B` | `0x02` | `0x00` | `0x00` |
|
||||
|
||||
**Response** -- matching token, successful flag, payload of `0x03170192` = 3.17.192:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Response Flags | Payload Length | Payload | Payload | Payload | Payload |
|
||||
| **Value** | `0x43` | `0x2B` | `0x01` | `0x04` | `0x92` | `0x01` | `0x17` | `0x03` |
|
||||
'''
|
||||
|
||||
routes:
|
||||
'''
|
||||
## Routes
|
||||
|
||||
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.
|
||||
'''
|
||||
}
|
||||
|
||||
type_docs: {
|
||||
|
@ -8,6 +8,7 @@
|
||||
documentation: {
|
||||
order: [
|
||||
broadcast_messages
|
||||
!broadcast_messages.md.j2
|
||||
]
|
||||
|
||||
reserved_tokens:
|
||||
@ -118,6 +119,7 @@
|
||||
Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
|
||||
|
||||
**Example Log Broadcast** -- log message "Hello QMK!"
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Broadcast Type | Length | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload |
|
||||
|
@ -92,6 +92,7 @@
|
||||
* [Unicode](feature_unicode.md)
|
||||
* [Userspace](feature_userspace.md)
|
||||
* [WPM Calculation](feature_wpm.md)
|
||||
* [XAP](xap.md)
|
||||
|
||||
* Hardware Features
|
||||
* Displays
|
||||
|
89
docs/xap.md
Normal file
89
docs/xap.md
Normal file
@ -0,0 +1,89 @@
|
||||
# XAP
|
||||
|
||||
XAP (“extensible application protocol”) API intends to provide access to various QMK subsystems.
|
||||
|
||||
## Overview
|
||||
|
||||
TODO
|
||||
|
||||
## Protocol Reference
|
||||
|
||||
[protocol_versions](xap_protocol.md ':include')
|
||||
|
||||
## Clients
|
||||
|
||||
TODO
|
||||
|
||||
## CLI
|
||||
|
||||
The QMK CLI provides a few XAP specific commands for diagnosis purposes.
|
||||
|
||||
### List Connected Devices
|
||||
Simple
|
||||
```
|
||||
$ qmk xap --list
|
||||
Ψ Available devices:
|
||||
Ψ 7844:8450 KPrepublic XD84 Pro [API:0.2.0] LOCKED
|
||||
```
|
||||
|
||||
Verbose
|
||||
```
|
||||
$ qmk --verbose xap --list
|
||||
Ψ Available devices:
|
||||
Ψ 7844:8450 KPrepublic XD84 Pro [API:0.2.0] LOCKED
|
||||
_id: 553831323538150A2113000000000000
|
||||
backlight.pin: F5
|
||||
bootloader: atmel-dfu
|
||||
community_layouts: 75_ansi, 75_iso
|
||||
debounce: 5
|
||||
diode_direction: COL2ROW
|
||||
features.audio: False
|
||||
features.backlight: True
|
||||
features.bootmagic: True
|
||||
features.command: False
|
||||
features.console: False
|
||||
features.extrakey: True
|
||||
features.mousekey: False
|
||||
features.nkro: True
|
||||
features.rgblight: True
|
||||
indicators.caps_lock: B2
|
||||
keyboard_folder: xiudi/xd84pro
|
||||
keyboard_name: XD84 Pro
|
||||
layouts: LAYOUT_75_ansi, LAYOUT_75_iso, LAYOUT_all
|
||||
maintainer: qmk
|
||||
manufacturer: KPrepublic
|
||||
matrix_pins.cols: B1, B3, B4, B5, B6, B7, C6, C7, D4, D6, D7, E6, F0, F1, F7
|
||||
matrix_pins.rows: D0, D1, D2, D3, D5, F4
|
||||
matrix_pins.unused: B0, E2
|
||||
matrix_size.cols: 15
|
||||
matrix_size.rows: 6
|
||||
mouse_key.enabled: False
|
||||
platform: unknown
|
||||
processor: atmega32u4
|
||||
processor_type: avr
|
||||
protocol: LUFA
|
||||
rgblight.animations.all: False
|
||||
rgblight.led_count: 12
|
||||
rgblight.pin: F6
|
||||
rgblight.sleep: False
|
||||
url:
|
||||
usb.device_ver: 0x0001
|
||||
usb.device_version: 0.0.1
|
||||
usb.pid: 0x8450
|
||||
usb.vid: 0x7844
|
||||
```
|
||||
|
||||
### Interactive shell
|
||||
```
|
||||
$ qmk xap -i
|
||||
Ψ Connected to:7844:8450 KPrepublic XD84 Pro
|
||||
Welcome to the XAP shell. Type help or ? to list commands.
|
||||
|
||||
Ψ> help
|
||||
|
||||
Documented commands (type help <topic>):
|
||||
========================================
|
||||
EOF about exit help keycode keymap layer listen unlock
|
||||
|
||||
Ψ>
|
||||
```
|
@ -52,14 +52,31 @@ Response messages will always be prefixed by the originating request _token_, di
|
||||
### Example "conversation":
|
||||
|
||||
**Request** -- version query:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Payload Length | Route | Route |
|
||||
| **Value** | `0x43` | `0x2B` | `0x02` | `0x00` | `0x00` |
|
||||
|
||||
**Response** -- matching token, successful flag, payload of `0x03170192` = 3.17.192:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Response Flags | Payload Length | Payload | Payload | Payload | Payload |
|
||||
| **Value** | `0x43` | `0x2B` | `0x01` | `0x04` | `0x92` | `0x01` | `0x17` | `0x03` |
|
||||
|
||||
## Routes
|
||||
|
||||
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 | Definition |
|
||||
| -- | -- | -- |
|
||||
| Version Query | `0x00 0x00` | XAP protocol version query. |
|
||||
|
||||
|
||||
|
@ -65,18 +65,79 @@ Response messages will always be prefixed by the originating request _token_, di
|
||||
### Example "conversation":
|
||||
|
||||
**Request** -- version query:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Payload Length | Route | Route |
|
||||
| **Value** | `0x43` | `0x2B` | `0x02` | `0x00` | `0x00` |
|
||||
|
||||
**Response** -- matching token, successful flag, payload of `0x03170192` = 3.17.192:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Response Flags | Payload Length | Payload | Payload | Payload | Payload |
|
||||
| **Value** | `0x43` | `0x2B` | `0x01` | `0x04` | `0x92` | `0x01` | `0x17` | `0x03` |
|
||||
|
||||
## Routes
|
||||
|
||||
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 | Definition |
|
||||
| -- | -- | -- |
|
||||
| Version Query | `0x00 0x00` | XAP protocol version query. |
|
||||
| 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 |
|
||||
| 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 | Definition |
|
||||
| -- | -- | -- |
|
||||
| Version Query | `0x01 0x00` | QMK protocol version query. |
|
||||
| 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` | Jump to bootloader |
|
||||
| info.json | `0x01 0x08` | 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.
|
||||
|
||||
|
||||
### 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_.
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
**Example Log Broadcast** -- log message "Hello QMK!"
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Broadcast Type | Length | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload |
|
||||
| **Value** | `0xFF` | `0xFF` | `0x00` | `0x0A`(10) | `0x48`(H) | `0x65`(e) | `0x6C`(l) | `0x6C`(l) | `0x6F`(o) | `0x20`( ) | `0x51`(Q) | `0x4D`(M) | `0x4B`(K) | `0x21`(!) |
|
||||
### Secure Status - `0x01`
|
||||
Secure status has changed.
|
||||
|
||||
|
@ -65,18 +65,108 @@ Response messages will always be prefixed by the originating request _token_, di
|
||||
### Example "conversation":
|
||||
|
||||
**Request** -- version query:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Payload Length | Route | Route |
|
||||
| **Value** | `0x43` | `0x2B` | `0x02` | `0x00` | `0x00` |
|
||||
|
||||
**Response** -- matching token, successful flag, payload of `0x03170192` = 3.17.192:
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Response Flags | Payload Length | Payload | Payload | Payload | Payload |
|
||||
| **Value** | `0x43` | `0x2B` | `0x01` | `0x04` | `0x92` | `0x01` | `0x17` | `0x03` |
|
||||
|
||||
## Routes
|
||||
|
||||
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 | Definition |
|
||||
| -- | -- | -- |
|
||||
| Version Query | `0x00 0x00` | XAP protocol version query. |
|
||||
| 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 |
|
||||
| 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 | Definition |
|
||||
| -- | -- | -- |
|
||||
| Version Query | `0x01 0x00` | QMK protocol version query. |
|
||||
| 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` | Jump to bootloader |
|
||||
| info.json | `0x01 0x08` | 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.
|
||||
|
||||
|
||||
### User - `0x03`
|
||||
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
|
||||
|
||||
|
||||
### Dynamic Keymap - `0x04`
|
||||
This subsystem allows for live modifications of the keymap, allowing keys to be reassigned without rebuilding the firmware.
|
||||
|
||||
|
||||
| Name | Route | 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` | TODO |
|
||||
|
||||
### Dynamic Encoders - `0x05`
|
||||
This subsystem allows for live modifications of the keymap, allowing encoder functionality to be reassigned without rebuilding the firmware.
|
||||
|
||||
|
||||
| Name | Route | 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` | TODO |
|
||||
|
||||
### Lighting - `0x06`
|
||||
This subsystem allows for control over the lighting subsystem.
|
||||
|
||||
|
||||
| Name | Route | Definition |
|
||||
| -- | -- | -- |
|
||||
| Capabilities Query | `0x06 0x00` | 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_.
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
**Example Log Broadcast** -- log message "Hello QMK!"
|
||||
|
||||
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Purpose** | Token | Token | Broadcast Type | Length | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload |
|
||||
| **Value** | `0xFF` | `0xFF` | `0x00` | `0x0A`(10) | `0x48`(H) | `0x65`(e) | `0x6C`(l) | `0x6C`(l) | `0x6F`(o) | `0x20`( ) | `0x51`(Q) | `0x4D`(M) | `0x4B`(K) | `0x21`(!) |
|
||||
### Secure Status - `0x01`
|
||||
Secure status has changed.
|
||||
|
||||
|
@ -1,5 +1,4 @@
|
||||
# XAP Protocol Reference
|
||||
|
||||
<!-- This file is generated -->
|
||||
* [XAP Version 0.2.0](xap_0.2.0.md)
|
||||
* [XAP Version 0.1.0](xap_0.1.0.md)
|
||||
* [XAP Version 0.0.1](xap_0.0.1.md)
|
||||
|
@ -30,8 +30,7 @@ def xap_generate_docs(cli):
|
||||
output_doc = QMK_FIRMWARE / "docs" / "xap_protocol.md"
|
||||
with open(output_doc, "w", encoding='utf-8') as out_file:
|
||||
out_file.write('''\
|
||||
# XAP Protocol Reference
|
||||
|
||||
<!-- This file is generated -->
|
||||
''')
|
||||
|
||||
for file in reversed(sorted(docs_list)):
|
||||
|
Loading…
Reference in New Issue
Block a user