libplayerc example
[libplayerc]
Collaboration diagram for libplayerc example:
client
proxy, used to control the Player server itself.Programs using libplayerc will generally have the following structure:
#include <stdio.h> #include <libplayerc/playerc.h> int main(int argc, const char **argv) { int i; playerc_client_t *client; playerc_position2d_t *position2d; // Create a client object and connect to the server; the server must // be running on "localhost" at port 6665 client = playerc_client_create(NULL, "localhost", 6665); if (playerc_client_connect(client) != 0) { fprintf(stderr, "error: %s\n", playerc_error_str()); return -1; } // Create a position2d proxy (device id "position2d:0") and susbscribe // in read/write mode position2d = playerc_position2d_create(client, 0); if (playerc_position2d_subscribe(position2d, PLAYERC_OPEN_MODE) != 0) { fprintf(stderr, "error: %s\n", playerc_error_str()); return -1; } // Enable the robots motors playerc_position2d_enable(position2d, 1); // Start the robot turning slowing playerc_position2d_set_cmd_vel(position2d, 0, 0, 0.1, 1); for (i = 0; i < 200; i++) { // Read data from the server and display current robot position playerc_client_read(client); printf("position : %f %f %f\n", position2d->px, position2d->py, position2d->pa); } // Shutdown and tidy up playerc_position2d_unsubscribe(position2d); playerc_position2d_destroy(position2d); playerc_client_disconnect(client); playerc_client_destroy(client); return 0; }
This example can be built using the command:
$ gcc -o simpleclient `pkg-config --cflags playerc` simpleclient.c `pkg-config --libs playerc`
Make sure that libplayerc
is installed somewhere that pkg-config can find it.
The above program can be broken into six steps, as follows.
-
Create and connect a client proxy.
client = playerc_client_create(NULL, "localhost", 6665); playerc_client_connect(client);
Thecreate
function creates a new client proxy and returns a pointer to be used in future function calls (localhost
should be replaced with the network host name of the robot). Theconnect
function notifies the Player server that a new client wishes to recieve data. -
Create and subscribe a device proxy.
position2d = playerc_position2d_create(client, 0); playerc_position2d_subscribe(position2d, PLAYERC_OPEN_MODE);
Thecreate
function creates a new position2d device proxy and returns a pointer to be used in future function calls. Thesubscribe
function notifies the Player server that the client is using the position2d device, and that the client expects to both send commands and recieve data (PLAYERC_OPEN_MODE
). -
Configure the device, send commands.
playerc_position2d_enable(position2d, 1); playerc_position2d_set_speed(position2d, 0, 0, 0.1);
Theenable
function sends a configuration request to the server, changing the robot's motor state fromoff
toon
, thereby allowing the robot to move. Thesetspeed
function sends a new motor speed, in this case commanding the robot to turn on the spot.Note that most Player devices will accept both asynchronous command and synchronous configuration requests. Sending commands is analogous using the standard Unix
write
device interface, while sending configuration requests is analogous to using theioctl
interface. For the most part,libplayerc
hides the distinction between these two interfaces. Users should be aware, however, that while commands are always handled promptly by the server, configuration requests may take significant time to complete. If possible, configuration requests should therefore be restricted to the initialization phase of the program. -
Read data from the device.
playerc_client_read(client); printf("position : %f %f %f\n", position2d->px, ... );
Theread
function blocks until new data arrives from the Player server. This data may be from one of the subscribed devices, or it may be from the server itself (which sends regular synchronization messages to all of its clients). Theread
function inspects the incoming data and automatically updates the elements in the appropriate device proxy. This function also returns a pointer to the proxy that was updated, so that user programs may, if desired, trigger appropriate events on the arrival of different kinds of data. -
Unsubscribe and destroy the device proxy.
playerc_position2d_unsubscribe(position2d); playerc_position2d_destroy(position2d);
Theunsubscribe
function tells the Player server that the client is no longer using this device. Thedestroy
function then frees the memory associated with the device proxy; thedevice
pointer is now invalid and should be not be re-used. -
Disconnect and destroy the client proxy.
playerc_client_disconnect(client); playerc_client_destroy(client);
Thedisconnect
function tells the server that the client is shutting down. Thedestroy
function then frees the memory associated with the client proxy; theclient
pointer is now invalid and should be not be re-used.