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.

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 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.

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 iOS Scaffold sample app from GitHub.

  1. Once you have downloaded the SDK or sample app, go to the Apps tab, and select the app you created in the previous steps.
  2. Choose "Device certificates" from the left section and enter a name for the device.
  3. Click on the device you just created and copy the snippet.
  4. Insert the snippet into into the Xcode project to initialize 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 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
}