A Driver encapsulates the communication protocol and its configuration parameters.

The Driver API abstracts the specificities of the end Fieldbus protocols providing a clean and easy to use set of calls that can be used to develop end-applications.

Using the Driver APIs, an application can simply use the connect and disconnect methods to open or close the connection with the Field device. Furthermore, the read and write methods allow exchanging​ data with the Field device.

A Driver instance can be associated with an Asset to abstract even more the low-level specificities and allow an easy and portable development of the Java applications that need to interact with sensors, actuators, and PLCs.

The Asset will use the Driver's protocol-specific channel descriptor to compose the Asset Channel description.

Supported Field Protocols and Availability

Drivers will be provided as add-ons available in the Eclipse IoT Marketplace.

See the IoT Edge Framework page for a list of the currently supported drivers.

Driver roles

A ESF driver usually implement a single specific role for its protocol, for example master or slave. This section briefly explains the meaning of the master and slave terms.

Master driver

A master driver acts as a client for the implemented protocol, its purpose is to enable read and/or write access to a set of data points hosted by an external device from the ESF framework. Examples of such data points can be Modbus registers or AllenBradley tags on remote PLCs.

Slave driver

A slave driver acts as a server for the implemented protocol, this kind of driver hosts a set of data points that are accessible in read and/or write mode from remote clients over the implemented protocols. The local set of data points is also accessible from the ESF framework. Examples of such data points are DNP3 or IEC 60870 data points (e.g. analog inputs, analog outputs, binary inputs) maintained by the corresponding ESF slave drivers.

Driver instances

A driver provides an implementation of a specific protocol roles. In order to be able to use a driver at least one instance of it must be created and configured.

A driver instance manages a set of operating system resources needed for communicating with external devices, this in general differs between

• Master drivers: Master driver instances usually represent different connections to different remote device.

• Slave drivers: Slave driver instances usually maintain separate and independent set of data points, and for example listen on a different TCP ports.

Usually multiple instances of the same driver or of different drivers can coexist on the same device. This allows for example to connect the gateway to multiple Modbus slaves or to implement multiple DNP3 outstations on the gateway with separate sets of data points listening on different ports.

Each driver instance usually provide a set of global parameters that can be configured through the Web UI. Examples of such parameters are the IP address and port to connect to/listen on.

Resource representation in the Driver/Asset model.

The data points mentioned above are accessible from the ESF framework in the Driver and Asset model with the concept of channel.
A channel identifies a specific data point accessible through the driver and allows to perform a set of operations on them. The semantic of these operation generally depend on the specific drivers, in general it is related to the driver role. The available operations are the following:

• READ: allows on-demand data transfer from the Driver to the ESF framework.

  • Master drivers: usually involves retrieving the current value of the data point to from remote device by performing an I/O request (e.g. read of a Modbus register from the remote PLC)
  • Slave drivers: usually involves retrieving the current value of a local data point maintained by the driver. In this case this operation does not involves I/O, it is a simple lookup from driver memory (e.g. get the current value of a DNP3 analog output maintained by the DNP3 slave driver).

• WRITE: allows data transfer from the ESF framework to the Driver.

  • Master drivers: usually involves writing a value to a remote device by performing an I/O request. (e.g. write a Modbus register to the remote PLC)
  • Slave drivers: usually involves modifying the current value of a local data point maintained by the driver. (e.g. updating the current value of a DNP3 analog input maintained by the DNP3 slave driver). After the write operation is performed, the new value will be visible to the external clients. The write operation may also trigger the delivery of an unsolicited notification from the device to the clients.

• LISTEN: enables the unsolicited delivery of events related to the referenced data points from the Driver to the ESF framework.

  • Master drivers: usually enables receiving data change events from the remote PLC. (e.g. create a OPC-UA subscription and monitored item)
  • Slave drivers: usually allows to receive notifications for the value change of a local data point maintained by the driver (e.g. a DNP3 analog output has been updated by a DNP3 master through a command).

Not all drivers support the LISTEN mode, support for this mode is usually reported in the driver specific documentation pages.

the data exchanged through a channel is encoded using a limited set of data types:

• BOOLEAN: corresponds to the Java boolean type.
• BYTE_ARRAY: corresponds to the Java byte[] type.
• DOUBLE: corresponds to the Java double type.
• INTEGER: corresponds to the Java integer type.
• LONG: corresponds to the Java long type.
• FLOAT: corresponds to the Java float type.
• STRING: corresponds to the Java String type. This data type is used by some Drivers to exchange structured data through the JSON encoding, if this feature is available, the JSON representation is described in the Driver specific documentation.

Channel definition and configuration

Channels are defined and configured by the user by providing a set of configuration parameters to the driver, these parameters can be classified in two sets: the driver independent and driver specific ones:

Driver independent parameters

• Channel name: each channel is identified by a user-defined string identifier.
• Channel mode: defines if the channel performs a read, write operation or if it is a listening channel
• Value type: defines the data type that should be returned by the driver as result of read requests or unsolicited events, and/or the value type provided for write requests

Driver specific parameters

Each driver includes a set of channel parameters that are defined by the driver itself. These parameters are used to identify the protocol specific resource that the channel will refer to.

For example the address of the Modbus register to operate on or the AllenBradley tag name.

These parameters are described in the driver specific documentation.

Driver-Specific Optimizations

The Driver API provides a simple method to read a list of Channel Records:

public void read(List<ChannelRecord> records) throws ConnectionException;

Typically, since the records to read do not change until the Asset configuration is changed by the user, a Driver can perform some optimisations to efficiently read the requested records at once. For example, a Modbus driver can read a range of holding registers using a single request.

Since these operations are costly, the ESF API adds methods to ask the driver to prepare reading a given list of records and execute the prepared read:

public PreparedRead prepareRead(List<ChannelRecord> records);

Invocation of the preparedRead method will result in a PreparedRead instance returned.

On a PreparedRead, the execute method will perform the optimized read request.