Home FAQ Player Stage Gazebo Contrib Documentation Publications Contributors Users Project Download Bugs/Feedback Mailing lists Radish Old news Old stuff

player [Interfaces] Detailed Description The player device represents the server itself, and is used in configuring the behavior of the server. There is only one such device (with index 0) and it is always open. This device produces no data and accepts no commands. Classes struct   player_device_id   A device identifier. More... struct   player_device_devlist   Configuration request: Get the list of available devices. More... struct   player_device_driverinfo   Configuration request: Get the driver name for a particular device. More... struct   player_device_req   Configuration request: Get device access. More... struct   player_device_resp   The format of the server's reply to a PLAYER_PLAYER_DEV_REQ request. More... struct   player_device_data_req   Configuration request: Get data. More... struct   player_device_datamode_req   Configuration request: Change data delivery mode. More... struct   player_device_datafreq_req   Configuration request: Change data delivery frequency. More... struct   player_device_auth_req   Configuration request: Authentication. More... struct   player_device_nameservice_req Defines #define  PLAYER_READ_MODE   114 #define  PLAYER_WRITE_MODE   119 #define  PLAYER_ALL_MODE   97 #define  PLAYER_CLOSE_MODE   99 #define  PLAYER_ERROR_MODE   101 #define  PLAYER_DATAMODE_PUSH_ALL   0 #define  PLAYER_DATAMODE_PULL_ALL   1 #define  PLAYER_DATAMODE_PUSH_NEW   2 #define  PLAYER_DATAMODE_PULL_NEW   3 #define  PLAYER_DATAMODE_PUSH_ASYNC   4 #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) Typedefs typedef player_device_id  player_device_id_t   A device identifier. typedef player_device_devlist  player_device_devlist_t   Configuration request: Get the list of available devices. typedef player_device_driverinfo  player_device_driverinfo_t   Configuration request: Get the driver name for a particular device. typedef player_device_req  player_device_req_t   Configuration request: Get device access. typedef player_device_resp  player_device_resp_t   The format of the server's reply to a PLAYER_PLAYER_DEV_REQ request. typedef player_device_data_req  player_device_data_req_t   Configuration request: Get data. typedef player_device_datamode_req  player_device_datamode_req_t   Configuration request: Change data delivery mode. typedef player_device_datafreq_req  player_device_datafreq_req_t   Configuration request: Change data delivery frequency. typedef player_device_auth_req  player_device_auth_req_t   Configuration request: Authentication. typedef player_device_nameservice_req  player_device_nameservice_req_t Define Documentation #define PLAYER_READ_MODE   114 #define PLAYER_WRITE_MODE   119 #define PLAYER_ALL_MODE   97 #define PLAYER_CLOSE_MODE   99 #define PLAYER_ERROR_MODE   101 #define PLAYER_DATAMODE_PUSH_ALL   0   Data delivery mode: Send data at a fixed rate (default 10Hz; see PLAYER_PLAYER_DATAFREQ_REQ below to change the rate) from ALL subscribed devices , regardless of whether the data is new or old. A PLAYER_MSGTYPE_SYNCH packet follows each set of data. Rarely used. #define PLAYER_DATAMODE_PULL_ALL   1   Data delivery mode: Only on request (see PLAYER_PLAYER_DATA_REQ request below), send data from ALL subscribed devices, regardless of whether the data is new or old. A PLAYER_MSGTYPE_SYNCH packet follows each set of data. Rarely used. #define PLAYER_DATAMODE_PUSH_NEW   2   Data delivery mode: Send data at a fixed rate (default 10Hz; see PLAYER_PLAYER_DATAFREQ_REQ below to change the rate) only from those subscribed devices that have produced new data since the last time data was pushed to this client. A PLAYER_MSGTYPE_SYNCH packet follows each set of data. This is the default mode. #define PLAYER_DATAMODE_PULL_NEW   3   Data delivery mode: Only on request (see PLAYER_PLAYER_DATA_REQ request below), send data only from those subscribed devices that have produced new data since the last time data was pushed to this client. Use this mode if your client runs slowly or at an upredictable rate (e.g., a GUI). A PLAYER_MSGTYPE_SYNCH packet follows each set of data. #define PLAYER_DATAMODE_PUSH_ASYNC   4   Data delivery mode: When a subscribed device produces new data, send it. This is the lowest-latency delivery mode; when a device produces data, the server (almost) immediately sends it on the client. So the client may receive data at an arbitrarily high rate. PLAYER_MSGTYPE_SYNCH packets are still sent, but at a fixed rate (see PLAYER_PLAYER_DATAFREQ_REQ to change this rate) that is unrelated to rate at which data are delivered from devices. #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) Typedef Documentation typedef struct player_device_id player_device_id_t   A device identifier. Devices are differentiated internally in Player by these identifiers, and some messages contain them. typedef struct player_device_devlist player_device_devlist_t   Configuration request: Get the list of available devices. 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. typedef struct player_device_driverinfo player_device_driverinfo_t   Configuration request: 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. typedef struct player_device_req player_device_req_t   Configuration request: Get device access. This is the most important request! Before interacting with a device, the client must request appropriate access. 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 error, and the client should not try to read from or write to the device. typedef struct player_device_resp player_device_resp_t   The format of the server's reply to a PLAYER_PLAYER_DEV_REQ request. typedef struct player_device_data_req player_device_data_req_t   Configuration request: Get data. When the server is in a PLAYER_DATAMODE_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. The client only needs to make this request when a PLAYER_DATAMODE_PULL_* mode is in use. typedef struct player_device_datamode_req player_device_datamode_req_t   Configuration request: Change data delivery mode. 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. typedef struct player_device_datafreq_req player_device_datafreq_req_t   Configuration request: Change data delivery frequency. 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 with this format. The server's reply will be a zero-length acknowledgement. typedef struct player_device_auth_req player_device_auth_req_t   Configuration request: Authentication. If server authentication has been enabled (by providing '-key <key>' on the command-line; see Command line options); then each client must authenticate itself before otherwise interacting with the server. To authenticate, send a request with this format. 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. This mechanism was never really used, and may be removed. typedef struct player_device_nameservice_req player_device_nameservice_req_t   Documentation about nameservice goes here.