HAL siaran radio

Bagian berikut menjelaskan cara menggunakan lapisan abstraksi hardware (HAL) untuk menerapkan radio siaran.

Antarmuka HAL radio siaran

HAL radio Broadcast menyediakan struktur data dan antarmuka di tingkat hardware untuk menerapkan radio siaran, seperti radio AM/FM dan DAB.

Antarmuka HIDL 2.0 dan AIDL

HAL radio siaran menggunakan antarmuka yang dijelaskan di bagian berikut.

IAnnouncementListener

IAnnouncementListener adalah antarmuka callback untuk pemroses pengumuman, yang dapat didaftarkan di HAL radio siaran untuk menerima pengumuman. Antarmuka memiliki metode berikut:

IAnnouncementListener
Deskripsi: Dipanggil setiap kali daftar pengumuman telah berubah.
	HIDL 2.0	oneway onListUpdated(vec<Announcement> announcements)
	AIDL	oneway void onListUpdated(in Announcement[] announcements)

ICloseHandle

ICloseHandle adalah handle penutup generik untuk menghapus callback yang tidak memerlukan antarmuka aktif.

ICloseHandle
Deskripsi: Tutup gagang.
	HIDL 2.0	close()
	AIDL	void close()

ITunerCallback

ITunerCallback adalah antarmuka callback yang dipanggil oleh HAL radio siaran untuk mengirim update ke layanan klien HAL.

ITunerCallback
Deskripsi: Dipanggil oleh HAL saat operasi penyetelan (penyetelan, penelusuran (di AIDL) atau pemindaian (di HIDL) dan langkah berhasil) gagal secara asinkron.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Deskripsi: Dipanggil saat penyetelan, pencarian (di AIDL) atau pemindaian (di HIDL), atau langkah berhasil.
	HIDL 2.0	oneway onTuneFailed(Result result, ProgramSelector selector)
	AIDL	void onTuneFailed(in Result result, in ProgramSelector selector)
Deskripsi: Dipanggil saat penyetelan, pencarian (di AIDL) atau pemindaian (di HIDL), atau langkah berhasil.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Deskripsi: Dipanggil saat daftar program diperbarui; ukuran setiap potongan harus dibatasi hingga 500 kiB.
	HIDL 2.0	oneway onProgramListUpdated(ProgramListChunk chunk)
	AIDL	void onProgramListUpdated(ProgramListChunk chunk)
Deskripsi: Dipanggil saat antena terhubung atau terputus.
	HIDL 2.0	oneway onAntennaStateChange(bool connected)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Deskripsi: Dipanggil saat nilai parameter khusus vendor diperbarui secara internal di HAL (jangan dipanggil setelah memanggil setParameters oleh klien HAL).
	HIDL 2.0	oneway onParametersUpdated(vec<VendorKeyValue> parameters)
	AIDL	void onParametersUpdated(in VendorKeyValue[] parameters)
Deskripsi: Baru di AIDL. Dipanggil saat tanda konfigurasi diperbarui secara internal di HAL (tidak boleh dipanggil setelah memanggil setConfigFlag oleh klien HAL).
	HIDL 2.0	Tidak berlaku.
	AIDL	void onConfigFlagUpdated(in ConfigFlag flag, in boolean value)

IBroadcastRadio

IBroadcastRadio adalah antarmuka utama untuk HAL radio siaran. Di HAL HIDL 2.0, gunakan antarmuka ITunerSession ke tuner untuk memanggil operasi. Namun, paling banyak satu tuner aktif dalam satu waktu (asalkan setiap instance HAL radio siaran hanya memiliki satu chip tuner). ITunerSession dihapus dari antarmuka AIDL dan antarmukanya dipindahkan ke IBroadcastRadio.

IBroadcastRadio
Deskripsi: Mendapatkan deskripsi modul dan kemampuannya.
	HIDL 2.0	getProperties() generates (Properties properties)
	AIDL	Properties getProperties()
Deskripsi: Mengambil konfigurasi wilayah AM/FM saat ini atau yang mungkin.
	HIDL 2.0	getAmFmRegionConfig(bool full) generates (Result result, AmFmRegionConfig config)
	AIDL	AmFmRegionConfig getAmFmRegionConfig(bool full)
Deskripsi: Mengambil konfigurasi wilayah DAB saat ini.
	HIDL 2.0	getDabRegionConfig() generates (Result result, vec<DabTableEntry> config)
	AIDL	DabTableEntry[] getDabRegionConfig()
Deskripsi: Mendapatkan gambar dari cache modul radio. Di AIDL, ukuran gambar harus kurang dari 1 MB karena batas ketat pada buffer transaksi binder.
	HIDL 2.0	getImage(uint32_t id) generates (vec<uint8_t> image)
	AIDL	byte[] getImage(in int id)
Deskripsi: Mendaftarkan pemroses pengumuman.
	HIDL 2.0	registerAnnouncementListener(vec<AnnouncementType> enabled,IAnnouncementListener listener) generates (Result result, ICloseHandle closeHandle)
	AIDL	ICloseHandle registerAnnouncementListener(in IAnnouncementListener listener, in AnnouncementType[] enabled)
Deskripsi: HIDL HAL: Saat sesi tuner baru dibuka, sesi lama harus dihentikan. AIDL HAL: Karena tidak ada sesi tuner yang tersedia, hanya callback tuner yang perlu disetel. Jika ada, callback lama harus dibatalkan.
	HIDL 2.0	openSession(ITunerCallback callback) menghasilkan (Result result, ITunerSession session)
	AIDL	void setTunerCallback(in ITunerCallback callback)
Deskripsi: HIDL HAL: Menutup sesi tuner tidak boleh gagal dan hanya boleh dikeluarkan satu kali. AIDL HAL: Tidak ada tuner dan hanya callback tuner yang perlu dibatalkan.
	HIDL 2.0	close()
	AIDL	unsetTunerCallback()
Deskripsi: Menyesuaikan ke program tertentu.
	HIDL 2.0	tune(ProgramSelector program) generates (Result result)
	AIDL	void tune(in ProgramSelector program)
Deskripsi: Mencari program valid berikutnya di udara. Untuk menghindari kebingungan di AIDL, scan diganti namanya menjadi seek.
	HIDL 2.0	scan(bool directionUp, bool skipSubChannel) generates (Result result)
	AIDL	void seek(in boolean directionUp, in boolean skipSubChannel)
Deskripsi: Langkah-langkah ke channel yang berdekatan, yang mungkin tidak ditempati oleh program apa pun.
	HIDL 2.0	step(bool directionUp) generates (Result result)
	AIDL	void step(in boolean directionUp)
Deskripsi: Membatalkan operasi penyetelan, pemindaian (di HIDL), atau pencarian (di AIDL), atau langkah yang tertunda.
	HIDL 2.0	cancel()
	AIDL	void cancel()
Deskripsi: Menerapkan filter ke daftar program dan mulai mengirim update daftar program melalui callback onProgramListUpdated.
	HIDL 2.0	startProgramListUpdates(ProgramFilter filter) generates (Result result)
	AIDL	void startProgramListUpdates(in ProgramFilter filter)
Deskripsi: Berhenti mengirim update daftar program.
	HIDL 2.0	stopProgramListUpdates()
	AIDL	void stopProgramListUpdates()
Deskripsi: Mengambil setelan saat ini dari tanda konfigurasi tertentu.
	HIDL 2.0	isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value)
	AIDL	boolean isConfigFlagSet(in ConfigFlag flag)
Deskripsi: Menetapkan tanda konfigurasi yang diberikan.
	HIDL 2.0	setConfigFlag(ConfigFlag flag, bool value) generates (Result result)
	AIDL	void setConfigFlag(in ConfigFlag flag, boolean value)
Deskripsi: Menetapkan nilai parameter khusus vendor.
	HIDL 2.0	setParameters(vec<VendorKeyValue> parameters) membuat, (vec<VendorKeyValue> results)
	AIDL	VendorKeyValue[] setParameters(in VendorKeyValue[] parameters)
Deskripsi: Mengambil nilai parameter khusus vendor.
	HIDL 2.0	getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters)
	AIDL	VendorKeyValue[] getParameters(in String[] keys)

Klarifikasi antarmuka

Perilaku asinkron

Karena setiap operasi penyetelan (misalnya, menyetel, memindai (di HIDL) atau mencari (di AIDL), dan melangkah) mungkin memakan waktu dan thread tidak boleh diblokir dalam waktu yang lama, operasi harus menjadwalkan operasi yang memakan waktu untuk terjadi nanti dan dengan cepat menampilkan status atau hasil. Secara mendetail, setiap operasi harus:

• Membatalkan semua operasi penyesuaian yang tertunda.
• Periksa apakah operasi dapat diproses berdasarkan input metode dan status tuner.
• Jadwalkan tugas penyesuaian, lalu segera tampilkan Result (di HIDL) atau status (di AIDL). Jika Result atau status adalah OK, callback tuner tuneFailed atau currentProgramInfoChanged harus dipanggil saat tugas penyetelan gagal (misalnya, karena waktu tunggu habis) atau selesai.

Demikian pula, startProgramListUpdates juga menjadwalkan tugas yang memakan waktu untuk memperbarui daftar program agar dilakukan nanti dan dengan cepat menampilkan status atau hasil. Metode pertama-tama membatalkan permintaan update yang tertunda, lalu menjadwalkan tugas update dan dengan cepat menampilkan hasilnya.

Kondisi race

Karena perilaku asinkron operasi penyetelan (misalnya, penyetelan, pemindaian (di HIDL) atau pencarian (di AIDL), dan langkah), terdapat kondisi persaingan antara pembatalan operasi dan operasi penyetelan. Jika cancel dipanggil setelah HAL menyelesaikan operasi penyetelan dan sebelum callback selesai, pembatalan dapat diabaikan dan callback harus selesai dan diterima oleh klien HAL.

Demikian pula, jika stopProgramListUpdates dipanggil setelah HAL menyelesaikan update daftar program dan sebelum callback onCurrentProgramInfoChanged selesai, stopProgramListUpdates dapat diabaikan dan callback harus selesai.

Batas ukuran data

Karena ada batas pasti pada buffer transaksi binder, batas data untuk beberapa metode antarmuka yang meneruskan data berukuran besar dijelaskan dalam AIDL HAL.

• getImage memerlukan gambar yang ditampilkan berukuran kurang dari 1 MB.
• onProgramListUpdate mengharuskan setiap chunk berukuran kurang dari 500 kiB. Daftar program yang lebih besar harus dibagi oleh implementasi HAL menjadi beberapa bagian dan dikirim melalui beberapa callback.

Perubahan pada struktur data AIDL HAL

Selain perubahan pada antarmuka, perubahan ini telah diterapkan pada struktur data yang ditentukan dalam AIDL HAL radio siaran, yang memanfaatkan AIDL.

• Enum Constant dihapus di AIDL dan ditentukan sebagai const int di IBroadcastRadio. Sementara itu, ANTENNA_DISCONNECTED_TIMEOUT_MS diganti namanya menjadi ANTENNA_STATE_CHANGE_TIMEOUT_MS. const int TUNER_TIMEOUT_MS baru ditambahkan. Semua operasi penyesuaian, pencarian, dan langkah harus diselesaikan dalam jangka waktu ini.
• Enum RDS dan Deemphasis dihapus di AIDL dan ditentukan sebagai const int di AmFmRegionConfig. Oleh karena itu, fmDeemphasis dan fmRds di ProgramInfo dideklarasikan sebagai int, hasil komputasi bit dari masing-masing tanda. Sementara itu, D50 dan D75 masing-masing diganti namanya menjadi DEEMPHASIS_D50 dan DEEMPHASIS_D75.
• Enum ProgramInfoFlags dihapus di AIDL dan ditentukan sebagai const int di ProgramInfo dengan awalan FLAG_ ditambahkan. Oleh karena itu, infoFlags di ProgramInfo dideklarasikan sebagai int, hasil komputasi bit flag. TUNED juga diganti namanya menjadi FLAG_TUNABLE, untuk mendeskripsikan definisinya dengan lebih baik bahwa stasiun dapat disetel ke frekuensi tersebut.
• Di AmFmBandRange, scanSpacing diganti namanya menjadi seekSpacing, karena scan diganti namanya menjadi seek di AIDL.
• Karena konsep gabungan diperkenalkan di AIDL, MetadataKey dan Metadata yang ditentukan di HIDL HAL tidak lagi digunakan. Gabungan AIDL Metadata ditentukan dalam AIDL HAL. Setiap nilai enum yang sebelumnya ada di MetadataKey kini menjadi kolom di Metadata dengan jenis string atau int, bergantung pada definisinya.

Dukungan radio DAB

Bagian ini menjelaskan dukungan radio DAB.

Pengenal

Jenis ID utama untuk radio DAB dan DMB di AIDL Broadcast Radio HAL adalah DAB_SID_EXT. DAB_SID_EXT menggunakan ID layanan (SID) 32-bit sehingga dapat merepresentasikan SID radio DAB dan DMB.

Selain ID utama, ID sekunder seperti DAB_ENSEMBLE dan DAB_FREQUENCY_KHZ juga didukung. Hal ini penting karena beberapa stasiun DAB dapat berbagi DAB_SID_EXT sambil memiliki nilai DAB_ENSEMBLE atau DAB_FREQUENCY_KHZ yang berbeda. Untuk memastikan pembaruan daftar program yang akurat, stasiun dengan DAB_SID_EXT yang sama diperbarui bersama menggunakan ITunerCallback#onProgramListUpdated. Kemudian, update ini diteruskan ke Broadcast Radio Service dan Radio Manager, dan akhirnya ke aplikasi radio melalui android.hardware.radio.ProgramList.

Metadata

Tabel berikut menunjukkan metadata yang didukung khusus untuk DAB di AIDL Broadcast Radio HAL:

Kolom metadata	Deskripsi
dabEnsembleName (bentuk singkat: dabEnsembleNameShort)	Nama ansambel stasiun DAB
dabServiceName (disingkat dari dabServiceNameShort)	Nama layanan stasiun DAB
dabComponentName (disingkat dari dabComponentNameShort)	Nama komponen stasiun DAB

Dukungan radio HD

Bagian ini menjelaskan dukungan radio HD.

Pengenal

HD_STATION_ID_EXT berfungsi sebagai ID utama untuk stasiun radio HD. Untuk lebih meningkatkan identifikasi stasiun, ID sekunder seperti HD_STATION_NAME dan HD_STATION_LOCATION juga disediakan. HD_STATION_LOCATION, yang memberikan informasi lokasi, diperkenalkan di Android 15.

Mengaktifkan atau menonaktifkan radio digital

Mulai Android 15, Anda dapat mengaktifkan atau menonaktifkan radio digital (seperti radio HD) dengan menyesuaikan ConfigFlag. Untuk mengontrol setelan ini untuk radio FM, gunakan flag FORCE_ANALOG_FM; untuk radio AM, gunakan flag FORCE_ANALOG_AM. Menyetel flag ke false akan mengaktifkan radio HD, sedangkan menyetelnya ke true akan mengaktifkan radio AM/FM analog.

Saluran HD tersedia

Mulai Android 15, saluran HD yang saat ini tersedia untuk stasiun radio HD dapat direpresentasikan oleh mask bit 8 bit, Metadata#hdSubChannelsAvailable, di ProgramInfo.metadata. Misalnya, nilai bit 1 dari kiri menunjukkan apakah subchannel HD2 tersedia untuk stasiun HD ini.

Status akuisisi sinyal

Di Android 15 dan versi yang lebih tinggi, aplikasi radio dapat menampilkan status perolehan sinyal stasiun radio HD kepada pengguna. Hal ini berguna karena mendapatkan sinyal HD yang kuat terkadang memerlukan waktu beberapa saat.

Untuk memberikan informasi ini, sistem menggunakan ProgramInfo.infoFlags untuk melacak status dan memperbarui aplikasi radio melalui ITunerCallback#onCurrentProgramInfoChanged.

Berikut cara status ditampilkan dalam ProgramInfo.infoFlags:

• Bit 6: Menunjukkan apakah sinyal radio HD telah diperoleh.
• Bit 7: Menampilkan apakah data Station Information Service (SIS) tersedia. SIS memberikan informasi tambahan tentang stasiun dan media yang sedang diputar.
• Bit 8: Menunjukkan apakah audio digital HD tersedia.

Metadata

Tabel berikut menunjukkan metadata radio HD yang didukung untuk Android 15 dan versi yang lebih tinggi.

Kolom metadata	Deskripsi
commentShortDescription	Deskripsi singkat konteks komentar
commentActualText	Teks komentar
commercial	Iklan radio
ufids	ID file unik (UFID) yang terkait dengan konten
hdStationNameShort	Nama singkat atau nama singkat universal stasiun radio HD
hdStationNameLong	Nama panjang, slogan, atau pesan dari stasiun radio HD.

Peringatan darurat

Di Android 15 dan yang lebih tinggi, peringatan darurat didukung untuk stasiun radio HD guna memberi tahu pengguna aplikasi radio tentang peringatan darurat yang dikirim dari stasiun radio. Pemberitahuan darurat (Alert) mengikuti Standar Common Alerting Protocol (CAP) 1.2 dan mendukung pemberitahuan yang ditampilkan dalam tabel berikut:

Informasi pemberitahuan	Deskripsi	Nilai enum yang tersedia
AlertStatus	Status pesan pemberitahuan	ACTUAL, EXERCISE, TEST
AlertMessageType	Jenis pesan peringatan darurat	ALERT, UPDATE, CANCEL
AlertCategory	Kategori peristiwa subjek pesan peringatan darurat	GEO, MET, SAFETY, SECURITY, RESCUE, FIRE, HEALTH, ENV, TRANSPORT, INFRA, CBRNE, OTHER
AlertUrgency	Urgensi peristiwa subjek pesan peringatan darurat	IMMEDIATE, EXPECTED, FUTURE, PAST, UNKNOWN
AlertSeverity	Tingkat keparahan peristiwa subjek pesan peringatan darurat	EXTREME, SEVERE, MODERATE, MINOR, UNKNOWN
AlertCertainty	Kepastian peristiwa subjek pesan peringatan darurat	OBSERVED, LIKELY, POSSIBLE, UNLIKELY, UNKNOWN

Anda dapat menggunakan Alert (yang berisi informasi dalam tabel), pesan teks pemberitahuan, dan AlertArea untuk menampilkan informasi tentang pemberitahuan saat ini. Alert adalah kolom opsional di ProgramInfo sehingga dapat dikirim dari Broadcast Radio HAL ke aplikasi radio melalui callback tuner untuk info program saat ini dan pembaruan daftar program.