iOS Library API Guide

This document describes the interface for the OpenXC library version 6.0.

Vehicle data is accessed after adding the framework to the demo app. Both of these can be found in openxc-ios-library.

You must first create an object of VehicleManager and set targets before you can receive any vehicle data.

var vm: VehicleManager!

VehicleManager is a singleton class, so instantiate using shared instance in viewDidLoad():

vm = VehicleManager.sharedInstance

This will require you to import OpenXC framework in your class:

import openXCiOSFramework

While setting up the callbacks, set the action as a method in viewDidLoad():

// setup the status callback, and the command response callback
vm.setManagerCallbackTarget(self, action: StatusViewController.manager_status_updates)
vm.setCommandDefaultTarget(self, action: StatusViewController.handle_cmd_response)
    
// turn on debug output
vm.setManagerDebug(true)

Once the callbacks are set and you have a connection to it in your controller, you can start sending and receiving messages with the vehicle interface.

The VehicleMessage is the parent of all message sent to and from the vehicle interface. You can register to receive asynchronous updates for anything from all receive messages to only those matching a certain key. All of the examples here show how to receive updates for more specific subtypes, but you do have the option of interfacing directly with VehicleMessages.

If the attached VI is sending low-level CAN messages, you can receive them in your iOS application.

First, grab the VehicleManager instance and then set the callback:

vm = VehicleManager.sharedInstance

vm.setCanDefaultTarget(self, action: CanViewController.default_can_change)

The callback method will receive the CAN message in the form on dictionary (key-value pairs):

  func default_can_change(_ rsp:NSDictionary) {
    // extract the CAN message
    let vr = rsp.object(forKey: "vehiclemessage") as! VehicleCanResponse

To clear the default can target:

vm.clearCanDefaultTarget()

First, grab the VehicleManager instance and then set the callback:

vm = VehicleManager.sharedInstance

vm.setDiagnosticDefaultTarget(self, action: DiagViewController.default_diag_response)

The callback method will receive the Diagnostic response in the form on dictionary (key-value pairs):

  func default_diag_response(_ rsp:NSDictionary) {
    // extract the diag response message
    let vr = rsp.object(forKey: "vehiclemessage") as! VehicleDiagnosticResponse

You can also send the request:

let cmd = VehicleDiagnosticResponse()
// Set the parameters for Diagnostic request: bus, message id, mode, payload

vm.sendDiagReq(cmd);

To clear the default target:

vm.clearDiagnosticDefaultTarget()

The commands defined in the OpenXC message format that are supported by your VI firmware can be sent using a Command message type.

To send a command and wait to receive a response:

// set callback
vm.setCommandDefaultTarget(self, action: StatusViewController.handle_cmd_response)

let cm = VehicleCommandRequest()
cm.command = .version
vm.send(cm);

For commands that don’t require any data in the request you can use:

let cm = VehicleCommandRequest()
cm.command = .version
vm.send(cm);

For commands that require any data in the request you can use:

let cm = VehicleCommandRequest()
cm.command = .passthrough
cm.bus = 1
cm.enabled = true
vm.send(cm);

The callback method will receive the Commands response in the form on dictionary (key-value pairs):

  func handle_cmd_response(_ rsp:NSDictionary) {
    // extract the command response message
    let cr = rsp.object(forKey: "vehiclemessage") as! VehicleCommandResponse

If you need to be kept up-to-date on any vehicle measurement, you can set callbacks to be notified of updates.

First, grab the VehicleManager instance and then set the callback:

vm = VehicleManager.sharedInstance

// set callback
vm.setMeasurementDefaultTarget(self, action: DashboardViewController.default_measurement_change)

The callback method will receive the measurement in the form on dictionary (key-value pairs):

  func default_measurement_response(_ rsp:NSDictionary) {
    // extract the measurement message
    let vr = rsp.object(forKey: "vehiclemessage") as! VehicleMeasurementResponse

	// extract name and value
	let name = vr.name as NSString
	let value = vr.value as AnyObject
	
	// check if the measurement response is evented
	if vr.isEvented {
	}