/** @addtogroup clientlibs Client Libraries */ /** @{ */ /** @defgroup player_clientlib_libplayerc libplayerc libplayerc is a client library for the Player robot device server. It is written in C to maximize portability, and in the expectation that users will write bindings for other languages (such as Python and Java) against this library; @ref player_clientlib_libplayerc_py "Python bindings" are already available. @section libplayerc_usage General usage libplayerc is based on a device proxy model, in which the client maintains a local proxy for each of the devices on the remote server. Thus, for example, one can create local proxies for the `position` and `laser` devices. There is also a special `client` proxy, used to control the Player server itself. Programs using libplayerc will generally have the following structure: @include simpleclient.c.doc This example can be built using the commands:

    $ gcc -c simple.c -o simple.o
    $ gcc -lm -lplayerc simple.o -o simple

Make sure that `playerc.h` is installed somewhere in you include path, and that `libplayerc.a` is in your library path.

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);

  The `create` 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). The `connect` function notifies the Player server that a new client wishes to recieve data.
- Create and subscribe a device proxy.

      position = playerc_position_create(client, 0);
      playerc_position_subscribe(position, PLAYER_ALL_MODE);

  The `create` function creates a new position device proxy and returns a pointer to be used in future function calls. The `subscribe` function notifies the Player server that the client is using the position device, and that the client expects to both send commands and recieve data (`PLAYER_MODE_ALL`).
- Configure the device, send commands.

      playerc_position_enable(position, 1);
      playerc_position_set_speed(position, 0, 0, 0.1);

  The `enable` function sends a configuration request to the server, changing the robot's motor state from `off` to `on`, thereby allowing the robot to move. The `setspeed` 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 the `ioctl` 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", position->px, ... );

  The `read` 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). The `read` 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_position_unsubscribe(position);
      playerc_position_destroy(position);

  The `unsubscribe` function tells the Player server that the client is no longer using this device. The `destroy` function then frees the memory associated with the device proxy; the `device` 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);

  The `disconnect` function tells the server that the client is shutting down. The `destroy` function then frees the memory associated with the client proxy; the `client` pointer is now invalid and should be not be re-used.

@section libplayerc_ref Proxy reference Detailed information for each proxy can be found in the Reference section. */