userdoc_companion.dox

来自「一个语言识别引擎」· DOX 代码 · 共 558 行 · 第 1/2 页

/** 
 * @page yarp The standard YARP companion utility.

The command-line utility "yarp" performs a set of useful operations
for a YARP network.  It can give status information, make and break
connections between ports, and send/receive data to/from ports.
\if MAN_PAGE_COND
\else
Here are the ways you can call yarp:
- \ref yarp_base
- \ref yarp_help
- \ref yarp_version
- \ref yarp_where
- \ref yarp_conf
- \ref yarp_name
- \ref yarp_connect
- \ref yarp_disconnect
- \ref yarp_read
- \ref yarp_write
- \ref yarp_rpc
- \ref yarp_server
- \ref yarp_check
\endif

@section yarp_base yarp

The utility gives a friendly message if called with no arguments
to confirm that it exists, and to give tips on where to get started
using it.  Our current implementation says:

\verbatim
This is the YARP network companion.
Call with the argument "help" to see a list of ways to use this program.
\endverbatim


@section yarp_help yarp help

This lists a human-readable summary of the 
ways the utility can be used.  Our current implementation
says:

\verbatim
Here are arguments you can give this program:
help         get this list
version      get version information
where        report where the yarp name server is running
conf         report what configuration file is being used
name         send commands to the yarp name server
connect      create a connection between two ports
disconnect   remove a connection between two ports
read         read from the network and print to standard output
write        write to the network from standard input
rpc          read/write commands to a port, in standard format
server       run yarp name server
check        run a simple sanity check to see if yarp is working
\endverbatim

@section yarp_server yarp server

\verbatim
  yarp server
  yarp server SOCKETPORT
  yarp server IP SOCKETPORT
\endverbatim

This starts a name server running on the current machine, optionally
specifying the socket-port to listen to (default whatever was used in
the previous invocation, as recorded in a configuration file, or 10000
if this is the first time to run).
Also, the IP by which the name server should be identified can
optionally be specified (default is a fairly random choice of
the IPs associated with the current machine).

If possible, a fallback multi-cast server will be started with IP
224.2.1.1 and port number 10001.  The purpose of this server is 
to allow yarp processes to find the yarp name server in the absence
of correct configuration.


\section yarp_where yarp where


This will report where the name server is believed to be running; for 
example:

\verbatim
Name server is available at ip 15.255.112.22 port 10000
\endverbatim


\section yarp_conf yarp conf


This will report where the name server location is configured.
For the author's machine, the result is:
\verbatim
/home/paulfitz/.yarp/conf/yarp.conf
\endverbatim
If the YARP_CONF directory is set, this will be where the conf/yarp.conf
file is created/read.


@section yarp_check yarp check

Does some sanity tests of your setup.  If you run "yarp server" in
one terminal, and then run this command ("yarp check") in another,
you should see something like:

\verbatim
yarp: ==================================================================
yarp: === Trying to register some ports
yarp: ==================================================================
yarp: === Trying to connect some ports
yarp: Receiving input from /tmp/port/2 to /tmp/port/1 using tcp
yarp: Sending output from /tmp/port/2 to /tmp/port/1 using tcp
yarp: ==================================================================
yarp: === Trying to write some data
yarp: ==================================================================
yarp: === Trying to read some data
yarp: *** Read number 42
yarp: ==================================================================
yarp: === Trying to close some ports
yarp: Removing input from /tmp/port/2 to /tmp/port/1
yarp: Removing output from /tmp/port/2 to /tmp/port/1
yarp: *** YARP seems okay!
\endverbatim

\section yarp_version yarp version

This will report on the yarp version available.  Example:

\verbatim
YARP network version 2.0
\endverbatim


\section yarp_read yarp read

\verbatim
yarp read INPUT_PORT [envelope]
yarp read INPUT_PORT [envelope] OUTPUT_PORT
\endverbatim

This will create an input port of the specified name.  It will
then loop, 
reading ``yarp bottles'' (a simple serialized list) and printing their content
to standard output.  This simple utility is intended for use in testing, and
getting familiar with using YARP.

For example, if you run "yarp server" in one terminal, "yarp read
/read" in another, and "yarp write /write verbatim /read" in another,
then everything you type on the "write" terminal will be echoed on the
"read" terminal.

Specifying an OUTPUT_PORT tries to connect that port to the current one.

Adding the "envelope" tag will request display of any envelope information
included in the message, such as timestamps.  Such information may
or may not be present, and is ignored if you do not specify this tag.

\section yarp_write yarp write

\verbatim
yarp write OUTPUT_PORT [verbatim]
yarp write OUTPUT_PORT [verbatim] INPUT_PORT1 INPUT_PORT2 ...
\endverbatim

This will create an output port of the specified name.  It will then
loop, reading from standard input and writing yarp bottles.
Optionally, a list of input ports to connect to automatically can be
appended to the command.  This simple utility is intended for use in
testing, and getting familiar with using YARP.

If the "verbatim" keyword is included after the OUTPUT_PORT name,
then input from standard input will be transmitted as a string,
rather than as a bottle.  This will preserve the exact text
with whitespace and quoting.  Otherwise the input is interpreted
as a list of values that are transmitted in a standard network
format that will not preserve whitespace, quoting, and other
features.

For example, if you run "yarp server" in one terminal, "yarp read
/read" in another, and "yarp write /write verbatim /read" in another,
then everything you type on the "write" terminal will be echoed on the
"read" terminal.


\section yarp_rpc yarp rpc

\verbatim
yarp rpc TARGET_PORT
yarp rpc TARGET_PORT CONNECTION_NAME
\endverbatim

This will send a message to the target port and expect a response.
Useful only if you have a port that actually will respond.  Ports
associated with devices may behave like this.  You may optionally
specify the name for the connection.  "RPC" stands for Remote
Procedure Call.


\section yarp_connect yarp connect

\verbatim
yarp connect OUTPUT_PORT INPUT_PORT
yarp connect OUTPUT_PORT INPUT_PORT CARRIER
\endverbatim

This will request the specified output port to send its output in 
future to the specified input port.
Optionally, the carrier to be used can be added as an extra argument
(e.g. tcp, udp, mcast, ...).

\section yarp_disconnect yarp disconnect

\verbatim
yarp disconnect OUTPUT_PORT INPUT_PORT
\endverbatim

This will request the specified output port to cease sending its output to
the specified input port.
















\section yarp_name yarp name

\verbatim
yarp name COMMAND ARG_1 ARG_2 ...
\endverbatim

This will send the given command and arguments to the YARP name server
and report the results.  Here are the possible commands:
\if MAN_PAGE_COND
\else
- \ref name_help
- \ref name_query
- \ref name_register
- \ref name_unregister
- \ref name_list
- \ref name_set
- \ref name_get
- \ref name_check
- \ref name_route
\endif

For example:
\verbatim
# user types...
yarp name list
   # system responds...
   registration name root ip 172.16.232.1 port 10000 type text
   registration name fallback ip 224.2.1.1 port 10001 type mcast
   registration name /read ip 172.16.232.1 port 10002 type tcp
   registration name /write ip 172.16.232.1 port 10012 type tcp
   *** end of message
\endverbatim

This is equivalent to:

\verbatim
# user types...
yarp where
   # system responds...
   Name server is available at ip 172.16.232.1 port 10000
# user types...