ULEP Ultra Lightweight Embedded Protocol

1. Protocol description and purpose

Ultra Lightweight Embedded Protocol is a TCP/IP application protocol designed to provide connection for a large number of similar devices. Similarly like in subscribe/publish model data is associated with topics, however it doesn’t require  client devices to subscribe to it. Topics are described by numbers in range 1-63 and can be mapped to every client on the server side. 

Protocol was created to provide a transport layer for applications running over limited bandwidth or data transfer cost expensive link, e.g. satellite connection.

2. System architecture

System basis on large, but limited number of active clients, which connect to the base server using TCP/IP protocol. System allows to change the format of some communications between users and server. Because of that it is required to have consistent configuration of all devices. 

System can work in 2 modes:

• Duplex transmission mode - messages transmitted to server in most cases have acknowledge responses
• Non-duplex transmission mode - only client messages are transmitted, server device is not sending responses. Client devices must assume that the server application is running on a particular host, messages were delivered properly, especially the connect message. Transmission works only in direction client -> server.

Protocol provides distinction of messages sent by different clients. Every client has its own ID in range (by default) 0x01-0xFFFFFFFF. Every incoming connection is assigned to a particular device, what can be stored in an external database. Authorization and authentication can also be based on an external database.

3. Workflow

Client connects to a known server application using CONNECT message:

Chart 3.1 Connect workflow

For connect message server will answer with a connack. If connection is successful, data transmission can begin in both directions:

Chart 3.2 Data transmission workflow

When a client decides to close the connection, it has to send a disconnect message. After receiving this message, there should be no further data flow:

Chart 3.3 Disconnect workflow

4. Messages description

4.1 Messages types and format

All messages starts with header byte which has format shown in table 4.1.1:

Table 4.1.1bHeader byte format

All messages have type value present in bits 7 and 6 in byte 1. These types are described in Table 4.1.2.

Table 4.1.2 Message types

4.2 Connect/Connack

Client is the side, which initializes connection. Client sends a fixed length message of connect type and waits for a response from the server with a connack message. Connack has a fixed length of 1 byte. Connect and connack messages are the same type.

4.2.1 Connect

Connect message is 22 byte long message, which should be sent by client during first communication. It contains 4 information in proper bit configuration described in table 4.2.1.1. Those values are:

• Type - 2 bits defining message type
• Dup - duplex transmission:
• 0 - duplex transmission is off, server won’t be replying to messages, but if all are correct, data will be processed, data transmission possible only from client to server, keep alive parameter is ignored
• 1 - duplex transmission is on, server will be replying
• Keep alive - 5 bits value of levels of keep alive time (predefined in whole system)
• Client ID - client individual identifier defined in 4 bytes (unsigned 32 bit integer), 0x00000000 is reserved (can’t be assigned to any device)
• Server API key for authorization - value which has to be equal to predefined value stored in server application.

Table 4.2.1.1

4.2.2 Connack

Connack message is 1 byte long and contains 2 fields:

• Type - as in connect message (0x00)
• Return code - feedback value from server which determines if connection is successful or there is some issue with connection.

Format of connack message is described in table 4.2.2.1

Table 4.2.2.1

Return codes are described in table 4.2.1.2

Table 4.2.1.2

4.3 Transmit

Transmit message contains 3 bytes header followed by defined data bytes containing message.

 Table 4.3.1

4.4 Transack

Transack message has a fixed length of 2 bytes and its content should be equal to the first 2 bytes of the transmit message which it is acknowledging except of the message type. Message should point to the received message by its topic identifier and message ID. Description of message is presented in table 4.4.1.

Table 4.4.1

4.5 Ping pong

Ping and pong messages are introduced to provide control of keeping a connection alive. Those messages derive from Transmit and Transack messages. Topic identifier 0x00 is reserved for ping messages. Ping message is sent from client device to server, Pong is response from server to client on Ping message.

Every message received by the server is resetting the keep alive timer. Ping messages are simply null transmissions to reset this timer.

Table 4.5.1 Ping message

Table 4.5.2 Ping message

4.6 Disconnect

Disconnect message is fixed length of 1 byte and can be sent from client and server side. It contains only type value, presented in table 4.5.1. When this message is transmitted or received, both sides should close the connection.

Table 4.6.1

5. Example of communication process

Server settings:
Api key: 0123456789abcdef

Connect packet:

0x3C 0x00 0x00 0x00 0x01 0x30 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x61 0x62 0x63 0x64 0x65 0x66

Header - 0x00 type combined with 0x3C (60) of keep alive

Cliend ID - 0x00000001 - 1

Api key - 0123456789abcdef utf-8 encoded*

Connack packet:

0x00

Header - 0x00 type combined with 0x00 return code (OK)

Transmit packet (client -> server):

0x41 0x00 0x04 0x74 0x65 0x73 0x74

Header - 0x40 type combined with 0x01 (1) topic ID

Message ID - 0x00 (0) as counter starts from 0

Message length - 0x04 (4) bytes long

Message data - test utf-8 encoded

Transack packet (server -> client)

0x81 0x00

Header - 0x80 combined with 0x01 (1) topic ID

Message ID - 0x00 (0) as message ID of received message

Transmit packet (server -> client):

0x41 0x00 0x04 0x74 0x65 0x73 0x74

Header - 0x40 type combined with 0x01 (1) topic ID

Message ID - 0x00 (0) as counter starts from 0

Message length - 0x04 (4) bytes long

Message data - test utf-8 encoded

Transack packet (client -> server)

0x81 0x00

Header - 0x80 combined with 0x01 (1) topic ID

Message ID - 0x00 (0) as message ID of received message

Disconnect packet (client -> server)

0xC0

Header - 0xC0 as it is fixed message for disconnect