next up previous contents
Next: 6.2 null Up: 6. Device Interfaces Previous: 6. Device Interfaces   Contents


6.1 Player


The player device represents the server itself, and is used in configuring the behavior of the server. This device is always open.


#define PLAYER_READ_MODE 'r'
#define PLAYER_ALL_MODE 'a'
The device access modes

The valid data delivery modes

#define PLAYER_PLAYER_DEVLIST_REQ ((uint16_t)1)
#define PLAYER_PLAYER_DRIVERINFO_REQ ((uint16_t)2)
#define PLAYER_PLAYER_DEV_REQ ((uint16_t)3)
#define PLAYER_PLAYER_DATA_REQ ((uint16_t)4)
#define PLAYER_PLAYER_DATAMODE_REQ ((uint16_t)5)
#define PLAYER_PLAYER_DATAFREQ_REQ ((uint16_t)6)
#define PLAYER_PLAYER_AUTH_REQ ((uint16_t)7)
The request subtypes


This interface accepts no commands.


This interface accepts no commands.

Configuration: Get device list

struct player_device_id : A device identifier; devices are differentiated internally in Player by these identifiers, and some messages contain them.

uint16_t code;
The interface provided by the device

uint16_t index;
The index of the device

uint16_t port;
The TCP port of the device (only useful with Stage)

struct player_device_devlist : Get the list of available devices from the server. It's useful for applications such as viewer programs and test suites that tailor behave differently depending on which devices are available. To request the list, set the subtype to PLAYER_PLAYER_DEVLIST_REQ and leave the rest of the fields blank. Player will return a packet with subtype PLAYER_PLAYER_DEVLIST_REQ with the fields filled in.

uint16_t subtype;

uint16_t device_count;
The number of devices

player_device_id_t devices[PLAYER_MAX_DEVICES];
The list of available devices.

Configuration: Get driver name

struct player_device_driverinfo : Get the driver name for a particular device. To get a name, set the subtype to PLAYER_PLAYER_DRIVERINFO_REQ and set the id field. Player will return the driver info.

uint16_t subtype;

player_device_id_t id;
The device identifier.

The driver name (returned)

Configuration: Request device access

struct player_device_req : This is the most important request! Before interacting with a device, the client must request appropriate access. The format of this request is:

uint16_t subtype;
Subtype; must be PLAYER_PLAYER_DEV_REQ

uint16_t code;
The interface for the device

uint16_t index;
The index for the device

uint8_t access;
The requested access

struct player_device_resp : The format of the server's reply is:

uint16_t subtype;
Subtype; will be PLAYER_PLAYER_DEV_REQ

uint16_t code;
The interface for the device

uint16_t index;
The index for the device

uint8_t access;
The granted access

uint8_t driver_name[PLAYER_MAX_DEVICE_STRING_LEN];
The name of the underlying driver

The access codes, which are used in both the request and response, are given above. Read access means that the server will start sending data from the specified device. For instance, if read access is obtained for the sonar device Player will start sending sonar data to the client. Write access means that the client has permission to control the actuators of the device. There is no locking mechanism so different clients can have concurrent write access to the same actuators. All access is both of the above and finally close means that there is no longer any access to the device. Device request messages can be sent at any time, providing on the fly reconfiguration for clients that need different devices depending on the task at hand.
Of course, not all of the access codes are applicable to all devices; for instance it does not make sense to write to the sonars. However, a request for such access will not generate an error; rather, it will be granted, but any commands actually sent to that device will be ignored. In response to such a device request, the server will send a reply indicating the actual access that was granted for the device. The granted access may be different from the requested access; in particular, if there was some error in initializing the device the granted access will be 'e', and the client should not try to read from or write to the device.

Configuration: Request data

struct player_device_data_req : When the server is in a pull data delivery mode (see next request for information on data delivery modes), the client can request a single round of data by sending a zero-argument request with type code 0x0003. The response will be a zero-length acknowledgement.

uint16_t subtype;

Configuration: Change data delivery mode

struct player_device_datamode_req : The Player server supports four data modes, described above. By default, the server operates in PLAYER_DATAMODE_PUSH_NEW mode at a frequency of 10Hz. To switch to a different mode send a request with the format given below. The server's reply will be a zero-length acknowledgement.

uint16_t subtype;

uint8_t mode;
The requested mode

Configuration: Change data delivery frequency

struct player_device_datafreq_req : By default, the fixed frequency for the push data delivery modes is 10Hz; thus a client which makes no configuration changes will receive sensor data approximately every 100ms. The server can send data faster or slower; to change the frequency, send a request of the format:

uint16_t subtype;

uint16_t frequency;
requested frequency in Hz

Configuration: Authentication

struct player_device_auth_req : If server authentication has been enabled (by providing -key <key> on the command-line; see Section 2.2), then each client must authenticate itself before otherwise interacting with the server. To authenticate, send a request of the format:

uint16_t subtype;

uint8_t auth_key[PLAYER_KEYLEN];
The authentication key

If the key matches the server's key then the client is authenticated, the server will reply with a zero-length acknowledgement, and the client can continue with other operations. If the key does not match, or if the client attempts any other server interactions before authenticating, then the connection will be closed immediately. It is only necessary to authenticate each client once.
Note that this support for authentication is NOT a security mechanism. The keys are always in plain text, both in memory and when transmitted over the network; further, since the key is given on the command-line, there is a very good chance that you can find it in plain text in the process table (in Linux try ps -ax | grep player). Thus you should not use an important password as your key, nor should you rely on Player authentication to prevent bad guys from driving your robots (use a firewall instead). Rather, authentication was introduced into Player to prevent accidentally connecting one's client program to someone else's robot. This kind of accident occurs primarily when Stage is running in a multi-user environment. In this case it is very likely that there is a Player server listening on port 6665, and clients will generally connect to that port by default, unless a specific option is given. Check the Stage documentation for how to specify a Player authentication key in your .world file.

struct player_device_nameservice_req : Documentation about nameservice goes here

uint16_t subtype;

The robot name

uint16_t port;
The corresponding port

next up previous contents
Next: 6.2 null Up: 6. Device Interfaces Previous: 6. Device Interfaces   Contents