IDTech Windows SDK Guide  3.2.4.393
API reference for Visual Studio .Net
Virtual Device Operation

The purpose of the SDK is to execute API commands and process the responses. While an API command such as getFirmware may seem straight forward in execution, the SDK needs to decide on the proper protocol depending on the device (IDG, NGA, ITP) to properly wrap the command, then it must prepare the data for the proper interface. A serial interface is unaltered command data, but if the interface is USB-HID, it can be two different type of HID report packets. If it is USB-KB, then it must execute 8-byte GetFeature/SetFeature packets.

It may be desired to leverage the SDK to communicate with devices not directly attached to the SDK. Examples of this would be for a company to connect to the device using their own SDK, or if the device is attached to an iOS or Android device through Xamarin.

This can be accomplished by configuring the SDK for Virtual Device Operation. You accomplish this be implementing a callback that will receive all the data that SDK wants to send to the device, and then any data that is received from the device you send back to the SDK. We are basically putting a hook in the SDK and diverting the data that would have normally gone to its COM or USB ports.

Step 1: Define the Device Write Callback
Implement a callback that will receive all the data the SDK would like to transmit to the device:
private void virtualWriteDelegate(byte[] data)
{
}
Step 2: Initialize the SDK
Set the SDK message callback (standard SDK implementation):
IDT_Device.setCallbackIP(MessageCallBack);

Request the SDK to open a virtual device, specifying the virtual device type, the connection type, and the virtual write callback

comm = IDT_Device.openVirtualDevice(IDT_DEVICE_Types.IDT_DEVICE_KIOSKIII, DEVICE_INTERFACE_Types.DEVICE_INTERFACE_USB, virtualWriteDelegate);

if "comm" does not come back null, the virtual device is initialized. This "comm" instance of IDTechComm will be needed to send device responses back into the SDK.

Step 3: Execute Commands
Execute a standard SDK command
RETURN_CODE rt = IDT_Device.SharedController.device_getFirmwareVersion(ref fw);

The SDK will construct the command and deliver it to the virtualWriteDelegate

private void virtualWriteDelegate(byte[] data)
{
//outgoing command received here. Send to connected device
}

Take that commands and direct it to a connected device (Xamarin->Android, Xamarin-iOS or other destination)

Step 4: Monitor Device Communication
You must continualy monitor the device for any data it is sending out. This can be data in response to a command, a notification, or even transaction data that may have been started on a different thread. Any data that is returned from the device must be directed back into the SDK:
if (comm != null)
{
comm.virtualRead(data);
}
Step 5: Device Type and Connection Settings
The SDK supports the following device types :
public enum IDT_DEVICE_Types
{
IDT_DEVICE_BTPAY,
IDT_DEVICE_BTMAG,
IDT_DEVICE_UNIPAY,
IDT_DEVICE_UNIPAYI_V,
IDT_DEVICE_UNIMAG,
IDT_DEVICE_SPECTRUM_PRO,
IDT_DEVICE_MINISMARTII,
IDT_DEVICE_AUGUSTA,
IDT_DEVICE_AUGUSTA_KB,
IDT_DEVICE_KIOSKIII,
IDT_DEVICE_CM100,
IDT_DEVICE_VENDI,
IDT_DEVICE_L100,
IDT_DEVICE_VENDIII,
IDT_DEVICE_VP3300,
IDT_DEVICE_VP8800,
IDT_DEVICE_SECUREMAG,
IDT_DEVICE_BTPAY_MINI,
IDT_DEVICE_K100,
IDT_DEVICE_NEO2,
IDT_DEVICE_TMS,
IDT_DEVICE_SECUREKEY,
IDT_DEVICE_SREDKEY2,
IDT_DEVICE_PIP
}

The SDK supports the following interface types for Virtual Devices

public enum DEVICE_INTERFACE_Types
{
DEVICE_INTERFACE_USB,
DEVICE_INTERFACE_SERIAL
}

Please note, the Device Type should accurately reflect the type of device being communicated with, but the Interface Type indicates how data will be provided and expected in return.

If DEVICE_INTERFACE_SERIAL is selected, all commands are complete command packets in their proper protcol wrapping, no additional modification are made. The response is expected to be the same.

If DEVICE_INTERFACE_USB is selected, the commands are further processed into USB Reports. These are 64 or 65 byte report format (when USB-HID), or 8 or 9 byte report format when USB-KB. Data is provided in the raw format the device will understand. It is expected the data will be sent through a communication bridge that is just acting as pass through mode.

Example: if you were to execute getFirmware to a virtual device that was defined as serial, a Kiosk IV, which is an IDG Device, will produce the command wrapped in IDG protocol with no additional data:

data = 0x5669564f74656368320029000000dea0

The Kiosk IV will respond back with an IDG packet, which needs to be sent to the virtualRead method in the SDk for processing

data = 0x5669564f746563683200290000124b696f736b2049562056312e32302e3130390aff
//pass this data to comm.virtualRead(data);

if you were to execute getFirmware to a virtual device that was defined as USB, a Kiosk IV, which is an IDG Device, will produce the command wrapped in IDG protocol in a USB-HID report format:

data = 0x015669564f74656368320029000000dea00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

The Kiosk IV will respond back with an IDG packet in USB-HID report format, which needs to be sent to the virtualRead method in the SDk for processing

data = 0x015669564f746563683200290000124b696f736b2049562056312e32302e3130390aff0000000000000000000000000000000000000000000000000000000000
//pass this data to comm.virtualRead(data);

In both cases, there is no need to decypter/process what is being sent/received. The SDK will do all appropriate processing with the raw data being provided.

Step 6: Closing Virtual Device
The SDK can only communicate with a single Virtual Device. The Virtual Device should be closed on exit. The Virtual Device should be closed if another Virtual Device is desire to be used. To close the currently open Virtual Device, execute:
IDT_Device.closeVirtualDevice();