qmk_firmware/data/xap/xap_0.0.1.hjson

{
    version: 0.0.1

    // Needed for table generation
    define: XAP_ROUTE

    // Documentation section is used purely for `qmk xap-generate-docs`.
    documentation: {
        order: [
            page_header
            type_docs
            !type_docs.md.j2
            term_definitions
            !term_definitions.md.j2
            request_response
            reserved_tokens
            response_flags
            !response_flags.md.j2
            example_conversation
        ]

        page_header:
            '''
            # QMK Firmware XAP Specs

            This document describes the requirements of the QMK XAP ("extensible application protocol") API.
            '''

        type_docs:
            '''
            ## Types

            **All integral types are little-endian.**
            '''

        term_definitions:
            '''
            ## Definitions

            This list defines the terms used across the entire set of XAP protocol documentation.
            '''

        request_response:
            '''
            ## 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 response 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.
            '''

        // This documentation section reserved for next version
        reserved_tokens: ''

        response_flags:
            '''
            Response messages will always be prefixed by the originating request _token_, directly followed by that request's _response flags_, then the response payload length:
            '''

        example_conversation:
            '''
            ### 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` |
            '''
    }

    type_docs: {
        u8:
            '''
            An unsigned 8-bit integral (octet, or byte), commonly seen as `uint8_t` from _stdint.h_.
            '''
        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_.
            '''
        "type[n]":
            '''
            An array of `type`, with array extent of `N` -- e.g. `u8[2]` signifies two consecutive octets.
            '''
    }

    term_definitions: {
        Subsystem:
            '''
            A high-level area of functionality within XAP.
            '''
        Route:
            '''
            A sequence of _IDs_ describing the route to invoke a _handler_.
            '''
        Handler:
            '''
            A piece of code that is executed when a specific _route_ is received.
            '''
        Response:
            '''
            The data sent back to the host during execution of a _handler_.
            '''
        Payload:
            '''
            Any received data appended to the _route_, which gets delivered to the _handler_ when received.
            '''
    }

    type_definitions: {
        identifier: {
            name: ID
            description: A single octet / 8-bit byte, representing Subsystem or Route index.
            type: u8
        }

        response_flags: {
            name: Response Flags
            description: An `u8` containing the status of the request.
            type: u8
        }

        token: {
            name: Token
            description: A `u16` associated with a specific request as well as its corresponding response.
            type: u16
        }

        request_header: {
            name: Request Header
            description: Packet format for inbound data.
            type: struct
            struct_length: 3
            struct_members: [
                {
                    type: token
                    name: token
                },
                {
                    type: u8
                    name: length
                }
            ]
        }

        response_header: {
            name: Response Header
            description: Packet format for outbound data.
            type: struct
            struct_length: 4
            struct_members: [
                {
                    type: token
                    name: token
                },
                {
                    type: response_flags
                    name: flags
                },
                {
                    type: u8
                    name: length
                }
            ]
        }
    }

    response_flags: {
        define_prefix: XAP_RESPONSE_FLAG
        bits: {
            0: {
                name: Success
                define: SUCCESS
                description:
                    '''
                    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).
                    '''
            }
        }
    }

    routes: {
        0x00: {
            type: router
            name: XAP
            define: XAP
            description:
                '''
                This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
                '''
            routes: {
                0x00: {
                    type: command
                    name: Version Query
                    define: VERSION_QUERY
                    description:
                        '''
                        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.
                        '''
                    return_type: u32
                    return_purpose: bcd-version
                    return_constant: XAP_BCD_VERSION
                }
            }
        }
    }
}