Set up remote access

Android 14 introduces the new remote access feature, which enables partners to remotely wake up Android in a vehicle to execute specific tasks. For example, to execute Garage mode overnight to apply software updates. Multiple non-Android components are required for the end-to-end workflow. Android doesn't define or provide implementation for non-Android components (this responsibility belongs to you).

To learn more, see the following sections:

Workflow. Workflow between multiple components in the sample architecture for client registration and task delivery.
Write a remote task client. Use remote access and learn how to write a remote task client.
Vendor implementation. Vendor components in the sample architecture to support remote access.
Factory reset and ownership transfer. Learn how to handle factory reset and vehicle ownership transfer.
Test the remote access client. Learn how to test the remote access feature.

Architecture

The following content presumes the following sample architecture is used, which is hypothetical and might not reflect actual architecture. OEMs should adapt an actual implementation to their vehicle and server architectures.

Figure 1. Sample architecture.

The sample architecture consists of these hardware components:

Hardware component	Description
App processor	Processor that runs Android. Android might run on virtual memory (VM) (not on actual hardware) on this processor.
Vehicle processor	Processor responsible for controlling power for the app processor.
Telematics control unit (TCU)	Processor in vehicle always capable of receiving remote messages from the cloud. The TCU is presumed to always be on or in low-power mode. Use remote messages to awaken the TCU.
Wake-up server	A remote server that runs in the cloud and is responsible for communicating with the TCU in the vehicle to issue wake-up commands.
Remote task server	Remote task server runs in the cloud and interacts with people and manages remote tasks.

The sample architecture consists of the these software components, all of which run on Android:

On-Android software component	Description
Car Service	AAOS framework service that provides remote access APIs.
Remote task client	A vendor-written `Service` class that executes remote tasks. One Android system can run multiple remote task clients.
Remote access HAL	Must be implemented for remote access. Abstraction layer for communication between AAOS and a non-Android component such as the TCU.

Non-Android software components are described below:

Non-Android software component	Description
Wake-up client	Software running on TCU that maintains a long-live connection with the wake-up server. It also maintains a connection with the Remote Access HAL to deliver remote tasks to the Car Service.
Wake-up server implementation	Server that communicates with the wake-up client running on TCU. Can send wake-up requests to the wake-up client.
Remote task server implementation	Server that manages remote tasks. Users interact with this server to issue and monitor remote tasks.

Workflow

This section lists the steps in a sample workflow.

Sample workflow

A detailed workflow can resemble the following:

User parks vehicle in garage.
Partner seeks to update vehicle overnight when vehicle interactions are unlikely.
Partner cloud server sends an update system remote task to the vehicle. Specifically, the telematic control unit (TCU).
The vehicle’s TCU wakes up the Android electronic control unit (ECU) and an OEM service triggers Garage mode.
Android runs Garage mode to download and install updates through Google Play.
After applying the update, Android marks the task as complete and either ends the connection or reaches a specified timeout.

Detailed workflow

There are two important steps required for remote access. The first is to register the client, which is to link a specific user to a specific remote task client running on a specific vehicle. The other is deliver a task, which is to deliver the remote task for a specific user to the specific remote task client running on the specific vehicle.

Register a client

To use the remote access feature, a user has to open the remote task client app at least once and finish the client registration process (bold text indicates tasks implemented by AAOS):

On boot-up, Car Service gets vehicle information from the remote access HAL.
On boot-up, Car Service launches all remote task clients based on intent-filter and permission.
Upon remote task client start, the remote task client registers itself with the Car Service.
Car Service notifies the remote task client about registration information, including vehicle ID and client ID. The client ID is unique and assigned by Car Service to this client. It's guaranteed to be unique among all remote task clients on the same vehicle.
User logs in to the remote task server via the remote task client and enables the remote access feature for this vehicle. This step typically involves authentication through the remote task server.
The remote task client uploads the user’s information along with vehicle ID and client ID to the remote task server and asks it to link the user with this specific client and this specific vehicle.

Optionally, this step might involve additional two-factor authentication from the user.

The remote task server must authenticate that the vehicle ID provided in the request matches the sender’s vehicle ID, which can be done through vehicle attestation.

Note: A user might own multiple vehicles. A sample database in the remote task server could use [userID, vehicleID] as a key and [client ID] as a value.

Unless a factory reset takes place, the client registration process is required once per user per vehicle. The client ID is stored locally in the Car Service and stays the same for the same client.

Figure 2. Register a client.

Unregister a client

A user can unlink the vehicle from their account either from the vehicle or from the remote task server:

On the vehicle, users can open the remote task client app and issue an unlink request to unlink this vehicle from its previously linked user accounts.
On the remote task server, users can log in to their account and unlink a previously linked vehicle from this account.

If the user unlinks the vehicle from their account, the remote task server must remove the stored mapping for the specific user.

Deliver tasks

In the cloud:

A user uses the remote task server to send a remote task to a specific vehicle.
The remote task server maps the user ID to the vehicle ID and client ID. It sends the task data, vehicle ID and client ID to the wake-up server.
The wake-up server finds the specific TCU for the vehicle ID (assuming the TCU registration is already done) and sends the task data and client ID to the TCU.

On the vehicle (bold text indicates tasks performed by AAOS):

TCU receives remote tasks from remote server.
If the app processor (AP) running AAOS is off, TCU uses the vehicle processor (VP) to wake up the AP.
Car Service receives tasks from TCU.
Car Service distributes tasks to the corresponding remote task client.
Remote task client receives and executes the task.

(Optional) Remote task client contacts task server for more task detail and executes the task.
(Optional) Remote task client service reports task result to task server.
Remote task client notifies Car Service when the task is completed.
If required, the Car Service restores the vehicle’s power state.

Figure 3. Deliver tasks.

Write a remote task client

CarRemoteAccessManager provides the API for remote access features. To learn more, see CarRemoteAccessManager. A remote task client is an Android service that executes remote tasks and uses CarRemoteAccessManager. This requires PERMISSION_USE_REMOTE_ACCESS and PERMISSION_CONTROL_REMOTE_ACCESS and must declare an intent filter for RemoteTaskClientService such as:

<service android:name=".remoteaccess.RemoteTaskClientService"
         android:directBootAware="true"
         android:exported="true">
    <intent-filter>
       <action android:name="android.car.remoteaccess.RemoteTaskClientService" />
    </intent-filter>
</service>

A remote task client should register itself to the Car Service during create:

public final class RemoteTaskClientService extends Service {
    @Override
    public void onCreate() {
        // mCar = Car.createCar()...
        mRemoteAccessManager = (CarRemoteAccessManager)
            mcar.getCarManager(Car.CAR_REMOTE_ACCESS_SERVICE);
        if (mRemoteAccessManager == null) {
            // Remote access feature is not supported.
            return;
        }
        mRemoteAccessManager.setRemoteTaskClient(executor, mRemoteTaskClient);
    }
}

It must override the onBind function to return null.

@Override
public IBinder onBind(Intent intent) {
    return null;
}

Car Service manages its life cycle. Car Service binds to this service during startup and when a remote task arrives. Car Service unbinds to this service when the task is complete. To learn more, see Managing the lifecycle of a service.

The remote task client runs as the system user so it doesn't have access to any user-specific data.

The following example shows how to handle the registered callbacks:

private final class RemoteTaskClient
    implements CarRemoteAccessManager.RemoteTaskClientCallback {
    @Override
    public void onRegistrationUpdated(
        RemoteTaskClientRegistrationInfo info) {
        // Register to remote task server using info.
    }
    @Override
    public void onRemoteTaskRequested(String taskId,
        byte[] data, int remainingTimeSec) {
        // Parses the data and execute the task.
        // Report task result to remote task server.
        mRemoteAccessManager.reportRemoteTaskDone(taskId);
    }
    @Override
    public void onShutdownStarting(CompleteableRemoteTaskFuture future) {
        // Stop the executing task.
        // Clear the pending task queue.
        future.complete();
    }
}

Vendor implementation

The remote access feature is optional and disabled by default. To enable the feature, add an RRO such as the following:

// res/xml/overlays.xml
<?xml version="1.0" encoding="utf-8"?>
<overlay>
    <item target="array/config_allowed_optional_car_features" value="@array/config_allowed_optional_car_features" />
</overlay>

// res/values/config.xml
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <string-array translatable="false" name="config_allowed_optional_car_features">
        <item>car_remote_access_service</item>
    </string-array>
</resources>

// Android.bp
runtime_resource_overlay {
    name: "RemoteAccessOverlay",
    resource_dirs: ["res"],
    manifest: "AndroidManifest.xml",
    sdk_version: "current",
    product_specific: true
}

Or use the following adb command on a userdebug/eng build:

adb shell cmd car_service enable-feature car_remote_access_service

On-Android requirements

Remote access HAL

The remote access hardware abstraction layer (HAL) is a vendor-implemented abstraction layer for communication between AAOS and another ECU (for example, a TCU). It is mandatory for supporting the remote access feature. It doesn't need to be implemented if the remote access feature isn't implemented.

The interface is defined at IRemoteAccess.aidl and includes these methods:

Class	Description
`String getVehicleId()`	Gets a unique vehicle ID that can be recognized by the wake-up server.
`String getWakeupServiceName()`	Gets the name for the remote wake-up server.
`String getProcessorId()`	Gets a unique processor ID that can be recognized by waking up the client.
`void setRemoteTaskCallback(IRemoteTaskCallback callback)` Sets a callback to be called when a remote task is requested.
`void clearRemoteTaskCallback()`	Clears a previously set remote task callback.
`void notifyApStateChange(in ApState state)` Detects if the app processor is ready to receive remote tasks.

The callback interface is defined at at IRemoteTaskCallback.aid.

Class	Description
`oneway void onRemoteTaskRequested(String clientId, in byte[] data)` A callback that is called when a remote task is requested.

See the reference implementation with an external TCU. The implementation uses a long-live read stream to receive remote tasks and supports the following debug command:

dumpsys android.hardware.automotive.remoteaccess.IRemoteAccess/default

Vehicle HAL

To support the remote access feature, VHAL must supports these properties:

Class	Description
`SHUTDOWN_REQUEST`	Requests the head unit to be shut down.
`VEHICLE_IN_USE`	Detects if the vehicle is in use. After the user unlocks the vehicle or as the user approaches the vehicle. Should be `true`. A specific duration after the user turns off the vehicle or when the user locks the vehicle. Should be `false`. When `true`, AAOS doesn't attempt to shut down the vehicle when the remote task is completed.

To learn more, see Supported System Properties.

Silent mode

Silent mode must be supported for the remote access feature so that the vehicle can boot up in silent mode to execute remote tasks when no user is present. With silent mode, AAOS device boots up with display and audio turned off.

Silent mode is controlled through two Linux kernel sysfs files.

Class	Description
`/sys/kernel/silent_boot/pm_silentmode_kernel_state` Represents the current silent mode.
`/sys/kernel/silent_boot/pm_silentmode_hw_state` Represents the hardware signal to set a new silent mode.

The vehicle processor sends a HW signal to Android SoC to turn on/off Silent mode. The signal (0 or 1)is written to /sys/kernel/silent_boot/pm_silentmode_hw_state. Then, AAOS framework updates /sys/kernel/silent_boot/pm_silentmode_kernel_state accordingly which represents the current Silent mode. AAOS modules checks /sys/kernel/silent_boot/pm_silentmode_kernel_state to know whether the system is in Silent mode or not.

When a remote task is received and AAOS boots up, the vehicle processor sets Silent mode and starts AAOS so that the system boots with display/audio off.

On-vehicle non-Android components

Vehicle processor

The vehicle processor is a processor in the vehicle that can control the power for the app processor running Android. In the example architecture, TCU wakes up the app processor via sending a signal to the vehicle processor.

On-vehicle non-Android components

The vehicle TCU can always receive remote messages.

The wake-up client runs on the TCU to ensure a long-lived connection with the remote wake-up server.

AAOS running on the AP can communicate with the wake-up client running on th TCU through the remote access HAL.

Figure 4. TCU (wake-up client).

On-cloud components

Wake-up server

The wake-up server communicates with the wake-up client on the TCU to:

Maintain a long-lived connection with the vehicle’s TCU.
Find a specific TCU based on a vehicle ID.
Report a vehicle’s status. For example, online or offline, or last online time to the remote task server.

In an actual implementation, a wake-up server can be merged with a remote task server.

Remote task server

The remote task server manages these remote tasks.

User interacts with the server to start new remote tasks and to monitor remote tasks.
Uses the remote wake-up server to wake up the app processor in the vehicles.
Interacts with the remote task client running on the vehicle.
Stores client registration information. This associates a specific user to a specific remote task client on a specific vehicle.

Typically the task data that is sent via the remote task server to the wake-up server, to the vehicle’s TCU, and eventually to the remote task client is simply a task ID. The remote task client uses the task ID to fetch the detailed information from the remote task server.

Privacy and security requirements

Task	Condition	Requirement
TCU (wake-up client)	MUST	Authenticate the wake-up server. Trust the code.
Wake-up server	MUST	Permit only allow-listed remote task servers to connect. Authenticate the wake-up client. Send the wake-up message to the target vehicle only.
Remote task client	MUST	Authenticate the user during registration. Authenticate the remote task server. Meet all security requirements for an Android service. For example, limited permissions.
Remote task server	MUST	Must authenticate the wake-up server. Provide vehicle attestation. That is, authenticate that the vehicle ID provided in the request matches the sender’s vehicle ID. If vehicle attestation isn't possible, must use other means to verify that the user currently owns the vehicle. Authenticate the user’s identity. Meet all security requirements for a server that handles user information.

Factory reset and ownership transfer

If a user performs a factory reset, the client ID stored in the Car Service is wiped. However, the servers (remote task server and remote wakeup server) are not informed. The servers retain a mapping from the now expired client ID to the vehicle. As a result, if the user starts a new remote task for the vehicle, it uses the expired client ID. The vehicle is awakened, but the remote task cannot be executed since the remote task client has a different client ID that doesn't match.

The following describes one possible implementation for a factory reset.

When a user issues a factory reset, the vendor prompts the user to log in to the remote task server and unlink the vehicle from their account if the user has previously linked the vehicle. The device isn't guaranteed to have network access during the time of factory reset. Therefore, issuing the unlink request at factory reset time from the device might not be feasible.

Whenever a vehicle’s ownership is transferred, some operations should be performed to ensure the previous owner can no longer issue remote tasks to the vehicle. For example, the new owner may be asked to:

Perform a factory reset. This ensures the client ID is regenerated. After this step, the previous owner can still wake up the vehicle, but can no longer execute remote tasks.
Open the remote task client app and follow the Unregister a client process to unlink the vehicle from the previous owner’s account. The new owner can follow the register a client process to link the vehicle to their account and replace the previously linked account.
The new owner can use the Register a client process to link the vehicle to their account and replace the previously linked account.

Test the remote task client

We provide the reference remote access HAL default directory to test remote task clients. You can use the following debug command to inject a fake remote task to the HAL, which is forwarded to your remote task client if you provide the correct client ID. You can get the client ID by logging the registration information in your remote task client implementation.

adb root && adb shell dumpsys android.hardware.automotive.remoteaccess.IRemoteAccess/default --inject-task [clientID] [taskData]