OEM custom inputs

Use OEM custom inputs to add new Car input events for new and non-standard Android features. Non-standard input events are not mapped by the existing Android KeyEvent, designed to be generic and to work on any Android surface but not extended to implement OEM-specific features. For example, a button located on the steering wheel control that, when pressed, opens a maps app (through an intent) with the car's current location. This feature enables drivers to visualize their current location without becoming distracted while driving.

This article describes how to reuse an existing Android KeyEvent to create a CustomInputEvent for use only when no Android KeyEvent can be used to represent the feature.

HW_CUSTOM_INPUT

An OEM custom input is represented by HW_CUSTOM_INPUT and CustomInputEvent.java. HW_CUSTOM_INPUT is the native event, instantiated by the car hardware (Vehicle HAL). OEMs determine how to instantiate this event. Access to HW_CUSTOM_INPUT is set as [read only], with VehiclePropertyAccess:READ.

To ensure the Vehicle HAL can always broadcast the latest available value, the HW_CUSTOM_INPUT notification is set as ON_CHANGE, with VehiclePropertyChangeMode:ON_CHANGE.

HW_CUSTOM_INPUT values are composed of an array of generic int32, set as global The three generic integers are:

1. The first element represents the input code to be defined by the OEM. You can associate any semantic to the input code.

   Note: If you don't need more than 10 input codes, then you can use the generic functions (see INPUT_CODE_F1 to INPUT_CODE_F10 constants defined in CustomInputType, see types.hal file) to help readability. Using the generic functions is completely optional.

2. The second element stores the target display, such as the main display or cluster.

3. The third element contains the number of times the event was repeated. For example, to indicate how many times a button was pressed.

CustomInputEvent and Car Input API

InputHalService is the Car service that receives an incoming HW_CUSTOM_INPUT from the Vehicle HAL.

InputHalService converts the incoming HW_CUSTOM_INPUT into the CustomInputEvent, a Java parcelable class located in car-lib/src/android/car/input, along with the respective aidl interface.

CarInputService, a core Car Input service, receives incoming CustomInputEvents and then sends them to any registered Android system service.

To register and receive incoming CustomInputEvents, system services must:

• Implement CarInputManager.CarInputCaptureCallback#onKeyEvents.

• Register through CarInputManager#requestInputEventCapture, passing CarInputManager.INPUT_TYPE_CUSTOM_INPUT_EVENT as the input type parameter.

  To unregister, services must invoke CarInputManager#releaseInputEventCapture.

The following diagram illustrates the workflow of an OEM Custom Input event.

OEM Android system services

OEMs provide their Android system service to handle incoming CustomInputEvents from CarInputService.

Only those services marked with the android.permission.INJECT_EVENTS privilege permission can register and receive CustomInputEvents from the Car Input API (CarInputManager). No third party service or application can be signed with this Android system permission (only OEM services). Therefore, no third party service or application can register against the Car Input API.

OEM Android system services can access SystemApi and public methods.

Reference implementation

See the reference implementation in packages/services/Car/tests/SampleCustomInputService, which is provided as an example and a guideline. For example, to add a new button in the steering wheel control. When pressed, this new button starts the maps app with the current car location.

In this example, the OEM selected INPUT_CODE_F1 (the first CustomInputEvent convenience function) to represent this new feature (opening the maps app with the current car location).

Note: The input code range represented by INPUT_CODE_F1 up to INPUT_CODE_F10 constants is used for convenience only. OEMs cat set any value for input code.

During start up, this service registers itself against CarInputManager through requestInputEventCapture (see the reference implementation registration code.

When receiving incoming CustomInputEvents, this service sends the intent to start the maps app. To learn how this is accomplished, see CustomInputEventListener.java.