Broadcast radio HAL

בקטעים הבאים מוסבר איך לעבוד עם שכבת הפשטת החומרה (HAL) כדי להטמיע רדיו לשידור.

ממשק HAL של שידורי רדיו

שכבת ה-HAL של רדיו השידור מספקת מבני נתונים וממשקים ברמת החומרה כדי להטמיע רדיו שידור, כמו רדיו AM/FM ו-DAB.

ממשקי HIDL 2.0 ו-AIDL

שכבת ה-HAL של רדיו השידור משתמשת בממשקים שמתוארים בקטעים הבאים.

IAnnouncementListener

‫IAnnouncementListener הוא ממשק הקריאה החוזרת של ה-listener להודעות, שאפשר לרשום אותו ב-HAL של רדיו השידור כדי לקבל הודעות. לממשק יש את השיטות הבאות:

IAnnouncementListener
תיאור: מופעל בכל פעם שרשימת ההודעות משתנה.
HIDL 2.0 oneway onListUpdated(vec<Announcement> announcements)
AIDL oneway void onListUpdated(in Announcement[] announcements)

ICloseHandle

‫ICloseHandle הוא ה-handle הכללי לסגירה שמשמש להסרת callback שלא צריך ממשק פעיל.

ICloseHandle
תיאור: סוגרים את הידית.
HIDL 2.0 close()
AIDL void close()

ITunerCallback

‫ITunerCallback הוא ממשק הקריאה החוזרת שמופעל על ידי HAL של רדיו השידור כדי לשלוח עדכונים לשירות הלקוח של HAL.

ITunerCallback
תיאור: הפונקציה הזו מופעלת על ידי HAL כשפעולת כוונון (tune, seek (in AIDL) or scan (in HIDL) and step succeeds) נכשלת באופן אסינכרוני.
HIDL 2.0 oneway onCurrentProgramInfoChanged(ProgramInfo info)
AIDL void onCurrentProgramInfoChanged(in ProgramInfo info)
תיאור: מופעל כשפעולות כמו כוונון, חיפוש (ב-AIDL) או סריקה (ב-HIDL) או מעבר שלב מצליחות.
HIDL 2.0 oneway onTuneFailed(Result result, ProgramSelector selector)
AIDL void onTuneFailed(in Result result, in ProgramSelector selector)
תיאור: מופעל כשפעולות כמו כוונון, חיפוש (ב-AIDL) או סריקה (ב-HIDL) או מעבר שלב מצליחות.
HIDL 2.0 oneway onCurrentProgramInfoChanged(ProgramInfo info)
AIDL void onCurrentProgramInfoChanged(in ProgramInfo info)
תיאור: מופעל כשרשימת התוכניות מתעדכנת. הגודל של כל נתח צריך להיות מוגבל ל-500KiB.
HIDL 2.0 oneway onProgramListUpdated(ProgramListChunk chunk)
AIDL void onProgramListUpdated(ProgramListChunk chunk)
תיאור: מופעל כשהאנטנה מחוברת או מנותקת.
HIDL 2.0 oneway onAntennaStateChange(bool connected)
AIDL void onCurrentProgramInfoChanged(in ProgramInfo info)
תיאור: מופעל כשערכי פרמטרים ספציפיים לספק מתעדכנים באופן פנימי ב-HAL (לא מופעל אחרי קריאה ל-setParameters על ידי לקוח HAL).
HIDL 2.0 oneway onParametersUpdated(vec<VendorKeyValue> parameters)
AIDL void onParametersUpdated(in VendorKeyValue[] parameters)
תיאור: תכונה חדשה ב-AIDL. הפונקציה מופעלת כשהדגל של ההגדרה מתעדכן באופן פנימי ב-HAL (לא אמורה להיות הפעלה אחרי קריאה ל-setConfigFlag על ידי לקוח HAL).
HIDL 2.0 לא ישים.
AIDL void onConfigFlagUpdated(in ConfigFlag flag, in boolean value)

IBroadcastRadio

‫IBroadcastRadio הוא הממשק הראשי של HAL של רדיו השידור. ב-HIDL 2.0 HAL, משתמשים בממשק ITunerSession של הטיונר כדי להפעיל פעולות. עם זאת, לכל היותר טיונר אחד פעיל בכל פעם (בתנאי שלכל מופע HAL של רדיו שידור יש רק שבב טיונר אחד). ‫ITunerSession הוסר מהממשקים של AIDL והממשקים שלו הועברו אל IBroadcastRadio.

IBroadcastRadio
תיאור: קבלת תיאור של מודול והיכולות שלו.
HIDL 2.0 getProperties() generates (Properties properties)
AIDL Properties getProperties()
תיאור: אחזור של הגדרות האזור הנוכחיות או האפשריות של AM/FM.
HIDL 2.0 getAmFmRegionConfig(bool full) generates (Result result, AmFmRegionConfig config)
AIDL AmFmRegionConfig getAmFmRegionConfig(bool full)
תיאור: אחזור של הגדרות האזור הנוכחיות של DAB.
HIDL 2.0 getDabRegionConfig() generates (Result result, vec<DabTableEntry> config)
AIDL DabTableEntry[] getDabRegionConfig()
תיאור: מקבל תמונה מהמטמון של מודול הרדיו. ב-AIDL, גודל התמונה חייב להיות קטן מ-1MB בגלל מגבלה קשיחה על מאגר העסקאות של ה-binder.
HIDL 2.0 getImage(uint32_t id) generates (vec<uint8_t> image)
AIDL byte[] getImage(in int id)
תיאור: רישום של מעבד האירוע של ההודעה.
HIDL 2.0 registerAnnouncementListener(vec<AnnouncementType> enabled,IAnnouncementListener listener) generates (Result result, ICloseHandle closeHandle)
AIDL ICloseHandle registerAnnouncementListener(in IAnnouncementListener listener, in AnnouncementType[] enabled)
תיאור:
  • ‫HIDL HAL: כשפותחים סשן חדש של כוונון, צריך לסיים את הסשן הישן.
  • ‫AIDL HAL: מכיוון שאין סשן של מקלט, צריך להגדיר רק את הקריאה החוזרת של המקלט. אם הוא קיים, צריך לבטל את ההגדרה של הקריאה החוזרת הישנה.
HIDL 2.0 ‫openSession(ITunerCallback callback) יוצר (Result result, ITunerSession session)
AIDL void setTunerCallback(in ITunerCallback callback)
תיאור:
  • ‫HIDL HAL: סגירה של סשן של מכוון לא יכולה להיכשל, והיא צריכה להתבצע רק פעם אחת.
  • ‫AIDL HAL: אין כרטיס טלוויזיה, וצריך לבטל את ההגדרה רק של הקריאה החוזרת של כרטיס הטלוויזיה.
HIDL 2.0 close()
AIDL unsetTunerCallback()
תיאור: מעבר לערוץ של תוכנית ספציפית.
HIDL 2.0 tune(ProgramSelector program) generates (Result result)
AIDL void tune(in ProgramSelector program)
תיאור: המערכת מחפשת את התוכנית התקפה הבאה בשידור. כדי למנוע בלבול ב-AIDL, השם scan משתנה ל-seek.
HIDL 2.0 scan(bool directionUp, bool skipSubChannel) generates (Result result)
AIDL void seek(in boolean directionUp, in boolean skipSubChannel)
תיאור: שלבים להגעה לערוץ הסמוך, שאולי לא מוצגת בו תוכנית.
HIDL 2.0 step(bool directionUp) generates (Result result)
AIDL void step(in boolean directionUp)
תיאור: ביטול של פעולות בהמתנה של כוונון, סריקה (ב-HIDL) או חיפוש (ב-AIDL) או פעולות של מעבר שלב.
HIDL 2.0 cancel()
AIDL void cancel()
תיאור: מחיל מסנן על רשימת הערוצים ומתחיל לשלוח עדכונים של רשימת הערוצים באמצעות קריאה חוזרת (callback) של onProgramListUpdated.
HIDL 2.0 startProgramListUpdates(ProgramFilter filter) generates (Result result)
AIDL void startProgramListUpdates(in ProgramFilter filter)
תיאור: מפסיק את השליחה של עדכונים לרשימת התוכניות.
HIDL 2.0 stopProgramListUpdates()
AIDL void stopProgramListUpdates()
תיאור: אחזור ההגדרה הנוכחית של דגל תצורה נתון.
HIDL 2.0 isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value)
AIDL boolean isConfigFlagSet(in ConfigFlag flag)
תיאור: מגדיר את דגל ההגדרה שצוין.
HIDL 2.0 setConfigFlag(ConfigFlag flag, bool value) generates (Result result)
AIDL void setConfigFlag(in ConfigFlag flag, boolean value)
תיאור: הגדרת ערכי פרמטרים ספציפיים לספק.
HIDL 2.0 setParameters(vec<VendorKeyValue> parameters)

יוצר,

(vec<VendorKeyValue> results)
AIDL VendorKeyValue[] setParameters(in VendorKeyValue[] parameters)
תיאור: מאחזר ערכי פרמטרים ספציפיים לספק.
HIDL 2.0 getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters)
AIDL VendorKeyValue[] getParameters(in String[] keys)

הבהרות בנוגע לממשק

התנהגות אסינכרונית

מכיוון שכל פעולת כוונון (לדוגמה, כוונון, סריקה (ב-HIDL) או חיפוש (ב-AIDL) וצעד) עשויה להיות ארוכה, והשרשור לא צריך להיות חסום למשך זמן רב, הפעולה צריכה לתזמן פעולות ארוכות למועד מאוחר יותר ולהחזיר במהירות סטטוס או תוצאה. בפירוט, כל פעולה צריכה:

  • ביטול כל פעולות ההתאמה שממתינות.
  • בודקים אם אפשר לעבד את הפעולה על סמך נתוני הקלט של השיטה והסטטוס של מכוון התדרים.
  • מתזמנים את משימת הכוונון ומחזירים את Result (ב-HIDL) או את status (ב-AIDL) באופן מיידי. אם הערך של Result או status הוא OK, צריך לקרוא ל-callback של המקלט tuneFailed או currentProgramInfoChanged כשתהליך הכוונון נכשל (למשל, בגלל פסק זמן) או כשהוא מסתיים.

באופן דומה, השיטה startProgramListUpdates מתזמנת את המשימה של עדכון רשימת התוכניות למועד מאוחר יותר, כדי להחזיר במהירות סטטוס או תוצאה. השיטה הזו מבטלת קודם בקשות עדכון בהמתנה, ואז מתזמנת את משימת העדכון ומחזירה את התוצאה במהירות.

מרוץ תהליכים

בגלל ההתנהגות האסינכרונית של פעולות כוונון (לדוגמה, כוונון, סריקה (ב-HIDL) או חיפוש (ב-AIDL) וצעד), קיים מצב של תחרות בין ביטול הפעולה לבין פעולות הכוונון. אם מתבצעת קריאה ל-cancel אחרי ש-HAL משלים פעולת כוונון ולפני שהקריאה החוזרת מסתיימת, אפשר להתעלם מהביטול והקריאה החוזרת צריכה להסתיים ולהתקבל על ידי לקוח HAL.

באופן דומה, אם מתבצעת קריאה ל-stopProgramListUpdates אחרי ש-HAL משלים עדכון של רשימת התוכניות ולפני שהקריאה החוזרת onCurrentProgramInfoChanged מסתיימת, אפשר להתעלם מ-stopProgramListUpdates והקריאה החוזרת צריכה להסתיים.

מגבלת גודל הנתונים

מכיוון שיש מגבלה קשיחה על מאגר הנתונים הזמני של עסקאות Binder, מגבלת הנתונים של חלק מהשיטות בממשק שמעבירות נתונים בגודל גדול פוטנציאלי מובהרת ב-AIDL HAL.

  • ‫getImage דורש שהתמונה תהיה קטנה מ-1MB.
  • onProgramListUpdate מחייב שכל chunk יהיה קטן מ-500kiB. רשימות תוכניות גדולות יותר צריכות להיות מחולקות על ידי הטמעת ה-HAL למספר מקטעים, ולהישלח באמצעות מספר קריאות חוזרות.

שינויים במבני הנתונים של AIDL HAL

בנוסף לשינויים בממשקי המשתמש, השינויים האלה חלים על מבני הנתונים שמוגדרים ב-HAL של AIDL לרדיו לשידור, שמנצל את ה-AIDL.

  • הספירה Constant הוסרה מ-AIDL ומוגדרת כ-const int ב-IBroadcastRadio. במקביל, השם של ANTENNA_DISCONNECTED_TIMEOUT_MS משתנה ל-ANTENNA_STATE_CHANGE_TIMEOUT_MS. נוסף קבוע חדש מסוג int‏ TUNER_TIMEOUT_MS. כל הפעולות של כוונון, חיפוש ודילוג חייבות להסתיים בתוך הזמן הזה.
  • הערכים RDS ו-Deemphasis מסוג Enum הוסרו ב-AIDL והוגדרו כ-const int ב-AmFmRegionConfig. בהתאם לכך, גם fmDeemphasis וגם fmRds ב-ProgramInfo מוצהרים כ-int, תוצאה של חישוב ביטים של הדגלים המתאימים. בינתיים, השמות של D50 ו-D75 ישתנו ל-DEEMPHASIS_D50 ו-DEEMPHASIS_D75, בהתאמה.
  • הספירה ProgramInfoFlags הוסרה מ-AIDL והוגדרה כ-const int ב-ProgramInfo עם הקידומת FLAG_. בהתאם לכך, infoFlags ב-ProgramInfo מוצהר כ-int, תוצאה של חישוב ביטים של דגלים. גם השם TUNED שונה ל-FLAG_TUNABLE, כדי לתאר טוב יותר את ההגדרה שלו, שלפיה אפשר לכוון את התחנה.
  • ב-AmFmBandRange, השם של scanSpacing משתנה ל-seekSpacing, כי השם של scan משתנה ל-seek ב-AIDL.
  • מאחר שהמושג union הוצג ב-AIDL, כבר לא נעשה שימוש ב-MetadataKey וב-Metadata שהוגדרו ב-HIDL HAL. ‫AIDL union Metadata מוגדר ב-AIDL HAL. כל ערך enum שהיה קודם ב-MetadataKey הוא עכשיו שדה ב-Metadata עם סוג של מחרוזת או int, בהתאם להגדרות שלו.

תמיכה ברדיו DAB

בקטע הזה מוסבר על תמיכה ברדיו DAB.

מזהים

סוג המזהה הראשי של רדיו DAB ו-DMB ב-AIDL Broadcast Radio HAL הוא DAB_SID_EXT. אפליקציית DAB_SID_EXT משתמשת במזהי שירות (SID) של 32 ביט כדי לייצג את ה-SID של רדיו DAB ו-DMB.

בנוסף למזהים העיקריים, יש תמיכה גם במזהים משניים כמו DAB_ENSEMBLE ו-DAB_FREQUENCY_KHZ. זה חשוב כי כמה תחנות DAB יכולות לשתף DAB_SID_EXT, אבל להשתמש בערכים שונים של DAB_ENSEMBLE או DAB_FREQUENCY_KHZ. כדי לוודא שרשימת התוכניות מתעדכנת בצורה מדויקת, תחנות עם אותו DAB_SID_EXT מתעדכנות יחד באמצעות ITunerCallback#onProgramListUpdated. העדכון הזה מועבר לשירות הרדיו של Broadcast ולמנהל הרדיו, ולבסוף לאפליקציית הרדיו דרך android.hardware.radio.ProgramList.

Metadata

בטבלה הבאה מוצגים המטא-נתונים הספציפיים ל-DAB שנתמכים ב-AIDL Broadcast Radio HAL:

שדה מטא-נתונים תיאור
dabEnsembleName (טופס מקוצר: dabEnsembleNameShort) שם האנסמבל של תחנת DAB
dabServiceName (קיצור של dabServiceNameShort) שם השירות של תחנת DAB
dabComponentName (קיצור של dabComponentNameShort) שם הרכיב של תחנת DAB

תמיכה ברדיו באיכות HD

בקטע הזה מוסבר על תמיכה ברדיו HD.

מזהים

HD_STATION_ID_EXT משמש כמזהה הראשי של תחנות רדיו HD. כדי לשפר עוד יותר את זיהוי התחנה, מסופקים גם מזהים משניים כמו HD_STATION_NAME ו-HD_STATION_LOCATION. ‫HD_STATION_LOCATION, שמאפשרת לקבל מידע על מיקום, נוספה ב-Android 15.

הפעלה או השבתה של רדיו דיגיטלי

החל מ-Android 15, אפשר להפעיל או להשבית רדיו דיגיטלי (כמו רדיו HD) על ידי שינוי ConfigFlag. כדי לשלוט בהגדרה הזו עבור רדיו FM, משתמשים בדגל FORCE_ANALOG_FM. כדי לשלוט בהגדרה הזו עבור רדיו AM, משתמשים בדגל FORCE_ANALOG_AM. הגדרת הדגל ל-false מפעילה רדיו HD, והגדרת הדגל ל-true מחייבת שימוש ברדיו אנלוגי AM/FM.

ערוצים באיכות HD זמינים

החל מ-Android 15, הערוצים ב-HD שזמינים כרגע לתחנת רדיו ב-HD יכולים להיות מיוצגים על ידי מסיכת ביטים של 8 ביטים, Metadata#hdSubChannelsAvailable, ב-ProgramInfo.metadata. לדוגמה, הערך של ביט 1 משמאל מייצג אם ערוץ המשנה HD2 זמין לתחנת HD הזו.

סטטוס קבלת האות

ב-Android בגרסה 15 ומעלה, אפליקציות רדיו יכולות להציג למשתמשים את סטטוס קליטת האות של תחנות רדיו HD. התכונה הזו שימושית כי לפעמים לוקח כמה רגעים עד שהמכשיר קולט אות HD חזק.

כדי לספק את המידע הזה, המערכת משתמשת ב-ProgramInfo.infoFlags כדי לעקוב אחרי הסטטוס ומעדכנת את אפליקציית הרדיו באמצעות ITunerCallback#onCurrentProgramInfoChanged.

כך הסטטוס מוצג ב-ProgramInfo.infoFlags:

  • ביט 6: מציין אם אות הרדיו HD נקלט.
  • ביט 7: מציין אם נתונים של שירות מידע על תחנות (SIS) זמינים. מערכת SIS מספקת מידע נוסף על התחנה ועל התוכן שמופעל בה.
  • ביט 8: מציין אם אודיו דיגיטלי באיכות HD זמין.

Metadata

בטבלה הבאה מוצגים המטא-נתונים של רדיו HD שנתמכים ב-Android 15 ובגרסאות מתקדמות יותר.

שדה מטא-נתונים תיאור
commentShortDescription תיאור קצר של ההקשר של התגובה
commentActualText טקסט התגובה
commercial פרסומת ברדיו
ufids מזהים ייחודיים של קבצים (UFID) שמשויכים לתוכן
hdStationNameShort השם המקוצר או השם המקוצר האוניברסלי של תחנת הרדיו ב-HD
hdStationNameLong השם הארוך של תחנת הרדיו ב-HD, הסלוגן שלה או הודעה מהתחנה.

התרעות על מקרה חירום

ב-Android 15 ואילך, יש תמיכה בהתרעות על מקרי חירום לתחנות רדיו HD, כדי ליידע משתמשים באפליקציות רדיו על התרעות על מקרי חירום שנשלחות מתחנות רדיו. התראת החירום (Alert) פועלת לפי התקן Common Alerting Protocol (CAP) 1.2, והיא תומכת בהתראות שמוצגות בטבלה הבאה:

פרטי ההתראה תיאור ערכי enum זמינים
AlertStatus סטטוס הודעת האזהרה ACTUAL, EXERCISE TEST
AlertMessageType סוג ההודעה של התרעה על מקרה חירום ALERT, UPDATE CANCEL
AlertCategory קטגוריה של אירוע הנושא של הודעת ההתרעה על מקרה חירום ‫GEO, MET, SAFETY, SECURITY, RESCUE, FIRE, HEALTH, ENV, TRANSPORT, INFRA, CBRNE, OTHER
AlertUrgency דחיפות האירוע שמופיע בהודעת ההתרעה על מקרה חירום IMMEDIATE, EXPECTED, FUTURE, PAST, UNKNOWN
AlertSeverity רמת החומרה של אירוע הנושא בהודעת ההתרעה על מקרה חירום EXTREME, SEVERE, MODERATE, MINOR, UNKNOWN
AlertCertainty רמת הוודאות של אירוע הנושא בהודעת ההתרעה על מקרה חירום OBSERVED, LIKELY, POSSIBLE, UNLIKELY, UNKNOWN
אתם יכולים להשתמש ב-Alert (שכולל את המידע שבטבלה), בהודעות טקסט של התראות וב-AlertArea כדי להציג מידע על ההתראה הנוכחית. ‫Alert הוא שדה אופציונלי ב-ProgramInfo כדי שאפשר יהיה לשלוח אותו מ-Broadcast Radio HAL לאפליקציות רדיו דרך קריאות חוזרות של מקלט לעדכונים של רשימת התוכניות ומידע על התוכנית הנוכחית.