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.

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.5@aar') {
        transitive = true
    }
    implementation 'com.highmobility:hmkit-auto-api:3.12.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 the Develop tab you will find your 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. At first you will find a Sandbox app which you can work on, but let's see how to create a new app.

  1. Go to the Develop tab, click the big plus (+) button and select Device App. Enter a name and continue.
  2. In the left section, select the permissions that your app needs under the "Permissions" tap. For the purporses of this tutorial, you will need to select the "Diagnostics" capability and then select "Get odometer" before pressing "save".
    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.

In the Develop tab you will find your apps. In each app's details page you are able to set the permissions it requires, manage devices and link virtual vehicles from your garage to test. At first you will find a Sandbox app which you can work on, but let's see how to create a new app.

Create a Vehicle

In the carmaker workspaces you will be able to create vehicles or other items to link with your app and to test with the emulators.

  1. Go to a carmaker workspace, click the big plus (+) button and select one vehicle to start. Enter a name and continue.
  2. You will find the vehicle capabilities listed to the left.
  3. If you click on the "Launch emulator" button you will see how it looks like. Next we will need to link an app with the vehicle.

Initialise the SDK

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

Once you have downloaded the SDK or sample app, go to the Apps tab, and select the app you created in the previous steps.
Choose "Device certificates" from the left section and enter a name for the device.
Click on the device you just created and copy the snippet.
Insert the snippet into into the Android Studio project to initialise the SDK.

Send a Telematics Command

Once the emulator is open, fire away a Telematics command. For example to unlock the doors of the vehicle. Note that you will get a "Vehicle Asleep" error returned if the emulator is closed.

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) {}
});