Update reserved tokens

data/xap/xap_0.0.1.hjson

@@ -48,7 +48,10 @@
 
             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.
+            Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response.
+            This allows 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.
+            To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`.
 
             This token is followed by a `u8` signifying the length of data in the request.
             '''
@@ -146,7 +149,7 @@
 
         token: {
             name: Token
-            description: A `u16` associated with a specific request as well as its corresponding response.
+            description: A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`.
             type: u16
         }
 

data/xap/xap_0.1.0.hjson

@@ -13,8 +13,8 @@
 
         reserved_tokens:
             '''
-            Two token values are reserved: `0x0000` and `0xFFFF`:
+            Two token values are reserved: `0xFFFE` 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.
+            * `0xFFFE`: 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.

docs/xap_0.0.1.md

@@ -28,13 +28,16 @@ This list defines the terms used across the entire set of XAP protocol documenta
 | _Request Header_ | Packet format for inbound data. Takes the format:<br>`token` - token<br>`u8` - length |
 | _Response Flags_ | An `u8` containing the status of the request. |
 | _Response Header_ | Packet format for outbound data. Takes the format:<br>`token` - token<br>`response_flags` - flags<br>`u8` - length |
-| _Token_ | A `u16` associated with a specific request as well as its corresponding response. |
+| _Token_ | A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`. |
 
 ## 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.
+Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response.
+This allows 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.
+To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`.
 
 This token is followed by a `u8` signifying the length of data in the request.
 

docs/xap_0.1.0.md

@@ -34,18 +34,21 @@ This list defines the terms used across the entire set of XAP protocol documenta
 | _Request Header_ | Packet format for inbound data. Takes the format:<br>`token` - token<br>`u8` - length |
 | _Response Flags_ | An `u8` containing the status of the request. |
 | _Response Header_ | Packet format for outbound data. Takes the format:<br>`token` - token<br>`response_flags` - flags<br>`u8` - length |
-| _Token_ | A `u16` associated with a specific request as well as its corresponding response. |
+| _Token_ | A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`. |
 
 ## 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.
+Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response.
+This allows 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.
+To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`.
 
 This token is followed by a `u8` signifying the length of data in the request.
 
-Two token values are reserved: `0x0000` and `0xFFFF`:
+Two token values are reserved: `0xFFFE` 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.
+* `0xFFFE`: 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.

docs/xap_0.2.0.md

@@ -34,18 +34,21 @@ This list defines the terms used across the entire set of XAP protocol documenta
 | _Request Header_ | Packet format for inbound data. Takes the format:<br>`token` - token<br>`u8` - length |
 | _Response Flags_ | An `u8` containing the status of the request. |
 | _Response Header_ | Packet format for outbound data. Takes the format:<br>`token` - token<br>`response_flags` - flags<br>`u8` - length |
-| _Token_ | A `u16` associated with a specific request as well as its corresponding response. |
+| _Token_ | A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`. |
 
 ## 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.
+Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response.
+This allows 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.
+To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`.
 
 This token is followed by a `u8` signifying the length of data in the request.
 
-Two token values are reserved: `0x0000` and `0xFFFF`:
+Two token values are reserved: `0xFFFE` 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.
+* `0xFFFE`: 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.

lib/python/qmk/cli/xap/xap_client.py

@@ -18,9 +18,9 @@ ResponseStruct = Struct('<HBB60s')
 
 
 def _gen_token():
-    """Generate XAP token - cannot start with 00xx or be FFFF
+    """Generate XAP token - cannot start with 00xx or 'reserved' (FFFE|FFFF)
     """
-    token = random.randrange(0x0100, 0xFFFE)
+    token = random.randrange(0x0100, 0xFFFD)
 
     # swap endianness
     return unpack('<H', pack('>H', token))[0]