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
UWB country code configuration
As shown in Figure 1, the UWB framework configures the UWB country code
during UWB stack initialization using the vendor-space UCI command
ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). The UWB framework attempts to
determine the UWB country code using the following sources (listed in priority
order). The UWB framework stops at the first source where the country code is determined.
- Override country code: Country code forced through an adb shell command (local or automated testing).
- Telephony country code: Country code retrieved through cellular. If there are multiple SIMs that return different codes, the country code chosen is nondeterministic.
- Wi-Fi country code: Country code retrieved through Wi-Fi (80211.ad).
- Last known telephony country code: Last known country code retrieved through cellular. If there are multiple SIMs that return different codes, the country code chosen is nondeterministic.
- Location country code: Country code retrieved from the
LocationManagerfused location provider. - OEM default country code: Country code set by the device manufacturer.
If the UWB framework is unable to determine a UWB country code, it calls the
ANDROID_SET_COUNTRY_CODE UCI command with a value of
DEFAULT_COUNTRY_CODE ("00") and notifies UWB apps that
the UWB stack state is DISABLED. Later on, when the UWB framework is able to determine a
valid country code, it configures the new country code using the
ANDROID_SET_COUNTRY_CODE command and notifies UWB apps that the UWB stack
is READY.
If UWB can't be used
due to local regulations in a country, the UWB controller returns the
STATUS_CODE_ANDROID_REGULATION_UWB_OFF status code. The UWB framework then notifies
UWB apps that the UWB stack state is DISABLED.
When a user travels to a different country, the UWB framework configures a new country
code using the ANDROID_SET_COUNTRY_CODE UCI command. Depending on the status code returned by the UWB controller (based on the UWB regulations in the new country), this might lead to a change in the UWB stack state.
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 Wi-Fi, or hardcoded by the OEM). The country code is sent
as a 2 byte value corresponding to the ISO-3166 country code. A
value of |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
Used by the notification to get UWB ranging diagnostics stats.
Supported only if
UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS is set
to 1.
|
|
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 | |
ENABLE_DIAGNOSTICS |
1 | 0xE8 |
2 | 1-byte value to enable or disable diagnostics reporting.
Configure this parameter only when Values:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 or 4 | 0xE9 |
2 | 1-byte or 4-byte bitmask to configure diagnostics reporting. This bitmask is 1 byte in Android 14 or higher and 4 bytes in Android 13 or lower. Configure this parameter only when the
Bit definitions:
|
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 |
4 | 0xE4 |
2 | 4 byte value indicating the supported minimum ranging interval in milliseconds. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 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:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU |
4 | 0xE8 |
2 | 4 byte value indicating the supported minimum slot duration in RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | 4 byte value indicating the supported maximum number of FiRa ranging sessions. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | 2 byte bitmask to indicate the channels that support AoA. Each
Values:
|
Status codes
The following are the status codes in the vendor space. These are returned in
UCI responses (such as SESSION_START_RSP) by the UWB subsystem (UWBS).
| Status code | Value | Description |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
Status code returned when the current ranging session can't be started due to conflict with other CCC or FiRa ranging sessions. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Status code returned when the current ranging session can't be started due to UWB regulatory reasons. |
State change reason code in SESSION_STATUS_NTF
The following are the state change reason codes defined in the vendor space for
the status field returned by a UWBS in SESSION_STATUS_NTF. This notification
is sent by the UWBS when the state of a ranging session changes (for example,
from ACTIVE to IDLE).
| State change reason code | Value | Description |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
Session state changed because the configured channel doesn't support AoA ranging. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
Session state changed because of conflict with other CCC or FiRa ranging sessions. |
REASON_REGULATION_UWB_OFF |
0x82 |
Session state changed because the UWB must be disabled due to a regulatory reason. |