Unity Package Getting Started Guide

Unity Version: 2020.3.27f1

Supported ICD Rev: H1
Supported VictoR Firmware Revision:

  • Application Firmware Rev: 03.080

  • Co-Processor Firmware Rev: 01.001

  • Kernel Module Firmware Rev: 01.001

  • BLE Firmware Rev: 03.032

Supported Build Types:

  • Universal Windows Platform

  • Android
    NOTE: As a result of using the Windows BLE stack, Unity projects built with the VictoR SDK can only be run on the target platform during development. Running the application within the editor is currently not supported.

Introduction

To enable development for the VictoR device in the Unity engine, a Unity package is available which contains the relevant Android and Windows libraries used to communicate with a VictoR device, along with example C# scripts and Unity gameobjects and example scene that demonstrate one of many ways users could incorporate the VictoR SDK into their Unity project. The following will walk users through importing the Unity package into their project and give a general overview of the provided scripts, gameobjects, and example scene.

Importing the VictoR SDK Unity Package

The VictoR SDK Unity package is of .unitypackage file type. Users can import this package into an existing Unity project by navigating to Assets/Import Package/Custom Package:

Image 1: Importing a custom unity package
Image 2: Unity package contents

Once the Unity package has been imported, users should have a set of new assets available in their project’s Assets folder. This should include:

  1. A plugins folder containing the necessary libraries to build either a UWP application or an Android application

  2. Prefabs for a basic UI to allow for…

    1. Scanning for VictoR devices over USB or BLE

    2. Connecting to scanned devices

    3. Reading the Device Configuration and Device Information service on the device

    4. Writing to the Device Configuration service

    5. Disconnecting from connected VictoR devices

  3. Scripts utilizing the Windows and Android VictoR SDK, along with prefabs using said scripts

  4. An example scene bringing the above items together for a buildable UWP or Android application

Prefabs and Scripts

The prefabs for the example project can be split between two spaces: UI and VictoR SDK.

VictoR SDK Prefabs

The VictoR SDK prefab makes use of the libraries contained in the Plugins folder to communicate with a VictoR device, through the attached VictorController script. The libraries used are determined by the platform the project has been set to. Currently, Universal Windows platform and Android are supported. The VictorController script also serves as both an example on how to use the Victor SDK for both platforms and is the primary script users should utilize when interfacing with the VictoR device from within a Unity project. It’s primary function is to use the appropriate device manager (Windows or Android SDK), dependent on the platform the application is running on. Once the appropriate device manager is instantiated, calls to Scan, Connect, Read/Write, and Subscribe/Unsubscribe can be made through the VictorController. The following will walk through how the Windows and Android DeviceManagers are handled through a Unity project.

UWP

When building a project for UWP, the VictorSDK classes can be used directly to communicate with VictoR devices. As a result, the VictorController script simply uses these classes directly. Users can reference the Victor SDK Getting Started Guide for Windows for example code on how to work with the Windows edition of the SDK.

Android

When building a project for Android, the VictorSDK for Android requires an additional layer of bindings in order to interface with the SDK in C#. The VictorAndroidDeviceManager script under the Scripts folder provides these bindings and is what users should leverage when making calls to the Android SDK. The example code below simply gives users a look into how these bindings are done. The core of this layer resides in Unity’s AndroidJNIModule in the UnityEngine library. This allows for using android java objects and making calls on said objects. The following demonstrates how these calls are made as they relate to the VictoR SDK:

Scanning For Devices

In order to scan for devices using the Android SDK from within a Unity project, users must first create an AndroidJavaObject representing the Java SDK’s VictorBleDeviceManager. In the example script, this is done inside the constructor. Once the device manager object has been created, the actual scan method is able to use the AndroidJavaObject to call the “scanForDevices” method. As this is a CompletableFuture on the Java side, this call is made inside of a Task on the C# side. An important item to note is that in order to properly call this function, users must first attach the current thread to a Java VM. Remember that the Unity package contains a VictorAndroidDeviceManager script that has performed this binding already for the user.

public class VictorAndroidDeviceManager : IVictorDeviceManager { AndroidJavaClass m_AJCUnityPlayer = new AndroidJavaClass("com.unity3d.player.UnityPlayer"); AndroidJavaObject m_AJOActivity; AndroidJavaObject m_AJODeviceManager; public VictorAndroidDeviceManager(bool useUSB) { m_AJCUnityPlayer = new AndroidJavaClass("com.unity3d.player.UnityPlayer"); m_AJOActivity = m_AJCUnityPlayer.GetStatic<AndroidJavaObject>("currentActivity"); string classNamePrefix = "com.fn.victorcommunications."; string className; if (useUSB) { className = "VictorUsbDeviceManager"; } else { className = "VictorBleDeviceManager"; } m_AJODeviceManager = new AndroidJavaObject(classNamePrefix + className, m_AJOActivity); m_useUSB = useUSB; } public async Task<HashSet<VictorDeviceInfo>> ScanForDevices() { AndroidJavaObject ajoScannedDevices = await Task<AndroidJavaObject>.Run(() => { AndroidJNI.AttachCurrentThread(); AndroidJavaObject ajo = m_AJODeviceManager.Call<AndroidJavaObject>("scanForDevices"); return ajo.Call<AndroidJavaObject>("get"); }); return ToHashSet(ajoScannedDevices); } }

Now that this function has been defined for an Android project, users can then call this scan function directly in their project’s code

public async Task Scan(int scan) { VictorDeviceScanParameters scanParameters = new VictorDeviceScanParameters(); scanParameters.ScanTime = scan; scanParameters.DeviceName = "victor"; scanParameters.CaseSensitive = false; var result = await m_deviceManager.ScanForDevices(scanParameters); }

Connecting To A Device

Connecting to a device follows a similar pattern as scanning for devices. A binding to the Android SDK must first be defined to call the connect method. This is already defined in the VictorAndroidDeviceManager script

public async Task<bool> Connect(string deviceAddress) { return await Task<bool>.Run(() => { AndroidJNI.AttachCurrentThread(); AndroidJavaObject ajo = m_AJODeviceManager.Call<AndroidJavaObject>("connect", deviceAddress); return ajo.Call<AndroidJavaObject>("get").Call<bool>("booleanValue"); }); }

The most important item of note here is the return of the function. The Android SDK’s Connect method returns a Boolean wrapped in a CompletableFuture.

In order to retrieve this return in the java binding, it is important to call the CompletableFuture’s “get” method to retrieve the return value, as well as the “booleanValue” method of the Java side Boolean to retrieve the underlying bool. Now that this function has been defined in our Unity project, we can simply call the Connect function on our VictorAndroidBLEDeviceManager object.

Callbacks

Callbacks when using the Android SDK requires not only a binding to the underlying Java call, but also defining the Callback abstract class in the Android SDK. Once again, the VictorAndroidDeviceManager provides an implementation for how both of these. First, the VictorDeviceCallback in the Android SDK is defined on the C# side. In the provided example, the VictorEventHandler and VictorEventHandlerMap in the Windows SDK is leveraged to manage passed in events.

Now that this callback has been defined, this object can be passed to the Android SDK’s version of the Subscribe and Unsubscribe functions.

With both items defined, users can create their own Event to pass to the VictorAndroidDeviceManager to be notified of attribute changes (for attributes that have the Notify flag enabled), connection state events, and device found events. It is important to remember that these callbacks will occur in a separate thread and should be especially noted if working on Unity Gameobjects that rely on these callbacks for modifications, as many operations on Unity Gameobjects can only be done on the main thread.

UI Prefabs

The UI prefab consists of a collection of controls that allow for scanning for devices, connecting/disconnecting to/from the device, and reading/writing to the device. Additionally, a Log prefab is used by the VictorUIManager script to print out a number of informational, warning, and error logs in the scroll view of the UI. Any reads made on the device will be printed out in the scroll view, as well as notifications of the state of a scan, connect, or disconnect call. One item of note is the USB toggle. If users wish to scan/connect to devices over USB, please ensure that the USB toggle has been turned on.

 

Building The Unity Project

Windows

Latest Windows SDK Supported: 10.1.19041.685

Below lists the settings used to build and run a UWP project in Unity when using the Victor SDK package.

NOTE: When attempting to build an app that intends to communicate with the device over USB, it is important that permissions for accessing serial devices has been added to the .appxmanifest for the resulting UWP build. Subsequent builds in the same folder will not overwrite this entry, however it is important to keep this in mind for any fresh builds. The best workflow for UWP builds is to perform an initial build and modify the .appxmanifest in the project’s build folder before running the application for the first time.

 

Android

Latest Android SDK Supported: 32

Below lists the settings used to build and run a an Android project in Unity when using the Victor SDK package. It is important to note that a device plugged into the development machine has been detected and will be the target device the application runs on once the build succeeds and deploys to the device.