Overview

You can create a custom driver for the SmartServer to provide support for additional protocols not built into the standard SmartServer software.  To develop a custom driver, you implement your driver-specific code in C or C++ using the GNU C++ compiler (g++) and link your driver with the IAP Driver Library (IDL) that is included with the SmartServer.  IDL is a C library that implements the interface to IAP/MQ that is required for all drivers. It is a dynamic library (.SO) that you link into your custom driver process. Your custom driver process is called IDI, which stands for IDL driver instance.

This section describes how to interface custom protocols with IAP/MQ and how to use the IDL API.

Custom Drivers

A custom driver must define at least six functions that it must register with IDL for the IDL to use them as callback functions when performing IAP/MQ related operations. These six include four functions for device actions (create, provision, deprovision and delete) and two functions for datapoint operations (read and write). These callbacks are registered with IDL using IDL registration APIs such as IdlDevCreateCallbackSet().

Most of the callbacks, when called by the IDL, must call the corresponding IDL result API to inform IDL whether the operation was successful or not, and provide the result. For example, when IDL calls the callback DpRead() to read a datapoint, the custom driver must call IdlDpReadResult() with the result of the read operation upon completion.

When IDL receives a device create request, it finds the corresponding XIF (interface file), parses it, and stores the device details and datapoint details in its memory. Polling of its datapoints can only start after the device has been provisioned. Periodic polling can be achieved by configuring the monitoring properties of each datapoint in the device, whereas on-demand polling can be achieved by viewing the datapoints in the CMS Datapoints widget. On-demand datapoint writes can also be done through the Datapoints widget, for both the normal priority as well as overrides.

When a user imports a new device type in the Device Types widget, the loader service loads the XIF file in the /var/apollo/data/<protocol>/res directory and then restarts the associated driver. On start-up, the driver checks the res directory and publishes AMD (application metadata) objects of each XIF definition present. The CMS then shows the type loaded notification.

Conf File

The IDL obtains details about the custom driver through a JSON object in a conf file. This file must reside on the SmartServer and it’s absolute path must be specified in the IDL init call. The parameters in the conf file describe the IDI instance and how it works.  

For more information and a description of the conf file parameters, see Conf File.