DLN API is designed for a maximum flexibility. It allows to build simple applications that interface a single device with only a few lines of code. It also provides a lot of functions to build more complex applications, which can interface several adapters simultaneously, even if they are connected to different computers. There is a number of approaches to distinguish between different adapters, different types of adapters, and check what subset of the functionality the particular adapter supports.
We will cover all the details in the following subsections. Some information may seem to be complex in the beginning. Feel free to skip it and move to the next chapter. Most of the applications need to call a single function to establish a connection with the DLN series adapter - DlnOpenUsbDevice() (or DlnOpenBleDevice(), DlnOpenTcpDevice(), etc.).
When the device is opened, the DLN library allocates resources required to maintain the connection and associates a device handle with this device. Most of the functions in the dln.dll library expects this handle to be passed as the first parameter. It is used to identify the adapter.
You can open the same adapter several times by calling one of the DlnOpenXXX() functions. We do not recommend this approach and in most cases changing the application architecture eliminates the necessity to open the same hardware repeatedly. Each time you call one of those functions, a new handle is associated with the same hardware and additional resources to manage this handle are allocated. If application design requires you to open the same device multiple times, it is important to close all handles when you don't need them. The C++ programmers can use our C++11-like unique_hdln class to manage the device handle.
The device handle is represented by the HDLN type which is defined in the dln.h file as:
typedef uint16_t HDLN;
The allocated resources are automatically cleared up when the application terminates. Nevertheless, it is a good practice to explicitly close the device handle by calling the DlnCloseHandle() function.
The DlnOpenDevice() function allows you to open all available devices in a loop. This function accepts two parameters - an index number of the adapter to open and the pointer to the variable that receives the device handle. The deviceNumber parameter is zero-based.
You can call the DlnGetDeviceCount() function to obtain the number of available devices, and then call the DlnOpenDevice() function in a loop to open all devices as illustrated in the following code snippet:
HDLN handle; DLN_RESULT result = DlnOpenDevice(0, &handle);
You should make no assumptions about the association between deviceNumber parameter and the specific hardware. You can call the DlnGetDeviceSn() or DlnGetDeviceId() function to identify the device after it is open, or use one of the functions listed in the next chapters to open a specific device.
The DlnOpenDevice() and DlnGetDeviceCount() functions enumerate and open devices currently accessible to the DLN library - the device should be accessible to the computer where the DLN Server is running and your application should be connected to this DLN Server. In case of Direct Mode, the library itself establishes connections to the devices accessible to local PC. You can treat this as if the library is connected to the DLN Server running on the same PC where the application is launched.
The connection to the DLN Server is established by calling the DlnConnect() function, providing server IP and TCP port. After connection is established you get access to all devices accessible to the PC where the server is running:
Devices connected to the USB port of this computer.
Devices located in the range of Bluetooth Low Energy (BLE) connectivity to this computer.
Every DLN-series adapter has a unique serial number, allocated during the manufacturing. You can obtain the serial number of the device by calling the DlnGetDeviceSn() function. Use the DlnOpenUsbDeviceBySn() function to open the device with the specific serial number.
The device serial number can’t be changed. We do not recommend to use it to distinguish between the devices that are expected to perform different actions. Using the serial number tightly couples your application to the specific hardware.
There is a much more scalable approach. You can assign an ID number to any DLN-series adapter and then use it to identify the specific hardware. To assign the ID number use our DeviceId.exe application or call the DlnSetDeviceId() function. The ID number is stored in the internal non-volatile memory. It remains the same even when the adapter is connected to another computer.
When you know the ID number of the specific adapter, you can open it with the DlnOpenDeviceById() function.
DLN series include a number of different devices. All these devices support API described in the current manual, but their available functionality may slightly differ. For example, they can support different SPI and I2C bus frequencies, not all of the adapters implement I2C/SPI slave interfaces, etc.
If you know that your application needs a specific DLN-series device, you can check the hardware type of the adapter by calling the DlnGetHardwareType() function. The hardware type constants are defined in the dln_generic.h file as follows:
#define DLN_HW_TYPE uint32_t #define DLN_HW_TYPE_DLN5 ((DLN_HW_TYPE)0x0500) #define DLN_HW_TYPE_DLN4M ((DLN_HW_TYPE)0x0401) #define DLN_HW_TYPE_DLN4S ((DLN_HW_TYPE)0x0402) #define DLN_HW_TYPE_DLN3 ((DLN_HW_TYPE)0x0300) #define DLN_HW_TYPE_DLN2 ((DLN_HW_TYPE)0x0200) #define DLN_HW_TYPE_DLN1 ((DLN_HW_TYPE)0x0100)
You can use the DlnOpenDeviceByHwType() function to open the adapter with the predefined hardware type.
Instead of checking the specific device type, you can check if the adapter implements the required functionality. DLN API provides you with a number of ways to do this.
You can interface the DLN series adapters either directly or through the DLN server application. The DLN server is a Windows Service or Linux / Mac OS X Daemon. The applications communicate with the DLN server through TCP/IP. The most prominent difference between the Direct and the Server Based interfaces is that the Direct Interface can provide you with the higher bandwidth when you transfer a large amount of data, while the Server Based Interface allows several applications to communicate with the same adapter simultaneously. For additional details please refer to the Interface Types chapter in the User Manual.
Without going into details (the details are described in the Server Base Interface implementation chapter), you need to connect to the DLN server if you use the Server Based Interface. The connection is established by calling the DlnConnect() function. The DLN Server IP address and TCP port number are passed to this function as parameters.
If the DLN series adapter is connected to the computer where you launch your application, and you don’t change the default port configuration, you can use the DlnConnectDefault() function to connect to the DLN server.
As with most of the functions that allocate resources, the established connection can be closed by calling the DlnDisconnect() function with the same parameters. Use the DlnDisconnectDefault() function to close the connection established with the DlnConnectDefault() function. If you want to close all currently opened connections, call the DlnDisconnectAll() function.
The dln.dll library for the Direct Interface does not require the connection to the DLN server. It is designed to directly communicate with DLN-series adapters connected to the computer where the application is running. You are not required to call the DlnConnect(), DlnDisconnect() and DlnDisconnectAll() functions in the Direct Interface, but you can do this to make your code compatible with the Server Based Interface. These functions do nothing in the Direct Interface, they simply return the successful result code