Interfejs HAL radia nadawczego

W sekcjach poniżej znajdziesz informacje o tym, jak korzystać z warstwy abstrakcji sprzętu (HAL) do implementowania radia FM.

Interfejs HAL radia nadawczego

Warstwa HAL radia Broadcast udostępnia struktury danych i interfejsy na poziomie sprzętu do implementowania radia Broadcast, takiego jak radio AM/FM i DAB.

Interfejsy HIDL 2.0 i AIDL

Warstwa HAL radia nadawczego korzysta z interfejsów opisanych w sekcjach poniżej.

IAnnouncementListener

IAnnouncementListener to interfejs wywołania zwrotnego dla odbiornika ogłoszeń, który można zarejestrować w warstwie HAL radia nadawczego, aby otrzymywać ogłoszenia. Interfejs ma te metody:

IAnnouncementListener
Description: Wywoływana za każdym razem, gdy zmieni się lista ogłoszeń.
	HIDL 2.0	oneway onListUpdated(vec<Announcement> announcements)
	AIDL	oneway void onListUpdated(in Announcement[] announcements)

ICloseHandle

ICloseHandle to ogólny uchwyt zamykania służący do usuwania wywołania zwrotnego, które nie wymaga aktywnego interfejsu.

ICloseHandle
Opis: zamknij uchwyt.
	HIDL 2.0	close()
	AIDL	void close()

ITunerCallback

ITunerCallback to interfejs wywołania zwrotnego wywoływany przez warstwę HAL radia nadawczego w celu wysyłania aktualizacji do usługi klienta HAL.

ITunerCallback
Opis: wywoływana przez HAL, gdy operacja strojenia (strojenie, wyszukiwanie (w AIDL) lub skanowanie (w HIDL) i krok) zakończy się niepowodzeniem asynchronicznie.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Opis: wywoływana, gdy dostrajanie, wyszukiwanie (w AIDL) lub skanowanie (w HIDL) albo krok zakończy się powodzeniem.
	HIDL 2.0	oneway onTuneFailed(Result result, ProgramSelector selector)
	AIDL	void onTuneFailed(in Result result, in ProgramSelector selector)
Opis: wywoływana, gdy dostrajanie, wyszukiwanie (w AIDL) lub skanowanie (w HIDL) albo krok zakończy się powodzeniem.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Opis: wywoływana, gdy lista programów jest aktualizowana; rozmiar każdego fragmentu powinien być ograniczony do 500 KiB.
	HIDL 2.0	oneway onProgramListUpdated(ProgramListChunk chunk)
	AIDL	void onProgramListUpdated(ProgramListChunk chunk)
Opis: wywoływana, gdy antena jest podłączona lub odłączona.
	HIDL 2.0	oneway onAntennaStateChange(bool connected)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Description: Wywoływana, gdy wartości parametru specyficznego dla dostawcy są aktualizowane wewnętrznie w HAL (nie wywołuj po wywołaniu setParameters przez klienta HAL).
	HIDL 2.0	oneway onParametersUpdated(vec<VendorKeyValue> parameters)
	AIDL	void onParametersUpdated(in VendorKeyValue[] parameters)
Opis: nowość w AIDL. Wywoływana, gdy flaga konfiguracji jest aktualizowana wewnętrznie w HAL (nie powinna być wywoływana po wywołaniu setConfigFlag przez klienta HAL).
	HIDL 2.0	Nie dotyczy.
	AIDL	void onConfigFlagUpdated(in ConfigFlag flag, in boolean value)

IBroadcastRadio

IBroadcastRadio to główny interfejs HAL radia nadawczego. W HIDL 2.0 HAL użyj interfejsu ITunerSession tunera, aby wywołać operacje. Jednak w danym momencie aktywny jest co najwyżej 1 tuner (pod warunkiem, że każda instancja HAL radia ma tylko 1 chip tunera). ITunerSession został usunięty z interfejsów AIDL, a jego interfejsy zostały przeniesione do IBroadcastRadio.

IBroadcastRadio
Opis: uzyskiwanie opisu modułu i jego możliwości.
	HIDL 2.0	getProperties() generates (Properties properties)
	AIDL	Properties getProperties()
Opis: pobiera bieżącą lub możliwą konfigurację regionu AM/FM.
	HIDL 2.0	getAmFmRegionConfig(bool full) generates (Result result, AmFmRegionConfig config)
	AIDL	AmFmRegionConfig getAmFmRegionConfig(bool full)
Opis: pobiera bieżącą konfigurację regionu DAB.
	HIDL 2.0	getDabRegionConfig() generates (Result result, vec<DabTableEntry> config)
	AIDL	DabTableEntry[] getDabRegionConfig()
Opis: pobiera obraz z pamięci podręcznej modułu radiowego. W AIDL rozmiar obrazu musi być mniejszy niż 1 MB ze względu na limit bufora transakcji bindera.
	HIDL 2.0	getImage(uint32_t id) generates (vec<uint8_t> image)
	AIDL	byte[] getImage(in int id)
Opis: rejestruje detektor ogłoszeń.
	HIDL 2.0	registerAnnouncementListener(vec<AnnouncementType> enabled,IAnnouncementListener listener) generates (Result result, ICloseHandle closeHandle)
	AIDL	ICloseHandle registerAnnouncementListener(in IAnnouncementListener listener, in AnnouncementType[] enabled)
Opis: HIDL HAL: gdy otwierana jest nowa sesja tunera, stara sesja musi zostać zakończona. AIDL HAL: ponieważ nie ma dostępnej sesji tunera, należy ustawić tylko wywołanie zwrotne tunera. Jeśli istnieje, należy usunąć starą funkcję wywołania zwrotnego.
	HIDL 2.0	openSession(ITunerCallback callback) generuje (Result result, ITunerSession session)
	AIDL	void setTunerCallback(in ITunerCallback callback)
Opis: HIDL HAL: zamknięcie sesji tunera nie może się nie powieść i musi być wykonane tylko raz. AIDL HAL: nie ma tunera i trzeba tylko cofnąć wywołanie zwrotne tunera.
	HIDL 2.0	close()
	AIDL	unsetTunerCallback()
Opis: przełącza na określony program.
	HIDL 2.0	tune(ProgramSelector program) generates (Result result)
	AIDL	void tune(in ProgramSelector program)
Opis: wyszukuje kolejny prawidłowy program nadawany. Aby uniknąć nieporozumień w AIDL, nazwa scan została zmieniona na seek.
	HIDL 2.0	scan(bool directionUp, bool skipSubChannel) generates (Result result)
	AIDL	void seek(in boolean directionUp, in boolean skipSubChannel)
Opis: kroki do sąsiedniego kanału, który może nie być zajęty przez żaden program.
	HIDL 2.0	step(bool directionUp) generates (Result result)
	AIDL	void step(in boolean directionUp)
Opis: anuluje oczekujące operacje dostrajania, skanowania (w HIDL) lub wyszukiwania (w AIDL) albo operacje krokowe.
	HIDL 2.0	cancel()
	AIDL	void cancel()
Opis: stosuje filtr do listy programów i rozpoczyna wysyłanie aktualizacji listy programów za pomocą wywołania zwrotnego onProgramListUpdated.
	HIDL 2.0	startProgramListUpdates(ProgramFilter filter) generates (Result result)
	AIDL	void startProgramListUpdates(in ProgramFilter filter)
Opis: przestaje wysyłać aktualizacje listy programów.
	HIDL 2.0	stopProgramListUpdates()
	AIDL	void stopProgramListUpdates()
Opis: pobiera bieżące ustawienie danej flagi konfiguracji.
	HIDL 2.0	isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value)
	AIDL	boolean isConfigFlagSet(in ConfigFlag flag)
Opis: ustawia podaną flagę konfiguracji.
	HIDL 2.0	setConfigFlag(ConfigFlag flag, bool value) generates (Result result)
	AIDL	void setConfigFlag(in ConfigFlag flag, boolean value)
Opis: ustawia wartości parametrów specyficznych dla dostawcy.
	HIDL 2.0	setParameters(vec<VendorKeyValue> parameters) generuje, (vec<VendorKeyValue> results)
	AIDL	VendorKeyValue[] setParameters(in VendorKeyValue[] parameters)
Opis: pobiera wartości parametrów specyficzne dla dostawcy.
	HIDL 2.0	getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters)
	AIDL	VendorKeyValue[] getParameters(in String[] keys)

Wyjaśnienia dotyczące interfejsu

Działanie asynchroniczne

Każda operacja dostrajania (np. dostrajanie, skanowanie (w HIDL) lub wyszukiwanie (w AIDL) i krok) może być czasochłonna, a wątek nie powinien być blokowany przez długi czas. Dlatego operacja powinna zaplanować czasochłonne operacje na później i szybko zwrócić stan lub wynik. Szczegółowo: każda operacja powinna:

• Anuluje wszystkie oczekujące operacje dostrajania.
• Sprawdź, czy operację można przetworzyć na podstawie danych wejściowych metody i stanu tunera.
• Zaplanuj zadanie dostrajania, a następnie natychmiast zwróć wartość Result (w HIDL) lub status (w AIDL). Jeśli wartość Result lub status to OK, wywołanie zwrotne tunera tuneFailed lub currentProgramInfoChanged musi zostać wywołane, gdy zadanie strojenia OK zakończy się niepowodzeniem (np. z powodu przekroczenia limitu czasu) lub zostanie ukończone.

Podobnie startProgramListUpdates planuje czasochłonne zadanie aktualizacji listy programów na później i szybko zwraca stan lub wynik. Metoda najpierw anuluje oczekujące żądania aktualizacji, a następnie planuje zadanie aktualizacji i szybko zwraca wynik.

Sytuacja wyścigu

Ze względu na asynchroniczne działanie operacji dostrajania (np. dostrajanie, skanowanie (w HIDL) lub wyszukiwanie (w AIDL) i krok) występuje wyścig między anulowaniem operacji a operacjami dostrajania. Jeśli funkcja cancel zostanie wywołana po zakończeniu operacji dostrajania przez HAL i przed zakończeniem wywołania zwrotnego, anulowanie może zostać zignorowane, a wywołanie zwrotne powinno zostać zakończone i odebrane przez klienta HAL.

Podobnie jeśli funkcja stopProgramListUpdates zostanie wywołana po tym, jak HAL zakończy aktualizację listy programów, a przed zakończeniem wywołania zwrotnego onCurrentProgramInfoChanged, można ją zignorować i wykonać wywołanie zwrotne.stopProgramListUpdates

Limit rozmiaru danych

Ze względu na sztywny limit bufora transakcji w przypadku niektórych metod interfejsu przekazujących dane o potencjalnie dużym rozmiarze w AIDL HAL określono limit danych.

• getImage wymaga, aby zwracany obraz miał mniej niż 1 MB.
• onProgramListUpdate wymaga, aby każdy plik chunk miał rozmiar mniejszy niż 500 KiB. Większe listy programów muszą zostać podzielone przez implementację HAL na kilka części i przesłane za pomocą wielu wywołań zwrotnych.

Zmiany w strukturach danych AIDL HAL

Oprócz zmian w interfejsach zostały one zastosowane do struktur danych zdefiniowanych w AIDL HAL radia FM, które korzysta z AIDL.

• Wyliczenie Constant zostało usunięte z AIDL i zdefiniowane jako stała liczba całkowita w IBroadcastRadio. Nazwa ANTENNA_DISCONNECTED_TIMEOUT_MS została zmieniona na ANTENNA_STATE_CHANGE_TIMEOUT_MS. Dodano nową stałą całkowitą TUNER_TIMEOUT_MS. W tym czasie należy wykonać wszystkie operacje strojenia, wyszukiwania i krokowe.
• Wyliczenia RDS i Deemphasis zostały usunięte z AIDL i zdefiniowane jako const int w AmFmRegionConfig. W związku z tym zarówno fmDeemphasis, jak i fmRds w ProgramInfo są deklarowane jako int, czyli wynik obliczeń bitowych odpowiednich flag. Jednocześnie nazwy D50 i D75 zostaną zmienione odpowiednio na DEEMPHASIS_D50 i DEEMPHASIS_D75.
• Wyliczenia ProgramInfoFlags są usuwane z AIDL i definiowane jako stałe liczby całkowite w ProgramInfo z dodanym prefiksem FLAG_. W związku z tym zmienna infoFlags w ProgramInfo jest deklarowana jako liczba całkowita, czyli wynik obliczeń bitowych flag. TUNED została też zmieniona na FLAG_TUNABLE, aby lepiej opisywać definicję stacji, do której można się dostroić.
• W przypadku AmFmBandRange element scanSpacing zmienia nazwę na seekSpacing, ponieważ w AIDL element scan zmienia nazwę na seek.
• Ponieważ w AIDL wprowadzono pojęcie unii, zdefiniowane w HIDL HAL typy MetadataKey i Metadata nie są już używane. Unia AIDL Metadata jest zdefiniowana w AIDL HAL. Każda wartość wyliczeniowa, która wcześniej znajdowała się w MetadataKey, jest teraz polem w Metadata o typie string lub int, w zależności od definicji.

Obsługa radia DAB

W tej sekcji opisujemy obsługę radia DAB.

Identyfikatory

Głównym typem identyfikatora radia DAB i DMB w AIDL Broadcast Radio HAL jest DAB_SID_EXT. DAB_SID_EXT używa 32-bitowych identyfikatorów usług (SID), dzięki czemu może reprezentować identyfikator SID zarówno radia DAB, jak i DMB.

Oprócz identyfikatorów podstawowych obsługiwane są też identyfikatory dodatkowe, takie jak DAB_ENSEMBLE i DAB_FREQUENCY_KHZ. Jest to ważne, ponieważ wiele stacji DAB może współdzielić DAB_SID_EXT, ale mieć różne wartości DAB_ENSEMBLE lub DAB_FREQUENCY_KHZ. Aby zapewnić dokładne aktualizacje listy programów, stacje z tym samym DAB_SID_EXT są aktualizowane razem za pomocą ITunerCallback#onProgramListUpdated. Ta aktualizacja jest następnie przekazywana do usługi Broadcast Radio Service i Radio Manager, a na końcu do aplikacji radiowej za pomocą android.hardware.radio.ProgramList.

Metadane

W tabeli poniżej znajdziesz obsługiwane metadane dotyczące DAB w AIDL Broadcast Radio HAL:

Pole metadanych	Opis
dabEnsembleName (w skrócie: dabEnsembleNameShort)	Nazwa zespołu stacji DAB
dabServiceName (skrót od dabServiceNameShort)	Nazwa usługi stacji DAB
dabComponentName (skrót od dabComponentNameShort)	Nazwa komponentu stacji DAB

Obsługa radia HD

W tej sekcji opisujemy obsługę radia HD.

Identyfikatory

HD_STATION_ID_EXT jest podstawowym identyfikatorem stacji radiowych HD. Aby jeszcze bardziej ułatwić identyfikację stacji, podajemy też identyfikatory dodatkowe, takie jak HD_STATION_NAME i HD_STATION_LOCATION. HD_STATION_LOCATION, która udostępnia informacje o lokalizacji, została wprowadzona w Androidzie 15.

Włączanie i wyłączanie radia cyfrowego

Od Androida 15 możesz włączać i wyłączać radio cyfrowe (np. radio HD) za pomocą ustawień ConfigFlag. Aby kontrolować to ustawienie w przypadku radia FM, użyj flagi FORCE_ANALOG_FM, a w przypadku radia AM – flagi FORCE_ANALOG_AM. Ustawienie flagi na false włącza radio HD, a ustawienie jej na true wymusza analogowe radio AM/FM.

Dostępne kanały HD

Od Androida 15 kanały HD dostępne obecnie dla stacji radiowej HD mogą być reprezentowane przez 8-bitową maskę bitową, Metadata#hdSubChannelsAvailable, w ProgramInfo.metadata. Na przykład wartość bitu 1 od lewej strony określa, czy podkanał HD2 jest dostępny dla tej stacji HD.

Stan pozyskiwania sygnału

W Androidzie 15 i nowszych wersjach aplikacje radiowe mogą wyświetlać użytkownikom stan odbioru sygnału stacji radiowych HD. Jest to przydatne, ponieważ uzyskanie silnego sygnału HD może czasami potrwać kilka chwil.

Aby przekazać te informacje, system używa ProgramInfo.infoFlags do śledzenia stanu i aktualizuje aplikację radiową za pomocą ITunerCallback#onCurrentProgramInfoChanged..

Oto jak stan jest przedstawiony w ProgramInfo.infoFlags:

• Bit 6: wskazuje, czy sygnał radia HD został uzyskany.
• Bit 7: wskazuje, czy dostępne są dane usługi informacji o stacjach (SIS). SIS dostarcza dodatkowych informacji o stacji i odtwarzanych treściach.
• Bit 8: określa, czy dostępny jest cyfrowy dźwięk HD.

Metadane

W tabeli poniżej znajdziesz obsługiwane metadane radia HD w przypadku Androida 15 i nowszych wersji.

Pole metadanych	Opis
commentShortDescription	Krótki opis kontekstu komentarza
commentActualText	Tekst komentarza
commercial	Reklama radiowa
ufids	Unikalne identyfikatory plików (UFID) powiązane z treściami
hdStationNameShort	Krótka nazwa stacji radiowej HD lub uniwersalna krótka nazwa
hdStationNameLong	Pełna nazwa stacji radiowej HD, slogan lub wiadomość od stacji.

Alerty o zagrożeniu

Na Androidzie 15 i nowszych wersjach alerty o zagrożeniu są obsługiwane w przypadku stacji radiowych HD, aby informować użytkowników aplikacji radiowych o alertach o zagrożeniu wysyłanych przez stacje radiowe. Alerty alarmowe (Alert) są zgodne ze standardem Common Alerting Protocol (CAP) 1.2 i obsługują alerty podane w tej tabeli:

Informacje o alercie	Opis	Dostępne wartości typu wyliczeniowego
AlertStatus	Stan alertu	ACTUAL, EXERCISE, TEST
AlertMessageType	Rodzaj komunikatu alertu o zagrożeniu	ALERT, UPDATE, CANCEL
AlertCategory	Kategoria zdarzenia będącego tematem alertu o zagrożeniu	GEO, MET, SAFETY, SECURITY, RESCUE, FIRE, HEALTH, ENV, TRANSPORT, INFRA, CBRNE, OTHER
AlertUrgency	pilność zdarzenia będącego tematem alertu o zagrożeniu;	IMMEDIATE, EXPECTED, FUTURE, PAST, UNKNOWN
AlertSeverity	Waga zdarzenia będącego tematem alertu o zagrożeniu	EXTREME, SEVERE, MODERATE, MINOR, UNKNOWN
AlertCertainty	Pewność zdarzenia będącego tematem komunikatu alarmowego	OBSERVED, LIKELY, POSSIBLE, UNLIKELY, UNKNOWN

Aby wyświetlić informacje o bieżącym alercie, możesz użyć Alert (zawierającego informacje z tabeli), alertów tekstowych i AlertArea. Alert to pole opcjonalne w ProgramInfo, dzięki czemu może być wysyłane z Broadcast Radio HAL do aplikacji radiowych za pomocą wywołań zwrotnych tunera w celu aktualizowania informacji o bieżącym programie i listy programów.