AOSP 초광대역(UWB) 스택은 FiRa 정의 UCI 인터페이스를 HAL 노출 영역으로 사용합니다. HAL 인터페이스는 불투명 파이프(IUwbChip::sendUciMessage() 및 IUwbClientCallback::onUciMessage())를 사용하여 UWB 명령어 인터페이스(UCI) 명령어, 응답, 알림을 주고받습니다.
모든 Android UWB 공급업체는 모든 FiRa 사양 정의 메시지를 지원해야 합니다. UWB 프레임워크는 이전 버전과 호환되며 UWB 공급업체가 기기에 구현한 모든 UCI 버전과 호환됩니다. AOSP UWB 프레임워크는 모듈이므로 주요 FiRa 표준 버전을 타겟팅하는 초안 UCI 사양의 승인된 변경 요청(CR)을 선택적으로 지원할 수 있습니다. 구현된 모든 초안 CR은 변경될 수 있습니다.
인터페이스 정의
UWB HAL 인터페이스는 안정적 AIDL을 사용하여 정의됩니다.
기본 인터페이스는 android.hardware.uwb 패키지를 사용합니다.
다음은 android.hardware.uwb 패키지의 두 가지 기본 인터페이스입니다.
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);
}
UWB 프레임워크에서의 HAL 호출 흐름
다음 이미지는 UWB 스택 초기화, UWB 스택 초기화 해제, UWB 세션 시작 및 중지 프로세스를 위한 UWB 프레임워크에서의 호출 흐름을 보여줍니다.
그림 1. UWB 스택 초기화 호출 흐름(UWB 전환 켬)
그림 2. UWB 스택 초기화 해제 호출 흐름(UWB 전환 끔)
그림 3. UWB 세션 시작/중지 흐름
UWB 국가 코드 설정
그림 1에서 볼 수 있듯이 UWB 프레임워크는 공급업체 공간 UCI 명령어 ANDROID_SET_COUNTRY_CODE(GID=0xC, OID=0x1)을 사용하여 UWB 스택을 초기화하는 동안 UWB 국가 코드를 구성합니다. UWB 프레임워크는 다음 소스(우선순위에 따라 나열)를 사용하여 UWB 국가 코드를 확인하려고 시도합니다. UWB 프레임워크는 국가 코드가 결정되는 첫 번째 소스에서 중지됩니다.
- 국가 코드 재정의: adb 셸 명령어(로컬 또는 자동 테스트)를 통해 강제로 적용된 국가 코드입니다.
- 전화 국가 코드: 셀룰러를 통해 검색된 국가 코드입니다. 서로 다른 코드를 반환하는 SIM이 여러 개 있는 경우 선택된 국가 코드는 비확정적입니다.
- Wi-Fi 국가 코드: Wi-Fi(80211.ad)를 통해 검색된 국가 코드입니다.
- 마지막으로 알려진 전화 국가 코드: 셀룰러를 통해 검색된 마지막으로 알려진 국가 코드입니다. 서로 다른 코드를 반환하는 SIM이 여러 개 있는 경우 선택된 국가 코드는 비확정적입니다.
- 위치 국가 코드:
LocationManager통합 위치 정보 제공자에서 검색된 국가 코드입니다. - OEM 기본 국가 코드: 기기 제조업체에서 설정한 국가 코드입니다.
UWB 프레임워크가 UWB 국가 코드를 확인할 수 없는 경우 DEFAULT_COUNTRY_CODE ("00") 값으로 ANDROID_SET_COUNTRY_CODE UCI 명령어를 호출하고 UWB 스택 상태가 DISABLED임을 UWB 앱에 알립니다 추후 UWB 프레임워크가 유효한 국가 코드를 확인할 수 있게 되면 ANDROID_SET_COUNTRY_CODE 명령어를 사용하여 새 국가 코드를 구성하고 UWB 스택이 READY임을 UWB 앱에 알립니다.
국가의 현지 규정으로 인해 UWB를 사용할 수 없는 경우, UWB 컨트롤러가 STATUS_CODE_ANDROID_REGULATION_UWB_OFF 상태 코드를 반환합니다. 그러면 UWB 프레임워크에서 UWB 스택 상태가 DISABLED임을 UWB 앱에 알립니다.
사용자가 다른 국가로 여행 시 UWB 프레임워크는 ANDROID_SET_COUNTRY_CODE UCI 명령어를 사용하여 새 국가 코드를 구성합니다. (새 국가의 UWB 규정을 기반으로) UWB 컨트롤러가 반환하는 상태 코드에 따라 UWB 스택 상태가 변경될 수 있습니다.
FIRA UCI 사양 정의 명령어 형식
UCI 제어 패킷의 형식은 UCI 사양의 섹션 4.4.2를 참고하세요.
인터페이스 버전 관리
UCI 사양은 UWB 공급업체가 UCI_GET_DEVICE_INFO_RSP 및 UCI_GET_CAPS_INFO_RSP 명령어를 사용하여 기기에 의해 구현된 UCI 스택의 버전을 노출할 수 있도록 지원합니다. 프레임워크는 이러한 명령어를 사용하여 기기의 UCI 버전을 가져오고 그에 따라 동작을 변경합니다.
UWB 모듈에서 지원하는 초안 CR 목록
UWB 모듈 버전 #330810000에서는 다음과 같은 FiRa 2.0용 초안 CR을 지원합니다.
Android UCI 인터페이스(FiRa 공급업체 부분)
UCI 사양은 모든 사양 정의 메시지를 위한 그룹 식별자(GID) 및 명령 코드 식별자(OID) 집합을 정의합니다. 이 사양은 또한 공급업체용으로만 예약된 GID 집합을 예약합니다. AOSP UWB 스택은 사양에 정의되지 않은 Android 관련 명령어로 이러한 공급업체 GID 및 OID 중 일부를 사용합니다. 자세한 내용은 UCI 사양의 섹션 8.4를 참고하세요.
Android에서 사용하는 이러한 공급업체 메시지는 android.hardware.uwb.fira_android HAL 패키지에 정의되어 있습니다.
공급업체 인터페이스 버전 관리
UWB 공급업체는 기기에서 지원되는 android.hardware.uwb.fira_android HAL 패키지의 버전을 IUwbChip.getSupportedAndroidUciVersion()을 통해 노출해야 합니다. 프레임워크는 이 버전 정보를 사용하여 이전 버전과의 호환성을 처리합니다.
Android GID 및 OID 목록
다음 표에는 Android용 GID 및 OID가 나와 있습니다. GID 0xE 및 0xF는 Android OEM에서 사용하도록 예약되어 있습니다.
| GID | OID | 정의 |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
명령어 및 응답이 UWB 전원 관련 통계를 얻는 데 사용됩니다.
UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY가 1로 설정된 경우에만 지원됩니다. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
현행 규제 국가 코드를 설정하는 데 사용됩니다(SIM 또는 Wi-Fi를 사용하여 정해지거나 OEM에서 하드코딩함). 국가 코드는 ISO-3166 국가 코드에 해당하는 2바이트 값으로 전송됩니다. 값 |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
UWB 범위 진단 통계를 얻기 위해 알림에서 사용합니다.
UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS가 1로 설정된 경우에만 지원됩니다.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
OEM용으로 예약되어 있습니다. |
UCI 사양 정의 메시지로의 공급업체 확장
이 섹션에서는 UCI 사양 정의 메시지로의 공급업체 확장 세부정보를 설명합니다.
SESSION_SET_APP_CONFIG_[CMD|RSP] 및 SESSION_GET_APP_CONFIG_[CMD|RSP]
다음은 APP_CONFIG에서 TLV의 공급업체 예약 부분에 AOSP 스택에 의해 정의되는 유형 길이 값(TLV)입니다.
- GID: 0001b(UWB 세션 구성 적용 그룹)
- OID: 000011b(
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b(
SESSION_GET_APP_CONFIG_CMD)
다음 표에는 UWB 세션 구성 메시지의 매개변수가 나와 있습니다.
| 매개변수 이름 | 길이 (옥텟) |
태그 (ID) |
공급업체 인터페이스 버전 | 설명 |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS |
1 | 0xE3 |
1 | AOA_RESULT_REQ가 0xF0으로 설정된 경우의 인터리브 처리 비율입니다. UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING이 1로 설정된 경우에만 지원됩니다. |
NB_OF_AZIMUTH_MEASUREMENTS |
1 | 0xE4 |
1 | |
NB_OF_ELEVATION_MEASUREMENTS |
1 | 0xE5 |
1 | |
ENABLE_DIAGNOSTICS |
1 | 0xE8 |
2 | 진단 보고를 사용 설정하거나 사용 중지하는 1바이트 값입니다.
값:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 또는 4 | 0xE9 |
2 | 진단 보고를 구성하는 1바이트 또는 4바이트 비트마스크입니다. 이 비트마스크는 Android 14 이상에서는 1바이트이고 Android 13 이하에서는 4바이트입니다.
비트 정의:
|
CORE_GET_CAPS_INFO_RSP
다음은 CAPS_INFO에서 TLV의 공급업체 예약 부분에 AOSP 스택에 의해 정의되는 TLV입니다.
- GID: 0000b(UWB 핵심 그룹)
- OID: 000011b(
CORE_GET_CAPS_INFO_RSP)
다음 표에는 UWB 기능 메시지의 매개변수가 나와 있습니다.
| 매개변수 이름 | 길이 (옥텟) |
태그 (ID) |
공급업체 인터페이스 버전 | 설명 |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | 전원 통계 쿼리 지원을 나타내는 1바이트 값입니다. 값:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | 안테나 인터리브 처리 기능 지원을 나타내는 1바이트 값입니다. 값:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | 지원되는 최소 범위 간격(밀리초)을 나타내는 4바이트 값입니다. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 0xE5 |
2 | 지원되는 RANGE_DATA_NTF_CONFIG 값을 나타내는 4바이트 비트마스크입니다.
각 비트가 SET_APP_CFG_CMD의 RANGE_DATA_NTF_CONFIG에 사용된 값에 대응되는 비트마스크입니다. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | RSSI 보고 지원을 나타내는 1바이트 값입니다. 값:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | 진단 보고 지원을 나타내는 1바이트 값입니다. 값:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU |
4 | 0xE8 |
2 | RSTU에서 지원되는 최소 슬롯 기간을 나타내는 4바이트 값입니다. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | 지원되는 최대 FiRa 범위 세션 수를 나타내는 4바이트 값입니다. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | AoA를 지원하는 채널을 나타내는 2바이트 비트마스크입니다. 비트마스크에서 각 값:
|
상태 코드
다음은 공급업체 공간의 상태 코드입니다. 이는 UWB 하위 시스템(UWBS)에서 UCI 응답(예: SESSION_START_RSP)으로 반환됩니다.
| 상태 코드 | 값 | 설명 |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
다른 CCC 또는 FiRa 범위 세션과의 충돌로 인해 현재 범위 세션을 시작할 수 없는 경우 반환되는 상태 코드입니다. |
STATUS_REGULATION_UWB_OFF |
0x53 |
UWB 규정상의 이유로 현재 범위 세션을 시작할 수 없는 경우 반환되는 상태 코드입니다. |
SESSION_STATUS_NTF의 상태 변경 이유 코드
다음은 SESSION_STATUS_NTF에서 UWBS가 반환한 상태 필드에 관해 공급업체 공간에서 정의된 상태 변경 이유 코드입니다. 이 알림은 범위 세션의 상태가 변경될 때(예: ACTIVE에서 IDLE로) UWBS에서 전송됩니다.
| 상태 변경 이유 코드 | 값 | 설명 |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
구성된 채널이 AoA 범위를 지원하지 않아 세션 상태가 변경되었습니다. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
다른 CCC 또는 FiRa 범위 세션과의 충돌로 인해 세션 상태가 변경되었습니다. |
REASON_REGULATION_UWB_OFF |
0x82 |
규정상의 이유로 UWB를 사용 중지해야 하므로 세션 상태가 변경되었습니다. |