Flexible Driver Tutorial (Incoming Data)

This article explores the capabilities of the Flexible Driver and shows how to handle arbitrary incoming data from a TCP connection.

Iotellect includes drivers for many different devices, which simplifies integrating them into the system. In cases where there is no driver in Iotellect for a given device (for example, a device using a proprietary protocol), there are several options for integrating the device. The first option is to write a plugin for Iotellect in Java, and although this is straightforward, it can be labor-intensive. Another option is to configure one or more instances of the Flexible Driver to process incoming data as variables or events.

Throughout this tutorial, expressions read incoming bytes from the environment variable command, referenced as {env/command}. In an Iotellect using the Flexible Driver, configured to receive incoming data, this variable contains the data that was received and is being processed by the driver.

The first step is to configure the Flexible Driver plugin to correctly route incoming data to a specific Flexible Driver device. In the root context, open the Drivers/Plugins context, select Flexible, and choose Edit Driver/Plugin Properties.

From the Properties window, add a new row for every device which will be processing incoming data. Initially, add a single row with the values shown in the following table:

The following screenshot shows a row of the Flexible Driver Global Settings configured according to the preceding table.

You have set the global configurations of the Flexible Driver plugin to accept TCP data on port 55040, decode the incoming data as US-ASCII text, and forward it to the Flexible Driver device with ID "1". The next section describes how to configure that device to process incoming messages.

To create a Flexible device, click Add Device from the Devices context in the root context. Configure the device with the following parameters:

The following screenshot shows the above configurations entered into the “Add Device” window. Click OK to save and open the Device Properties page.

Once the device has been created, the Device Properties window should open automatically. The window can also be opened by clicking Edit Device Properties from the context menu of the newly created device.

In order to associate incoming data with the device, create at least one variable. Navigate to the Static Variables tab and add a row with the following data:

Configuring a row in the Static Variables tab results in the following:

The device now has a variable data, where incoming data can be written.

Another way of interacting with the device is to trigger specific events. Open the Static Events tab of the Device Properties, and add a row with the indicated data, leaving unmentioned fields blank:

Configuring a static event with the above values results in the following:

The device will trigger events when certain data packets are received.

The properties of the Operations tab determine how the device will respond to incoming data in the case of an incoming connection as well as how outgoing connections are processed. The following configurations are for devices which accept incoming connections.

Data Operations

contains({env/command},"variable") ? 1 
: (contains({env/command},"event") ? 0 : 1)

Asynchronous Variable Processing

Asynchronous Event Processing

The remaining sections can be left blank. Configure the properties of the Operations tab to match the example shown in the following screenshot:

Now that the Iotellect device is configured to process incoming messages with the Flexible Driver, it can be tested by sending some messages.

There are a few ways to send arbitrary TCP data. One option is to use a specialized tool, such as Packet Sender. Another is to write a simple program which creates a TCP connection and sends the desired data.

• Download and install packet sender on the same operating system where the Iotellect server is running.

• Create a packet with the following configurations:

The configured Packet Sender window will appear as follows.

Click Send to send the packet to the Iotellect Flexible Driver device.

• Install Python 3 on the same machine running Iotellect server.

• Save the following example script in a file called sendpacket.py:

import socket

# Set up the socket connection
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

# Hostname or IP address where server is running
host = 'localhost'
# Port where Flexible Driver is configured to listen to incoming data
port = 55040
# Start connection
s.connect((host, port))

# Send data
data = b'var: Update "data" variable with some arbitrary TCP data.\n'
s.sendall(data)

# Close the connection
s.close()

• Run the script from the command line with the command python3 sendpacket.py.

• Open the context menu of the device from the root context, and click Manage Device.

• This opens a window with all the device variables, in this case the variable data, with the data we sent as a packet: var: Update "data" variable with some arbitrary TCP data.

• Use the expression language to read the variable: {users.admin.devices.flexible_incoming:data}

Use the device name you actually created earlier in the tutorial. If you named it differently, adjust the context path accordingly.

We can trigger the updateData event we configured above, rather than updating a variable, by simply changing the data being sent to the device.

Recall that the Event/Variable Update Qualifier Expression determines whether incoming data will be processed as an event or a variable update operation. We used the following expression:

contains({env/command},"variable") ? 1 : (contains({env/command},"event") ? 0 : 1)

This expression first checks to see if the command contains the string “variable”. If so, it evaluates to 1 and the incoming message is interpreted as a variable update. If the command does not contain the string “variable”, it checks if the command contains the string “event”. If the command does contain the string “event”, the expression evaluates to 0, and the command is processed as an event. If neither “variable” nor “event” is present, it defaults to 1 and updates the variable.

To trigger an event, simply change the content of the test packet to contain the string “event” and remove the string “variable”. For example: event: This is an event!.

Using Packet Sender, update the ASCII and HEX data as indicated in the following table:

If using the Python script, update the data variable (which forms the payload sent to the device) as indicated in the following example:

...
# Send data
data = b'event: This is an event!\n'
...

\n is not part of the message text. It is a delimiter that marks the end of a command in the TCP stream.

In the Iotellect Context Tree, open the context menu of the Incoming Flexible device, and select Monitor Related Events.

A window appears, indicating all current events of the Incoming Flexible device. In our case, there are no active events, so the data table is empty.

Send the packet from Packet Sender, or run the Python script, and see that the event is fired:

Once you have created more events for the device, the Event Name Expression and Event Data Expression can be configured with more complex functions in order to trigger different events, based on the content of the command.

Was this page helpful?

Tell us more

Send

Thank you!