Before you continue, review Driving Distraction Guidelines.
This page describes the Car User Experience (UX) Restrictions rules you can use to create multiple UX Restrictions rule configurations (for example, European Union versus Japan) and then determine which set of rules to apply at run time. For more information, see CarUxRestrictions.
The Car UX Restrictions service enables developers to define a new Car UX Restrictions configuration. Should a developer want to modify the restriction rules (such as to comply with local safety standards), the developer can use the API to define the new configuration.
The API to set the configuration persists in the new configuration only. In other words, the configuration does not take effect immediately. Instead, the new configuration is loaded when the UX Restrictions service restarts and the car is in Park. The car service ensures the car is in Park before reloading the new configuration.
In addition to the new UX Restrictions service method, APIs are provided to construct the configuration. The state of gear selection and speed is converted to one of three drivingstates:
- Parked. Gear in Park.
- Idling. Gear not in Park and speed is zero.
- Moving. Gear not in Park and speed isn't zero.
To learn how apps consume a car's driving state and the corresponding UX restrictions, see Consuming Car Driving State and UX Restrictions.
Restriction configuration based on drive states
To prevent driver distraction, Android maps the driving state to a set of UX Restriction
/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java
- Parked. Unrestricted.
- Idling. No video and no configuration screen.
- Moving. Fully restricted (all restrictions are required).
The mapping illustrated above is pre-determined and configured as an XML resource. The
/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java
then saves the rules in memory. The service then maps the current driving state to UX Restrictions
and broadcasts the current restrictions to the entire system.
<!-- No restrictions when car is parked --> <DrivingState car:state="parked"> <Restrictions car:requiresDistractionOptimization="false" car:uxr="baseline"/> </DrivingState> <!-- Restrictions when car is idling --> <DrivingState car:state="idling"> <Restrictions car:requiresDistractionOptimization="true" car:uxr="no_video|no_config"/> </DrivingState> <!-- Restrictions for speed >= 0 m/s --> <DrivingState car:state="moving" car:minSpeed="0.0"> <Restrictions car:requiresDistractionOptimization="true" car:uxr="fully_restricted"/> </DrivingState>
Configurations for multiple displays
By default, no restrictions are applied to additional displays. To create restriction
configurations for multiple displays, include the RestrictionMapping
tag with the
physicalPort for that display. The appropriate restrictions are automatically applied to each
display. In the following example, the displays with physical Port Ids 1 and 2 have different
configurations:
<RestrictionMapping car:physicalPort="1"> <DrivingState car:state="moving"> <Restrictions car:requiresDistractionOptimization="true" car:uxr="no_keyboard|no_video"/> </DrivingState> </RestrictionMapping> <RestrictionMapping car:physicalPort="2"> <DrivingState car:state="moving"> <Restrictions car:requiresDistractionOptimization="true" car:uxr="no_video"/> </DrivingState> </RestrictionMapping>
Configurations for restriction modes
You can select any name for the mode, such as teen. In the following example, different restrictions are configured for default and passenger modes (previously, only passenger mode was supported):
<DrivingState car:state="idling"> <Restrictions car:mode="passenger" car:requiresDistractionOptimization="false" car:uxr="baseline"/> <Restrictions car:requiresDistractionOptimization="true" car:uxr="no_video"/> </DrivingState> </Restrictions>You can use the API to set any string name for the mode. For instance, the
setRestrictionMode(@NonNull String mode)
method in CarUxRestrictionsManager.
(Previously, you would use the
setRestrictionMode(@CarUxRestrictionsManager.UxRestrictionMode int mode)
method in
CarUxRestrictionsManager).
CarUxRestrictionsConfiguration APIs
Restrictions with CarUxRestrictionsConfiguration
The new class CarUxRestrictionsConfiguration
is mapped 1:1 to the current XML
configuration schema. CarUxRestrictionsConfiguration
can be constructed with CarUxRestrictions.
, which validates the configuration
upon build().
new CarUxRestrictionsConfiguration.Builder() // Explicitly set restrictions for each driving state. .setUxRestrictions(CarDrivingStateEvent.DRIVING_STATE_PARKED, /* requiresOptimization= */ false, /* restrictions= */ UX_RESTRICTIONS_BASELINE) .setUxRestrictions(CarDrivingStateEvent.DRIVING_STATE_IDLING, true, UX_RESTRICTIONS_NO_VIDEO|UX_RESTRICTIONS_NO_SETUP) .setUxRestrictions(CarDrivingStateEvent.DRIVING_STATE_MOVING, true, UX_RESTRICTIONS_FULLY_RESTRICTED) // Set restriction parameters. .setMaxStringLength(int max) .setMaxCumulativeContentItems(int max) .setMaxContentDepth(int max) // Build a new CarUxRestrictionsConfiguration. .build();
CarUxRestrictionsManager API
Set CarUxRestrictionsConfiguration
for the next drive with CarUxRestrictionsManager
. This method requires permission,
Car.PERMISSION_CAR_UX_RESTRICTIONS_CONFIGURATION
.
public synchronized boolean saveUxRestrictionsConfigurationForNextBoot( CarUxRestrictionsConfiguration config);
Persist a new UX Restrictions configuration
When a new configuration is passed in, the UX Restrictions service returns a boolean to indicate whether the new configuration has been successfully saved. This new configuration is only used when the Integrated Head Unit (IHU) restarts and the car is parked. Internally, the UX Restrictions service contains two sets of configurations:
- Production. While optional, this configuration is often present. The UX Restrictions service reads this configuration when starting.
- Staged. Also optional, this configuration has no effect on UX Restrictions and is promoted to Production when the car service starts and when the car is parked.
Figure 1. Production configuration
Address failures
Until driving state information is received from CarPropertyManager (for example, during boot-up), UX Restrictions won't be enforced. The system performs as if the driving state is Parked.
Should reading a saved configuration fail (for example, SettingNotFoundException results), the UX Restrictions service falls back to the hard-coded, fully restricted mode:
// Idling/moving state is fully restricted. private static CarUxRestrictionsConfiguration generateDefaultConfig() {}
Driving state and user restrictions
The following content describes the interactions displayed in the following design diagram:
Figure 2. Driving state interactions
Properties used to derive driving state
Use the following three VehiclePropertyIds
to derive the driving state:
APIs available to apps
The code resides in the following locations:
Code | Location |
---|---|
CarUxRestrictionsManager Public APIs to register for UX Restriction changes. |
/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java
|
CarUxRestrictions UX restrictions definition. |
/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java
|
CarDrivingStateManager
System APIs to register for driving state changes. |
/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java
|
To simulate driving states, see Testing.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-10-11 UTC.