The AOSP
ultra-wideband (UWB) stack
uses the
FiRa-defined UCI interface
as the HAL surface. The HAL interface uses an opaque pipe
(IUwbChip::sendUciMessage() and IUwbClientCallback::onUciMessage()) to send
and receive UWB command interface (UCI) commands, responses, and notifications.
All Android UWB vendors must support all the FiRa specification defined
messages. The UWB framework is backward compatible and works with any UCI
version implemented by the UWB vendor on the device. Because the AOSP UWB
framework is a module,
it can also selectively add support for approved change requests (CRs) from
draft UCI specifications targeted for major FiRa standards releases. Any such
draft CRs implemented are subject to change.
Interface definition
The UWB HAL interface is defined using
stable AIDL.
The main interface uses the android.hardware.uwb package.
The following are the two main interfaces in the android.hardware.uwb
package.
IUwbChip.aidl
package android.hardware.uwb;
interface IUwbChip {
String getName();
void open(in android.hardware.uwb.IUwbClientCallback clientCallback);
void close();
void coreInit();
void sessionInit(int sessionId);
int getSupportedAndroidUciVersion();
int sendUciMessage(in byte[] data);
}
IUwbClientCallback.aidl
package android.hardware.uwb;
interface IUwbClientCallback {
oneway void onUciMessage(in byte[] data);
oneway void onHalEvent(in android.hardware.uwb.UwbEvent event, in android.hardware.uwb.UwbStatus status);
}
HAL call flow from UWB framework
This following images illustrate the call flow from the UWB framework for the UWB stack initialization, UWB stack deinitialization, and UWB session start and stop processes.
Figure 1. UWB stack initialization call flow (UWB toggle on)
Figure 2. UWB stack deinitialization call flow (UWB toggle off)
Figure 3. UWB session start/stop flow
FIRA UCI specification-defined command format
For the format of UCI control packets, see section 4.4.2 of the UCI specification.
Interface versioning
The UCI specification lets UWB vendors expose the version of the UCI stack
implemented by the device using the UCI_GET_DEVICE_INFO_RSP and
UCI_GET_CAPS_INFO_RSP commands. The framework uses these commands to fetch the
UCI version of the device and change its behavior accordingly.
List of draft CRs supported by the UWB module
The following draft CRs for FiRa 2.0 are supported by UWB module version #330810000:
Android UCI interface (FiRa vendor portion)
The UCI specification defines a set of group identifiers (GIDs) and opcode identifiers (OIDs) for all the specification-defined messages. The specification also reserves a set of GIDs reserved exclusively for vendor usage. The AOSP UWB stack uses some of these vendor GIDs and OIDs for Android-specific commands that aren't defined in the specification. For details, see section 8.4 of the UCI specification.
These vendor messages used by Android are defined in the
android.hardware.uwb.fira_android HAL package.
Vendor interface versioning
UWB vendors must expose the version of the android.hardware.uwb.fira_android
HAL package supported on the device through
IUwbChip.getSupportedAndroidUciVersion(). The framework uses this
versioning information to handle backward compatibility.
List of Android GIDs and OIDs
The following table lists the GIDs and OIDs for Android. GIDs 0xE and 0xF are
reserved for Android OEMs to use.
| GID | OID | Definition |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Used by the command and response to get UWB power related stats.
Supported only if
UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY
is set to 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Used to set the current regulatory country code (determined using SIM or hardcoded by OEM). | |
OEM = 0xE,0xF |
0x00 - 0x3F |
Reserved for OEM use. |
Vendor extensions to UCI specification defined messages
This section describes details of vendor extensions to UCI specification-defined messages.
SESSION_SET_APP_CONFIG_[CMD|RSP] and SESSION_GET_APP_CONFIG_[CMD|RSP]
The following are the type length values (TLVs) defined by AOSP stack in the
vendor reserved portion of the TLVs in APP_CONFIG:
- GID: 0001b (UWB session config group)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD)
The following table lists the parameters for UWB session config messages.
| Parameter name | Length (octets) |
Tag (IDs) |
Vendor interface version | Description |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS |
1 | 0xE3 |
1 | Interleaving ratio if AOA_RESULT_REQ is set
to 0xF0. Supported only if the
UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING
set to 1. |
NB_OF_AZIMUTH_MEASUREMENTS |
1 | 0xE4 |
1 | |
NB_OF_ELEVATION_MEASUREMENTS |
1 | 0xE5 |
1 |
CORE_GET_CAPS_INFO_RSP
The following are the TLVs defined by the AOSP stack in the vendor reserved
portion of the TLVs in CAPS_INFO:
- GID: 0000b (UWB core group)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
The following table lists the parameters for UWB capability messages.
| Parameter name | Length (octets) |
Tag (IDs) |
Vendor interface version | Description |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | 1 byte value indicating support for power stats query. Values:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | 1 byte value indicating support for the antenna interleaving feature. Values:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
1 | 0xE4 |
2 | 4 byte value indicating the supported minimum ranging interval in milliseconds. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
1 | 0xE5 |
2 | 4 byte bitmask indicating the supported
RANGE_DATA_NTF_CONFIG values.
Bitmask where each bit corresponds to values used in
RANGE_DATA_NTF_CONFIG in SET_APP_CFG_CMD. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | 1 byte value indicating the support of RSSI reporting. Values:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | 1 byte value indicating the support of diagnostics reporting. Values:
|