Guida all'integrazione per gli OEM

Questa pagina descrive come elaborare gli input rotativi in VHAL, configurare la build per includere il servizio rotatorio e come personalizzarla in tutte le app. Per le app OEM preinstallate, ad esempio un Avvio app fornito dall'OEM, consulta Libreria UI auto (car-ui-library).

VHAL

Un controller rotativo supporta le seguenti azioni:

  • Sposta leggermente verso l'alto, il basso, a sinistra e a destra.
  • Ruota in senso orario e antiorario.
  • Premi il pulsante centrale.
  • Premi il pulsante Indietro.
  • Premi il pulsante Home.
  • Premi altri pulsanti, come Telefono e Media.

Consulta hardware/interfaces/automotive/vehicle/2.0/types.hal per la documentazione su proprietà di sistema e il relativo int32Values.

Il VHAL dovrebbe gestire le seguenti azioni:

Sollecito

Quando l'utente spinge il controller rotativo verso destra, il VHAL deve utilizzare la HW_KEY_INPUT proprietà con i seguenti int32Values per inviare un su Android:

  1. ACTION_DOWN
  2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
  3. Display di destinazione.

Quando l'utente rilascia il controller rotatorio, il VHAL deve usare la stessa proprietà. keycode con ACTION_UP. Per i solleciti in altre direzioni è necessario utilizzare i codici chiave corrispondenti.

Non esistono codici chiave per le diagonali, ma il VHAL può combinare tra loro due canali per produrre una diagonale se l'hardware supporta le diagonali. Ad esempio, sollecitare a sinistra dovrebbe produrre:

  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN

In entrambi gli ordini (e successivamente) il rilascio del controller rotatorio dovrebbe produrre:

  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

L'utente può spingere il controller rotatorio in direzione perpendicolare prima di rilasciarlo. Ad esempio, il seguente scenario:

Direzione perpendicolare
Figura 1. Direzione perpendicolare
.

Dovrebbe essere generata la seguente sequenza di eventi:

  1. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
  2. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN
  3. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
  4. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

Non devono essere generati eventi ripetuti mentre è tenuto il rotary controller in una sola direzione.

Ruota

Quando l'utente ruota il controller rotativo in senso orario di un arresto (clic), il VHAL deve utilizzare la proprietà HW_ROTARY_INPUT con i seguenti int32Values per inviare un evento ad Android:

  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. Un (1) fermo.
  3. Display di destinazione.

Il timestamp dell'evento deve essere impostato sul tempo trascorso in nanosecondi.

Una rotazione di un (1) arresto in senso antiorario dovrebbe generare lo stesso evento, ma con -1 per il numero di fermi.

Se si verificano più fermi della rotazione nella stessa direzione in rapida successione, dovrebbero combinare i fermi in un unico evento in modo da non sovraccaricare il sistema di eventi. In questo caso, il timestamp dell'evento deve corrispondere al momento in cui si è verificato il primo blocco della rotazione. int32Values deve includere il numero di nanosecondi tra i fermi consecutivi dalla rotazione.

Ad esempio, la seguente sequenza di rotazioni:

  • Nel momento t0, l'utente ha ruotato un fermo in senso antiorario.
  • Al tempo t0 + 5 ns, l'utente ha ruotato un fermo in senso antiorario.
  • Al tempo t0 + 8 ns, l'utente ha ruotato un fermo in senso antiorario.

dovrebbe generare questo evento:

  • Proprietà: HW_ROTARY_INPUT
  • Data e ora: t0
  • int32Values:
    1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
    2. -3 (tre fermi in senso antiorario).
    3. Display di destinazione.
    4. 5 ns tra il primo e il secondo fermo.
    5. 3 ns tra il secondo e il terzo fermo.

Pulsante centrale

Quando l'utente preme il pulsante centrale, il VHAL dovrebbe usare HW_KEY_INPUT con il seguente int32Values per inviare un evento ad Android:

  1. ACTION_DOWN
  2. KEYCODE_DPAD_CENTER
  3. Display di destinazione.

Quando l'utente rilascia il controller rotativo, il VHAL deve usare la stessa proprietà. e keycode con ACTION_UP.

Non generare eventi ripetuti quando si tiene premuto il pulsante centrale.

Pulsante Indietro

Quando l'utente preme il pulsante Indietro, il VHAL dovrebbe usare HW_KEY_INPUT con il seguente int32Values per inviare un evento ad Android:

  1. ACTION_DOWN
  2. KEYCODE_BACK
  3. Display di destinazione.

Quando l'utente rilascia il controller rotativo, il VHAL deve usare la stessa proprietà. e keycode con ACTION_UP.

Non devono essere generati eventi ripetuti mentre si tiene premuto il pulsante centrale.

Pulsante Home

Puoi gestire il pulsante Home come faresti con il pulsante Indietro, ma con KEYCODE_HOME di KEYCODE_BACK.

Altri pulsanti

Tuttavia, se il controller rotatorio include pulsanti aggiuntivi, il VHAL può gestirli all'OEM, perché non sono considerati parte rotatoria dal punto di vista di Android. In genere vengono gestiti come i pulsanti Indietro e Home, ma con codici chiave diversi. Ad esempio, KEYCODE_CALL o KEYCODE_MUSIC.

Configurazione build

La navigazione rotatoria è fornita da un servizio di accessibilità chiamato RotaryService. Per includere questo servizio nell'immagine di sistema del tuo dispositivo, aggiungi la seguente riga al tuo Makefile:

PRODUCT_PACKAGES += CarRotaryController

Puoi anche includere i pacchetti seguenti nelle build di debug:

  • RotaryPlayground Un'app di riferimento per gli annunci rotativi (vedi RotaryPlayground).
  • RotaryIME Un IME rotativo dimostrativo (vedi Input Method Editor).
  • CarRotaryImeRRO L'overlay per RotaryIME.

Il servizio rotatorio viene abilitato automaticamente all'avvio del dispositivo e quando un utente il passaggio a un altro dispositivo. Ciò garantisce che l'utente possa utilizzare il controller rotativo durante la configurazione.

Se usi la stessa build per auto con e senza controller rotativo, aggiungi CarRotaryController come mostrato sopra in modo che sia incluso il codice necessario durante la creazione. Per impedire che il servizio rotatorio venga abilitato sulle automobili non rotative, crea un'istanza RRO statico per sovrapporre la risorsa stringa rotaryService in packages/services/Car/service con una stringa vuota. Utilizzerai la stessa build, ma prevedono configurazioni di prodotto separate per dispositivi rotativi e non. Solo quest'ultimo include l'overlay.

Personalizzazione

Gli OEM possono personalizzare la logica di ricerca delle priorità, l'evidenziazione dell'elemento attivo e alcuni elementi aggiuntivi tramite overlay delle risorse nelle seguenti posizioni:

  • car-ui-library si trova in packages/apps/Car/libs/car-ui-lib
  • RotaryService si trova a packages/apps/Car/RotaryController
  • Core si trova a frameworks/base/core

Cronologia suggerimenti

L'OEM può configurare se abilitare o meno ciascuno dei due tipi di cronologia dei consigli e, in tal caso, il criterio di dimensione e scadenza della cache. Per farlo, basta eseguire l'override di varie car-ui-library Google Cloud.

Imposta lo stato attivo sulla cache della cronologia

(Android 11 QPR3, Android 11 Car, Android 12)
Questa cache per FocusArea archivia la visualizzazione selezionata più recente all'interno FocusArea in modo che possa essere concentrato quando torni indietro al FocusArea. Questa cache può essere configurata sovrapponendo le seguenti risorse car-ui-library:

  • car_ui_focus_history_cache_type:
    1. La cache è disabilitata.
    2. La cache scadrà dopo un po' di tempo (vedi di seguito).
    3. La cache non scadrà mai.
  • car_ui_focus_history_expiration_period_ms: il numero di millisecondi prima che venga La cache scade se il tipo di cache è impostato su due (2) (vedi sopra).

Cache della cronologia di FocusArea

(Android 11 QPR3, Android 11 Car, Android 12)
Questa cache archivia una cronologia dei solleciti in modo che quelli nella direzione opposta possano riporta lo stato attivo sullo stesso FocusArea. Questa cache può essere configurata sovrapponendo la seguenti risorse car-ui-library:

  • car_ui_focus_area_history_cache_type:
    1. La cache è disabilitata.
    2. La cache scade dopo un po' di tempo (vedi di seguito).
    3. La cache non scade mai.
  • car_ui_focus_area_history_expiration_period_ms: quanti millisecondi prima del giorno La cache scade se il tipo di cache è impostato su 2 (vedi sopra).
  • car_ui_clear_focus_area_history_when_rotating: indica se svuotare la cache quando l'utente ruota il controller.

Rotazione

(Android 11 QPR3, Android 11 Car, Android 12)
L'OEM può eseguire l'override di due risorse intere nel campo RotaryService per specificare se c'è un'accelerazione, come l'accelerazione del mouse, per la rotazione:

  • rotation_acceleration_3x_ms: intervallo di tempo (in millisecondi) utilizzato per decidere se Google deve accelerare la rotazione del controller per un arresto della rotazione. Se l'intervallo tra questo fermo e il precedente arresto di rotazione è inferiore a questo valore, verrà considerato come tre blocchi di rotazione. Impostalo su 2147483647 per disattivare 3× dell'accelerazione.
  • rotation_acceleration_2x_ms: simile a rotation_acceleration_3x_ms. Utilizzato per l'accelerazione 2x. Imposta l'opzione su 2147483647 per disattivare l'accelerazione 2x.

L'accelerazione funziona meglio quando sono presenti singoli timestamp per ogni blocco di la rotazione, obbligatorio dal VHAL. Se non sono disponibili, RotaryService presume che i fermi di di rotazione sono distribuiti uniformemente.

/**
     * Property to feed H/W rotary events to android
     *
     * int32Values[0] : RotaryInputType identifying which rotary knob rotated
     * int32Values[1] : number of detents (clicks), positive for clockwise,
     *                  negative for counterclockwise
     * int32Values[2] : target display defined in VehicleDisplay. Events not
     *                  tied to specific display must be sent to
     *                  VehicleDisplay#MAIN.
     * int32values[3 .. 3 + abs(number of detents) - 2]:
     *                  nanosecond deltas between pairs of consecutive detents,
     *                  if the number of detents is > 1 or < -1
     *
     * VehiclePropValue.timestamp: when the rotation occurred. If the number of
     *                             detents is > 1 or < -1, this is when the
     *                             first detent of rotation occurred.
     *
     * @change_mode VehiclePropertyChangeMode:ON_CHANGE
     * @data_enum RotaryInputType
     * @access VehiclePropertyAccess:READ
     */
    HW_ROTARY_INPUT = (
        0x0A20
        | VehiclePropertyGroup:SYSTEM
        | VehiclePropertyType:INT32_VEC
        | VehicleArea:GLOBAL),

Evidenziazione in evidenza

L'OEM può sostituire l'evidenziazione predefinita dell'elemento attivo nel framework Android. diverse risorse in evidenza in car-ui-library.

Evidenziazione predefinita dell'elemento attivo

Il framework Android fornisce un'evidenziazione predefinita tramite l'attributo selectableItemBackground. In Theme.DeviceDefault, questo si riferisce a item_background.xml in Core. L'OEM può sovrapporre item_background.xml per modificare l'evidenziazione predefinita su cui è possibile evidenziare l'elemento.

In genere, questo drawable deve essere un StateListDrawable, che regola lo sfondo in base a diverse combinazioni di stati, tra cui android:state_focused e android:state_pressed. Quando l'utente utilizza il controller rotativo per impostare lo stato attivo su una vista, android:state_focused sarà true, ma Il valore di android:state_pressed sarà false. Se l'utente preme poi il pulsante centrale del controller rotativo, sia android:state_focused che android:state_pressed sarà true mentre l'utente tiene premuto il pulsante. Quando l'utente rilascia il pulsante, rimarrà solo android:state_focused true.

car-ui-library utilizza un tema derivato da Theme.DeviceDefault. Di conseguenza, l'overlay interessa le app che utilizzano la libreria e le app che usano qualsiasi tema derivato da Theme.DeviceDefault. Non inciderà sulle app che usano un tema non correlato. ad esempio Theme.Material.

Concentrazione sulle risorse dei contenuti in evidenza in car-ui-library

L'OEM può eseguire l'override di diverse risorse car-ui-library per controllare l'evidenziazione dell'elemento principale guarda le viste con un'evidenziazione non rettangolare (ad esempio a forma di pillola) e in app che usano un tema non derivato da Theme.DeviceDefault. Questi le risorse devono essere sovrapposte in modo che l'evidenziazione in evidenza sia coerente con disegnabile con evidenziazione predefinita dello stato attivo.

(Android 11 QPR3, Android 11 Car, Android 12)
Le seguenti risorse vengono utilizzate per indicare quando una visualizzazione viene selezionata ma non viene premuta:

  • car_ui_rotary_focus_fill_color: colore riempimento.
  • car_ui_rotary_focus_stroke_color: colore dei contorni.
  • car_ui_rotary_focus_stroke_width: spessore del contorno.

(Android 11 QPR3, Android 11 Car, Android 12)
Le seguenti risorse vengono utilizzate per indicare quando una visualizzazione viene evidenziata e viene premuta:

  • car_ui_rotary_focus_pressed_fill_color: colore riempimento.
  • car_ui_rotary_focus_pressed_stroke_color: colore dei contorni.
  • car_ui_rotary_focus_pressed_stroke_width: spessore del contorno.

A volte, a un pulsante viene assegnato un colore di sfondo a tinta unita per attirare l'attenzione dell'utente. come nell'esempio mostrato. Ciò potrebbe rendere difficile la visualizzazione dell'evidenziazione in evidenza.

Pulsante con sfondo in tinta unita
Figura 2. Pulsante con sfondo in tinta unita
.

In questo caso, lo sviluppatore può specificare un'evidenziazione personalizzata per l'elemento attivo utilizzando colori secondari:
    .
  • (Android 11 QPR3, Android 11 Car, Android 12)

    car_ui_rotary_focus_fill_secondary_color car_ui_rotary_focus_stroke_secondary_color
  • (Android 12).

    car_ui_rotary_focus_pressed_fill_secondary_color car_ui_rotary_focus_pressed_stroke_secondary_color

Tutti i colori possono essere trasparenti e entrambe le dimensioni possono essere zero se, ad esempio, solo un riempimento o un contorno.

Evidenziazione dell'area di messa a fuoco

(Android 11 QPR3, Android 11 Car, Android 12)
FocusArea può disegnare due tipi di evidenziazione quando uno dei suoi discendenti viene concentrato. Se lo desideri, entrambi possono essere utilizzati insieme. Questa funzione è disattivata per impostazione predefinita in AOSP, ma può essere attivato eseguendo l'override delle risorse car-ui-library:

  • car_ui_enable_focus_area_foreground_highlight: disegna un'evidenziazione sopra a FocusArea e i relativi discendenti. In AOSP, questo disegnabile è un contorno intorno a FocusArea. Gli OEM possono sostituire Drawable car_ui_focus_area_foreground_highlight.
  • car_ui_enable_focus_area_background_highlight: disegna un'evidenziazione sopra lo FocusArea ma dietro i suoi discendenti. In AOSP, questo drawable è un riempimento solido. Gli OEM possono sostituire il drawable car_ui_focus_area_background_highlight.

Editor metodo di input

Gli IME (Input Method Editor) sono metodi di immissione. Ad esempio, una tastiera sullo schermo.

(Android 11 QPR3, Android 11 Car, Android 12)
L'OEM deve sovrapporre la risorsa stringa default_touch_input_method in RotaryService per specificare il ComponentName del IME basato sul tocco. Ad esempio, se l'OEM utilizza l'IME fornito con Android Automotive, devono specificare com.google.android.apps.automotive.inputmethod/.InputMethodService.

(Android 11 QPR3, Android 11 Car, Android 12)
Se l'OEM ha creato un IME specifico per gli elementi rotativi, deve specificarne ComponentName nella risorsa rotary_input_method. Se questa risorsa viene sovrapposto, l'IME specificato viene usato ogni volta che l'utente interagisce con l'unità principale tramite il movimento, la rotazione e il pulsante centrale del controller rotatorio. Quando l'utente tocca sullo schermo, verrà usato l'IME precedente. Il pulsante Indietro (e altri pulsanti della parte rotante controller) non hanno alcun effetto sulla selezione dell'IME. Se questa risorsa non è sovrapposta, nessun cambio IME . Carboard non supporta gli elementi rotatori, quindi l'utente non può inserire testo al loro interno se l'OEM non ha fornito un IME rotativo.

RotaryIME è un IME rotativo dimostrativo. Sebbene sia basilare, è sufficiente provare il passaggio automatico IME descritto sopra. Il codice sorgente di RotaryIME disponibile in packages/apps/Car/tests/RotaryIME/.

Incoraggiamenti fuori schermo

Per impostazione predefinita, quando l'utente tenta di allontanare il bordo dello schermo, non succede nulla. L'OEM può configurare cosa deve accadere per ciascuna delle quattro direzioni specificando combinazione di:

  1. Un'azione globale definita da AccessibilityService. Ad esempio: GLOBAL_ACTION_BACK.
  2. Un codice chiave, ad esempio KEYCODE_BACK.
  3. L'intenzione di avviare un'attività rappresentata sotto forma di URL.

(Android 11 QPR3, Android 11 Car, Android 12)
Questi vengono specificati sovrapponendo le seguenti risorse di array nel RotaryService:

  • off_screen_nudge_global_actions: array di azioni globali da eseguire quando l'utente sposta verso l'alto, verso il basso, a sinistra o a destra il bordo dello schermo. Nessuna azione globale è se l'elemento pertinente di questo array è -1.
  • off_screen_nudge_key_codes: array di codici chiave degli eventi di clic da inserire quando l'utente spinge verso l'alto, il basso, a sinistra o a destra dal bordo dello schermo. Nessun evento è inserito se l'elemento pertinente di questo array è 0 (KEYCODE_UNKNOWN).
  • off_screen_nudge_intents: array di intent per avviare un'attività quando l'utente sposta verso l'alto, verso il basso, a sinistra o a destra il bordo dello schermo. Nessuna attività è se l'elemento pertinente di questo array è vuoto.

Altre configurazioni

Devi sovrapporre le seguenti RotaryService risorse:

  • (Android 11 QPR3, Android 11 Car, Android 12)
    config_showHeadsUpNotificationOnBottom: valore booleano per indicare se le notifiche in evidenza devono essere visualizzate in basso e non in alto. Deve hanno lo stesso valore di config_showHeadsUpNotificationOnBottom Risorsa booleana in frameworks/base/packages/CarSystemUI/res/values/config.xml
  • (Android 11 QPR3, Android 11 Car, Android 12)
    notification_headsup_card_margin_horizontal: margine sinistro e destro per finestra di notifica in evidenza. Deve avere lo stesso valore del parametro notification_headsup_card_margin_horizontal risorsa dimen in packages/apps/Car/Notification/res/values/dimens.xml
  • (Android 12).
    excluded_application_overlay_window_titles: un array di titoli di finestre che non devono essere considerate finestre overlay. Devono essere inclusi i titoli di finestre dell'app che rappresentano TaskViews o TaskDisplayAreas. Per impostazione predefinita, questo elenco contiene solo "Maps".

Puoi sovrapporre la seguente risorsa RotaryService:

  • (Android 11 QPR3, Android 11 Car, Android 12)
    long_press_ms: valore intero che rappresenta il numero di millisecondi Il pulsante centrale deve essere tenuto premuto per attivare una pressione prolungata. Zero indica il sistema. deve essere usato il timeout predefinito della pressione prolungata. Questo è il valore predefinito.