Vuzix Connectivity SDK for Android

Overview

The Vuzix Connectivity SDK for Android gives developers access to the Vuzix Connectivity framework allowing simple messaging between apps running on you Vuzix device and apps running on a phone. The same Connectivity SDK library is used regardless of which side of the communication you are on; Vuzix device or phone.

Setup and Installation

To use the SDK, you only need small additions to your build.gradle file(s). First, declare a new maven repository in a repositories element that points to the Vuzix maven repository.

You can use the repositories element under allprojects in your project’s root build.gradle file:

allprojects { 
	repositories { 
		google() 
		jcenter() 
		maven { url "https://jitpack.io" } 
	} 
}

Alternatively you can use a repositories element under the android element in your app’s build.gradle file:

apply plugin: 'com.android.application' 
android { 
	... repositories { 
	maven { url "https://jitpack.io" } 
	} 
}

Finally, add the Connectivity SDK as a dependency in your app’s build.gradle file:

dependencies { 
	// To maintain consistency, configure this project to use the current version such as:
	// implementation 'com.vuzix:connectivity-sdk:**VERSION'
	// Alternatively you may use the latest library which will automatically update
	// from time to time. This is not recommended for production projects:
	implementation 'com.vuzix:connectivity-sdk:master-SNAPSHOT' 
}

The latest **version is:

That’s it! You are now ready to start sending messages using the Connectivity framework.

The Connectivity Class

The Connectivity class is your main entry point into the Connectivity SDK. The first thing you need to do is use the static get() method to obtain the singleton instance of the Connectivity class. You’ll need to pass in a non-null Context object:

Connectivity c = Connectivity.get(myContext);

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 Connectivity SDK JavaDocs for complete information on the available methods. Here are some key methods to be aware of:

isAvailable()

isAvailable() can be used to test if the Vuzix Connectivity framework is available on the device. For Vuzix devices, this method should always return true. On phones, this method will return true if the Vuzix Companion App is installed and false otherwise. If this method returns false, no other Connectivity methods should be called.

getDevices(), getDevice(), isLinked()

getDevices() returns you all the remote devices you are currently linked to. Currently Vuzix devices and the Companion App only support one linked device in either direction. However, the Connectivity framework supports multiple linked devices as a future enhancement. getDevice() is a convenience method that will return you a single linked device if one exists or null if you’re not linked to anything. isLinked() is a convenience method that returns true if you are currently linked to a remote device and false otherwise.

isConnected()

isConnected(device) is used to determine if you are connected to a specific remote device. The no arg version of isConnected() will return true if any remote device is currently connected.

addDeviceListener(listener), removeDeviceListener(listener)

You can add DeviceListeners to be notified when remote devices are added, removed, connected and disconnected. If you only care about one or two particular events, the DeviceListenerAdapter class has no-op implementations of all the DeviceListener methods. Always remember to properly remove your DeviceListeners when done with them.

Sending a Broadcast to a Remote Device

The Connectivity framework supports both regular broadcasts and ordered broadcasts. 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:

Intent myRemoteBroadcast = new Intent("com.example.myapp.MY_ACTION");

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 setPackage() method on the Intent class:

myRemoteBroadcast.setPackage("com.example.myapp");

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

myRemoteBroadcast.putExtra("my_string_extra", "hello"); myRemoteBroadcast.putExtra("my_int_extra", 2);

The following intent extra types are supported:

• boolean, boolean[]

• Bundle, Bundle[]

• byte, byte[]

• char, char[]

• double, double[]

• float, float[]

• int, int[]

• Intent, Intent[]

• Long, long[]

• short, short[]

• 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 sendBroadcast() method on Connectivity:

Connectivity.get(myContext).sendBroadcast(myRemoteBroadcast);

To send as an ordered broadcast, use the sendOrderedBroadcast() method. For ordered broadcasts, you need to specify the remote device:

Connectivity c = Connectivity.get(myContext); 
Device device = c.getDevice(); 
c.sendOrderedBroadcast(device, myRemoteBroadcast, new BroadcastReceiver() {
	@Override public void onReceive(Context context, Intent intent) 
	{ if (getResultCode() == RESULT_OK) 
		{ // do something with results } 
	} 
});

Notice you can specify a BroadcastReceiver to get results back from the remote device.

Receiving a Remote Broadcast

Receiving a remote broadcast is as easy as receiving a local broadcast. You simply register a BroadcastReceiver in your app.

@Override protected void onStart() { 
	super.onStart(); 
	registerReceiver(receiver, new IntentFilter("com.example.myapp.MY_ACTION")); 
} 
@Override protected void onStop() { 
	super.onStop(); 
	unregisterReceiver(receiver); 
} 
private BroadcastReceiver receiver = new BroadcastReceiver() {
	@Override public void onReceive(Context context, Intent intent) { 
		// do something with intent 
	} 
};

As with all BroadcastReceivers, don’t forget to unregister your receiver.

You can also declare a BroadcastReceiver in your manifest:

<receiver android:name=".MyReceiver"> 
	<intent-filter> 
		<action android:name="com.example.myapp.MY_ACTION"/> 
	</intent-filter> 
</receiver>

Returning Data from an Ordered Broadcast

An advantage of 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 use any combination of the setResult(), setResultCode(), setResultData() or setResultExtras() methods. You should also check the isOrderedBroadcast() method to make sure you are receiving an ordered broadcast. Setting result data on a non-ordered broadcast will result in an exception being thrown.

private BroadcastReceiver receiver = new BroadcastReceiver() {
	@Override public void onReceive(Context context, Intent intent) { 
		if (isOrderedBroadcast()) { 
			setResultCode(RESULT_OK); 
			setResultData("some result data"); 
			Bundle extras = new Bundle(); 
			extras.putString("key", "value"); 
			setResultExtras(extras); 
		} 
	} 
};

Note that the result extras Bundle is subject to the same restrictions as broadcast extras (see above).

That’s all you need to do to return data back to the remote sender of the broadcast. The Connectivity framework handles routing the result back to the proper place.

Verifying a Remote Broadcast

Since remote broadcasts are received just like local broadcasts, sometimes you may want to verify a broadcast came from a remote device through the Connectivity framework. You may also want to verify which app on the remote side the broadcast came from. Fortunately, both of these are easy to verify using the Connectivity SDK and the verify() method.

To verify a broadcast came through the Connectivity framework, pass the intent to the verify method. verify() will return true if the broadcast is a legitimate and false otherwise:

private BroadcastReceiver receiver = new BroadcastReceiver() { 
	@Override public void onReceive(Context context, Intent intent) { 
		// verify broadcast came from Connectivity framework 
		if (Connectivity.get(context).verify(intent)) { 
			// do something with intent 
		} 
	} 
};

You can also verify the broadcast came from a specific remote app through the Connectivity framework. Pass both the intent and a package name to the verify() method. Note that patterns are not allowed, you must pass the exact package name you are looking for.

private BroadcastReceiver receiver = new BroadcastReceiver() { 
	@Override public void onReceive(Context context, Intent intent) { 
		// verify broadcast came from the correct remote app 
		if (Connectivity.get(context).verify(intent, "com.example.myapp")) { 
			// do something with intent 
		} 
	} 
};

Adding or Removing Remote Devices

Apps using the Connectivity SDK cannot add or remove remote devices. For remote device management, users should be directed to the Vuzix M400/M4000 Companion App to set those devices up ahead of time. Once a remote device is set up, it becomes available for use through the SDK.

Sample Project

A sample application for Android Studio demonstrating the Vuzix Connectivity SDK for Android is available here.