Getting Started with Android

In this tutorial you'll find detailed instructions for getting started with the Android SDK. The Android SDK consists of libraries hmkit-android and hmkit-auto-api. These frameworks enable your application to work with vehicle data.

Table of Contents

Introduction and Setup

Requirements

HMKit requires Android 5.0 or above. You can run it on your Mobile or Wear device.

INTEGRATION

HMKit is packed as an aar library (Android Archive Library) for easy inclusion into an Android project. There are also many different sample applications, all of which showcase different features. These can be downloaded on the Samples page.

Add the SDK to Your Project

In case you already have an Android Studio project, add the SDKs and Java 8 support in the module's build.gradle file.

android {
    ...

    compileOptions {
        targetCompatibility 1.8
        sourceCompatibility 1.8
    }
}

dependencies {
    implementation('com.highmobility:hmkit-android:2.0.9@aar') {
        transitive = true
    }
    implementation 'com.highmobility:hmkit-auto-api:13.2.0'
    implementation 'at.favre.lib:slf4j-timber:1.0.0' // AutoAPI log binding to Timber
}

Click Tools ›› Android ›› Sync Project with Gradle Files.

Create an App

In "Develop mode" you will find your sandbox apps. In the app details page you are going to set the permissions it requires, manage devices and link virtual vehicles from your garage to test. Let's see how to create a new app.

  1. Go to the Build tab, select "Develop mode" and click the big plus (+) button, select "Driver" as the type and then select "Device App".
  2. In the left section, select the permissions that your app needs under the "Permissions" tap.
    Note: Each permission must be manually added to each new app.
  3. You can edit your app name and image from the menu icon next to the app name.

Create a Vehicle

In the "Simulation studio" you are able to create vehicles to link with your app and to test with the simulators. Go to the simulation studio and click the big plus (+) button.

Initialise the SDK

For a straight forward example of how to initialise the SDK, download the Android Scaffold sample app from GitHub.

  1. Once you have downloaded the SDK or sample app, go to the Develop mode tab, and select the app you created in the previous steps.
  2. Generate a key-pair using the SDK
  3. Use the Device Management API POST /device/certificates and store the response.
  4. Insert the snippet into into the Android Studio project to initialise the SDK.

We have published a video that shows the full workflow for creating a Device Certificate: See video on Loom

Send a Telematics Command

Once the simulator is open, fire away a Telematics command. For example to unlock the doors of the vehicle.

If you see that the app lacks permissions, you will need to revisit step two of the "Create an App" section of this document and select the appropriate permissions for your telematics command.

Read more about Telematics

Auto API

Check out the Android code reference for Auto API for further details on how to use vehicle commands.

HMKit.getInstance().getTelematics().sendCommand(new Doors.LockUnlockDoors(LockState.UNLOCKED), serial, new Telematics.CommandCallback() {
    @Override
    public void onCommandResponse(Bytes bytes) {
        // Parse command here
        Command command = CommandResolver.resolve(bytes);

        if (command instanceof Doors.State) {
          Doors.State doorsState = (Doors.State) command;
            // access the doors state object
        }
    }

    @Override
    public void onCommandFailed(TelematicsError error) {}
});