Antilatency Device Network Library

开始之前，需要：

熟悉ADN的概念和结构；
检查AntilatencyService应用程序中的Device Network（设备网络）选项卡。

内容

库功能
使用库
ILibrary
IDeviceFilter
设备筛选器掩码
INetwork
INetwork：时间同步
NodeStatus
UpdateId
ICotask及ICotaskConstructor
IPropertyCotask
异常和错误

库功能

DeviceNetwork库允许您使用支持ADN协议的设备。该库创建设备连接层次结构，并将用户从其物理连接的详细信息中抽象出来。因此，当前版本的ADN支持通过USB和IP网络连接设备。此外，一些设备可以通过其他设备（例如，无线电协议）连接。

该库为使用ADN设备提供了一个相对较低级别的接口。库的主要功能:

跟踪设备与网络的连接和断开；
读写设备属性；
在设备上运行任务并与之交换数据包。

使用库

所有用于Antilatency备的库都与DeviceNetwork库交互。

DeviceNetwork标准用例：

加载库；
获取ILibrary;
使用createFilter创建空的IDeviceFilter设备筛选器；
使用addUsbDevice和addIpDevice方法向IDeviceFilter添加必要的USB和IP设备；
使用先前填充的筛选器（createNetwork）创建INetwork的实例；
使用getUpdateId跟踪UpdateId更改；
根据需要：读取各种设备的属性；
搜索支持所需Task（任务）的设备，然后启动此任务。

您可以在C#或C++的示例中反汇编用例。

此示例应用程序在每次UpdateId更改时显示有关ADN树的连接节点的信息。对于由带Alt的Universal Radio Socket和不带Alt的Bracer组成的设备树，应用程序显示以下信息：

ILibrary

在ILibrary中，用户可以使用getVersion查找库的当前版本，并使用setLogLevel设置所需的LogLevel。LogLevel=Off（默认）。

要创建ADN网络，需要创建并填写IDeviceFilter设备筛选器，该筛选器将用于选择要添加到INetwork的设备。创建筛选器并向其中添加设备后，可以使用ILibrary.createNetwork创建INetwork实例。

不能使用空筛选器创建INetwork实例。

IDeviceFilter

IDeviceFilter选择设备以连接到INetwork的特定实例。筛选器的工作原理是添加：创建为空，然后必须将应连接到ADN实例的设备掩码添加到其中。

首先使用ILibrary.createFilter方法创建一个IDeviceFilter，然后在那里添加USB设备（addUsbDevice）和IP设备（addIpDevice）。两种类型的设备都可以添加到一个筛选器中。

C#示例：

/*
 * Get a device filter for Antilatency USB Sockets (HMD Radio Socket and Wired USB Socket).
 */
private static Antilatency.DeviceNetwork.IDeviceFilter GetAntilatencyUsbSocketDevicesFilter(Antilatency.DeviceNetwork.ILibrary deviceNetworkLibrary) {
    var result = deviceNetworkLibrary.createFilter();

    var usbDeviceFilter = new Antilatency.DeviceNetwork.UsbDeviceFilter() {
        vid = UsbVendorId.Antilatency, pid = 0x0000, pidMask = 0xFFFF
    };
    result.addUsbDevice(usbDeviceFilter);
    
    return result;
}

C++示例。

在绝大多数情况下，使用以下常数为所有设备创建一个筛选器就足够了：AllUsbDevices、AllIpDevicesMask和AllIpDevicesIp。

C#示例：

#region DeviceFilter samples
/*
 * Get a device filter for all Antilatency USB devices.
 */
private static Antilatency.DeviceNetwork.IDeviceFilter GetAllUsbDevicesFilter(Antilatency.DeviceNetwork.ILibrary deviceNetworkLibrary) {
    var result = deviceNetworkLibrary.createFilter();
    result.addUsbDevice(Antilatency.DeviceNetwork.Constants.AllUsbDevices);
    return result;
}

/*
 * Get a device filter for all IP devices.
 */
private static Antilatency.DeviceNetwork.IDeviceFilter GetAllIpDevicesFilter(Antilatency.DeviceNetwork.ILibrary deviceNetworkLibrary) {
    var result = deviceNetworkLibrary.createFilter();
    result.addIpDevice(Antilatency.DeviceNetwork.Constants.AllIpDevicesIp, Antilatency.DeviceNetwork.Constants.AllIpDevicesMask);
    return result;
}

创建INetwork后，用户可以使用INetwork.getDeviceFilter方法获取IDeviceFilter，并检查与getIpDeviceMask、getIpDevice和getUsbDevice一起使用的掩码和设备。创建INetwork实例后，只能查看而不能修改筛选器。

IDeviceFilter允许您在同一主设备上运行的多个ADN实例之间分布连接的设备。要做到这一点，需要创建尽可能多的非重叠筛选器，就像同时运行ADN实例一样。不能使用相交筛选器创建INetwork对象。

设备筛选器掩码

USB设备

USB设备使用Vendor ID和Product ID（VID和PID）进行标识，其中Vendor ID（制造商ID）是制造商ID（在USB IF)中注册），Product ID（产品ID）是特定设备型号的ID。Antilatency设备Vendor ID：Antilatency = 0x3237，该常数可从UsbVendorId获得。

接下来，要向过滤器添加一个或多个设备，需要设置pid掩码。考虑给定的pid（Target Pid）、掩码（Mask）和可能的设备pid（Possible Device Pid）。掩码中的每个1表示连接设备pid中的该位必须等于给定pid（Target Pid）中的相应位；掩码中的0表示对应位可以采用任何值。看看下个例子：

IP设备

对于IP设备，相同的掩码规则适用于USB设备。

您可以在AntilatencyService中更改Antilatency设备的usb/Pid属性的值。

INetwork

使用INetwork，您可以恢复所有设备的连接层次结构，因为对于每个节点，可以找到其父节点。要做到这一点，请使用getNodes和nodeGetParent.

INetwork的另一个功能是处理节点属性。

从缓存中读取属性由nodeGetStringProperty和nodeGetBinaryProperty方法执行。
属性任务是使用nodeStartPropertyTask方法启动的，该方法返回IPropertyCotask。

有关使用属性和属性缓存的更多信息，请参阅ADN文章和IPropertyCotask节。

此外，在处理设备任务（Task）时使用INetwork。INetwork方法不直接用于启动任务，因此开发了Cotask和Cotask构造函数机制。

INetwork：时间同步

从Antilatency SDK 4.0.0开始，ADN库支持USB设备的时间同步。INetwork中添加了新方法：

getCurrentTime是INetwork实例的当前时间，单位为纳秒。
nodeGetCurrentOutofsyncTime是特定设备和ADN根节点之间的当前时间偏差，单位为秒。如果该值为负值，则该设备不同步。

我们使用一种自适应算法，该算法与Antilatency设备执行重复时间同步。结果，应用程序和设备之间的时间以大约100-200微秒的精度对齐。无线电设备上的时间校准精度约为10微秒。

NodeStatus

NodeStatus是在运行任何任务之前应检查的节点状态。‑TaskRunning和Idle值表示任务当前是否在此节点上运行。‑如果设备被禁用或不可用，则nodeGetStatus请求将收到Invalid值，并且无法在此设备上运行任何任务。‑当设备连接时，其NodeStatus将默认处于Idle状态。

UpdateId

库中有一个特殊的UpdateId计数器。每次连接/断开设备以及在任何节点上启动/结束任务时，此计数器都会增加。可以使用INetwork.getUpdateId方法找出计数器的当前值。计数器的增量可以表示INetwork实例中的更改：应该更新已连接设备（getNodes）的列表并检查其状态（nodeGetStatus）。

ICotask及ICotaskConstructor

Task、Cotask、CotaskConstructor是用于管理设备功能和任务的互联SDK工具。每个任务都有自己的Cotask（可能不止一个）和CotaskConstructor（Cotask构造函数）。

Cotask是任务（Task）和用户之间的链接。Cotask隐藏了数据传输和工作逻辑，并提供了处理任务的接口。要获得Cotask，必须首先创建ICotaskConstructor的实例。Cotask构造函数检查节点的任务支持并运行此任务，返回ICotask实例。

关于Cotask和CotaskConstructor的详细信息可以在这里阅读。

DeviceNetwork库包含ICotask和ICotaskConstructor接口。其他库的所有Cotasks都继承了ICotask.isTaskFinished方法，该方法检查相应的任务是否已完成。所有Cotask构造函数都继承isSupported方法（是否支持特定任务）和findSupportedNodes（查找支持该任务的节点）。ICotaskConstructor方法覆盖了INetwork接口的低级方法：不需要显式使用nodeIsTaskSupported和nodeStartTask。

IPropertyCotask

IPropertyCotask由INetwork.nodeStartPropertyTask启动。由于这也是一项任务，首先必须在设备上完成上一个任务，然后启动此任务。因此，当读取属性时，直接从设备使用值，而不是从属性缓存中使用值，缓存会自动更新。

IPropertyCotask允许您读取、写入和删除特定属性。此外，可以通过索引获取getPropertyKey属性名，这允许查找设备上的完整属性集。

此处包括一个新的章节，但暂时还没有中文版本。请阅读此章节的英文版。

异常和错误

如果试图使用与已创建network的其他筛选器相交的筛选器创建networkN，
则networkN实例将为null。
如果试图使用空筛选器创建network，
则会引发异常。
如果在禁用/无效Node（节点）上创建Cotask，
则会引发异常。
如果您试图运行一个已经启动的任务，
那么第二个Cotask将为null。
如果试图获取禁用/无效Node（节点）的缓存属性，
则会引发异常。
如果试图删除sys/属性，
则会引发异常。
如果在getPropertyKey中试图通过无效索引获取属性名，
则会引发异常。

有用链接

Antilatency库

Antilatency Device Network LibraryBehaviour.Initialize("Title")

内容

库功能

使用库