Getting Started with iOS

In this tutorial we provide instructions for getting started with the iOS SDK – HMKit. The SDK consists of four different libraries that enable your application to work with vehicle data: AutoAPI, HMCryptoKit, HMUtilities and HMKit.

Table of Contents

Introduction and Setup

Requirements

All libraries are written in Swift 5.1 and require iOS 10 or above.

Integration

There are several ways to integrate the Swift libraries.

As frameworks:
Least recommended
Each lib's Xcode project can be built as a .framework and the resulting package (file) dragged to your own Xcode project. This only creates the framework for a device or a simulator, which could be lipo-d together to develop your application and run it on both a device and a simulator. The simulator slices need to be removed before being able to upload to AppStoreConnect.

As XCFrameworks:
Recommended when SPM usage is not possible
Each lib has a script XCFrameworkBuilder.sh in Scripts/ folder. When running this from the root dir, the .xcframwork package (file) will be built. This contains both device and simulator binaries that should be dragged to your own Xcode project. Then Xcode selects automatically which binary to use, thus enabling development on both a device and a simulator. No futher action is needed to upload to AppStoreConnect.

Through Swift Package Manager:
Recommended
Easiest would be to use the build-in SPM in Xcode 11+ and add the following dependencies to your project or Package.swift: AutoAPI, HMCryptoKit, HMUtilities, HMKit.

This has the benefits of not having to deal with manually copying/dragging files (packages can be updated from Xcode) nor worring about AppStoreConnect upload.

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 iOS 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 keypair using the SDK
  3. Use the Device Management API POST /device/certificates and store the response.
  4. Use the device certificate values from the server response and insert them into the Xcode project to initialize the SDK.

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 iOS code reference for Auto API for further details on how to use vehicle commands.

let bytes = AADoors.lockUnlockDoors(insideLocksState: .locked)

try HMTelematics.sendCommand(bytes, serial: vehicleSerial) { result in
    // Handle the result
}