Communications Between Agent and Iotellect Server

This article describes how Agent communicates with Iotellect Server using Iotellect Communications Protocol. Communication takes place when Agent establishes a connection with Iotellect Server and logs in. At this point, control of the Agent is passed to the Iotellect Agent driver. Iotellect Server then starts sending commands using Iotellect Communications Protocol to find out what data is provided by the Agent.

Agents always establish outgoing TCP connections to the server, never vice versa. Normally, Agents should maintain a persistent connection with the server to allow periodic polling and instant event delivery. However, in some rare cases Agents may work by periodically reconnecting for a short period of time to dump buffered events to the server and allow it to poll recent variable values.

Once a new connection between server and agent it established, server issues a series of commands according to the below Command-by-Command Structure of Communications section. This command sequence is repeated during every full synchronization cycle.

There are two types of command exchange that may occur outside of full synchronization cycles:

• Server may poll values of variables that have custom synchronization period

• Agent may sent events to the server

Both agent and server should periodically test connection availability. However, testing is more crucial for agent since it should be able to reconnect in case of connection failure. As for the server-initiated testing, it's only required to switch a non-replying agent's account into offline mode in order to ensure proper status indication.

Server tests connection during each full synchronization cycle, as well as single variable polling. If no reply to a command is received within Command Timeout specified in the global settings of Agent device driver, agent is deemed disconnected. An existing TCP connection is closed (if still open) or dropped and agent is marked as offline.

Agent-side testing procedures should be carefully designed by agent developers. There are two methods of connection testing:

• Expect at least one command to be received from the server during each minimal polling period of all agent's variables. E.g. if synchronization period is 5 minutes, but variable A has 2 minutes custom synchronization period and variable B has 30 seconds period, an agent may expect to receive an incoming command every 40-60 seconds. If this didn't happen, an agent should reconnection since existing connection may have been lost.

• Periodically send some dummy events to the server and make sure those events are confirmed by the server within a reasonable time. If an event was not confirmed it may mean a communication failure or a major server malfunctioning, in both cases reconnection is recommended.

First, Iotellect Server gets information about context declared by the Agent. The following commands are sent:

• Get Variable info

• Get Variable children

• Get Variable variables

• Get Variable functions

• Get Variable events

• Set Variable date of the Agent context to the current time in the Agent's Device Account timezone.

Iotellect Server now synchronizes the values of all device setting variables between its cache and Agent. More information about synchronization and device settings caching may be found in the Iotellect Agent driver article

• Get Variable modtime. Server gets modification times of all device settings variables to detect the proper direction of synchronization (Device-to-Server or Server-to-Device) for each of them.

• For each device setting variable, either a Get Variable or a Set Variable command is executed, depending on the direction of synchronization. These commands are used to update value of variable in the Agent's device context (for Server-To-Device synchronization) or in the server cache (for Device-To-Server synchronization).

• Set Variable modtime. The server updates device modification times stored in Agent.

• Call function synchronized from Agent context

When Agent is connected to the Iotellect Server, it may send event commands to the server whenever events are generated.

Iotellect Server never explicitly starts or stops listening for Agent's events by sending Add Event Listener or Remove Event Listener commands of Iotellect Communication Protocol. It listens for events implicitly, without notifying Agent about that it has started listening. Therefore, Agent may start sending events of any defined type to the server immediately after synchronization is complete, i.e. after the server has called the synchronized function from Agent's root context.

Was this page helpful?

Tell us more

Send

Thank you!