Android 16 introduced the Ranging module. This protocol and payload specification defines the message sequence and the payload of out-of-band (OOB) communication used to exchange ranging configurations, and to start and stop ranging, between the initiator and the responder device that engage in ranging.
The main goal of this page is to enable non-Android device providers to implement this specification so that their devices can be compatible for ranging with Android devices.
Messages and message sequence
This section describes the messages and the sequence of the message exchange.
The following table shows all of the messages that are present in the OOB exchange:
| Message | Message ID |
|---|---|
Ranging Capability Request |
0x0 |
Ranging Capability Response |
0x1 |
Ranging Configuration |
0x2 |
Ranging Configuration Response (optional) |
0x3 |
Stop Ranging |
0x6 |
Stop Ranging Response (optional) |
0x7 |
As shown in Figures 1 and 2, how the message exchange is triggered depends on the communication channel.
For connection-based communication channels such as BLE GATT, the message
exchange starts with the initiator device sending Ranging Capability Request
to the responder device. The responder device replies by sending Ranging
Capability Response, as shown in Figure 1:
Figure 1. OOB message exchange using a connection-based communication channel.
For advertisement-based communication channels, the responder device starts by
advertising Ranging Capability. In this case, Ranging Capability Request
isn't sent from the initiating device. Instead, after detecting the
advertisement, when the initiating (initial scanner) device is ready, it
responds by advertising Ranging Configuration as its first message, as shown
in Figure 2:
Figure 2. OOB message exchange using an advertisement-based communication.
The rest of the message exchange is the same in both cases. The responder device
starts ranging immediately after receiving the Ranging Configuration message.
The responder device stops ranging after it receives or detects the Stop
Ranging message.
In the connection-based flow, the responder device populates the capabilities
only of the ranging technologies requested in the Ranging Capability Request
message, while in the advertisement flow, the responder device must list all of
its capabilities because there is no preceding capability request message.
The initiator device assumes it will receive only one response to any request
message it sends. The responder device must not make any such assumption so that
it can respond to any request in any order. This ensures that the responder
device can respond to multiple consecutive Ranging Capability Request
messages, or any other out of order messages, from the initiator device.
Ranging technology IDs
The IDs of the ranging technologies are listed in the following table:
| Ranging technology | ID |
|---|---|
| UWB | 0x0 |
| CS | 0x1 |
| Wi-Fi NAN RTT | 0x2 |
| RSSI | 0x3 |
| RFU | 0x4 - 0xFF |
These IDs are used in the following tables where the ranging technology ID is required. For fields containing ranging technology bitfield, a bit corresponding to the index of the ID of the technology is set when that technology is included in the bitfield.
For example, RSSI has an ID value 3, but if RSSI is included in the ranging technology bitfield, then the bit with position of the ID (3) must be switched on (first bit being at position 0), which makes the resulting value of the bitfield 0x8. If both UWB and RSSI are included, then the value of the bitfield is 0x0A (both bits 0 and 3 switched on).
Message format
Each message consists of a header and a payload.
Figure 3. Message format.
Header
Size: 2 bytes
Description: Common across all messages, the header is the first part that
goes into a message. The header contains a version and the ID of the message
type. The version field specifies the version of this specification that the
contents of the message conform to. The current version of this specification is
1. For more information on how versioning is used between devices on different
versions, see Versioning. The header
remains backward compatible across different versions, which means the use case
can always parse it to determine the version and the ID of the message.
The header is summarized in the following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Version | 0x1 - Current version |
| 1 | unit8 | Message ID |
|
Payload
Size: Varies (depends on the type of the message)
Description: Payload is the last part of the message, after the header. The payload depends on the type of the message. The format for the payload of each individual message type is defined in the following sections.
Ranging Capability Request message payload
Size (header size not included): 2 bytes
Description: Sent by the initiator device to initiate the message exchange.
This message is optional when the communication channel is based on advertising,
in which case the responder device is required to advertise a Ranging
Capability message as the first step. The initiator device (initial scanner)
reads the advertisement and directly responds with a Ranging Capability
message, avoiding the need for this message.
The Ranging Capability Request message payload is summarized in the following
table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8*2 | Requested ranging technologies bitfield |
|
Ranging Capability Response message payload
Size (header size not included): Varies (common part 2 bytes plus the size of each included ranging technology bytes)
Description: Sent by the responder as a response to a Ranging Capability
Request message. This message payload consists of the common part, and ranging
technology-specific parts (BLE CS, Wi-Fi NAN RTT CS, BLE RSSI), as shown in the
following tables. Each ranging technology-specific part must be added only if
that ranging technology is supported by the responder device and is requested in
the Ranging Capability Request message. In the case of an advertisement
communication channel, all supported ranging technologies must be included.
The common Ranging Capability Response message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8*2 | Supported ranging technologies bitfield. Indicates the set of capabilities of ranging technologies that follow in the rest of the payload. |
|
| 2 | byte array | Ranging technology capability bytes. | Repeated blocks of structs defined per technology. |
The UWB Ranging Capability Response message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x0 - UWB |
| 1 | uint8 | Size | Size of UWB capabilities bytes (including Technology ID and Size fields) in bytes. |
| 2 | uint8*2 | UWB address | 2 byte device UWB address. |
| 4 | uint8*4 | Supported channels bitfield | Bitfield of supported channels. Bit set to 0 indicates not supported, 1 indicates supported. Bit 0 corresponds to channel 0.LSB == channel 0MSB == channel 31 |
| 8 | uint8*4 | Supported preamble index bitfield | Bitfield of supported preamble indexes. Bit set to 0 indicates not supported, 1 indicates supported. Bit 0 corresponds to preamble index 1.LSB == preamble index 1MSB == preamble index 32 |
| 12 | uint8*4 | Supported config IDs bitfield | Bitfield of supported UWB config IDs. Bit set to 0 indicates not supported, 1 indicates supported.LSB == config Id 0> MSB == config Id 31 |
| 16 | uint8*2 | Supported minimum ranging interval | Indicates the fastest supported ranging interval in milliseconds. Allowed values (in ms):
|
| 18 | uint8 | Supported minimum slot duration | Indicates the smallest supported slot duration in milliseconds. For example, if the device returns 1 ms then it's assumed it also supports 2 ms+ slot durations. Allowed values (in ms):
|
| 19 | Supported UWB device role bitfield | Bitfield of the supported UWB roles. For example, if both supported the final field value is 0x3.
|
The BLE CS Ranging Capability Request message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x1 - BLE CS |
| 1 | uint8 | Size | Size of BLE CS capabilities bytes (including Technology ID and Size fields) in bytes. |
| 2 | uint8 | Supported security type bitfield | Bitfield of supported security types for BLE CS.
|
| 3 | uint8*6 | Device address | The address of the device used for BLE CS; in big endian order. |
The Wi-Fi NAN RTT CS Ranging Capability Request message payload is summarized
in the following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x2 - Wi-Fi NAN RTT |
| 1 | uint8 | Size | Size of BLE RSSI capabilities bytes (including Technology ID and Size fields) in bytes. |
| 2 | uint8 | Supported features bitfield | Bitfield of supported features.
|
| 3 | uint8 | Supports periodic ranging |
|
| 4 | uint8 | Supported bandwidth | This information helps derive the achievable ranging accuracy using Wi-Fi NAN and can help apps determine whether to use UWB, BLE CS, BLE RSSI, or Wi-Fi NAN for ranging.
|
| 5 | uint8 | Supported number of receive chains | This information helps derive the achievable ranging accuracy using Wi-Fi NAN and can help apps determine whether to use UWB, BLE CS, BLE RSSI, or Wi-Fi NAN for ranging.
|
The BLE RSSI Ranging Capability Request message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x3 - BLE CS |
| 1 | uint8 | Size | The size of BLE RSSI capabilities bytes (including Technology ID and Size fields) in bytes |
| 2 | uint8*6 | Device address | The address of the device used for BLE RSSI; in big endian order |
Ranging Configuration message payload
Size (header size not included): Varies (common part 4 bytes plus the size of each included ranging technology bytes).
Description: This message is sent by the initiator and it contains the configurations that each ranging technology can start ranging with. The responder device must try to start ranging with each indicated ranging technology upon receiving this message. This message payload consists of the common part, and ranging technology-specific parts (UWB, BLE CS, Wi-Fi NAN RTT, BLE RSSI), as shown in the following tables.
The common Ranging Configuration message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8*2 | Ranging technologies configuration set bitfield | Bitfield of ranging technologies that this message contains configuration data for and for which configuration parameters must be set.
|
| 2 | uint8*2 | Bitfield | RFU. Must be set to the same value as the Ranging technologies configuration set bitfield field. |
| 4 | byte array | Ranging technologies configurations bytes | Repeated blocks of structs defined per technology |
The UWB Ranging Configuration message payload is summarized in the following
table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x0 - UWB |
| 1 | uint8 | Size | Size of UWB configuration (including Technology ID and Size fields) in bytes |
| 2 | uint8*2 | UWB address | 2 byte device UWB address |
| 4 | uint8*4 | Session ID | Generated session ID. Session ID is a unique identifier for the ranging session between the phone and the peripheral. |
| 8 | uint8 | Selected config ID | Selected config ID number in integer. The config ID specifies the timing parameters and the type of security that must be used for the UWB ranging session. |
| 9 | uint8 | Selected channel | Selected channel for the UWB ranging session |
| 10 | uint8 | Selected preamble index | Selected preamble index for the UWB ranging session |
| 11 | uint8*2 | Selected ranging interval | Selected ranging interval rate in milliseconds. Allowed values (in ms):
|
| 13 | uint8 | Selected slot duration | Selected slot duration in milliseconds. Allowed values (in ms):
|
| 14 | uint8 | Session key length | Length of the session key in bytes |
| 15 | byte array | Session key | Session key. If S-STS is used then the first two bytes are VENDOR ID and the following six bytes are STATIC STS IV. If P-STS is used, this is either a 16 byte or 32 byte session key. The type of security used is determined by the config ID. |
| varies | uint8*2 | Country code | ISO 3166-1 alpha-2 country code, represented by two ASCII characters |
| varies | uint8 | Selected device role |
|
| varies | uint8 | Selected device mode |
|
The BLE CS Ranging Configuration message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x1 - BLE CS |
| 1 | uint8 | Size | Size of BLE CS configuration (including Technology ID and Size fields) in bytes |
| 2 | uint8 | Selected security type | Selected security type. Allowed values:
|
| 3 | uint8*6 | Device address | The address of the device used for BLE CS; in big endian order |
The Wi-Fi NAN RTT Ranging Configuration message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x2 - Wi-Fi NAN RTT |
| 1 | uint8 | Size | Size of Wi-Fi NAN RTT configuration (including Technology ID and Size fields) in bytes |
| 2 | uint8 | Service name length | Length of the Service name field in bytes. Refer to Wi-Fi Aware Specification v4.0 section 1.3.3 Table 1. Definitions. |
| 3 | byte array | Service name | Service name. Refer to Wi-Fi Aware Specification v4.0 section 1.3.3 Table 1. Definitions. |
| varies | uint8 | Device role |
|
| varies | uint8 | Use periodic ranging |
|
The BLE RSSI Ranging Configuration message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8 | Ranging technology ID | 0x3 - BLE RSSI |
| 1 | uint8 | Size | Size of BLE RSSI configuration (including Technology ID and Size fields) in bytes |
| 2 | uint8*6 | Device address | The address of the device used for BLE RSSI; in big endian order |
Ranging Configuration Response message payload
Size (header size not included): 2 bytes
Description: This message is sent by the responder as a response to the
Ranging Configuration message. This message is optional, it's required only
when the used communication channel requires an explicit response for each
request.
The Ranging Configuration Response message payload is summarized in the
following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8*2 | Ranging technologies configuration set successfully bitfield | Bitfield of ranging technologies that were set successfully. The bitfield sets the ranging technology bit to 1 if the technology was requested and set successfully, and 0 otherwise.
|
Stop Ranging message payload
Size (header size not included): 2 bytes
Description: This message is sent by the initiator device when it's time to stop ranging with the specified ranging technology.
The Stop Ranging message payload is summarized in the following table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8*2 | Ranging technologies to stop bitfield | Bitfield of ranging technologies that must stop ranging. Bit set to 1 indicates the ranging technology must stop ranging, and 0 indicates the ranging technology either wasn't ranging in the first place, or that it must continue ranging if it was already ranging. For some ranging technologies (like CS) this is a no-op because ranging is initiated and stopped only on the initiator side.
|
Stop Ranging Response message payload
Size (header size not included): 2 bytes
Description: This message is sent by the responder as a response to the
Stop Ranging message. This message is optional, it's required only when the
used communication channel requires an explicit response for each request.
The Stop Ranging Response message payload is summarized in the following
table:
| Octet | Data type | Description | Value |
|---|---|---|---|
| 0 | uint8*2 | Ranging technologies stopped successfully bitfield | Bitfield of ranging technologies that stopped ranging successfully. The bitfield sets the ranging technology bit to 1 if the technology was requested to be stopped and if it stopped successfully, and 0 otherwise.
|
Versioning
The version of the specification is contained in the header of each message. This section defines how communication is conducted when one of the devices (either the initiator or the responder) is on an older version than the other device.
Case 1: Connection-based communication channel
This section describes cases that use a connection-based communication channel,
where Ranging Capability Request is the first message sent by the initiator
device.
Case 1.a: Initiator supports newer version, responder supports older version of specification.
The initiator device sends the Ranging Capability Request message with the
newer version. The responder device supports only the older version, so it
responds with that, and then the responder's older version is used for the rest
of the message exchange. This means that the Ranging Capability Request
message has to be backward compatible.
Case 1.b: Initiator supports older version, responder supports newer version of specification.
The responder device sees that the initiator device isn't capable of using the newer version so it sends messages only using the older version requested initially by the initiator device.
Case 2: Advertisement-based communication channel
This section describes cases that use an advertisement-based communication
channel, where the responder device advertises Ranging Capability Request
directly, without an initial request.
Case 2.a: Initiator supports newer version, responder supports older version of specification.
The older version set in the Ranging Capability Response advertisement is used
for the rest of the communication.
Case 2.b: Initiator supports older version, responder supports newer version of specification.
The newer version of the Ranging Capability Response advertisement must be
backward compatible so that the initiator device can read the message even
though it's using a newer version. The initiator device then sends the Ranging
Configuration message using the older version it supports. This is the version
that is used for the rest of the communication.
To make sure Ranging Capability Response is backward compatible, any new
fields that are added to the next version of this specification in the Ranging
Capability Response message payload must be appended to the end of the payload,
and none of the existing fields can be modified. When parsing the configuration,
if the indicated size is bigger than expected, additional fields must be ignored
by any device that can only understand the older version of the specification.
Fragmentation
This specification is communication channel agnostic, so it doesn't define how to fragment the message payload in cases where a single message is too big to fit into a transfer packet of the communication channel used. The Ranging module expects to receive each message in its full form. The responsibility of the fragmentation lies on the implementor of the OOB communication channel.
Ranging-technology-specifics
This section contains details specific to ranging technology.
Ultra-wideband (UWB) specifics
This section describes ultra-wideband specific details.
Config IDs
OOB configuration data exchanged for UWB doesn't contain a full set of available configurable parameters that UWB requires to start an UWB ranging session. This is because some parameters are implicitly selected by the chosen config ID.
Each config ID is a set of predefined UWB configuration parameters that is
documented in
UwbRangingParams. The
responder device sends a list of all config IDs that it supports as part of the
capability response message, and the initiator selects one of the supported
config IDs that is used. This allows for a smaller set of config parameters to
be exchanged during OOB. It also limits the amount of possible combinations of
parameters that can be used for ranging with UWB, which makes testing of only
allowed combinations of parameters possible.
Requesting capabilities after each UWB session
After stopping an existing UWB session and before starting a new UWB session, the initiator device must request the capabilities of the responder device and set the configuration parameters again, because the UWB address can rotate as soon as the current ranging session ends.
BLE channel sounding (CS) specifics
This section describes channel sounding specific details.
Required bond between devices
An existing bond between the initiator and the responder device is required for ranging using channel sounding to work. This specification doesn't provide a way for creating a bond between devices. The user of the Ranging APIs must establish this bond between the devices.
Action required by the responder side for CS
In UWB, both devices are required to call the UWB start ranging and stop ranging
API explicitly. In contrast, for CS, only the initiator device is required to
start CS ranging by calling the Bluetooth (BT) stack. The rest of the
initialization on the responder side happens in band through BT. This means that
upon receiving the Ranging Configuration message or the Stop Ranging message
for CS, the responder side doesn't have to do anything if BT is enabled. The
responder device could use those messages as a trigger to update the UI or, for
example, blink the device LEDs.