Flexible Driver

The flexible device driver acts as a "driver construction kit". It provides configuration options to connect with devices that use proprietary protocols, and in many cases can eliminate the need to develop a dedicated device driver in the Java programming language.

Flexible Driver Use Cases

The flexible driver is suitable for connecting a new device or data source with the following criteria:

Communications are performed via TCP, UDP, or through a serial port of the local machine.
The device either accepts connections from Iotellect Server or establishes connections to the server itself.
Iotellect Server acts as the client side of communications (i.e. sends commands and gets replies and/or gets asynchronous messages from a device) while the device acts as the server side.
Device protocol doesn't use "transactions", i.e. chains of separate messages acting as a single consolidated protocol unit (though transaction support can be still implemented in some cases).
Device protocol doesn't assume parsing incoming data stream into distinct protocol units according to time delays (as implemented in certain serial protocols).

The flexible driver works in the following cases:

Device protocol is ASCII (text) or binary.
The protocol is based on:
- Asynchronous messages initiated by a device.
- Server commands are followed by device replies.
- Both synchronous commands/replies and asynchronous device-initiated messages (mixed mode).
Device replies may be matched to server commands in two ways:
- The device may reply to commands in the same order as they were sent by the server.
- Server commands and device replies may be matched to each other with unique IDs. In this case, the device may reply to server commands in an arbitrary order.

The flexible device driver is a tool that required good understanding of the platform's unified data model, data tables, variables, functions, events, expression language, devices concept, and generic device drivers architecture.

Driver Information

Driver Plugin ID:

com.tibbo.linkserver.plugin.device.flexible

Global Settings

Global settings of the driver include Configuration table that regulates interaction with devices that establish incoming connections to the Iotellect Server:

Property	Description
Description	Description of device vendor/model/type/version handled by this record.
Protocol	Device protocol: TCP, UDP, or Serial. For UDP connections, both the Read Device ID Expression and Device ID Processing Expression must be implemented.
Port	TCP/UDP port to listen for incoming connections.
Input Splitter Mode	If the option “Attempt to Split on Every Byte” is selected, the driver "feeds" the incoming data buffer to the Input Stream Splitter Expression on every single byte of data received from a device. If “Attempt to Split in the End of Block” option is selected, the Input Stream Splitter Expression is only evaluated once after a block of bytes is received from a device using a single Java/OS socket read operation. Attempt to split in the end of block option may increase performance since the number of input buffer analysis attempts is significantly decreased.
		It's important to understand that incoming data blocks received from input socket are not directly related to protocol data units (PDUs). Network and operating systems (both device-side and Iotellect Server-side) may randomly split or join data blocks sent by the device itself. It can not be guaranteed that every single PDU sent by the device in a single operation will be received by the driver in a single data block.
Input Stream Splitter Expression	Used to extract commands from the incoming data buffer. Returns number of first bytes in the buffer that constitute a fully defined protocol unit or null if no full protocol unit is contained in the buffer.
Encode Expression	Performs encoding of outgoing command before it's sent to a socket or serial port. Returns an encoded command string. Can be used to prepend suffixes, append CRC or encode command bytes in any other way. Should refer to an original command via `command` environment variable.
Decode Expression	Performs decoding of incoming command after it's extracted from incoming data stream by Input Stream Splitter Expression. Can remove command prefix and suffix, check CRC or check command integrity in any other way. Should return transformed command as a string or NULL if command it invalid and should be discarded.
Device ID Detection Method Expression	This expression should return numeric value identifying a method that will be used to detect device ID: If 0 is returned by this expression, device ID will be discovered synchronously by sending a dedicated ID detection command to the device according to Read Device ID Expression and Device ID Processing Expression settings If 1 is returned by this expression, device ID will be discovered asynchronously from the first device-initiated message that will be analyzed using Device ID Processing Expression
Read Device ID Expression	This expression should return a command that will be sent to the device in order to retrieve the Device ID. Required for UDP connections.
Device ID Processing Expression	This expression is used to analyze the device's response to the Read Device ID Expression and return the Device ID. Must return the same value as the Read Device ID Expression. The response is available as a String contained in `command` environment variable. The expression may refer to it via the `{env/command}` reference. Required for UDP connections.
Encoding	String encoding used by the driver.

User Level Settings

None defined.

Device Account Properties

Connection Properties

Connection properties define how Iotellect Server communicates with a device. These settings may be accessed using the Edit Device Properties action of Device Context. The following connection properties are available:

Property	Description
Connection	Type of connection: Outgoing (the driver will establish a connection itself) or Incoming (one of incoming device connections will be associated with this device account).
Device ID	ID of this device account used to associate an incoming device connection with it.
Mode	Device communications mode: via TCP, UDP or Serial port. Used for outgoing device connections only.
IP address or Host Name	Address of the device (for TCP and UDP modes). Used for outgoing device connections only.
Port	Device port for TCP and UDP modes. Used for outgoing device connections only.
Baud Rate	Baud Rate (for Serial mode).
Incoming Flow Control	Incoming flow control type: None, CTS/RTS, or XON/XOFF (for Serial mode).
Outgoing Flow Control	Outgoing flow control type: None, CTS/RTS, or XON/XOFF (for Serial mode).
Data Bits	Serial data bits (for Serial mode).
Stop Bits	Serial stop bits (for Serial mode).
Parity	Serial parity (for Serial mode).
Timeout	Command timeout (default is 30 seconds). If no reply matching a sent server command is received during this timeout, the command it deemed "unreplied" and its execution fails with an error.

Command Exchange

This table configures basic parameters of exchanging protocol data units with the device.

The below command exchange settings will be used only for Outgoing device connections.

If connection type is Incoming, command exchange settings specified in driver's global configuration record that was used to accept the incoming connection will be used instead.

Property	Description
Input Stream Splitter Expression	Used to extract commands from the incoming data buffer. Returns number of first bytes in the buffer that constitute a fully defined protocol unit or null if no full protocol unit is contained in the buffer.
Input Splitter Mode	If Attempt to split on every byte option is selected, the driver "feeds" incoming data buffer to Input Stream Splitter Expression on every single byte of data received from a device. If Attempt to split in the end of block option is selected, the Input Stream Splitter Expression is only evaluated once after a block of bytes is received from a device using a single Java/OS socket read operation. Attempt to split in the end of block option may increase performance since the number of input buffer analysis attempts is significantly decreased.
		It's important to understand that incoming data blocks received from input socket are not directly related to protocol data units (PDUs). Network and operating systems (both device-side and Iotellect Server-side) may randomly split or join data blocks sent by the device itself. It can not be guaranteed that every single PDU sent by the device in a single operation will be received by the driver in a single data block.
Encode Expression	Performs encoding of outgoing command before it's sent to a socket or serial port. Returns an encoded command string. Can be used to prepend suffixes, append CRC or encode command bytes in any other way. Should refer to an original command via the `command` environment variable.
Decode Expression	Performs decoding of incoming command after it's extracted from incoming data stream by the Input Stream Splitter Expression. Can remove command prefix and suffix, check CRC or check command integrity in any other way. Must return the transformed command as a string or NULL if the command it invalid and should be discarded.
Encoding	String encoding used by the driver.

Operations

This table contains various expressions that define basic operations of the flexible device driver.

Property	Description
Asynchronous Command Detector Expression	Checks contents of a decoded command and returns TRUE if it's an asynchronous device message (event, value update, etc.) or FALSE if it's a synchronous reply to a previously sent server command.
Event/Variable Update Qualifier Expression	Checks contents of an asynchronous device message and returns 0 if it's an event or 1 if it's a device-initiated variable value update.
Command ID Expression	Used to find out a unique ID of the command within current communication session. This can be done by either generating an ID (randomly, sequentially, etc.) or checking Command data that is available via `command` environment variable. ID returned by this expression will be later matched to IDs returned by Reply ID Expression in order to find a reply to this specific command.
		If command/reply IDs are not used in the communication protocol, set this expression and Reply ID Expression to return some static value, e.g. to `"id"`. This will match first received reply to the first sent command and so on.
Reply ID Expression	Analyses contents of a synchronous device reply and returns its ID as a String. This will be matched to ID of a previously sent server command that was generated and returned by Command ID Expression.
		If command/reply IDs are not used in the communication protocol, set this expression and Command ID Expression to return some static value, e.g. to `"id"`. This will match first received reply to the first sent command and so on.
Variable Name Expression	Used to extract name of changed Iotellect Server variable from a command that was qualified as a device-initiated variable value update.
Variable Timestamp Expression	Used to extract date/time of a device variable change from a command that was qualified as a device-initiated variable value update.
Variable Quality Expression	Used to extract new value's quality from a command that was qualified as a device-initiated variable value update.
Variable Value Expression	Used to extract new variable's value from a command that was qualified as a device-initiated variable value update. Should return new value as a Data Table.
Event Name Expression	Used to extract name (type) of a Iotellect Server event from a command that was qualified as an asynchronous device notification message.
Event Timestamp Expression	Used to extract date/time of a device event from a command that was qualified as an asynchronous device notification message.
Event Level Expression	Used to extract level of Iotellect Server event from a command that was qualified as an asynchronous device notification message. Must return level value as an integer number.
Event Data Expression	Used to extract event-specific data from a command that was qualified as an asynchronous device notification message. Should return event's data as a Data Table.
Variable Definitions Expression	This expression should retrieve list of available variables from the device and return it as a Data Table. It normally refers some script or model's rule set that, in its turn, calls Send Command function to fetch parts of device metadata via device-specific commands. Every row of the table returned by this expression will be then converted to a separate variable definition as described in Working with Dynamic Metadata section.
Function Definitions Expression	This expression should retrieve list of available functions from the device and return it as a Data Table. It normally refers some script or model's rule set that, in its turn, calls Send Command function to fetch parts of device metadata via device-specific commands. Every row of the table returned by this expression will be then converted to a separate function definition as described in Working with Dynamic Metadata section.
Event Definitions Expression	This expression should retrieve list of available event types from the device and return it as a Data Table. It normally refers some script or model's rule set that, in its turn, calls Send Command function to fetch parts of device metadata via device-specific commands. Every row of the table returned by this expression will be then converted to a separate event definition as described in Working with Dynamic Metadata section.
Start Synchronization Expression	This expression is evaluated in the beginning of every device synchronization cycle. It can perform some initialization of the driver and/or device context. Expression result is ignored.
Finish Synchronization Expression	This expression is evaluated in the end of every device synchronization cycle. It can perform some cleanup of the driver and/or device context. Expression result is ignored.
Connect Expression	This expression is evaluated after a successful device connection. It is typically used to implement device login or other actions related to authentication/authorization by calling Send Command function to exchange data with the device. Expression result is ignored.
Disconnect Expression	This expression is evaluated after a successful device disconnection. Expression result is ignored.

Static Variables

This table defines which device variables will be available in any case, in addition to ones retrieved from the device during the dynamic metadata reading stage.

Each variable is defined by the following parameters:

Parameter	Description
Name	Name of the variable.
Description	Human-readable variable description.
Format	Format of the variable. See format section for details.
Readable	Flag indicating that variable is readable.
Writable	Flag indicating that variable is writable.
Help	Detailed variable description.
Group	Variable group, or NULL if variable does not belong to any group.
Read Request Expression	This expression should return data that will be sent to device in order to request current value of the variable. The expression must return a String. This string is first transformed by Encode Expression and result of this transformation is then converted to a byte array that is sent to the device. Conversion from the resulting String to a byte array uses UTF-8 encoding.
Read Result Processing Expression	This expression transforms data returned by the device (received from a socket or serial port) to a Data Table representing value of the device variable. The data received from the device is available as a String contained in `command` environment variable. The expression may refer it via `{env/command}` reference. The above data String is previously returned by Decode Expression that transforms raw data received from the device. Constructing a Data Table representing variable value is normally performed by `table()` expression language function. The `table()` function should use variable format that can be retrieved via `variableFormat()` expression language function.
Write Request Expression	This expression should return data that will be sent to device to push new value of the variable that was modified on the server side. This data effectively contains value of update variable encoded according to device's communication protocol. Updated value of the variable is available as a default data table during expression evaluation. The expression must return a String. This string is first transformed by Encode Expression and result of this transformation is then converted to a byte array that is sent to the device. Conversion from the resulting String to a byte array uses UTF-8 encoding.
Write Result Processing Expression	This expression analyses data returned by the device upon a variable write request (received from a socket or serial port). The expression's purpose is figuring out whether the write operation was successful or not. The expression must return text of write error as a String or NULL if write operation was successful. The reply received from the device is available as a String contained in `command` environment variable. The expression may refer it via `{env/command}` reference. The above reply String is previously returned by Decode Expression that transforms raw data received from the device.

Static Functions

This table defines which device functions will be available in any case, in addition to ones retrieved from the device during dynamic metadata reading stage.

Each function is defined by the following parameters:

Parameter	Description
Name	Name of the function.
Description	Human-readable function description.
Input Format	Input format of the function. See format section for details.
Output Format	Output format of the function. See format section for details.
Help	Detailed function description.
Group	Function group, or NULL if function does not belong to any group.
Execution Request Expression	This expression should return data that will be sent to the device in order to execute a device operation. This data effectively contains input parameters of the operation (function) encoded according to the device's communication protocol. Input parameters of the operation (function) are available as a default data table during expression evaluation. The expression must return a String. This string is first transformed by Encode Expression and the result of this transformation is then converted to a byte array that is sent to the device. Conversion from the resulting String to a byte array uses UTF-8 encoding.
Execution Result Processing Expression	This expression transforms data representing output of the device operation (received from a socket or serial port) to a Data Table representing the result of a server-side device function. The data received from the device is available as a String contained in `command` environment variable. The expression may refer to it via the `{env/command}` reference. The above data String is previously returned by the Decode Expression that transforms the raw data received from the device. Constructing a Data Table representing function output is normally performed with the `table()` expression language function. The `table()` expression language function should use a context function format that can be retrieved with the `functionOutputFormat()` expression language function.

Static Events

This table defines which device events will be available in any case, in addition to ones retrieved from the device during dynamic metadata reading stage.

Each event is defined by the following parameters:

Parameter	Description
Name	Name of the event.
Description	Human-readable event description.
Format	Format of the event. See format section for details.
Help	Detailed event description.
Level	Default level of the event.
Group	Event group, or NULL if event does not belong to any group.

Dynamic Variables

This table defines expressions that will be used to extract variable definition parameters from rows of a table returned by Variable Definitions Expression. Thus, it's used to convert every row of this table to a separate variable definition.

Parameter	Description
Name Expression	Expression that returns name of the variable.
Description Expression	Expression that returns human-readable variable description.
Format Expression	Expression that returns string representation of variable's format or null if its format is dynamic. See table format encoding section for details. Format string may use visible or invisible separators.
Readable Expression	Expression that returns flag indicating that variable is readable.
Writable Expression	Expression that returns flag indicating that variable is writable.
Help Expression	Expression that returns detailed variable description.
Group Expression	Expression that returns variable group, or NULL if variable does not belong to any group.
Read Request Expression Constructor	This is an expression that should return text of another expression. This other resulting expression should return data that will be sent to device in order to request current value of the variable. The expression must return a String. This string is first transformed by Encode Expression and result of this transformation is then converted to a byte array that is sent to the device. Conversion from the resulting String to a byte array uses UTF-8 encoding.
Read Result Processing Expression Constructor	This is an expression that should return text of another expression. This other resulting expression transforms data returned by the device (received from a socket or serial port) to a Data Table representing value of the device variable. The data received from the device is available as a String contained in `command` environment variable. The expression may refer it via `{env/command}` reference. The above data String is previously returned by Decode Expression that transforms raw data received from the device. Constructing a Data Table representing variable value is normally performed by `table()` expression language function. The `table()` function should use variable format that can be retrieved via `variableFormat()` expression language function.
Write Request Expression Constructor	This is an expression that should return text of another expression. This other resulting expression should return data that will be sent to device to push new value of the variable that was modified on the server side. This data effectively contains value of updated variable encoded according to device's communication protocol. Updated value of the variable is available as a default data table during expression evaluation. The expression must return a String. This string is first transformed by Encode Expression and result of this transformation is then converted to a byte array that is sent to the device. Conversion from the resulting String to a byte array uses UTF-8 encoding.
Write Result Processing Expression Constructor	This is an expression that should return text of another expression. This other resulting expression analyses data returned by the device upon a variable write request (received from a socket or serial port). The expression's purpose is figuring out whether the write operation was successful or not. The expression must return text of write error as a String or NULL if write operation was successful. The reply received from the device is available as a String contained in `command` environment variable. The expression may refer it via `{env/command}` reference. The above reply String is previously returned by Decode Expression that transforms raw data received from the device.

Dynamic Functions

This table defines expressions that will be used to extract function definition parameters from rows of a table returned by Function Definitions Expression. Thus, it's used to convert every row of this table to a separate function definition.

Parameter	Description
Name Expression	Expression that returns name of the function.
Description Expression	Expression that returns human-readable function description.
Input Format Expression	Expression that returns string representation of function's input format or null if its input format is dynamic. See table format encoding section for details. Format string may use visible or invisible separators.
Output Format Expression	Expression that returns string representation of function's output format or null if its output format is dynamic. See table format encoding section for details. Format string may use visible or invisible separators.
Help Expression	Expression that returns detailed function description.
Group Expression	Expression that returns function group, or NULL if variable does not belong to any group.
Execution Request Expression Constructor	This is an expression that should return text of another expression. This other resulting expression should return data that will be sent to device in order to execute a device operation. This data effectively contains input parameters of the operation (function) encoded according to device's communication protocol. Input parameters of the operation (function) are available as a default data table during expression evaluation. The expression must return a String. This string is first transformed by Encode Expression and result of this transformation is then converted to a byte array that is sent to the device. Conversion from the resulting String to a byte array uses UTF-8 encoding.
Execution Result Processing Expression Constructor	This is an expression that should return text of another expression. This other resulting expression transforms data representing output of the device operation (received from a socket or serial port) to a Data Table representing result of a server-side device function. The data received from the device is available as a String contained in `command` environment variable. The expression may refer it via `{env/command}` reference. The above data String is previously returned by Decode Expression that transforms raw data received from the device. Constructing a Data Table representing function output is normally performed by `table()` expression language function. The `table()` expression language function should use context function's format that can be retrieved via `functionOutputFormat()` expression language function.

Dynamic Events

This table defines expressions that will be used to extract event definition parameters from rows of a table returned by Event Definitions Expression. Thus, it's used to convert every row of this table to a separate event definition.

Parameter	Description
Name Expression	Expression that returns name of the event.
Description Expression	Expression that returns human-readable event description.
Format Expression	Expression that returns string representation of event's format or null if its format is dynamic. See table format encoding section for details. Format string may use visible or invisible separators.
Help Expression	Expression that returns detailed event description.
Level Expression	Expression that returns default level of the event.
Group Expression	Expression that returns event group, or NULL if event does not belong to any group.

Device Assets

Assets are not supported by the driver.

Device Settings

Flexible device account offers a combination of two device variable sets:

Variables manually defined in Static Variables table
Variables those definitions are dynamically retrieved from a device according to rules described in Working with Dynamic Metadata section

Device Operations

Flexible device account offers a combination of two device function sets:

Functions manually defined in Static Functions table
Functions those definitions are dynamically retrieved from a device according to rules described in Working with Dynamic Metadata section

Device Events

Flexible device account offers a combination of two device event sets:

Events manually defined in Static Events table
Events those definitions are dynamically retrieved from a device according to rules described in Working with Dynamic Metadata section

Connection Handling

This driver makes the device Online if:

TCP connection with the device was successfully established (for TCP mode)
Serial port is successfully opened (for Serial mode)

Synchronization Details

Synchronization details are covered in flexible device driver description.

DPF_EXPORT_V5.8.8 / TIME_1743710559 / 2025-04-03 20:02:39 / STRLEN_42875 / STRLEN_HTML_46021

{VERSION}

Was this page helpful?