Vuzix Connectivity Framework for iOS

Overview

Vuzix Connectivity framework allows iOS apps to share the BLE connnection to communicate with apps that are running on a Vuzix device. There is no need to pair the BLE connection, as the framework uses the same BLE connection established and setup in the Vuzix Companion App. There is also no need to define a protocol model as we have already done that. You can send simple messages between Vuzix devices and your iPhone app seamlessly. Apps running on a Vuzix device will need to utilize the Vuzix Android Connectivity library. Since messages are sent as BLE messages, it is best to send smaller messages as throughput is limited when using BLE.

Requirements

M4000/M400

• OS 1.1.4 or higher.

Blade/Blade 2

• OS 2.10 or higher.

Shield

• OS 1.1.0 or higher.

All

• Latest version of Vuzix Companion app running on iPhone from the App Store.

• App running on M4000/M400 must use the Android Connectivity SDK.

• The Vuzix Glasses and phone app must be linked.

Setup and Installation

To use the framework within your Xcode project you can install through cocoa pods or manually.

CocoaPods

CocoaPods is a dependency manager for Xcode projects. For usage and installation instructions, visit their [website](http://www.cocoapods.org).

To integrate the Vuzix Connectivity framework into your Xcode project using CocoaPods, specify it in your Podfile:

Pod ‘VuzixConnectivity’

Manually

If you prefer to not use Cocoapods, then you can integrate the Vuzix Connectivity framework into your project manually.

Simply download the framework from: Vuzix’s github page and follow the steps below:

• Drag the Connectivity.framework into your project.

• Go to General pane of the application target in your project. Add Connectivity.framework to the Embedded Binaries section.

• Import Connectivity in your Swift file and use in your code.

The Connectivity Class

The Connectivity class is your main entry point into the Connectivity framework. The first thing you need to do is use the static shared property to obtain the singleton instance of the Connectivity class.

let connectivity = Connectivity.shared

Once you have a reference to the Connectivity object, you can call various methods to learn more about the current connectivity status, send broadcasts, and perform other functions related to connectivity. Consult the framework for complete documentation on the available methods.

Here are some key methods to be aware of:

isConnected

connectivity.isConnected returns a boolean. It is used to determine if you are connected to a remote device.

requestConnection()

connectivity.requestConnection is used to request a connection to your vuzix smart glasses. Make this request to share the bandwidth with the companion app. Listen for notification on the connectivity state.

if connectivity.isConnected == false {
	connectivity.requestConnection()
}

ConnectivityStateChanged

After requesting connection to the device, observe the state of the device by adding an observer on the Notification.Name -- connectivityStateChanged property. Six possible states are possible: .connected, searchingForDevice, bluetoothOff, notConnected, connecting and notSupported which are defined in ENUM ConnectivityState. You can display the correct UI for the states while connections are being made

NotificationCenter.default.addObserver(forName: .connectivityStateChanged, object: nil, queue: nil) {
	[weak self] (notification) in if let state = notification.userInfo?["state"] as? ConnectitivyState {
		if state == ConnectitivyState.connected {
			self?.textView.text = "--Connected to Vuzix device!"
		}
		else if state == ConnectitivyState.searchingForDevice {
			self?.textView.text = "--Searching for Device"
		}
		else if state == ConnectitivyState.connecting {
			self?.textView.text = "--Connecting to Device"
		}
		else if state == Connectivity.bluetoothOff {
			self?.textView.text = "--Bluetooth turned off on Phone"
		}
		else if state == Connectivity.notConnected {
			self?.textView.text = "--Not Connected. Not searching"
		}
		else if state == Connectivity.notSupported {
			self?.textView.text = "--Device OS and/or Companion App needs update"
		}
	}
}

Sending data to the Vuzix device

The Connectivity framework supports an Android data model of using broadcasts and ordered broadcasts. A broadcast is nothing more than a Swift Notification that is sent across the framework to the other end. An orderedBroadcast is a broadcast which responds back with data.

Broadcasts should be limited to 10 kilobytes or less if possible. Larger broadcasts are supported, but you will always be subject to the Binder transaction buffer limit of 1MB which is shared across your app’s process. In addition, larger broadcasts will take longer to transfer between devices.

The first step to sending a broadcast is creating an Intent with an action:

var intent = Intent(action: "com.vuzix.a3rdparty.action.MESSAGE")

It is strongly recommended, but not required, that you specify the remote app package that will receive the intent. This ensures that the broadcast is only delivered to a specific app. Use the package property on the Intent class to set the target.

intent.package = "com.vuzix.a3rdparty"

If you need to set the category or modify any flags on the intent, you can do so. You can also fill up the intent with extras. For example:

intent.addExtra(key: "my_string_extra", value: "hello") 
intent.addExtra(key: "my_int_extra", value: 2)

The following intent extra types are supported:

• Bool,[Bool]

• BundleContainer,[BundleContainer]

• Data

• Character,[Character]

• Double,[Double]

• Float,[Float]

• Int,[Int]

• Intent,[Intent]

• Int64,[Int64]

• Int16,[Int16]

• String,[String]

If you specify an intent extra of any other type, it will be ignored and will not be broadcast to the remote device.

Once your intent is populated with data, you’re ready to broadcast it to the remote device. To send as a regular broadcast, simply use the broadcast(intent:) method on Connectivity:

connectivity.broadcast(intent: intent)

To receive data back from the Vuzix device, send an ordered broadcast. Using the Connectivity shared instance, call orderedBroadcast(intent:callBack:) method with your intent and extras that you want to send. Extras is an optional.

connectivity.orderedBroadcast(intent: intent, extras: extras) {
	[weak self] (result) in if result.code == 1 {
		//result is of type BroadcastResult
		//result will contain the data from your Vuzix device.
	}
}

Notice you specify a closure to receive the results back from the remote device.

Receiving a Remote Broadcast

Receiving a remote broadcast is as easy as simply registering a listener in your app.

let connectivity = Connectivity.shared connectivity.registerReceiver(intentAction: "com.a3rdParty.action.message") {
	[weak self] intent in if let message = intent.extras?.getValueForKey(key: "message") as? String {
		print(message) DispatchQueue.main.async {
			self?.textView.text = message
		}
	}
}

Returning Data from an Ordered Broadcast

An advantage of an ordered broadcasts is that they can return data to the sender. The same is true of ordered broadcasts sent through the Connectivity framework. To return data to the remote sender, simply set the data on the BroadcastResult in the onReceive listener.

var itemReceiver = BroadcastReceiver() itemReceiver.onReceive {
	(result: BroadcastResult) in result.data = <your data you want to return to the other side>
	result.code = -1
}
connectivity.registerReceiver(intent: "com.vuzix.a3rdparty.action.ITEM2", receiver: itemReceiver)