Kanzi Vehicle Properties 1.0.0-beta2¶

Kanzi Vehicle Properties provides ready-made integrations between Kanzi and the Android CarPropertyManager. With Kanzi Vehicle Properties, you can access Android Vehicle Properties from your application with minimal code. You can fully customize the list of exposed properties, and even use OEM-specific ones.

Kanzi Vehicle Properties automatically adds for each Android Vehicle Property a data object and the necessary bidirectional boilerplate code. You can use bindings to read and write to these data objects.

_images/kanzi-vehicle-properties-banner.png

Note

This is a prerelease of Kanzi Vehicle Properties. Some functionality, workflow, and the API is going to change in the future releases of Kanzi Vehicle Properties.

Your feedback is very important to us. To send your questions, findings, and comments, use the Kanzi Support Portal at support.rightware.com. When submitting a request regarding Kanzi Vehicle Properties, set the Product field to Vehicle Properties library.

Requirements¶

You can use the library on a device with Android Automotive 10 (API Level 29) or higher.
Building with the library requires that you have the Android 12 (API Level 31) SDK platform installed.
An application using the Kanzi Android framework.

Example application¶

Kanzi Vehicle Properties includes an example application that you can build and run on an AAOS device or emulator.

To run the example application:

In Android Studio, open examples/Simple/Application/configs/platforms/android_gradle/build.gradle.
In the Gradle tasks window, double-click simpleplugin:Tasks:kanzi:exportJarRelease.

This way you export the JAR file to lib/java/Release/simpleplugin.jar. This file enables you to use the data source in Kanzi Studio.
In Kanzi Studio, open the examples/Simple/Tool_project/Simple.kzproj project.
In the main menu, select File > Export > Export KZB.
In Android Studio, build, and run the app module.

Adding the Kanzi Vehicle Properties library to a Kanzi Android framework (droidfw) app¶

Importing Kanzi Vehicle Properties¶

To add Kanzi Vehicle Properties to a target Kanzi Android framework (droidfw) app that already has a plugin:

In Android Studio, open the target project.
In the build.gradle file:
- Ensure that minSdkVersion is set to at least 29.
- Ensure that compileSdkVersion and targetSdkVersion are set to at least 31. The level 31 API contains property constants that the default library uses.
Copy Kanzi Vehicle Properties from

<Archive>/libs/kanzivehicleproplib.jar

to

<KanziWorkspace>/Engine/plugins/vehicleproperties/libs/kanzivehicleproplib.jar

In the build.gradle file for your plugin, add the dependency on the JAR file from the previous step:

apply plugin: 'com.rightware.gradle.kanzi'

import com.rightware.gradle.KanziHelpers

dependencies {
   // other dependencies

   def vpropDir = new File(KanziHelpers.getKanziHome(project), '/Engine/plugins/vehicleproperties/libs')
   if (!vpropDir.exists()) {
      throw new GradleException("Plugin vehicleproperties could not be located")
   }
   implementation files("${vpropDir}/kanzivehicleproplib.jar")
}

In the build.gradle file for your plugin, add the dependency on the Android Car library.
```
android {
   useLibrary 'android.car'
}
```

Add a custom configured Vehicle Property data source to the plugin.

Create a Java class named MyDataSource.

Update the contents of the MyDataSource file to the basic implementation:

package your.package.name.here;

import static android.car.VehicleAreaSeat.*;
import static android.car.VehicleAreaWheel.*;
import static android.car.VehiclePropertyIds.*;

import com.rightware.kanzi.DataSource;
import com.rightware.kanzi.Domain;
import com.rightware.kanzi.Metaclass;
import com.rightware.kanzi.Metadata;
import com.rightware.kanzi.ObjectRef;
import com.rightware.kanzi.vehicleproperty.VehiclePropertyDataSource;
import com.rightware.kanzi.vehicleproperty.VehiclePropertyDataType;

public class MyDataSource extends VehiclePropertyDataSource
{
    /**
     * The Metaclass for the class.
     */
    @Metadata
    public static final Metaclass metaclass = new Metaclass("Example.MyDataSource");

    /**
     * Creates a MyDataSource.
     * @param domain UI Domain to contain this object.
     * @param name The name of MyDataSource.
     */
    public static <T extends VehiclePropertyDataSource> ObjectRef<T> create(Domain domain, String name)
    {
        return DataSource.createDerived(domain, name, metaclass);
    }

    /**
     * Constructs the MyDataSource.
     * @param domain UI Domain to contain this object.
     * @param handle The native handle for the MyDataSource.
     * @param metaclass The metaclass for this object.
     */
    private MyDataSource(Domain domain, long handle, Metaclass metaclass)
    {
        super(domain, handle, metaclass);
    }
}

Copy the loadConfiguration method to the MyDataSource class from the sample implementation:

examples/Simple/Application/configs/platforms/android_gradle/simpleplugin/src/main/java/com/example/simpleplugin/SimpleVehiclePropertyDataSource.java

Import the Kanzi Vehicle Properties namespace:

import com.rightware.kanzi.vehicleproperty.*;

Edit the registerClasses method to add:

@Override
public void registerClasses(MetaclassRegistry metaclassRegistry)
{
    // Existing registration code.
    VehiclePropertyLibrary.registerClasses(metaclassRegistry);
    metaclassRegistry.registerProxy(MyDataSource.class)
}

In the Gradle tasks window, double-click <PluginName>:Tasks:kanzi:exportJarRelease.

This way you export the JAR file to Application/lib/java/<PluginName>.jar. This file enables you to use the data source in Kanzi Studio.

In the plugin AndroidManifest.xml add these permissions:

<uses-permission android:name="android.car.permission.CAR_DYNAMICS_STATE" />
<uses-permission android:name="android.car.permission.CAR_POWERTRAIN" />
<uses-permission android:name="android.car.permission.READ_CAR_DISPLAY_UNITS" />
<uses-permission android:name="android.car.permission.CONTROL_CAR_DOORS" />
<uses-permission android:name="android.car.permission.CAR_ENGINE_DETAILED" />
<uses-permission android:name="android.car.permission.CAR_EXTERIOR_ENVIRONMENT" />
<uses-permission android:name="android.car.permission.CAR_ENERGY_PORTS" />
<uses-permission android:name="android.car.permission.CAR_EXTERIOR_LIGHTS" />
<uses-permission android:name="android.car.permission.CONTROL_CAR_EXTERIOR_LIGHTS" />
<uses-permission android:name="android.car.permission.CONTROL_CAR_CLIMATE" />
<uses-permission android:name="android.car.permission.CAR_INFO" />
<uses-permission android:name="android.car.permission.CAR_MILEAGE" />
<uses-permission android:name="android.car.permission.READ_CAR_STEERING" />
<uses-permission android:name="android.car.permission.CONTROL_CAR_SEATS" />
<uses-permission android:name="android.car.permission.CAR_TIRES" />
<uses-permission android:name="android.car.permission.CONTROL_CAR_WINDOWS" />

You can also use the system shared user. See Android permissions.

In a Kanzi Studio project, import the Kanzi Engine plugin that you created earlier in this procedure:
1. In the Library, right-click Kanzi Engine Plugins and select Import Kanzi Engine Plugin.
2. Select the Application/lib/java/<PluginName>.jar JAR file that you created earlier.
In the Data Sources window, click Create Data Source, set Data Source Type to Example.MyDataSource, and click OK.

You can now use the data source to bind node properties. To learn more about data sources in Kanzi, in the Kanzi framework documentation see Working with > Data sources > Using a data source.

Android permissions¶

The Kanzi Vehicle Properties library requires various Android permissions to access the CarPropertyManager data.

You can:

Add individual permissions for the specific properties that you need. To include a permission, edit the AndroidManifest.xml to include that permission.

For example:
```
<uses-permission android:name="android.car.permission.CONTROL_CAR_CLIMATE" />
```
Modify the application to use the system shared user. Edit the AndroidManifest.xml to include android:sharedUserId="android.uid.system":
```
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.simpleplugin"
    android:sharedUserId="android.uid.system">
```
This approach requires that you sign the application with the system’s platform key. When you use the system shared user, you can access the most properties, but signing your application with the platform key requires that you have access to the source of the Android operating system that the device is running. Therefore, you cannot sign the devices running stock Android operation systems because of the lack of access to the platform key.

Configuration¶

By default, the Kanzi Vehicle Properties library includes a small default configuration that covers basic HVAC controls. A complete configuration is included in the example app, specified in

examples/Simple/Application/configs/platforms/android_gradle/simpleplugin/src/main/java/com/example/simpleplugin/SimpleVehiclePropertyDataSource.java

You can copy the loadConfiguration implementation into your custom data source.

Because each included property requires additional permissions and increases the startup time, comment out or remove properties that your application does not use.

Each property is defined with a call to the addConfiguration method. For example:

src.addConfiguration("HVAC.SeatTemperatureLeft", HVAC_SEAT_TEMPERATURE, SEAT_ROW_1_LEFT, VehiclePropertyDataType.Integer);

This creates a DataObjectInt with a lookup path of “HVAC.SeatTemperatureLeft”. The value is bound to the HVAC_SEAT_TEMPERATURE VehiclePropertyId exposed by the CarPropertyManager.

Each section of the example loadConfiguration method has a comment that indicates what Android permission is required for the properties in the following block.

The Hardware Abstraction Layer (HAL) on each device or vehicle can add new OEM specific properties or change the valid zones for existing properties. The existing items can be different, or the HAL can have new items to support these changes.