The VictoR Windows Software Development Kit (SDK) allows developers to communicate with a VictoR device over Bluetooth Low Energy (BLE) and USB in C#. The following documentation will walk users through the workflow of connecting to a device, reading and writing data to the services of the VictoR device, and how to register for notifications should the state of the device or its services change while connected. Currently, only the Device Configuration and Device Information services are directly supported by the SDK.

Supported ICD Rev: GH1
Supported VictoR Firmware Revision:

• Application Firmware Rev: 03.054 080

• Co-Processor Firmware Rev: 01.001

• Kernel Module Firmware Rev: 01.001

• BLE Firmware Rev: 03.017032

SDK:

• Minimum UWP: 10.0.10240.0

• NetStandard 2.0.3

Nuget Packages:

• NLog: 4.7.15

• Microsoft.Windows.SDK.Contracts: 10.0.22000.196

• Crc32.Net: 3.0.2

Introduction

The Victor SDK is made up of two C# libraries, VictoRCore and VictoRCommunications. Both are essential in working with a VictoR device. It is important users add both libraries as dependencies for a C# project dealing with VictoR devices. If working in Visual Studio, the libraries can be added to the project by first navigating to the Project Structure option under the File menu.<Image>menu from the toolbar and selecting Add Project Reference.

...

Once the Add Project Structure Reference window opens, users can select the Browse Option to add dependencies to the C# libraries.

<Image>Image Added

In order to add the SDK as dependencies to your project users should press the Browse button to open the file browser. After locating and selecting the installed VictoRCommunications.dll (release) and VictorCore.dll (release) or VictoRCommunicationsd.dll (debug) and VictoRCored.dll (debug) users should press the Add button to confirm their selections.

...

After adding the SDK DLLs the user can finalize their added dependencies in the dialog by pressing the OK button.

...

Device Manager

Instantiation

The act of connecting and disconnecting to a device, as well as maintaining a record of connected devices, is handled by the device manager. Before any work can be done on reading, writing, and subscribing to services, users must first create and work with the device manager.

BLE

VictorBleDeviceManager m_deviceManager = new VictorBleDeviceManager();

USB

VictorUsbDeviceManager m_deviceManager = new VictorUsbDeviceManager();

Scanning for Devices

Once a VictorBleDeviceManager DeviceManager has been instantiated, a scan must be performed to identify any active VictoR devices accepting connections over bluetooththe device manager’s protocol. By default, scanning for devices is set to take 10 seconds, with a query for any devices with the term “victor” (BLE) or “WASP” (USB) in its name, with case sensitivity not taken into account. Once the scan has completed, a Set of VictorDeviceInfo objects is returned, which each contain the name and address of a VictoR device.

var scannedDevices = await m_deviceManager.ScanForDevices();

Setting Scan Parameters

Users have a means to also specify VictorDeviceScanParameters when scanning for VictoR devices. Options include specifying the scan time, the string query for victor device names, and whether the case of the device name is important.

VictorDeviceScanParameters scanParameters = new VictorDeviceScanParameters();
scanParameters.ScanTime = scan;
scanParameters.DeviceName = "victor";
scanParameters.CaseSensitive = false;

var scannedDevices = await m_deviceManager.ScanForDevices(scanParameters);

Device Callbacks

Additionally, users can choose to receive a callback during the act of scanning for devices, rather than having to wait for the scan to complete. Callbacks can be set by passing a VictorDeviceCallback object that defines the onDeviceFound methodan EventHandler<VictorDeviceScannedEventArgs>.

List<string> m_discoveredDevices = new List<string>();

public async Task Connect()
{
    var result = await m_deviceManager.ScanForDevices(OnDeviceAdded);
}

public async void OnDeviceAdded(object sender,  VictorDeviceScannedEventArgs args)
{
    m_discoveredDevices.Add(args.Info);
}

Connecting To A Device

Once a powered on VictoR device has been found by scanning for devices with the VictorBleDeviceManagerDeviceManager, the resulting VictorDeviceInfo VictorDeviceScannedEventArgs, along with the DeviceManager that found the device, can be used to connect to the device along with the VictorBleDeviceManager that found the device.

List<string> m_discoveredDevices = new List<string>();

public async Task Connect()
{
    var result = await m_deviceManager.ScanForDevices(OnDeviceAdded);
}

public async void OnDeviceAdded(object sender, VictorDeviceScannedEventArgs args)
{
    m_discoveredDevices.Add(args.Info);
    bool result = await m_deviceManager.Connect(args.Info);
}

Subscribing to Connection State Changes

It is also possible to subscribe to the connection state of a VictoR device. This results in callbacks being triggered whenever the device is connected to or disconnected from.

public bool SubscribeConnectionState()
{
  bool subscriptionStatus = m_deviceManager.SubscribeConnectionStateChange(m_deviceName, ConnectionStateUpdated);

  return subscriptionStatus;
}

public void ConnectionStateUpdated(object sender, VictorConnectionStateChangedEventArgs args)
{
  onConnectionStateChanged.Invoke(args.Info.Address, args.Connected);
}

Disconnecting From A Device

A VictoR device can be disconnected by using the device manager that originally connected to the device, along with the device’s address.

await m_deviceManager.Disconnect(deviceID);

Reading From A VictoR Device

In order to read from a VictoR device, once a connection has been established through a device manager, a service object the attribute in question is associated with must first be created. Once the service object has been created, calls to read data from the connected device can be made, given the device manager containing the device has been passed to the service object on creation.

DeviceConfigurationService m_deviceConfigurationService = new DeviceConfigurationService(ref m_deviceManager);
DeviceInformationService m_deviceInformationService = new DeviceInformationService(ref m_deviceManager);

Deserialization of the data from the VictoR device is handled by the service objects, resulting in either a primitive data type or a custom made class defined in the SDK where appropriate. For example, when reading the serial number for the device through the DeviceInformationService class, the CompletableFuture Task returns a string.

public async Task<string> GetSerialNumber()
{
  return await m_deviceInformationService.GetSerialNumber(m_deviceName);
}

However, when reading the General System Parameters for the device through the DeviceConfigurationService class, the CompletableFutrue Task returns a GeneralSystemParameters object (defined in the SDK) that provides accessors for the various pieces of data inside of the General System Parameters attribute.

var generalSystemParameters = await m_deviceConfigurationService.GetGeneralSystemParameters(m_deviceName);
bool bluetoothEnabled = generalSystemParameters.isBluetoothLinkEnabled();
PowerProfileOption powerProfileOption = generalSystemParameters.getPowerProfile();
ushort minimumInactivityInterval = generalSystemParameters.getMinimumInactivityInterval();

NOTE: When reading from a device, please reference the supported ICD document specified above to ensure the attribute itself, as well as reading from the attribute, is supported.

...

Similar to reading from a VictoR device, writing to a VictoR device requires an established connection with a powered on device through a device manager and a service object that contains the data to be written. Serialization of data when writing to the VictoR device is handled by the service objects, converting the data into a byte array before being sent to the device.

VictorCore.Services.VideoParameters videoParameters = new VictorCore.Services.VideoParameters();

VictorCore.Services.FrameSize frameSize = new VictorCore.Services.FrameSize();
frameSize.Rows = (ushort)128;
frameSize.Columns = (ushort)64;

videoParameters.FrameSize = frameSize;
videoParameters.FrameRate = (ushort)24;
videoParameters.OpticalPath = VictorCore.Services.VideoParameters.OpticalPathOptions.AutoRange;

await m_VictorController.SetVideoParameters(videoParameters);

NOTE: When writing to a device, please reference the supported ICD document specified above to ensure the attribute itself, as well as writing to the attribute, is supported.

...

Attributes on the VictoR device, when supported, can be subscribed to through the usage of the VictorDeviceCallback class EventHandler<VictorConnectionStateChangedEventArgs> and the service containing the data to be subscribed to.

await deviceInformationService.SubscribeToCurrentBatteryLevel(OnBatteryValueChanged);

private async void OnBatteryValueChanged(DeviceInformationEventArgs args)
{
  string batteryLevel = args.CurrentBatteryLevel.ToString();
}

NOTE: When subscribing to an attribute, please reference the supported ICD document specified above to ensure that subscribing to the attribute itself supported.

Custom NLog Target

The VictoR Windows Software Development Kit (SDK) utilizes NLog as it’s logging mechanism. Log info is filtered into Debug, Info, and Warn severity levels. The SDK provides a convenience method to register custom targets to the NLog configuration in order to capture any useful information to a consuming application. A custom target which consumes all levels of the SDK log statements may be created and registered as follows.

[Target("CustomNlogTarget")]
public sealed class CustomNlogTarget: TargetWithLayout
{
    protected override void Write(LogEventInfo logEvent)
    {
        string message = logEvent.Message;
        //do something with the message here
        ...
    }
}

//NLog.LogLevel.Trace will capture all levels of logging, alternative options are
//Nlog.LogLevel.Debug;
//Nlog.LogLevel.Info;
//Nlog.LogLevel.Warn;
//Nlog.LogLevel.Error;
//Nlog.LogLevel.Fatal;
//Nlog.LogLevel.Off;
DeviceLoggerExtensions.RegisterTarget("CustomNlogTarget", typeof(CustomNlogTarget), NLog.LogLevel.Trace);