Iotellect Communication Protocol

Iotellect Communication Protocol is an open, secure, and well-documented communication protocol used for communications between Iotellect servers, agents, and web/desktop clients. Communication is performed through a single TCP connection that is secured by SSL/TLS encryption by default.

The protocol enables intelligent remote access to the unified data model of servers and agents, allowing peers to “learn” about their capabilities, read and write properties, execute operations and get asynchronous notifications. Speaking briefly, if the data model is a unified representation of any device or resource, the protocol is a way to get full remote control over it.

There are several open-source implementations of Iotellect Protocol, including Java and Android Java, .NET and .NET Compact, C/C++, Iotellect BASIC, etc.

Within a communication session, both sides exchange commands. The originator of the commands is called client, and the other side is called server:

• In communications between Iotellect Server and Iotellect Client, originator (client) is Iotellect Client

• In communications between Iotellect Server and Iotellect Agent, originator (client) is Iotellect Server

• In distributed architecture, command originator (client) is consumer while provider acts as a server

Currently, there are two modern versions of the protocol: 2 and 3. The differences between the versions are described in each paragraph of the documentation article.

Commands are encapsulated using <STX> (0x02) and <CR> (0x0D) characters. Commands are extracted from the data stream, and all other data is discarded. Other aspects depend on the protocol version.

Command encapsulation structure is the following:

<STX>command<CR>

If there are two or more <STX> characters without <CR>, all data belonging to the current is discarded on each received <STX>:

<STX>aaa<STX>bbb<CR> is treated as command bbb.

Command encapsulation structure is the following:

<STX><L1><L2><L3><L4><T>command<CR>

After the <STX> character a 4-byte integer is followed: <L1><L2><L3><L4>. It is a followed command length in bytes.

Next is <T> command type byte. In this protocol version, a command can be one of two types: Raw (0) and Compressed (1). Raw means that a command is sent as a raw char array. Compressed type means that a command is sent compressed as a ZLIB byte array.

Then a command is followed in raw or compressed state and encapsulation is closed by a <CR> character.

Example of command encapsulation for 3 protocol version: <STX><0><0><0><7><0>R/123/A<CR>

Each command consists of several parts separated by 0x17 (“Command Separator”) characters. The command separator character is represented by / in this manual. For example:

<STX>aaa/bbb/ccc<CR>

contains three parts: aaa, bbb and ccc.

Thus, three characters are reserved and may not appear inside command parts:

Every command has the following structure:

<STX>command_code/command_parameters…<CR>

command_code is a single character, one of:

command_parameters is one or more parameters specific to the command code and separated by /.

The structure of this command is as follows (from this point, leading <STX> and terminating <CR> characters are not shown):

M/message_ID/message_code/message_parameters…

message_ID is unique within the current session.

message_code is a character, indicating the message type. Available message codes:

message_parameters is one or more parameter(s) specific to the message code, separated by /.

R/reply_ID/reply_code/reply_parameters…

reply_ID should be equal to the ID of the message being replied.

reply_code parameter is a character that indicates type of reply. Available reply codes:

M/message_ID/S/protocol_version

The format of this message is guaranteed to remain unchanged in the future. It should be sent by the client as the very first command during the data exchange with the server. The server returns an error if any other message is issued before the Start message was sent.

protocol_version is an integer number indicating the version of the communications protocol supported by client. The current version is 3.

Server responds to the Start command with a Reply command. If protocol version specified by client is supported by server, the reply code is Success, otherwise it is Denied. See description of the Reply command for more info.

M/message_ID/O/operation/context_name/entity[/data_table]

The Operation command orders the server to execute an operation on a given context.

Operation is a character specifying the operation to be executed. context_name is the name of the context for which the requested operation is executed. entity is an operation-specific parameter. It can be a variable name if operation is “Set Variable”, or a function name if operation is “Call Function”.

List of available operation codes:

data_table is an optional parameter containing operation specific data. See Data Table Encoding appendix for details.

M//E/context_name/event_name/event_level/event_ID/event_listener_ID/data_table/server_timestamp

This message is sent to the client when an event named event_name fires in context_name and this client was previously added as a listener for this event. It does not require any reply from the client. If the event is persistent, the event_ID field contains its unique ID. event_listener_ID is an integer number that indicates the listener object on the client side. data_table contains event-specific data.

The server_timestamp field contains server-side event creation time in milliseconds since January 1, 1970 00:00:00 UTC.

Note: The "event" message has empty message_ID parameter.

M/message_id/O/G/context_name/variable_name

This operation returns variable_name from context_name.

If the variable is found and no error occurred, the reply to this command includes the data table containing the value of the requested variable:

R/reply_id/A/data_table

M/message_id/O/S/context_name/variable_name/data_table/queue_name

This operation sets variable_name of context_name to the value contained in data_table.

If queue_name is specified, the processing is performed within a names queue that guarantees all commands to processed sequentially in the order they are sent.

If the variable value was changed successfully, the server replies:

R/reply_id/A

M/message_id/O/C/context_name/function_name/data_table[[/queue_name]/flags]

This operation calls function_name from context_name with data_table as input.

If queue_name is specified and is not empty, the processing is performed within a names queue that guarantees all commands to processed sequentially in the order they are sent.

The operation optionally supports the following flags:

If no error occurred and N flag is not specified, the reply includes a data table containing the function's output:

R/reply_id/A/data_table

M/message_id/O/L/context_name/event_name/event_listener_ID[/filter_text]

This operation registers a listener with the specified integer event_listener_ID for the event_name in context_name. When this event fires, client receives an “Event” (E) message with the same event_listener_ID code.

The optional filter_text parameter allows to pre-filter events based on the provided filter expression. This expression will be calculated for every matching event, and if it results to false, event will not be sent to the client.

On successfully adding event listener, server replies:

R/reply_id/A

M/message_id/O/R/context_name/event_name/event_listener_ID[/filter_text]

This operation removes listener with the specified event_listener_ID of event_name in context_name. If filter_text is specified, only listener with this filter is removed.

On successfully removing listener, server replies:

R/reply_id/A

All data values received or sent within this protocol are represented by Data Tables.

Every Data Table is encoded to a byte array to be inserted into a command.

See Data Table Encoding for details.

Was this page helpful?

Tell us more

Send

Thank you!