doc/orte/orte_usage.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <section id="orte-usage">
   3   <title>ORTE Usage Information</title>
   4
   5   <section id="orte-installation">
   6     <title>Installation and Setup</title>
   7
   8     <para>
   9     In this chapter is described basic steps how to makes installation
  10     and setup process of the ORTE. The process includes next steps:
  11     </para>
  12
  13     <para>
  14       <orderedlist>
  15         <listitem><para>Downloading the ORTE distribution</para></listitem>
  16         <listitem><para>Compilation</para></listitem>
  17         <listitem><para>Installing the ORTE library and utilities</para></listitem>
  18         <listitem><para>Testing the installation</para></listitem>
  19       </orderedlist>
  20     </para>
  21
  22     <para><phrase role="strong">Note:</phrase></para>
  23     <para>
  24     On windows systems we are recommend to use Mingw or Cygwin systems. The
  25     ORTE support also MSVC compilation, but this kind of installation is not
  26     described here.
  27     </para>
  28     <section id="orte-installation-downloading">
  29       <title>Downloading </title>
  30
  31        <para>
  32         The ORTE component can be obtained from OCERA SourceForge web page
  33         (<ulink url="http://www.sf.net/projects/ocera/"></ulink>). Here is the component
  34         located also in self distribution branch as well as in OCERA distribution.
  35         Before developing any application check if there is a new file release.
  36        </para>
  37        <para>
  38         The CVS version of ORTE repository can be checked out be anonymous (pserver)
  39         CVS with the following commands.
  40          <programlisting>
  41 cvs -d:pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera login
  42 cvs -z3 -d:pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera co ocera/components/comm/eth/orte/
  43          </programlisting>
  44         Attention, there is developing version and can't be stable!
  45        </para>
  46     </section>
  47
  48     <section id="orte-installation-compilation">
  49       <title>Compilation</title>
  50         <para>
  51         Before the compilation process is necessary to prepare the source.
  52         Create a new directory for ORTE distribution. We will assume name of this
  53         directory <filename>/orte</filename> for Linux case. Copy or move downloaded
  54         ORTE sources to <filename>/orte</filename> (assume the name of sources
  55         <filename>orte-0.2.3.tar.gz</filename>). Untar and unzip this files by using
  56         next commands:
  57         <programlisting>
  58 gunzip orte-0.2.3.tar.gz
  59 tar xvf orte-0.2.3.tar
  60         </programlisting>
  61         Now is the source prepared for compilation. Infrastructure of the ORTE is
  62         designed to support GNU make (needs version 3.81) as well as autoconf compilation. In
  63         next we will continue with description of autoconf compilation, which is more
  64         general. The compilation can follows with commands:
  65         <programlisting>
  66 mkdir build
  67 cd build
  68 ../configure
  69 make
  70         </programlisting>
  71         This is the case of outside autoconf compilation. In directory <filename>build</filename>
  72         are all changes made over ORTE project. The source can be easy move to original
  73         state be removing of directory <filename>build</filename>.
  74         </para>
  75     </section>
  76
  77     <section id="orte-installation-installing">
  78        <title>Installing</title>
  79
  80        <para>
  81        The result of compilation process are binary programs and ORTE library. For the
  82        next developing is necessary to install this result. It can be easy done be typing:
  83        <programlisting>
  84 make install
  85        </programlisting>
  86        All developing support is transferred into directories with direct access of
  87        design tools.
  88        </para>
  89        <informaltable frame='none'>
  90           <tgroup cols='2'>
  91           <colspec align="left" colwidth="1*"/>
  92           <colspec align="left" colwidth="1*"/>
  93           <thead>
  94           <row>
  95             <entry align="center">name</entry>
  96             <entry align="center">target path</entry>
  97           </row>
  98           </thead>
  99           <tbody>
 100           <row><entry>ortemanager, orteping, ortespy</entry>
 101                <entry><filename>/usr/local/bin</filename></entry></row>
 102           <row><entry>library</entry>
 103                <entry><filename>/usr/local/lib</filename></entry></row>
 104           <row><entry>include</entry>
 105                <entry><filename>/usr/local/include</filename></entry></row>
 106           </tbody>
 107           </tgroup>
 108        </informaltable>
 109        <para>
 110        The installation prefix <filename>/usr/local/</filename> can be changed
 111        during configuration. Use command <command>../configure --help</command> for
 112        check more autoconf options.
 113        </para>
 114     </section>
 115
 116     <section id="orte-installation-testing">
 117        <title>Testing the Installation</title>
 118
 119        <para>
 120        To check of correct installation of ORTE open three shells.
 121        </para>
 122
 123        <para>
 124         <orderedlist>
 125           <listitem>
 126             <para>In first shell type</para>
 127             <programlisting>ortemanager</programlisting>
 128           </listitem>
 129           <listitem>
 130             <para>In second shell type</para>
 131             <programlisting>orteping -s</programlisting>
 132             <para>
 133             This command will invoked creation of a subscription. You should see:
 134             </para>
 135             <programlisting>
 136 deadline occurred
 137 deadline occurred
 138 ...
 139             </programlisting>
 140           </listitem>
 141           <listitem>
 142             <para>In third shell type</para>
 143             <programlisting>orteping -p</programlisting>
 144             <para>
 145             This command will invoked creation of a publication. You should see:
 146             </para>
 147             <programlisting>
 148 sent issue 1
 149 sent issue 2
 150 sent issue 3
 151 sent issue 4
 152 ...
 153             </programlisting>
 154             <para>
 155             If the ORTE installation is properly, you will see incoming messages
 156             in second shell (<command>orteping -s</command>).
 157             </para>
 158             <programlisting>
 159 received fresh issue 1
 160 received fresh issue 2
 161 received fresh issue 3
 162 received fresh issue 4
 163 ...
 164             </programlisting>
 165             <para>
 166             It's sign, that communication is working correctly.
 167             </para>
 168           </listitem>
 169         </orderedlist>
 170       </para>
 171
 172     </section>
 173   </section>
 174
 175   <section id="orte-manager">
 176     <title>The ORTE Manager</title>
 177
 178     <para>
 179     A manager is special application that helps
 180     applications automatically discover each other on the Network.
 181     Each time an object is created or destroyed, the manager
 182     propagate new information to the objects that are internally
 183     registered.
 184     </para>
 185     <para>
 186     Every application precipitate in communication is managed by least
 187     one manager. The manager should be designed like separated application
 188     as well as part of designed application.
 189     </para>
 190
 191     <figure id="cap:orte_managers_img">
 192       <title>Position of Managers in RTPS communication
 193       </title>
 194       <mediaobject>
 195         <imageobject>
 196           <imagedata align="center" fileref="&orte_managers_img;"
 197             format="EPS" scale="35" srccredit="OCERA CTU 2004" />
 198         </imageobject>
 199       </mediaobject>
 200     </figure>
 201
 202     <para>
 203     The ORTE provides one instance of a manager. Name of this utility
 204     is <filename>ortemanager</filename> and is located
 205     in directory <filename>orte/ortemanager</filename>. Normally is necessary to
 206     start <filename>ortemanager</filename> manually or use a script on
 207     UNIX systems. For Mandrake and Red-hat distribution is this script created
 208     in subdirectory <filename>rc</filename>. Windows
 209     users can install <filename>ortemanager</filename> like service by
 210     using option <parameter class='option'>/install_service</parameter>.
 211     </para>
 212     <para><phrase role="strong">Note:</phrase></para>
 213     <para>
 214     Don't forget to run a manager (ortemanager) on each RTPS participate node.
 215     During live of applications is necessary to be running this manager.
 216     </para>
 217
 218     <section id="orte-manager-example">
 219       <title>Example of Usage ortemanager</title>
 220
 221       <para>
 222       Each manager has to know where are other managers in the network.
 223       Their IP addresses are therefore specified as IPAddressX parameters of
 224       ortemanager. All managers participate in one kind of communication use
 225       the same domain number. The domain number is transferred to port number by
 226       equation defined in RTPS specification (normally domain 0 is transferred to
 227       7400 port).
 228       </para>
 229       <para>
 230       Let's want to distribute the RTPS communication of nodes with IP addresses
 231       192.168.0.2 and 192.168.0.3. Private IP address is 192.168.0.1.
 232       The ortemanager can be execute with parameters:
 233       </para>
 234       <programlisting>
 235 ortemanager -p 192.168.0.2:192.168.0.3
 236       </programlisting>
 237       <para>
 238       To communicate in different domain use (parameter -d):
 239       </para>
 240       <programlisting>
 241 ortemanager -d 1 -p 192.168.0.2:192.168.0.3
 242       </programlisting>
 243       <para>
 244       Very nice feature of ortemanager is use event system to inform
 245       of creation/destruction objects (parameter -e).
 246       </para>
 247       <programlisting>
 248 ortemanager -e -p 192.168.0.2:192.168.0.3
 249       </programlisting>
 250       <para>
 251       Now, you can see messages:
 252       </para>
 253       <programlisting>
 254 [smolik@localhost smolik]$ortemanager -e -p 192.168.0.2:192.168.0.3
 255 manager 0xc0a80001-0x123402 was accepted
 256 application 0xc0a80002-0x800301 was accepted
 257 application 0xc0a80002-0x800501 was accepted
 258 application 0xc0a80002-0x800501 was deleted
 259 manager 0xc0a80001-0x123402 was deleted
 260       </programlisting>
 261
 262       &orte_ortemanager;
 263     </section>
 264   </section>
 265
 266   <section id="orte-utils">
 267     <title>Simple Utilities</title>
 268       <para>
 269       The simple utilities can be found in the <filename>orte/examples</filename>
 270       subdirectory of the ORTE source subtree. These utilities are useful
 271       for testing and monitoring RTPS communication.
 272       </para>
 273
 274       <para>
 275       The utilities provided directly by ORTE are:
 276       </para>
 277
 278       <variablelist>
 279         <varlistentry>
 280           <term>orteping</term>
 281
 282           <listitem>
 283             <para>the utility for easy creating of publications and subscriptions.
 284             </para>
 285           </listitem>
 286         </varlistentry>
 287
 288         <varlistentry>
 289           <term>ortespy</term>
 290
 291           <listitem>
 292             <para>monitors issues produced by other application in specific domain.
 293             </para>
 294           </listitem>
 295         </varlistentry>
 296
 297       </variablelist>
 298
 299     &orte_orteping;
 300     &orte_ortespy;
 301
 302   </section>
 303 </section>