4.9 KiB
QMK Firmware XAP Specs
This document describes the requirements of the QMK XAP ("extensible application protocol") API.
Types
All integral types are little-endian.
Name | Definition |
---|---|
struct{} | A structure of data, packing different objects together. Data is "compacted" -- there are no padding bytes between fields. Equivalent to a 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. |
u32 | An unsigned 32-bit integral, commonly seen as uint32_t from stdint.h. |
u64 | An unsigned 64-bit integral, commonly seen as uint64_t from stdint.h. |
u8 | An unsigned 8-bit integral (octet, or byte), commonly seen as uint8_t from stdint.h. |
Definitions
This list defines the terms used across the entire set of XAP protocol documentation.
Name | Definition |
---|---|
Capability | A way to determine if certain functionality is enabled in the firmware. Any subsystem that provides build-time restriction of functionality must provide a route for a capabilities query. |
Handler | A piece of code that is executed when a specific route is received. |
ID | A single octet / 8-bit byte. |
Payload | Any received data appended to the route, which gets delivered to the handler when received. |
Response | The data sent back to the host during execution of a handler. |
Response Flags | An u8 containing the status of the request. |
Route | A sequence of IDs describing the route to invoke a handler. |
Secure Route | A route which has potentially destructive consequences, necessitating prior approval by the user before executing. |
Subsystem | A high-level area of functionality within XAP. |
Token | A u16 associated with a specific request as well as its corresponding response. |
Unlock sequence | A physical sequence initiated by the user to enable execution of secure routes. |
Requests and Responses
Communication generally follows a request/response pattern.
Each request needs to include a token -- this u16
value prefixes each outbound request from the host application and its corresponding response, allowing repsonse messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. Host applications should randomly generate a token ID for every outbound request, unless using a reserved token defined below.
This token is followed by a u8
signifying the length of data in the request.
Two token values are reserved: 0x0000
and 0xFFFF
:
0x0000
: A message sent by a host application may use this token if no response is to be sent -- a "fire and forget" message.0xFFFF
: Signifies a "broadcast" message sent by the firmware without prompting from the host application. Broadcast messages are defined later in this document.
Any request will generate at least one corresponding response, with the exception of messages using reserved tokens. Maximum total message length is 128 bytes due to RAM constraints.
Response messages will always be prefixed by the originating request token, directly followed by that request's response flags, then the response payload length:
Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0 |
---|---|---|---|---|---|---|---|
Unlocked | Unlocking | - | - | - | - | Secure Failure | Success |
Bit 7
: When this bit is set, an unlock sequence has completed, and secure routes may be invoked.Bit 6
: When this bit is set, an unlock sequence is in progress.Bit 1
: When this bit is set, the requested route was marked secure but an unlock sequence has not completed.Bit 0
: 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:
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 |
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.