BRAK Software Abstraction Layer (BRAK/SAL) Status Protocol Stream Specification Version 0.1, March 31, 2000 Version 0.2, April 1, 2000 1) Introduction The purpose of this document is to define the status protocol stream which is passed to from the BRAK Software Abstraction Layer (BRAK/SAL) to monitoring software such as a GUI client application. The stream is currently defined as a one-way communication. The client application is expected to recognize all packets described in this document; any packets which are unimplemented or unused in the client application can then be discarded. Also, if the client looses its place in the stream there is no way to cause the server to re-synchronize. However, since this code is designed to be used with other BRAK socket layer library routines, this should not be an issue for most client applications. Future extensions to this status protocol stream will define methods for client applications to communicate with the server so that capabilities of the client can be identified and the types of data sent over the stream to the client can be tailored. 2) Overall packet format Each packet contains an identifier code (id_code), a data item type subcode (id_sub_code), an item identifier (id), and data packet. In addition to the general id_code (values 0x0000 thru 0x0fff), two code modifiers are defined: groups and polys. A "group" consists of a collection of sensors, actuators or motors with consecutive identifiers; a "poly" is a collection of sensors, actuators or motors with non-consecutive identifiers. 2.1) General packet (id_codes 0x0000 through 0x0fff) A general packet consists of a single data packet. The id_code identifies the class of packet (sensor, motor, actuator, orientation or misc) while the packet-specific id_sub_code identifies the specific type of packet within that class. The id identifies which particular item is associated with the data packet. u_int16_t id_code (0x0000-0x0fff) u_int8_t id_sub_code (item type) u_int16_t id (id of item) data packet (data item) 2.2) Poly packet (id_code plus 0x4000) A poly packet consists of one or more unrelated data packets. The id_code identifies the class of packet (sensor, motor, actuator, orientation or misc) while the packet-specific id_sub_code identifies the specific type of packet within that class. The count gives the total number of data packets within the overall packet; it is always greater than 0. Each data packet is preceded by the id of the particular item. u_int16_t id_code (0x4000-0x4fff) u_int8_t id_sub_code (item type) u_int8_t count (number of items) u_int16_t id (id of first item) data packet (data of first item) .... u_int16_t id (id of nth item) data packet (data of nth item) 2.3) Group packet (id_code plus 0x8000) A group packet consists of one or more related data packets. The id_code identifies the class of packet (sensor, motor, actuator, orientation or misc) while the packet-specific id_sub_code identifies the specific type of packet within that class. The count gives the total number of data packets within the overall packet; it is always greater than 0. A single id is transmitted, representing the identifier of the first data packet. Each successive data packet is assumed to have a consecutive id (i.e., the last data packet has identifier id+n-1). u_int16_t id_code (0x8000-0x8fff) u_int8_t id_sub_code (item type) u_int8_t count (number of items) u_int16_t id (id of first item) data packet (data of first item) .... data packet (data of nth item) 3) Sensor data packet formats (id_code type 0x0010) Sensor data packets contains information from various sensors on the robot. All sensor packets have an id_code=0x0010. The specific id_sub_code identifies the specific type of sensor data contained in the data packet. There are currently four types of sensor data packets: ultrasonic, relative encoder, absolute encoded, and accelerometer. 3.1) Ultrasonic data packet format (id_sub_code type 0x01) u_int16_t delay; (the time delay recorded by the robot) rtimeval time; (the time the reading was taken) 3.2) Relative encoder data packet format (id_sub_code type 0x02) int16_t d_count; (the last read change in position) rtimeval d_time; (the time the last reading was taken) int16_t count; (the accumulated change in position) rtimeval time; (the time that count was last cleared) 3.3) Absolute encoder data packet format (id_sub_code type 0x03) int16_t count; (the last position) rtimeval time; (the time the last reading was taken) 3.4) Accelerometer data packet format (id_sub_code type 0x04) float accel; (the last acceleration reading) rtimeval time; (the time the reading was last taken) 4) Motor data packet formats (id_code type 0x0020) Motor data packets contains information from various motors on the robot. All motor packets have an id_code=0x0020. The specific id_sub_code identifies the specific type of motor data contained in the data packet. There is currently one type of motor data packet: DC motor. 4.1) DC motor data packet format (id_sub_code type 0x01) int16_t speed; (the speed sent to the motor) rtimeval time; (the time the speed was last set) 5) Actuator data packet formats (id_code type 0x0030) Actuator data packets contains information from various actuator on the robot. All actuator packets have an id_code=0x0030. The id_sub_code identifies the specific type of actuator data contained in the data packet. There is currently two types of actuator data packets: Steering wheel and driving wheel. 5.1) Steering wheel data packet format (id_sub_code type 0x01): float angle; (angle of wheel relative to robot, in radians) rtimeval time; (the time angle was last updated) 5.2) Driving wheel data packet format (id_sub_code type 0x02): float rotation; (rotations of wheel) rtimeval time; (the time rotation was last reset) 6) Robot orientation packet format (id_code type 0x0040) Robot orientation data packets contains information about the location and orientation of the robot in its environment. All orientation packets have an id_code=0x0040. The id_sub_code identifies the specific type of data contained in the data packet. There is currently two types of orientation data packets: ego-centric (robot-centered) and omni-centric (world-centered). 6.1) Ego-centric data packet format (id_sub_code type 0x01): float xpos; (estimated x location in world) float ypos; (estimated y location in world) float orientation; (estimated orientation in radians) rtimeval time; (the time the estimated was last computed) 6.2) Omni-centric data packet format (id_sub_code type 0x02): float direction; (estimated direction of motion in radians) // direction is relative robot's coordinate system float speed; (estimated speed: always positive or zero) rtimeval time; (the time the direction/speed last computed) 7) Misc data packet formats (id_code type 0x0800) Miscellaneous data packets contain any information about the system which does not neatly fit into another category. All misc packets have an id_code=0x0800. The id_sub_code identifies the specific type of data contained in the data packet. There is currently one type of miscellaneous data packets: base time. 7.1) Base time data (id_sub_code type 0x01): timeval time; (base time for all rtimeval values) 8) Other data type formats All other data items used in the system are described below. 8.1) timeval data type timeval is used to represent time in seconds and microseconds. The seconds, when used with Unix system functions such as gettimeofday(2), represents elapsed seconds since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC). It is defined in the header file . typedef long int __time_t; struct timeval; { __time_t tv_sec; // Seconds __time_t tv_usec; // Microseconds } 8.2) rtimeval data type rtimeval is used to represent elapsed time on the system in milliseconds. The elapsed time used by all items is relative to the base time (see "Misc data packets"). As such, it can represent intervals up to approximately 49 days in length. It is defined in the header file typedef long int __time_t; typedef __time_t time_t; typedef time_t rtimeval; // elapsed time in milliseconds 8.3) General data types float: single-precision IEEE floating point (4 bytes) Most of these are defined in . The names may be changed in the future to conform to Glib/GTK+ naming conventions, but the sizes should remain the same. int16_t: signed short integer (2 bytes) u_int16_t: unsigned short integer (2 bytes) u_int8_t: unsigned short byte (1 byte)