Getting started with the Fleet SDK

Introduction and Setup

The distributed Java package name is hmkit-fleet and it's available on
mavenCentral(). There
is also a sample application that demonstrates the use of all SDK functions, which can
be downloaded from the hmkit-fleet Github repository..

Requirements

The SDK requires Java 8 to be installed.

Add the SDK to your project

implementation "com.high-mobility:hmkit-fleet:{latest-version}"

Latest versions for hmkit-fleet

Synchronise the Gradle project.

Create a Production Cloud App

In the Production tab you will find your apps for retrieving data from our live environment. In the app details page you are going to set the permissions it requires and manage its credentials. Let's see how to create a new app.

Sandbox

It is also possible to peform the same steps in "Develop mode" if you are working with the car simulator.

1. Go to the "Live data" tab, click the big plus (+) button, select "Fleet" as the type and select Cloud App.
2. Select the permissions that your app needs by clicking the "Select Permissions" button. Select the data points that you want to consume and hit "Save".
3. Fill in all app information and click "Submit for review". Once done we will enable your application for live data access as soon as we have performed our app verification procedures. You will get notified as soon as it's done and it usually takes less than 48h.

Initialise the SDK

Already when the Cloud App has been created you can go ahead and get the credentials you
need in order to initialise the SDK.

There are 2 options to get the the credentials:

1. OAuth client_id/client_secret

Get the OAuth client_id and client_secret from the OAuth Client tab.

HMKitCredentials credentials = new HMKitOAuthCredentials(
  "client_id",
  "client_secret"
);

HMKitConfiguration configuration = new HMKitConfiguration.Builder()
  .credentials(credentials)
  .environment(HMKitFleet.Environment.SANDBOX)
  .build();

HMKitFleet hmkit = new HMKitFleet(configuration);

2. OAuth client_id/private_key

Get the OAuth client_id and private_key from the OAuth Client tab. For the
private_key and private_key_id, you need to create a new Private Key and download it.

The downloaded private key will look something like this:

{
  "inserted_at": "2021-03-18T10:34:21",
  "id": "83ffc724-d333-41c3-b09a-91a5961d4160",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGdd...[REDACTED].../zAqJAMd+vdZLRm\n-----END PRIVATE KEY-----"
}

Initialize the SDK with the private key:

HMKitCredentials credentials = new HMKitPrivateKeyCredentials(
  "client_id",
  "private_key",
  "private_key_id"
);

HMKitConfiguration configuration = new HMKitConfiguration.Builder()
  .credentials(credentials)
  .environment(HMKitFleet.Environment.SANDBOX)
  .build();

HMKitFleet hmkit = new HMKitFleet(configuration);

Get clearance for vehicle

Before data can be retrieved for a vehicle, it has to be cleared for access. The clearance procedure is different for each carmaker and should be considered an asynchronous process. Clearing vehicles is done by passing in the Vehicle Identification Number (VIN). Multiple requests can be run in parallel.

Response<RequestClearanceResponse> response =
        hmkit.requestClearance(vin, Brand.MERCEDES_BENZ).get();

if (response.getResponse() != null) {
  RequestClearanceResponse requestClearanceResponse = response.getResponse();

  if (requestClearanceResponse.getStatus() == ClearanceStatus.Status.ERROR) {
      // description property is filled when the status is ERROR
      logger.error(format("Request clearance error: %s", requestClearanceResponse.getDescription()));
  } else {
      logger.info(format("requestClearances response: %s", requestClearanceResponse));
  }
}
else {
    logger.info(format("requestClearances error: %s", response.getError().getTitle()));
}

The response will tell you if the vehicle was sucessfully queued for clearance.

Control Measure

For Mercedes-Benz vehicles, it's also necessary to pass in a control measure object with the current vehicle odometer reading. This value is verified with the actual odometer reading during the clearance procedure.

Here's an example of adding the odometer value as a control measure for a vehicle clearance request.

ControlMeasure measure = new Odometer(110000, Odometer.Length.KILOMETERS);
List<ControlMeasure> measures = List.of(measure);

Response<RequestClearanceResponse> response =
        hmkit.requestClearance(vin, Brand.MERCEDES_BENZ, measures).get();

Get clearance statuses

Requesting clearance doesn't mean access to the vehicle just yet, as the clearance has to be approved first. The clearance status can be requested with getClearanceStatuses()

Response<List<ClearanceStatus>> response = hmkit.getClearanceStatuses().get();

if (response.getResponse() != null) {
    logger.info(format("getClearanceStatuses response"));
    for (ClearanceStatus status : response.getResponse()) {
        logger.info(format("status: %s:%s",
                status.getVin(),
                status.getStatus()));
    }
} else {
    logger.info(format("getClearanceStatuses error: %s", response.getError().getTitle()));
}

Get Vehicle State

For a cleared vehicle, you can query the vehicle state. The vehicle state is a collection of data points that are available for the vehicle.

Response<String> response = hmkit.getVehicleState(vin).get();

if (response.getResponse() != null) {
  String jsonString = response.getResponse();

  logger.info(format("getVehicleState response: %s", jsonString));
} else {
  logger.info(format("getVehicleState error: %s", response.getError().getTitle()));
}

Auto API

Check out the Auto API OpenAPI Specification for all details.

Get Vehicle Static Data

Get the static information about a vehicle. Static data can include the vehicle's brand, equipment and more.

Response<String> response = hmkit.getVehicleStaticData(vin).get();

if (response.getResponse() != null) {
  String jsonString = response.getResponse();

  logger.info(format("vehicle static data response: %s", jsonString));
} else {
  logger.info(format("vehicle static data error: %s", response.getError().getTitle()));
}

Static Data

Check out the Static Data API tutorial for more details.

Delete Vehicle Clearance

You can delete the clearance for a specific vehicle using vin:

Response<Boolean> response = hmkit.deleteClearance(vin).get();

if (response.getError() != null) {
    logger.info(format("deleteClearance error: %s", 
                                                response.getError().getDetail()));
} else {
    logger.info(format("deleteClearance success"));
}

After successful request, the vehicle state cannot be queried anymore.