The BeTelGeuse Protocol
BeTelGeuse data transmission protocol (2.10.2008)
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 a byte array in the following manner:
int len = arr[0]*256*256 + arr[1]*256 + arr[2];
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 BeTelGeuse to some other device. Direction --->> means messages which are sent to BeTelGeuse. 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. |
Connection initialization message -- C
1 |
3 |
2 |
1 |
1 |
12 |
1 |
n |
Cmd |
Length |
SessionID |
Sender type |
Compression |
Bta |
Friendly name length |
Friendly name |
1 |
n |
1 |
n |
Username length |
Username |
Password length |
Password |
-
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 Betelgeuse is initializing a new connection. If Betelgeuse wants to retain its old session ID (for example after a disconnect) it can transmit it to the server.
Sender type - Type of the sender. Default is 0 which is assigned to standard BTG phone version.
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.
Bta - Devices Bluetooth address on which BeTelGeuse is currently running. Bluetooth address is 12 byte long hexadecimal number.
Friendly name length - The length of the friendly name.
Friendly name - The friendly name of the betelgeuse platform. Computer name on windows platforms, hostname on Linux platforms, and mobile Bluetooth friendly name on mobile platforms. May be omitted.
Username length - The length of the username.
User name - The username of the current user of BeTelGeuse.
Password length - The length of the password.
Password - The password of the current user of BeTelGeuse.
BeTelGeuse initializes the connection with the initialization message. The response to this message contains an identification number.
Connection initialization response -- R
1 |
3 |
2 |
1 |
1 |
n |
1 |
m |
Cmd |
Length |
Session ID |
Login status code |
DB SessionID length |
DB SessionID |
Time length |
Server time |
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 BeTelGeuse for this session. One connection period corresponds to one session. The ID is a 2 byte number (0 - 65535)
Login status code - A code indicating of login with the username and password was succesfull or not. Value 0 means the login was succesfull, 1 password or username was wrong and 2 that some other error occured.
DB Session ID length - The length of the DB SessionID.
DB Session ID - An identification number assigned to BeTelGeuse for this session on the database side. One connection period corresponds to one session. The ID is an n-byte number.
Time lemgth - The length of the time field.
Time - The java timestamp of when the message was sent from the server. This can be used to synchronize the time of BeTelGeuse with the server's time.
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 Betelgeuse requested to keep, sending of sensor configuration messages is not necessary. However if a new session ID is assigned to Betelgeuse, sensor configuration messages need to be sent before sending any data.
Sensor configuration message -- S
Sensor configuration message is used to transmit information about sensors and the format of the data that will be sent.
1 |
3 |
2 |
2 |
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 BeTelGeuse 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:
2 |
12 |
2 |
1 |
m |
2 |
n |
Sensor ID |
BT address |
Sensor type |
LON |
Friendly name |
Number of parameters |
Parameter ... Parameter |
Reader ID - identification number assigned to the sensor. The number is used in the data messages to distinguish the sensors.
BT address - the Bluetooth address of the sensor
Sensor type - the type of the sensor, as defined in the BeTelGeuse manual.
LON - the length of the Friendly name field (0-255)
Friendly name - the friendly name of the sensor device. A character string of m chracters, where m is LON.
Number of parameters - the number of parameters.
Parameters - The field has the following format:
1
2
p
Parameter ID
Parameter name length
Parameter name
Parameter ID - the number used to identify the parameter in data messages (together with the sensor ID).
Parameter name length - the length of the parameter name.
Parameter name - the name of the parameter, e.g, "Longitude".
Sensor identification message -- I
The server replies to sensor configuration with sensor identification message.
1 |
3 |
2 |
2 |
Cmd |
Length |
SessionID |
Number of sensors |
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 BeTelGeuse for this session. One connection period corresponds to one session.
Number of sensors - The number of sensors that were configured.
Data message -- D
Data message is used to transmit sensor data from BeTelGeuse.
1 |
3 |
2 |
2 |
n |
Cmd |
Length |
Session ID |
Number 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 BeTelGeuse 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:
2 |
1 |
1 |
2 |
x |
1 |
2 |
x |
... |
1 |
2 |
x |
Sensor ID |
NOP |
Param ID |
Length |
Value |
Param ID |
Length |
Value |
... |
Param ID |
Length |
Value |
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.
Connection termination message -- Q
1 |
3 |
2 |
Cmd |
Length |
Session 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 BeTelGeuse for this session. One connection period corresponds to one session. The ID is 2 byte value number (0 - 65535)
BeTelGeuse or the receiver sends a connection termination message when they want to close the connection.
Connection termination confirmation -- T
1 |
3 |
2 |
Cmd |
Length |
Session 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 BeTelGeuse 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 sender is ready to close the connection after receiving the connection termination message.