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.

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.

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:

• CR 287
• SUS API and UCI Spec Support for CCC Digital Key Interface Requirements

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.

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.

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.

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).

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).