<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<!-- $Id: header.html 8799 2010-06-28 04:12:42Z jpgr87 $ -->
<HEAD>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=utf-8">
<meta name="keywords" content="stage, robot, simulation, player, player/stage">
<link href="doxygen.css" rel="stylesheet" type="text/css">
<style type="text/css">
.floatright { float: right; margin: 0 0 1em 1em; }
body {
font-family: sans-serif;
#font-family: Geneva, Verdana, Helvetica, Arial, sans-serif;
background-color: #FFF;
color:#000;
}
a:link {
color: #A00;
}
a:visited {
color: #800;
}
a { text-decoration: none; }
a:hover { text-decoration: underline; }
.timestamp { text-align:right; background-color: #DDD; font-size:75%;}
h1 {
font-size:160%;
}
h2 {
font-size:110%;
#color: #FFF;
#background-color: #666;
#padding:3px;
}
h3 { text-align:left; }
img {
border: 0;
}
ul.menu {
position:relative;
left:-2.5em;
margin-bottom:0px;
margin-top:0px;
}
ul.menu1 {
position:relative;
left:-2.1em;
margin-bottom:0px;
margin-top:0px;
}
li.menu {
list-style-type: none;
position:relative;
#left:-0.5em;
}
#sidebar { position: absolute; left:0px; padding:2em; top:0em; width:12em;}
#content { position: absolute; left:12em; top:0em; padding-left:3em; padding-right:3em; padding-bottom:2em; margin-top:1em; margin-right:2em; }
div.box { background-color:#EEE; border: 1px solid #000; padding: 0.5ex 0.4em 0.5ex 0.6em; margin:1em; }
div.title { font-weight:bold; background-color:#eee; margin-bottom:2px;}
div.topbar { position: absolute; top:0px; left:9em; margin:1em; }
</style>
<TITLE>Player Manual</TITLE>
</HEAD>
<body>
<div id="sidebar">
<h2 style="text-align:center;">
<a href="index.html">
<img width=140 src="http://playerstage.sourceforge.net/images/player_button_v3.png" alt="Player logo"><br></a>
</h2>
<div class="box">
<div class=title>Player</div>
<ul class=menu>
<li class=menu><a href="index.html">Frontpage</a>
<li class=menu><a href="modules.html">Contents</a>
</ul>
</div>
<div class="box">
<div class=title>User</div>
<ul class=menu>
<li class=menu><a href="install.html">Installation</a>
<li class=menu><a href="start.html">Quick start</a>
<li class=menu><a href="supported_hardware.html">Supported devices</a>
<li class=menu><a href="group__tutorials.html">Tutorials</a>
<li class=menu><a href="group__utils.html">Utilities</a>
<li class=menu><a href="group__clientlibs.html">Client libraries</a>
<li class=menu><a href="http://playerstage.sourceforge.net/wiki/Basic_FAQ">FAQ</a>
<li class=menu><a href="help.html">Help</a>
</ul>
</div>
<div class=box>
<div class="title">Developer</div>
<ul class=menu>
<li class=menu><a href="architecture.html">Architecture</a>
<li class=menu><a href="group__libplayercore.html">libplayercore</a>
<ul class=menu1>
<li class=menu><a href="group__interfaces.html">interfaces</a></li>
</ul>
<li class=menu><a href="group__libplayerdrivers.html">libplayerdrivers</a>
<ul class=menu1>
<li class=menu><a href="group__drivers.html">drivers</a></li>
</ul>
<li class=menu><a href="group__libplayercommon.html">libplayercommon</a>
<li class=menu><a href="group__libplayerutils.html">libplayerutils</a>
<li class=menu><a href="group__libplayersd.html">libplayersd</a>
<li class=menu><a href="group__libplayertcp.html">libplayertcp</a>
<li class=menu><a href="group__libplayerxdr.html">libplayerxdr</a>
<li class=menu><a href="todo.html">TODO</a>
</ul>
</div>
<div class=box>
<!-- <a href="http://sourceforge.net"><img border=0 src="http://sourceforge.net/sflogo.php?group_id=42445&type=1"></a> -->
<div class="title">Online</div>
<a href="http://playerstage.sourceforge.net">Homepage</a><br>
<a href="http://sourceforge.net/project/showfiles.php?group_id=42445">Download</a><br>
<a href="http://sourceforge.net/projects/playerstage">Project</a><br>
<a href="http://sourceforge.net/tracker/?group_id=42445">Bugs</a><br>
<a href="http://sourceforge.net/mail/?group_id=42445">Help</a>
</div>
</div>
<div id="content" >
<!-- Generated by Doxygen 1.7.1 -->
<div class="header">
<div class="headertitle">
<h1>libplayerc example<br/>
<small>
[<a class="el" href="group__player__clientlib__libplayerc.html">libplayerc</a>]</small>
</h1> </div>
</div>
<div class="contents">
<p>An example.
<a href="#_details">More...</a></p>
<table class="memberdecls">
</table>
<p>An example. </p>
<p>libplayerc is based on a device <em>proxy</em> 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 <a class="el" href="group__interface__position2d.html">position2d</a> and <a class="el" href="group__interface__laser.html">laser</a> devices. There is also a special <code>client</code> proxy, used to control the Player server itself.</p>
<p>Programs using libplayerc will generally have the following structure:</p>
<div class="fragment"><pre class="fragment"></pre></div><p>This example can be built using the command: </p>
<pre>
$ gcc -o simpleclient `pkg-config --cflags playerc` simpleclient.c `pkg-config --libs playerc`
</pre><p>Make sure that <code>libplayerc</code> is installed somewhere that pkg-config can find it.</p>
<p>The above program can be broken into six steps, as follows.</p>
<ul>
<li>
<p class="startli">Create and connect a client proxy.</p>
<p></p>
<pre>
client = playerc_client_create(NULL, "localhost", 6665);
playerc_client_connect(client);
</pre><p> The <code>create</code> function creates a new client proxy and returns a pointer to be used in future function calls (<code>localhost</code> should be replaced with the network host name of the robot). The <code>connect</code> function notifies the Player server that a new client wishes to recieve data.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Create and subscribe a device proxy.</p>
<p></p>
<pre>
position2d = playerc_position2d_create(client, 0);
playerc_position2d_subscribe(position2d, PLAYERC_OPEN_MODE);
</pre><p> The <code>create</code> function creates a new position2d device proxy and returns a pointer to be used in future function calls. The <code>subscribe</code> 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 (<code>PLAYERC_OPEN_MODE</code>).</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Configure the device, send commands.</p>
<p></p>
<pre>
playerc_position2d_enable(position2d, 1);
playerc_position2d_set_speed(position2d, 0, 0, 0.1);
</pre><p> The <code>enable</code> function sends a configuration request to the server, changing the robot's motor state from <code>off</code> to <code>on</code>, thereby allowing the robot to move. The <code>setspeed</code> function sends a new motor speed, in this case commanding the robot to turn on the spot.</p>
<p></p>
<p>Note that most Player devices will accept both asynchronous <em>command</em> and synchronous <em>configuration</em> requests. Sending commands is analogous using the standard Unix <code>write</code> device interface, while sending configuration requests is analogous to using the <code>ioctl</code> interface. For the most part, <code>libplayerc</code> 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Read data from the device.</p>
<p></p>
<pre>
playerc_client_read(client);
printf("position : %f %f %f\n", position2d->px, ... );
</pre><p> The <code>read</code> 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 <code>read</code> 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.</p>
<p>In pull mode read will process a full set of messages from the server, in push mode read will process a single message.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Unsubscribe and destroy the device proxy.</p>
<p></p>
<pre>
playerc_position2d_unsubscribe(position2d);
playerc_position2d_destroy(position2d);
</pre><p> The <code>unsubscribe</code> function tells the Player server that the client is no longer using this device. The <code>destroy</code> function then frees the memory associated with the device proxy; the <code>device</code> pointer is now invalid and should be not be re-used.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Disconnect and destroy the client proxy.</p>
<p></p>
<pre>
playerc_client_disconnect(client);
playerc_client_destroy(client);
</pre><p> The <code>disconnect</code> function tells the server that the client is shutting down. The <code>destroy</code> function then frees the memory associated with the client proxy; the <code>client</code> pointer is now invalid and should be not be re-used.</p>
<p class="endli"></p>
</li>
</ul>
</div>
<!-- render the modification time of the source file -->
<div class="timestamp">
<hr>
<table style="width:100%;">
<tr>
<td style="text-align:left;">
Last updated 12 September 2005 21:38:45
<!--
<td style="text-align:right;">
<a href="http://validator.w3.org/check/referer"><img style="vertical-align:middle;border:0;width:88px;height:31px"
src="http://www.w3.org/Icons/valid-html401"
alt="Valid HTML 4.01!"></a>
<a href="http://jigsaw.w3.org/css-validator/">
<img style="vertical-align:middle;border:0;width:88px;height:31px"
src="http://jigsaw.w3.org/css-validator/images/vcss"
alt="Valid CSS!">
</a>
-->
</tr>
</table>
</div>
</tr>
</table>
</BODY>
</HTML>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
727fa15453fcace956b835e2377d4269
>
files
>
723
