UWB HAL interface

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.

UWB stack initialization

Figure 1. UWB stack initialization call flow (UWB toggle on)

UWB stack deinitialization

Figure 2. UWB stack deinitialization call flow (UWB toggle off)

UWB session start and stop

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.

  1. Override country code: Country code forced through an adb shell command (local or automated testing).
  2. Telephony country code: Country code retrieved through cellular. If there are multiple SIMs that return different codes, the country code chosen is nondeterministic.
  3. Wi-Fi country code: Country code retrieved through Wi-Fi (80211.ad).
  4. 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.
  5. Location country code: Country code retrieved from the LocationManager fused location provider.
  6. 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 00 is used to indicate that the country code is unknown.

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 CORE_GET_CAPS_INFO_RSP returns SUPPORTED_DIAGNOSTICS with a value of 1 indicating the diagnostics reporting feature is supported.

Values:

  • 1: Feature enabled
  • 0: Feature disabled

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 CORE_GET_CAPS_INFO_RSP returns SUPPORTED_DIAGNOSTICS with a value of 1 indicating the diagnostics reporting feature is supported.

Bit definitions:

  • b0 (0x01): Activate RSSI fields
  • b1 (0x02): Activate AoA fields
  • b2 (0x04): Activate CIR fields

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:

  • 1: Feature supported
  • 0: Feature not supported
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

1 byte value indicating support for the antenna interleaving feature.

Values:

  • 1: Feature supported
  • 0: Feature not supported
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:

  • 1: Feature supported
  • 0: Feature not supported
SUPPORTED_DIAGNOSTICS 1 0xE7 2

1 byte value indicating the support of diagnostics reporting.

Values:

  • 1: Feature supported
  • 0: Feature not supported
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 1 in the bitmask corresponds to a specific UWB channel.

Values:

  • 0x01: Channel 5 supported
  • 0x02: Channel 6 supported
  • 0x04: Channel 8 supported
  • 0x08: Channel 9 supported
  • 0x10: Channel 10 supported
  • 0x20: Channel 12 supported
  • 0x40: Channel 13 supported
  • 0x80: Channel 14 supported

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.