5.4 Message Formats

Player clients and servers communicate with a simple symmetric message protocol. Each message is composed of two parts: a header and a payload. We now describe the format of the header and of the payloads of the 4 different message types.

5.4.1 Header

Every Player message has a 32-byte header that contains information about how to interpret the payload of the message. The header format is shown in Table 5.2.

Table 5.2: Message header fields and types

Byte 0 Byte 31

STX type device index t_sec t_usec ts_sec ts_usec reserved size

short short short short int int int int int int

The fields in the header have the following meanings:

• STX - This short is a special symbol that signals the start of a message. It always has the same value: 0x5878. Remember that this number, like all other shorts and ints, is transmitted in network byte-order.

• type - This short designates the type of the message to follow. There are 4 message types in the Player protocol. Their type codes are given in Table 5.3 and they are described in detail in Sections 5.4.2-5.4.8.

  
  

  Table 5.3: Message type codes

  Value Meaning

  0x0001 Data message

  0x0002 Command message

  0x0003 Request message

  0x0004 Acknowledgement response message

  0x0005 Synchronization message

  0x0006 Negative acknowledgment response message

  0x0007 Error response message

  
  

• device - This short designates the interface to which the message pertains. The currently available interface types are given in Table 5.4. Descriptions of the interfaces can found in Chapter 6.

  
  

  Table 5.4: Device interface type codes

  Value Interface Description

  0x0001 player The player server itself

  0x00FF null Null interface

  0x0002 power Power subsytem

  0x0003 gripper Simple robotic gripper

  0x0004 position Mobile robot base

  0x0005 sonar Array of fixed acoustic range-finders

  0x0006 laser Single-origin scanning range-finder

  0x0007 blobfinder Visual color segmentation system

  0x0008 ptz Pan-tilt-zoom camera unit

  0x0009 audio Fixed-tone generation and detection

  0x000A fiducial Fiducial (e.g., landmark) detector

  0x000B comms General-purpose communication system

  0x000C speech Speech synthesis/recognition system

  0x000D gps Global positioning system

  0x000E bumper Tactile bumper array

  0x000F truth Ground truth (only available in Stage)

  0x0010 idarturret Collection of IDAR sensors

  0x0011 idar IDAR (Infrared Data and Ranging) sensor

  0x0012 descartes The Descartes mobile robot base

  0x0014 dio Digitial I/O

  0x0015 aio Analog I/O

  0x0016 ir Array of fixed infrared range-finders

  0x0017 wifi Wireless Ethernet card

  0x0018 waveform Raw digital data (e.g., audio)

  0x0019 localize Multi-hypothesis localization system

  0x001A mcom Inter-robot stack-based communication

  0x001B sound Play pre-recorded sound files

  0x001C audiodsp Fixed-tone generation and detection

  0x001D audiomixer Control sound levels

  0x001E position3d Robot base that moves in 3D

  0x001F simulation Interface for controlling simulator

  0x0020 service_adv Service discovery

  0x0021 blinkenlight Blinking lights

  0x0022 camera Camera images

  
  

• index - This short designates the particular device of type device to which the message pertains. For example, if your robot is equipped with two laser range-finders, an index of 0x0000 addresses the first and an index of 0x0001 addresses the second.

• t_sec - (Only set by server) This int is the seconds portion of the server's current time.

• t_usec - (Only set by server) This int is the microseconds portion of the server's current time.

• ts_sec - (Only set by server on data messages) This int is the seconds portion of the timestamp supplied by the device from which the data originated. It can be interpreted as the time at which the device ``sensed'' the phenomenom represented by the data.

• ts_usec - (Only set by server on data messages) This int is the microseconds portion of the timestamp supplied by the device from which the data originated. It can be interpreted as the time at which the device ``sensed'' the phenomenom represented by the data.

• reserved - This field is reserved for future use.

• size - This int is the size in bytes of the payload to follow (it does not include the size of the header).

5.4.2 Data Messages

When read access has been granted for a device, sensor data from that device it is sent to the client in a data message (type 0x0001). By default, the server continuously sends sensor data at 10Hz. The device and index fields designate the device from which the data comes and the ts_sec and ts_usec fields give the time at which the device generated the data. The t_sec and t_usec fields give the server's current time the payload contains the sensor data, the format of which is device-specific. Data formats are given in Chapter 6.

5.4.3 Command Messages

When write permission has been granted for a device, the client can command the device by sending a command message (type 0x0002) to the server. The device and index fields designate the device for which the command is intended. The t_sec, t_usec, ts_sec, and ts_usec fields are unused. The payload contains the actuator command, the format of which is device-specific. In the interest of simplifying the protocol, the server does NOT respond to command messages. Badly formatted commands and commands to devices for which write permission was never established will only cause errors to be printed on the console from which Player was launched. Command formats are given in Chapter 6.

5.4.4 Request Messages

Request messages (type 0x0003) are sent by the client to the server to make configuration changes to devices. Although stricly speaking the device need not be open in order for the client to configure it, the client should always open it first to ensure that the configuration change is actually made (the player device is always ``open''). The device and index fields designate the device for which the configuration is intended. The t_sec, t_usec, ts_sec, and ts_usec fields are unused. The payload contains the configuration request, the format of which is device-specific. The server will respond to each request message with an appropriate response message (type 0x0004, 0x0006, or 0x0007).

5.4.5 Acknowledgement Response Messages

Acknowledgement response messages (type 0x0004) are generated as a result of request messages (type 0x0003) that were successfully received, interpreted, and executed by a device. Acknowledgement response messages are only sent by the server to the client. The device and index fields designate the device for which the configuration is intended. The t_sec and t_usec fields give the server's current time; the ts_sec and ts_usec fields are time at which the device generated the reply. The payload contains the response, the format of which is device-specific.

5.4.6 Synchronization Messages

After each round of data, the server sends a single synchronization message (type 0x0005), with a zero-length body. This message lets the client know that all data for this cycle has been sent. The synchronization message is sent even when no data was sent, as can occur if the client is using one of the data delivery modes that only send new data.

5.4.7 Negative Acknowledgement Response Messages

Negative acknowledgement response messages (type 0x0006) are generated as a result of request messages (type 0x0003) that were successfully received by a device, but which could not be properly interpreted or executed. Negative acknowledgement response messages are only sent by the server to the client. The device and index fields designate the device for which the configuration is intended. The t_sec and t_usec fields give the server's current time; the ts_sec and ts_usec fields are time at which the device generated the reply. The payload contains the response, the format of which is device-specific.

5.4.8 Error Acknowledgement Response Messages

Error acknowledgement response messages (type 0x0007) are generated as a result of request messages (type 0x0003) that could not be handed off to the target device, usually because the device's incoming configuration queue is full. Error acknowledgement response messages are only sent by the server to the client. The device and index fields designate the device for which the configuration is intended. The t_sec and t_usec fields give the server's current time; the ts_sec and ts_usec fields are unused. The payload will be empty.