YARP
Yet Another Robot Platform
 
Loading...
Searching...
No Matches

This tutorial covers how to write and read XML files that are used by yarprobotinterface tool and by the libYARP_robotinterface C++ library.

+ Collaboration diagram for YARP robotinterface XML files:

This tutorial covers how to write and read XML files that are used by yarprobotinterface tool and by the libYARP_robotinterface C++ library.

A minimal XML file

Here is a minimal config file, let's call it "config.xml":

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE robot PUBLIC "-//YARP//DTD yarprobotinterface 3.0//EN" "http://www.yarp.it/DTD/yarprobotinterfaceV3.0.dtd">
<robot name="robotinterfaceExample" portprefix="/icub" build="0" xmlns:xi="http://www.w3.org/2001/XInclude">
<devices>
<device name="fake_motor_device" type="fakeMotionControl">
<group name="GENERAL">
<!-- Number of joints of the fake_motor_device -->
<param name="Joints"> 3 </param>
</group>
</device>
<device name="fake_motor_nws_yarp" type="controlBoard_nws_yarp">
<!-- See https://www.yarp.it/latest/classControlBoard__nws__yarp.html for parameter documentation -->
<param name="name"> ${portprefix}/body </param>
<param name="period"> 0.01 </param>
<action phase="startup" level="5" type="attach">
<!-- This is the same name that we specified with the name attribute of the device element of a previously created device -->
<param name="device"> fake_motor_device </param>
</action>
<action phase="shutdown" level="5" type="detach" />
</device>
</devices>
</robot>

This configuration files create two devices:

Reference documentation of XML format.

robot Element

The robot element is the root element of the XML file. It contains the following attributes:

devices Element

The devices element is a child element of robot element.

It is a collector of YARP devices that are spawned by the robotinterface instance.

device Element

The device element is a child element of devices element.

It is used to specify a YARP device that is spawned by the robotinterface. It contains the following attributes:

group Element

The group element is a child element of device or action element.

It is a collector of parameters under a specific group name.

param Element

The param element is a child element of device, action or group element.

This element it is used to specify a specific configuration parameter. It contain the following attributes:

The inner text of the element represents the value of the parameter. If the inner text contains a macros (e.g. ${portprefix}, ${portprefixnoslah}, ${robotname}), the macro will be substituted with its value.

Examples:

Here the value of the parameter depthResolution can be overwrittern by the command line: yarprobotinterface --depthRes "(640 480)"

<device xmlns:xi="http://www.w3.org/2001/XInclude" name="realsenseD450" type="realsense2">
<group name="SETTINGS">
<param extern-name= "depthRes" name="depthResolution"> (640 480) </param>
<param extern-name= "rgbRes" name="rgbResolution"> (640 480) </param>
</device>

Here the ${portprefix} and ${portprefixnoslah} macros are used to generate the value of the parameters.

<device xmlns:xi="http://www.w3.org/2001/XInclude" name="RGBDWrapperros" type="rgbdSensor_nws_ros2">
<param name="period"> 0.033 </param>
<param name="color_topic_name"> {portprefix}/camera_rgbd/color/image_rect_color </param>
<param name="depth_topic_name"> {portprefix}/camera_rgbd/depth/image_rect </param>
<param name="color_frame_id"> ${portprefixnoslah}/depth_center </param>
<param name="depth_frame_id"> ${portprefixnoslah}/depth_center </param>
<param name="node_name"> /rgbdsensor_ros_node </param>
<param name="namespace"> ${portprefixnoslah} </param>
</device>

action Element

This element still needs to be documented.

Inclusion of multiple XML files

Here is an example of .xml config file which includes other xml files, using the xi:include tag:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE robot PUBLIC "-//YARP//DTD yarprobotinterface 3.0//EN" "http://www.yarp.it/DTD/yarprobotinterfaceV3.0.dtd">
<robot name="exampleV2" build="1" portprefix="cer" xmlns:xi="http://www.w3.org/2001/XInclude">
<devices>
<xi:include href="wrappers/odometry/odometry_nws_yarp.xml" disabled_by="disable_odometry" />
<xi:include href="wrappers/odometry/odometry_nws_ros.xml" enabled_by="enable_ros" disabled_by="disable_odometry" />
<xi:include href="wrappers/odometry/odometry_nws_ros2.xml" enabled_by="enable_ros2" disabled_by="disable_odometry" />
<xi:include href="hardware/odometry/odometry.xml" disabled_by="disable_odometry" />
<xi:include href="hardware/body/body_nws_yarp.xml" disabled_by="disable_body" />
<xi:include href="wrappers/body/body.xml" disabled_by="disable_body" />
</devices>
</robot>

Contents of the file "wrappers/odometry/odometry_nws_yarp.xml".

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE devices PUBLIC "-//YARP//DTD yarprobotinterface 3.0//EN" "http://www.yarp.it/DTD/yarprobotinterfaceV3.0.dtd">
<device xmlns:xi="http://www.w3.org/2001/XInclude" name="cer_odometry_nws_yarp" type="odometry2D_nws_yarp">
<param name="odometry_port_name"> /cer/odometry </param>
<param name="odometer_port_name"> /cer/odometer </param>
<param name="velocity_port_name"> /cer/velocity </param>
<action phase="startup" level="15" type="attach">
<param name="device"> cer_odometry </param>
</action>
<action phase="shutdown" level="5" type="detach" />
</device>

It must be noticed that the included file contains just a single device section, that will be incorporated inside the devices block in the parent file. In this way, it is possible to better organize the xml file and eventually add/remove/replace individual devices. Additionally each device included through a xi:include can be enabled/disabled by the the use of enabled_by and disabled_by attributes. By default, if no attribute is added, than the file is automatically included.

Examples:

The latter two examples show the use of the special enable_all tag, which can be used to enable all optional devices (i.e. marked by a enabled_by attribute)

N.B. The disable_tags is always processed after the enable_tags and can be used to remove previously enabled devices. The enabled_by/disabled_by attributes are parsed by the yarprobotinterface pre-processor, hence they can be used only in combination with a xi:include tag.