Difference between revisions of "DCE Binary Communication Protocol"

Revision as of 15:35, 16 May 2007

Introduction

A device can create a command connection and one or more event connections to the router.

The command connection is used as an incoming connection and device will use it to receive message from the router (commands).

An event connection is used by the device as an outgoing connection to notify the router about events or the deliver commands to other devices.

The DCERouter process is listening on 3450 port.

How to create an event connection

Here is how the handshake is made for an event connection:

>> Device sends:

HELLO <my_device_id> '\n'

<< To router can response with :

NOT IN THIS INSTALLATION IP=<device_ip_address> '\n'

or

OK 43 IP=<device_ip_address> '\n'

>> Device sends:

EVENT 43 '\n'

<< To router will response with :

OK 43 IP=<device_ip_address> '\n'

>> To send a message, the device will send :

MESSAGE <size_of_binary_message> '\n'

and then

<serialized_binary_message>

How to create a command connection

Here is how the handshake is made for an event connection:

>> Device sends:

HELLO <my_device_id> '\n'

<< To router can response with :

NOT IN THIS INSTALLATION IP=<device_ip_address> '\n'

or

OK 43 IP=<device_ip_address> '\n'

>> Device sends:

COMMAND 43 '\n'

<< To router will response with :

OK 43 IP=<device_ip_address> '\n'

>> The device will wait for messages from dcerouter; the router will send :

MESSAGE <size_of_binary_message> '\n'

and then

<serialized_binary_message>

How to serialize data

DCE uses SerializeClass to serialize/deserialize data.

The sources can be found here : src/SerializeClass/Serialize.h/cpp.

The deserialize the data, the deserializing module must know the way the data was serialized like this:

- 4 bytes, long, value must be 1234 //magic number

- 4 bytes, unsigned long

- 1 byte, unsigned char

- 4 bytes, long, value must be 5678 //magic number

Primitives:

- 8 bytes, unsigned int64

- 8 bytes, int64

- 4 bytes, unsigned long

- 4 bytes, unsigned short

- 1 byte, unsigned char

- 1 byte, char

- 1 byte, long

- 4 bytes, float

- 8 bytes, double

- 2 bytes, short

Complex types:

1. string

- 4 bytes, STR_LENGTH + 1

- STR_LENGTH bytes, the array with chars

- 1 bytes, '/0'

2. block of data

- BLOCK_LENGTH bytes, the array with bytes

3. vector of strings

- VECT_LENGTH bytes, the number of strings from vector

- string 0

- string 1

...

- string VECT_LENGTH - 1

Other complex types serialized (see SerializeClass.cpp for details) :

- map<int,string>

- map<u_int64_t,string>

- map<int,int>

- map<string,string>

- vector<int>

- vector< pair<int,int> >

- map<string, pair<int,int> >

SerializeClass also allowed you to serialize/deserialize custom objects. Examples:

- PlutoColor

- PlutoPoint

- PlutoSize

- PlutoRectangle

- PlutoDataBlock

How to serialize a message

The class used by DCE is Message class from src/DCE/Message.h/cpp unit.

This is how the raw data looks like into a binary message:

- long, value must be 1234 (magic number)

- long, <device_from_id>

- long, <device_to_id>

- long, <device_group_to_id>

- long, <message_id>

- long, <message_priority>

- long, <message_type>

- long, <device_category_to>

- long, <device_template_to>

- unsigned char, <include_children>

- long, <message_broadcast_level>

- long, <message_retry>

- unsigned char, <relative_to_sender>

- long, <expected_response>

- string, <device_list_to>

- unsigned long, <number_of_string_parameters>

• foreach <string_parameter>

• - long, <string_parameter_id>

• - string, <string_parameter_value>

• end_foreach

- unsigned long, <number_of_data_parameters>

• foreach <data_parameter>

• - long, <data_parameter_id>

• - unsigned long, <data_parameter_length>

• - array of bytes, <data_parameter_value>

• end_foreach

- unsigned long, <number_of_extra_messages>

• foreach <extra_message>

• - unsigned long, <serialized_extra_message_length>

• - array of bytes, <serialized_extra_message_value>

• end_foreach

- unsigned long, must be 6789

How to serialize data-grids

coming soon...