BeTelGeuse logo

Home

Download

User Manual

Developers' Guide

BeTelGeuse Protocol

Javadoc

License

BeTelGeuse - BeTelGeuse Protocol

BeTelGeuse data transmission protocol (15.5.2006)

The BeTelGeuse data transmission protocol (BDT) is designed for BeTelGeuse software. Its goal is to allow simple and lightweight communication of sensor data to, for example, a server. BDT is designed so that communication overhead is minimal.

Conventions of this document

  • All numbers in this document are decimal unless otherwise indicated. Hexadecimal numbers are indicated with a leading 0x. For example, the decimal 23 would be 0x17 in hexadecimal.

  • Unless otherwise indicated, all byte values are unsigned values of eight (8) bits, representing the range of values from 0 to 255 or 0x00 to 0xFF.

  • Multiple byte values are transmitted big-endian: For example, the length 258 of a message is stored in three bytes like this: 0x00 0x01 0x02. This could be read from an unsigned byte array in the following manner:

    int len = arr[0]*256*256 + arr[1]*256 + arr[2];
  • The data source (for example BeTelGeuse) is refered as client in this document. The receiver of the data is refered as server.

Requirements

The communication media must support raw byte values. For example, HTTP RPC requests are out of question because of the limitations of XML. BDT needs to be lightweight because BeTelGeuse was designed to be run on mobile devices.

BDT protocol

Direction --->> means a transmission from the client to a server. Direction <<--- means messages which are sent from the server to a client. The BDT messages are:

Command Direction Description
c, C - 0x63 or 0x43
--->>
Connection initialization message
r, R - 0x72 or 0x52
<<---
Connection initialization response
s, S - 0x73 or 0x53
--->>
Sensor configuration message
i, I - 0x69 or 0x49
<<---
Sensor identification message
d, D - 0x64 or 0x44
--->>
Data message
q, Q - 0x71 or 0x51
><<--->>
Connection termination message
t, T - 0x74 or 0x54
<<--->>
Connection termination confirmation
  1. Connection initialization message - C

    1 3 2 12 1 n
    Cmd Length SessionID Bta Compression Friendly name

    • Cmd - command byte (0x43 or 0x63)

    • Length - The length of the rest of the message, a 3-byte value. In this case, 2 + 12 + 1 + n. (n may be 0 if the friendly name is omitted)

    • Session id - This field is 0 (two zero bytes) if th client is initializing a new connection. If the client wants to retain its old session ID (for example after a disconnect) it can transmit it to the server.

    • Bta - Devices Bluetooth address on which the client is currently running. Bluetooth address is 12 byte long hexadecimal number.

    • Compression - Indicates if some kind of compression is used for sending other messages than communication initialization and its response. Default value is 0, which means no compression is used.

    • Friendly name - The friendly name of the the client platform. Computer name on windows platforms, hostname on Linux platforms, and mobile Bluetooth friendly name on mobile platforms. May be omitted.

    The client initializes the connection with the initialization message. The response to this message contains an identification number which the client uses to identify itself in following messages. The client can send it old identification number to the server, if the client was connected to the server earlier. This is helpful in the instance of connection loss; the client does not need to send sensor configurations to the server, if the server recognizes the old session identifier. However, if different session identification number was received, or the client requested new session identifier, sensors and parameters need to be configured using sensor configuration message before sending of sensor data can beging.

  2. Connection initialization response - R

    132n
    CmdLengthSession IDDB Session ID

    • Cmd - command byte (0x52 or 0x72)

    • Length - The length of the rest of the message, a 3-byte value. In this case, 2 + n.

    • Session ID - An identification number assigned to the client for this session. One connection period corresponds to one session. The ID is a 2 byte number (0 - 65535)

    • DB Session ID - An identification number assigned to the client for this session on the server side. One connection period corresponds to one session. The ID is an n-byte number.

    After the connection initialization response the connection is considered to be open. Sensor configuration and data messages are disregarded before connection initialization and its response have been sent. Session ID is used to identify the sender. If the session ID is the same the client requested to keep, sending of sensor configuration messages is not necessary. However if a new session ID is assigned to the client, sensor configuration messages need to be sent before sending any data. DB Session ID is the identification number server assings to the client inside its own database.

  3. Sensor configuration message - S

    Sensor configuration message is used be the client to transmit information about sensors and the format of the data that will be sent. The server respods with sensor identification message which includes identification numbers for each sensor and parameter.

    1322 n
    Cmd Length Session ID Number of sensors Sensor ... Sensor

    Sensor configuration message has a header which consists of:

    • Cmd - command byte (0x53 or 0x73)

    • Length - The length of the rest of the message, a 3-byte value. In this case, 2 + 2 + n.

    • Session ID - An identification number assigned to the client for this session. One connection period corresponds to one session. The ID is 2 byte value number (0 - 65535)

    • Number of sensors: number of sensor configurations in the payload. The field is a two-byte value (0 - 65535).

    The payload consists of one or more sensor configurations. The format for a sensor configuration is:

    12212mn
    BT addressSensor typeLONLOPFriendly nameParameters
    • BT address - the Bluetooth address of the sensor

    • Sensor type - the type of the sensor, as defined in the BeTelGeuse manual (for example, 0x0100 represents a GPS sensor).

    • LON - the length of the Friendly name field (0-255)

    • LOP - the length of parameters field. The length field is a two-byte value (0 - 65535).

    • Friendly name - the friendly name of the sensor device. A character string of m chracters, where m is LON.

    • Parameters - The parameters of the sensor, which are separated by ';'. An example:

      longitude;latitude;time;speed;heading

      The parameter names can contain alphanumeric characters. The receiver uses the parameters field to break up data messages and later to decide how to process the data.

  4. Sensor identification message - I

    1322n
    CmdLengthSessionIDNumber of sensorsReply ... Reply

    Sensor identification message has a header which consists of:

    • Cmd - Command byte (0x49 or 0x69)

    • Length - The length of the rest of this message, a 3-byte value. In this case, 2 + 2 + n.

    • Session ID - An identification number assigned to the client for this session. One connection period corresponds to one session.

    • Number of sensors - The number of sensors configuration/identification blocks

    The payload consists of one or more sensor identification blocks. The format for a sensor identification block is:

    12221
    BT addressSensor ID NPIDParam ID ... Param ID

    • BT address - The bluetooth address of the sensor.

    • Sensor ID - Two byte identification value assigned to the sensor.

    • NPID - Number of parameter ID fields

    • Param ID - One byte identification value assigned to a parameter of the sensor.

    The message is used to assign sensor and parameter identification numbers. These identification numbers are used in data messages to specify which parameter is sent.

  5. Data message - D

    Data message is used to transmit sensor data from the client to the server.

    1322n
    CmdLengthSession IDNumber of blocks Data ... Data

    Data message header consists of:

    • Cmd - command byte (0x44 or 0x44)

    • Length - The length of the rest of this message, a 3-byte value. In this case, 2 + 2 + n.

    • Session ID - An identification number assigned to the client for this session. One connection period corresponds to one session. The ID is 2 byte value (0 - 65535)

    • Number of blocks - number of data blocks in the payload. The field is a two-byte value (0 - 65535).

    The payload consists of one or more data blocks. The format for a data block is:

    2112x12x...12x
    Sensor IDNOPParam IDLengthValue Param IDLengthValue...Param IDLengthValue
    • Sensor ID - the identification number assigned to the sensor

    • NOP - the number of parameters

    • Param ID - the parameter ID of the next parameter

    • Length - a two-byte value that indicates the length of the following value field.

    • Value - the value of one parameter.

    The session ID field in the header is used to identify the sender. Sensor IDs are used to identify the sensors and parameter ID fields to identify the parameters. Betelgeuse can send all the parameters from all the sensors connected to it with just one Data message, or it can choose to send only small subset of one sensor's parameters.

  6. Connection termination message - Q

    132
    CmdLengthSession ID
    • Cmd - 0x51 or 0x71

    • Length - The length of the rest of this message, a 3-byte value. In this case, 2.

    • Session ID - An identification number assigned to the client for this session. One connection period corresponds to one session. The ID is 2 byte value number (0 - 65535)

    The client or the server sends a connection termination message when they want to close the connection.

  7. Connection termination confirmation - T

    132
    CmdLengthSession ID
    • Cmd - 0x54 or 0x74

    • Length - The length of the rest of this message, a 3-byte value. In this case, 2.

    • Session ID - An identification number assigned to the client for this session. One connection period corresponds to one session. The ID is 2 byte value number (0 - 65535)

    Connection termination confirmation is sent when the client or the server is ready to close the connection after receiving the connection termination message.


Last modified 2007-02-26