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:

C/C++

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 DLN API is logically divided into modules. Each module contains a set of functions and declarations for the specific interface (for example, GPIO, I2C Master interface, I2C Slave interface, etc.).

You can check if the specific interface is supported by the connected adapter by calling the corresponding DlnXXXGetPortCount() function.

All these functions return the DLN_RESULT value. If the interface is supported, the corresponding function returns the DLN_RES_SUCCESS value. Otherwise the return code is equal to DLN_RES_NOT_IMPLEMENTED.

If these functions succeed, they fill in the count parameter with the number of available ports.

The example below prints the number of I2C master ports supported by the connected DLN-series adapter:

C/C++

DlnConnect("localhost",
DLN_DEFAULT_SERVER_PORT);
 HDLN device;
 DlnOpenDevice(0, &device);

 uint8_t count;
 DLN_RESULT result = DlnI2cMasterGetPortCount(device, &count);
 if (DLN_SUCCEEDED(result))
  printf("The adapter has %d I2C master ports.\n", count);
 else
  printf("The adapter does not support an I2C master interface\n");

The GPIO ports consist of 8 pins. If the number of available GPIO pins is not multiple of 8, the last port (with the highest index) can have less that 8 pins. Use the DlnGpioGetPinCount() function to obtain the number of GPIO pins for the current DLN-series adapter.

In the previous chapter we saw how you can use the return value of the DlnXXXGetPortCount() function to check if the corresponding interface is implemented by the DLN-series adapter. The same approach can be applied for all functions from the DLN API.

For example, some of the adapters have internal pull-up resistors on GPIO pins, while others do not. Moreover, the pull-up resistors may be available only for a subset of GPIO pins. You can enable these pull-ups with the DlnGpioPinPullupEnable() function. This function, as well as all other DLN API functions, returns the DLN_RESULT value. If the return value is equal to DLN_RES_NOT_IMPLEMENTED, you can’t enable the internal pull-up resistor for current pin.

This approach of checking for the available functionality sometimes has an undesirable side effect. If the function succeeds, it performs an action (for example, DlnGpioPinPullupEnable() function enables the pull-up resistor if it can do so). If you need to check the supported functionality, but not to perform an action, use the DlnGetCommandRestriction() function. As you will see in the following section, this function may also provide some additional information about the requested functionality.

As described in the corresponding section of the User Manual, the event driven interface can save your computational and USB resources and increase the application responsibility.

Each module has its own set of available events. The examples of how to handle and configure these events are provided in the corresponding parts of the current manual.

In the following sections we examine the general approach of DLN event processing and review two examples. The first example handles device connection/disconnection events and prints the corresponding messages at the standard output (stdout). The second example can be used as a generic events monitor. In addition to handling device connection/disconnection, it also processes all other event types. It dumps the event data at the standard output (stdout).

The communication with a device is performed by the use of messages. A message is a packet of data that is sent from the library to a device and vice versa. The DLN adapters utilize three types of messages:

• commands;

• responses;

• events.

Here is a short comparison to make things more logical and simple.

Commands are sent from the user application to a device. They contain some instructions to the device. You may instruct the device to perform an action (for example, to change voltage on a pin) or to configure the settings of the device. Each command has corresponding response.

A response is sent from the device to the user application after a command execution. A response always returns the result of the command execution. If the command was successfully executed, the response informs the user application about this. If it is impossible to complete the command, the response returns the error code. Some commands request specific data (for example, the serial number of a device or the total number of connected adapters). In this case the response returns the requested data in addition to the result of the command execution.

Events are sent from the device to the user application. They contain information about some changes that have taken place. A user can predefine the condition of an event generation. For example, an event may be generated when a new device is connected or when voltage changes on an input pin.

All the messages are transferred through the DLN library.

The messages (commands, responses and events) are delivered with the help of three functions:

• DlnSendMessage() - sends a specified message (an asynchronous command) to the device.

• DlnGetMessage() - retrieves messages (responses and events) sent by the device.

• DlnTransaction() - sends a synchronous command, waits for a response and returns the response details. Messages sent by the device (responses and events) are pushed into the DLN library message queue. The user may call the DlnGetMessage() function to get the message from the queue.

The DlnGetMessage() function removes the message from the queue and passes the message details to the user application.

The following example shows how to open DLN device, get its main parameters (hardware version, identifier and serial number), print them to console and close device. You can find the complete example in the “..\Program Files\Diolan\DLN\examples\c_cpp\examples\simple” folder after DLN setup package installation.

C/C++

#include "..\..\..\common\dln_generic.h"
#pragma comment(lib, "..\\..\\..\\bin\\dln.lib")

int main(int argc, char* argv[])
{
	// Open device
	HDLN device;
	DlnOpenUsbDevice(&device);

	// Get device parameters
	DLN_VERSION version;
	uint32_t sn, id;
	DlnGetVersion(device, &version);
	DlnGetDeviceSn(device, &sn);
	DlnGetDeviceId(device, &id);

	// Print it
	printf("Device HwType = 0x%x, SN = 0x%x, ID = 0x%x\n", version.hardwareType,
sn, id);

	// Close device
	DlnCloseHandle(device);
	return 0;
}

• Line 1:#include "..\..\..\common\dln_generic.h"

  The dln_generic..h header file declares functions and data structures for the generic interface.

• Line 2:#pragma comment(lib, "..\\..\\..\\bin\\dln.lib")

  Use dln.lib library while project linking.

• Line 8: DlnOpenUsbDevice(&device);

  The function establishes the connection with the DLN adapter. This application uses the USB connectivity of the adapter. For additional options, refer to the Device Opening & Identification section.

• Line 13:DlnGetVersion(device, &version);

  This function assigns device parameters to the DLN_VERSION type structure variable.

• Line 14:DlnGetDeviceSn(device, &sn);

  This function assigns device serial number to the provided pointer to 32-bit integer type variable. Serial number is unchangeable for each device and assigned once during device production.

• Line 15:DlnGetDeviceId(device, &id);

  This function assigns device id to the provided pointer to 32-bit integer type variable. Id number can be assigned by user by calling DlnSetDeviceId() function.

• Line 18:printf("Device HwType = 0x%x, SN = 0x%x, ID = 0x%x\n", version.hardwareType, sn, id);

  Printing the results. In the console you will see hardware type, serial number and id of the connected device.

• Line 21:DlnCloseHandle(device);

  Closing handle to the previously opened DLN-series adapter.

You can use the following functions to establish communication with DLN series adapters, identify them using ID and serial numbers, and obtain version information for all components involved in the communication.