Most of the time, YARP ports are conduits for messages.
Users write messages to ports, and read messages from ports, and the ports themselves don't inspect the content of those messages.
In some cases, though, you may find yourself wishing to talk to a port itself, in order to query it about its state, or to request it to take some action (such as making or breaking a connection). There is a low level protocol for this, but it is somewhat arcane (see Port commands).
To send an administrative message to a port is simple. From the commandline, just use "yarp admin write" or "yarp admin rpc" instead of "yarp write" or "yarp rpc":
echo "listConnectionsIn" | yarp admin rpc /port_name
This will list all the inputs to the port /port_name.
From code, set the "admin" flag in yarp::os::Network::write, or call yarp::os::Port::setAdminMode. Messages can be read/written as regular yarp::os::Bottle objects. Nothing else is needed.
Here are the things you can do using the administrative interface:
help help $command
help lists all the available administration commands, while help $command gives the prototype and the description of the given command (its parameters and its reply). For instance:
echo "help addConnection" | yarp admin rpc /port_name
All the administration commands are defined in the thrift service PortCoreMsgs (src/libYARP_os/src/idl/PortCoreMsgs.thrift), and the descriptions given by help are the documentation comments of that file.
addConnection /port/name addConnection /port/name carrier
Add an output to the specified port, using a given carrier (tcp, udp, etc.). The carrier is optional.
delConnection /port/name
Remove any input or output connection involving the specified port.
The reply of both commands is ok success message, where success is fail if the connection could not be added/removed, and message is a human readable description of the result. From code, use the corresponding methods of yarp::os::impl::PortCoreClient, which return the structs yarp::os::return_addConnection and yarp::os::return_delConnection. The field ret of the returned struct is false if the remote port could not be reached.
listConnectionsIn listConnectionsOut getConnectionInfoIn /portname getConnectionInfoOut /portname
listConnectionsIn and listConnectionsOut list the names of the ports connected to the input or to the output of the port. The reply is ok (names...).
getConnectionInfoIn and getConnectionInfoOut give details about the connection coming from (or going to) the specified port. The reply is ret found from_port to_port carrier connectionless push, where found is fail if there is no such connection.
From code, use the corresponding methods of yarp::os::impl::PortCoreClient, which return the structs yarp::os::return_listConnections and yarp::os::return_getConnectionInfo. The field ret of the returned struct is false if the remote port could not be reached.
getAdminProtocolVersion
Report the version of the administrative protocol of the port. It is distinct from the YARP library version. The reply is ok major minor patch.
From code, use the corresponding method of yarp::os::impl::PortCoreClient, which returns the struct yarp::os::return_getAdminProtocolVersion. The field ret of the returned struct is false if the remote port could not be reached.
attachPortmonitorIn "(type dll) (file test_numbers1)" attachPortmonitorOut "(type dll) (file test_numbers1)" detachPortmonitorIn detachPortmonitorOut
Attach a portmonitor plug-in to the input or to the output of the port, or detach it. The argument of the attach commands is a single string containing the portmonitor configuration, e.g. its type (dll, lua, ...) and its file. Attaching a new portmonitor replaces the one previously attached (if any). The reply is ok on success, fail otherwise.
These commands are defined in the thrift service PortCoreMsgs (src/libYARP_os/src/idl/PortCoreMsgs.thrift). From code, they can be sent using the corresponding methods of yarp::os::impl::PortCoreClient:
setPortmonitorParamsIn "(key1 value1) (key2 value2)" setPortmonitorParamsOut "(key1 value1) (key2 value2)" getPortmonitorParamsIn getPortmonitorParamsOut
Set or get the parameters of the portmonitor plug-in attached to the input or to the output of the port (see attachPortmonitorIn / attachPortmonitorOut / detachPortmonitorIn / detachPortmonitorOut). The parameters are a single string in yarp::os::Property format; their meaning depends on the portmonitor (they are passed to its setparam / getparam methods).
The reply of the set commands is ok success message; the reply of the get commands is ok success params message, where params is a string in yarp::os::Property format. success is fail if no portmonitor is attached to the port, and in this case message describes the error.
For example, the test_numbers1 portmonitor (which adds a value to each number it receives) accepts the parameter increment:
echo "setPortmonitorParamsIn \"(increment 5)\"" | yarp admin rpc /port_name echo "getPortmonitorParamsIn" | yarp admin rpc /port_name
setConnectionParamsIn /portname "(key1 value1) (key2 value2)" setConnectionParamsOut /portname "(key1 value1) (key2 value2)" getConnectionParamsIn /portname getConnectionParamsOut /portname
Set or get the carrier parameters of the connection coming from (In) or going to (Out) the specified port. The parameters are a single string in yarp::os::Property format, and they are passed to the carrier of the connection (see yarp::os::Carrier::setCarrierParams and yarp::os::Carrier::getCarrierParams); their meaning depends on the carrier. For instance, on a connection using the portmonitor carrier (e.g. fast_tcp+recv.portmonitor+type.dll+file.test_numbers1) they are forwarded to the portmonitor of the connection.
The replies have the same format of the portmonitor parameters commands: ok success message for the set commands, and ok success params message for the get commands. success is fail if there is no such connection.
From code, use the corresponding methods of yarp::os::impl::PortCoreClient, which return the structs yarp::os::return_setPortmonitorParams, yarp::os::return_getPortmonitorParams, yarp::os::return_setConnectionParams and yarp::os::return_getConnectionParams. The field ret of the returned struct is false if the remote port could not be reached.
getPortInfo
Give information about the port itself, and about the process which owns it. The reply contains, in this order, the fields of:
From code, use the corresponding method of yarp::os::impl::PortCoreClient, which returns the struct yarp::os::return_getPortInfo. The field ret of the returned struct is false if the remote port could not be reached.
getConnectionQosIn /portname getConnectionQosOut /portname setConnectionQosIn /portname scheduler_priority scheduler_policy qos_tos setConnectionQosOut /portname scheduler_priority scheduler_policy qos_tos setProcessScheduling priority policy
The quality of service of a connection consists of the scheduling parameters (priority and policy) of the thread which handles the connection, and of the type of service (TOS) of the IP packets of the connection. See Channel Prioritization for the meaning of the values.
getConnectionQosIn and getConnectionQosOut give the qos of the connection coming from (or going to) the specified port. The reply is ok found tid scheduler_priority scheduler_policy qos_tos, where found is fail if there is no such connection, tid is the id of the thread which handles the connection, and qos_tos is -1 if it is not available.
setConnectionQosIn and setConnectionQosOut set the qos of the connection coming from (or going to) the specified port. A scheduler_priority of -1 leaves the scheduling of the thread unchanged, while a negative qos_tos leaves the type of service unchanged. The values are numeric: see Channel Prioritization for the TOS values of the priority levels and of the DSCP classes. The reply is ok success message, where success is fail if there is no such connection or if the qos could not be set, and message describes the error.
setProcessScheduling sets the scheduling parameters of all the threads of the process which owns the port. The reply is ok on success, fail otherwise.
From code, use the corresponding methods of yarp::os::impl::PortCoreClient, which return the structs yarp::os::return_getConnectionQos and yarp::os::return_setConnectionQos, or the higher level functions yarp::os::Network::getConnectionQos and yarp::os::Network::setConnectionQos, which configure both sides of a connection. The field ret of the returned struct is false if the remote port could not be reached.