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_WRITE_MODE 'w' #define PLAYER_ALL_MODE 'a' #define PLAYER_CLOSE_MODE 'c' #define PLAYER_ERROR_MODE 'e' |
The device access modes
|
#define PLAYER_DATAMODE_PUSH_ALL 0
#define PLAYER_DATAMODE_PULL_ALL 1 #define PLAYER_DATAMODE_PUSH_NEW 2 #define PLAYER_DATAMODE_PULL_NEW 3 |
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) #define PLAYER_PLAYER_NAMESERVICE_REQ ((uint16_t)8) |
The request subtypes
This interface accepts no commands.
This interface accepts no commands.
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; |
Subtype; must be PLAYER_PLAYER_DEVLIST_REQ.
| uint16_t device_count; |
The number of devices
| player_device_id_t devices[PLAYER_MAX_DEVICES]; |
The list of available devices.
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; |
Subtype; must be PLAYER_PLAYER_DRIVERINFO_REQ.
| player_device_id_t id; |
The device identifier.
| char driver_name[PLAYER_MAX_DEVICE_STRING_LEN]; |
The driver name (returned)
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.
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; |
Subtype; must be PLAYER_PLAYER_DATA_REQ
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; |
Subtype; must be PLAYER_PLAYER_DATAMODE_REQ
| uint8_t mode; |
The requested mode
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; |
Subtype; must be PLAYER_PLAYER_DATAFREQ_REQ
| uint16_t frequency; |
requested frequency in Hz
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; |
Subtype; must by PLAYER_PLAYER_AUTH_REQ
| 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; |
Subtype; must by PLAYER_PLAYER_NAMESERVICE_REQ
| uint8_t name[PLAYER_MAX_DEVICE_STRING_LEN]; |
The robot name
| uint16_t port; |
The corresponding port