iOS HMLocalDevice
HMLocalDevice is a representation of the device the code runs on – aka the current device.
It enables bluetooth advertising, customisation of the broadcast, and discovery of HM-enabled devices through it's delegate. Furthermore, it manages the storage and handling of certificates in a secure database.
In addition, it offers a possibility for safety-critical use cases, by sending a continuous beat through a dedicated channel – bluetooth's own connection state changes are too lazy for these uses.
Finally, HMLocalDevice is a singleton, that must be configured, before using other functionality, with initialise(strings) or initialise(cert, keys).
Table of Contents
- Type Properties
- Instance Methods: Essential
- disconnect()
- initialise(certificate:devicePrivateKey:issuerPublicKey:)
- initialise(certificate:devicePrivateKey:issuerPublicKey:)
- startBroadcasting(configuration:)
- stopBroadcasting()
- Instane Methods: Certificate
- isAuthorised(toVehicle:)
- register(certificate:)
- resetStorage()
- revokeCertificate(withSerial:type:)
- store(certificate:)
- Instance Properties
- .certificate
- .configuration
- .delegate
- .links
- .name
- .loggingOptions
- .registeredCertificates
- .state
- .serial
- .storedCertificates
- Types
Type Properties
Instance Methods: Essential
Stops broadcasting, removes the services (thus disconnecting from centrals) and clears the links.
Declaration
func disconnect()
Example
import HMKit
HMLocalDevice.shared.disconnect()
Initialise the HMLocalDevice with essential values before using other functionality
Declaration
func initialise(certificate: HMBase64String, devicePrivateKey: HMBase64String, issuerPublicKey: HMBase64String) throws
Parameters
| certificate | (String) base64 representation of a Device Certificate |
| devicePrivateKey | (String) base64 encoded device's private key – elliptic curve p256v1 |
| issuerPublicKey | (String) base64 encoded Device Certificate's issuer's public key |
Discussion
If an input is invalid, an HMLocalDeviceError is thrown.
The private key must match the public key in Device Certificate. Valid inputs are forwarded to initialise and the device is successfully configured.
Read More
Example
import HMKit
let devCert: String = "dGVzdBaAn20Kaiitf...9Sdrh+eZRbvpnWoAZdgo/P6"
let devKey: String = "qe7Xe/uTOBE8cUWgpNUc4eF3iTHfHj8btnkZoL++0qk="
let issuerKey: String = "9YZA1GxGYpCCRCrSW57...68gfW1QWnCip5nxO0RW9g=="
do {
try HMLocalDevice.shared.initialise(certificate: devCert, devicePrivateKey: devKey, issuerPublicKey: issuerKey)
}
catch {
print("Failed to initialise the LocalDevice, error: \(error)")
}
Set the device certificate, private key and certificate authority's public key before using other functionality
Declaration
func initialise(certificate: HMDeviceCertificate, devicePrivateKey: SecKey, issuerPublicKey: SecKey) throws
Parameters
| certificate | (HMDeviceCertificate) with the device's serial number and public key |
| devicePrivateKey | (SecKey) device's private key – using elliptic curve p256v1 |
| issuerPublicKey | (SecKey) Device Certificate's issuer's public key |
Discussion
If an input is invalid, an HMLocalDeviceError is thrown.
The private key must match the public key in Device Certificate. If inputs are valid, the device is successfully configured.
Read More
Example
import HMCryptoKit
import HMKit
let devCert: HMDeviceCertificate = HMDeviceCertificate(...)
let devKey: SecKey = try HMCryptoKit.privateKey(privateKeyBinary: ..., publicKeyBinary: ...)
let issuerKey: SecKey = try HMCryptoKit.publicKey(binary: ...)
do {
try func initialise(certificate: devCert, devicePrivateKey: devKey, issuerPublicKey: issuerKey)
}
catch {
print("Failed to set the Device Certificate, private key or certificate authority's public key, error: \(error)")
}
Start broadcasting the device by BLE advertising
Declaration
func startBroadcasting(with configuration: HMLocalDeviceConfiguration? = default) throws
Discussion
Configuration defaults to nil.
If a prerequisite is not fulfilled, an HMLocalDeviceError is thrown.
Read More
Example
import HMKit
do {
try HMLocalDevice.shared.startBroadcasting()
// or
let conf: HMLocalDeviceConfiguration!
try HMLocalDevice.shared.startBroadcasting(with: conf)
}
catch {
print("Failed to start broadcasting, error: \(error)")
}
Stop broadcasting the device
Declaration
func stopBroadcasting()
Example
import HMKit
HMLocalDevice.shared.stopBroadcasting()
Instane Methods: Certificate
Check if the device has a certificate to authorise with a vehicle
Declaration
func isAuthorised<C>(toVehicle serial: C) throws -> Bool where C : Collection, C.Element == UInt8
Parameters
| serial | (UInt8 Collection) serial of the vehicle to check |
Discussion
If HMLocalDevice is not initialised, or the input is not 9 bytes, an HMLocalDeviceError is thrown.
Read More
Example
import HMKit
let serial: [UInt8] = [0x11, 0x22, 0x33...0x77, 0x88, 0x99]
do {
let isAuthorised = try HMLocalDevice.shared.isAuthorised(toVehicle: serial)
}
catch {
print("Failed to check authorisation state, error: \(error)")
}
Registers an access certificate with the device
Declaration
func register(certificate: HMAccessCertificate) throws
Parameters
| certificate | (HMAccessCertificate) certificate to register |
Discussion
If the certificate is not for the HMLocalDevice, an HMLocalDeviceError is thrown.
Read More
Example
import HMKit
let accessCertificate: HMAccessCertificate!
do {
try HMLocalDevice.shared.register(certificate: accessCertificate)
}
catch {
print("Failed to register Access Certificate, error: \(error)")
}
Reset the device's access certificates database
Declaration
func resetStorage()
Example
import HMKit
HMLocalDevice.shared.resetStorage()
Revoke an access certificate registered or stored with the device
Declaration
public func revokeCertificate<C>(withSerial serial: C, type: HMSerialType) -> HMAccessCertificate? where C : Collection, C.Element == UInt8
Parameters
| serial | (UInt8 Collection) serial number to use for finding the certificate |
| type | (Bool) is the serial a providing (or gaining) one |
Discussion
If the serial is providing, then a stored certificate, otherwise a registered one, is revoked.
Returns true if a certificate was revoked.
Read More
Store an access certificate on the device
Declaration
func store(certificate: HMAccessCertificate)
Parameters
| certificate | (HMAccessCertificate) certificate to store |
Discussion
This certificate is read by other devices.
Read More
Example
import HMKit
let accessCertificate: HMAccessCertificate!
HMLocalDevice.shared.store(certificate: accessCertificate)
Instance Properties
Device certificates of the device
Configurable settings for Bluetooth
Declaration
lazy var configuration: HMLocalDeviceConfiguration
Discussion
Changing some configuration settings while the device is broadcasting, won't have an effect and the broadcasting needs to be restarted.
Read More
Object that conforms to HMLocalDeviceDelegate protocol for callbacks from the HMLocalDevice
Links connected to the device
Declaration
var name: String { get }
Discussion
This is the name displayed as the peripheral's name in bluetooth.
Type of logs printed to the console
Declaration
static var loggingOptions: HMLoggingOptions = [.general] { get set }
Discussion
This is shared with HMTelematics
Read More
HMAccessCertificate-s registered with the HMLocalDevice
State of the HMLocalDevice singleton
Declaration
var state: HMLocalDeviceState { get }
Discussion
Changes are sent through the delegate
Read More
Convenience accessor for the device's serial.
Declaration
var serial: [UInt8]? { get }
HMAccessCertificate-s stored in the HMLocalDevice
Types
HMSerialType
Declaration
enum HMSerialType {
case gaining
case providing
}