HMKit Auto API

This repository contains the java parsers for Auto API.

Dependencies

• hmkit-utils

Install

Releases are pushed to mavenCentral. To include hmkit-auto-api in your project, add to build.gradle:

repositories {
mavenCentral()
}
dependencies {
implementation('com.high-mobility:hmkit-auto-api:{version}')
}

SLF4J is used for logging. Add slf4j binding to see the logs, for example:

implementation 'org.slf4j:slf4j-simple:1.8.0-beta1'

Find the latest version name in mavenCentral

How to create/parse commands

Find the command name in auto api doc, then locate a class in com.highmobility.autoapi package with the same name. Every command has a designated class and it is used for all of the common use cases:

Parse the received command's bytes

byte[] bytes = ...
Commandcommand = CommandResolver.resolve(bytes);
VehicleStatusvehicleStatus;
Capabilitiescapabilities;
if (commandinstanceofVehicleStatus) {
vehicleStatus = (VehicleStatus) command;
}
elseif (commandinstanceofCapabilities) {
capabilities = (Capabilities) command;
}

Get a specific state from the vehicle status

LockStatestate = vehicleStatus.getState(LockState.TYPE);
if (state != null) {
...
}

Inspect whether the capability is supported for the vehicle

if (capabilities.isSupported(LockState.TYPE)) {
...
}

Send a command

BytescommandBytes = newLockUnlockDoors(Lock.LOCKED).getBytes();
sendCommand(commandBytes)

Get a capability

BytescommandBytes = newGetCapability(SendHeartRate.TYPE).getBytes();
sendCommand(commandBytes)

Check for the failed command's type

Failurefailure;
if (commandinstanceofFailure) {
failure = (Failure)command;
if (failure.getFailedType != null && failure.getFailedType.equals(LockUnlockDoors.TYPE) {
// the lock unlock command failed
}
}

Builders for bigger commands(states)

Builder pattern is used to build commands with more properties, for example Vehicle status:

// create the builderVehicleStatus.Builderbuilder = newVehicleStatus.Builder();
// add known properties as simple values builder.setVin(newProperty("JF2SHBDC7CH451869"));
builder.setPowerTrain(newProperty(PowerTrain.ALLELECTRIC));;
builder.setModelYear(newProperty(2017));
// builder.setPower(220);// can also add unknown propertiesbuilder.addProperty(newProperty(220));
// can chain the properties addingbuilder.setNumberOfDoors(newProperty(5)).setNumberOfSeats(newProperty(5));
// use builders from other commands to append them to vehicle statusTrunkState.BuildertrunkState = newTrunkState.Builder();
trunkState.setLockState(newProperty(Lock.UNLOCKED));
trunkState.setPosition(newProperty(Position.OPEN));
builder.addProperty(newProperty(trunkState.build()));
ControlMode.BuildercontrolCommand = newControlMode.Builder();
controlCommand.setMode(newProperty(ControlModeValue.STARTED));
builder.addProperty(newProperty(controlCommand.build()));
// build the actual vehicleStatus commandVehicleStatusstatus = builder.build();
// get the raw bytes of the vehicle statusbyte[] command = status.getByteArray();

A signature and a nonce can be added to any of the command's builders:

VehicleStatus.Builderbuilder = getVehicleStatusBuilderWithoutSignature();
// set the noncebuilder.setNonce(newBytes("324244433743483436"));
// get the temporary data that needs to be signedBytesbytesToBeSigned = builder.build().getSignedBytes();
// sign itBytessig = Crypto.sign(bytesToBeSigned, privateKey);
// add the signature propertybuilder.setSignature(sig);
// get the final bytes with signatureBytescommand = builder.build();

Adding a new Capability

• Add the Identifier in Identifier.java
• Follow, for instance, Fueling.java to add the capability-s skeleton commands.
• Create the tests. Copy this from previous FuelingTest.
• Implement the new Capability commands.

OEM

Some commands are not available if using AutoAPI on the vehicle (OEM) side. For them to work, the environment needs to be set to VEHICLE in CommandResolver:

CommandResolver.setEnvironment(CommandResolver.Environment.VEHICLE);