UWB HAL Interface

Stay organized with collections Save and categorize content based on your preferences.

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

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:

  • 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 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:

  • 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