Readability of ConnPolicy xml specification

Hello list,

I just took a look at an example featured here
http://www.ros.org/wiki/rtt_ros_integration
and I have to say that it's nontrivial to understand part of its meaning:

<struct name="ROSConMsg" type="ConnPolicy">
<simple name="type" type="short"><value>0</value></simple>
<!-- The meaning of the "0" value is not self-evident... -->
<simple name="size" type="short"><value>1</value></simple>
<simple name="transport" type="short"><value>3</value></simple>
<!-- ...same applies to "3" here -->
<simple name="name_id" type="string"><value>YourNodeName</value></simple>
</struct>

Without reading the docs (or very explicit comments), there is no way I can
know that the connection type==0 means unbuffered, and that 1 means
buffered. The mapping from index to value is not implicit. The same applies
to the transport type: Why not use a string, like "DATA" in the former case,
and "ROS"in the latter?. I think "size" is OK, but would prefer something
more explicit like "bufferSize", YMMV. Is there some rationale for this
convention?. Deployer xml files should be as self-explaining as possible.

TIA,

Adolfo

Ruben Smits's picture

Readability of ConnPolicy xml specification

On Thursday 18 November 2010 10:08:57 Adolfo Rodríguez Tsouroukdissian wrote:
> Hello list,
>
> I just took a look at an example featured here
> http://www.ros.org/wiki/rtt_ros_integration
> and I have to say that it's nontrivial to understand part of its meaning:

You're completly right, the example obviously misses some explanation of the
ConnPolicy fields.

> <struct name="ROSConMsg" type="ConnPolicy">
> <simple name="type" type="short"><value>0</value></simple> <!-- The
> meaning of the "0" value is not self-evident... -->
>
> <simple name="size" type="short"><value>1</value></simple>
> <simple name="transport" type="short"><value>3</value></simple> <!--
> ...same applies to "3" here -->

Is it actually somewhere document what the values 0, 1, and 2 are?

> <simple name="name_id" type="string"><value>YourNodeName</value></simple>
> </struct>

Looking at the deployer documentation, only the type and size are explained,
there is no documentation on the transport and name_id field in the orocos-
deployment manual on http://www.orocos.org/stable/documentation/ocl/v2.x/doc-
xml/orocos-deployment.html

> Without reading the docs (or very explicit comments), there is no way I can
> know that the connection type==0 means unbuffered, and that 1 means
> buffered. The mapping from index to value is not implicit. The same
> applies to the transport type: Why not use a string, like "DATA" in the
> former case, and "ROS"in the latter?.

I'm perfectly ok with this, it should be easy to change this in the deployer-
component code.

> I think "size" is OK, but would
> prefer something more explicit like "bufferSize", YMMV. Is there some
> rationale for this convention?. Deployer xml files should be as
> self-explaining as possible.

I fully agree.

Ruben
---
Dr. Ir. Ruben Smits
Mechatronics & Robotics Research Group
Department of Mechanical Engineering
Katholieke Universiteit Leuven

Readability of ConnPolicy xml specification

2010/11/18 Adolfo Rodríguez Tsouroukdissian <adolfo [dot] rodriguez [..] ...>:
> Hello list,
>
> I just took a look at an example featured here
> http://www.ros.org/wiki/rtt_ros_integration
> and I have to say that it's nontrivial to understand part of its meaning:
>
> <struct name="ROSConMsg" type="ConnPolicy">
> <simple name="type" type="short"><value>0</value></simple> <!-- The
> meaning of the "0" value is not self-evident... -->
>
> <simple name="size" type="short"><value>1</value></simple>
> <simple name="transport" type="short"><value>3</value></simple> <!--
> ...same applies to "3" here -->
>
> <simple name="name_id" type="string"><value>YourNodeName</value></simple>
> </struct>
>
> Without reading the docs (or very explicit comments), there is no way I can
> know that the connection type==0 means unbuffered, and that 1 means
> buffered. The mapping from index to value is not implicit. The same applies
> to the transport type: Why not use a string, like "DATA" in the former case,
> and "ROS"in the latter?. I think "size" is OK, but would prefer something
> more explicit like "bufferSize", YMMV. Is there some rationale for this
> convention?. Deployer xml files should be as self-explaining as possible.

I've added this information on the wiki.

Steven

>
> TIA,
>
> Adolfo
>
>
>
> --
> Adolfo Rodríguez Tsouroukdissian, Ph. D.
>
> Robotics engineer
> PAL ROBOTICS S.L
> http://www.pal-robotics.com
> Tel. +34.93.414.53.47
> Fax.+34.93.209.11.09
>
> CONFIDENTIALITY NOTICE: This e-mail and the accompanying document(s) may
> contain confidential information which is privileged and intended only for
> the individual or entity to whom they are addressed.  If you are not the
> intended recipient, you are hereby notified that any disclosure, copying,
> distribution or use of this e-mail and/or accompanying document(s) is
> strictly prohibited.  If you have received this e-mail in error, please
> immediately notify the sender at the above e-mail address.
>

Readability of ConnPolicy xml specification

On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:

> Hello list,
>
> I just took a look at an example featured here
> http://www.ros.org/wiki/rtt_ros_integration
> and I have to say that it's nontrivial to understand part of its meaning:
>
> <struct name="ROSConMsg" type="ConnPolicy">
> <simple name="type" type="short"><value>0</value></simple> <!-- The meaning of the "0" value is not self-evident... -->
>
> <simple name="size" type="short"><value>1</value></simple>
> <simple name="transport" type="short"><value>3</value></simple> <!-- ...same applies to "3" here -->
>
> <simple name="name_id" type="string"><value>YourNodeName</value></simple>
> </struct>
>
> Without reading the docs (or very explicit comments), there is no way I
> can know that the connection type==0 means unbuffered, and that 1 means
> buffered. The mapping from index to value is not implicit. The same
> applies to the transport type: Why not use a string, like "DATA" in the
> former case, and "ROS"in the latter?. I think "size" is OK, but would
> prefer something more explicit like "bufferSize", YMMV. Is there some
> rationale for this convention?. Deployer xml files should be as
> self-explaining as possible.
>
> TIA,
>
> Adolfo
>

I fully agree with the comments you make. The "only" problem right now
is that these "semantic tags" (DATA, bufferSize,...) still have to be
standardized, in the _community_, before the things you mention are
_really_ solved. Some orocos people (myself included) are involved in such
efforts, but it takes A LOT of time to get this "standardization" effort
started, sigh... Personally, I will keep on trying to motivate the Leuven
developers to not put such "magic numbers" in any code anymore...

But you should not let others improve the situation: keep on sending
similar messages to all projects where you experience these problems :-)
(Or even better: start contributing to the efforts yourself :-) )

Herman

Readability of ConnPolicy xml specification

2010/11/18 Herman Bruyninckx <Herman [dot] Bruyninckx [..] ...>

> On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:
>
> Hello list,
>>
>> I just took a look at an example featured here
>> http://www.ros.org/wiki/rtt_ros_integration
>> and I have to say that it's nontrivial to understand part of its meaning:
>>
>> <struct name="ROSConMsg" type="ConnPolicy">
>> <simple name="type" type="short"><value>0</value></simple> <!-- The
>> meaning of the "0" value is not self-evident... -->
>>
>> <simple name="size" type="short"><value>1</value></simple>
>> <simple name="transport" type="short"><value>3</value></simple> <!--
>> ...same applies to "3" here -->
>>
>> <simple name="name_id" type="string"><value>YourNodeName</value></simple>
>> </struct>
>>
>> Without reading the docs (or very explicit comments), there is no way I
>> can know that the connection type==0 means unbuffered, and that 1 means
>> buffered. The mapping from index to value is not implicit. The same
>> applies to the transport type: Why not use a string, like "DATA" in the
>> former case, and "ROS"in the latter?. I think "size" is OK, but would
>> prefer something more explicit like "bufferSize", YMMV. Is there some
>> rationale for this convention?. Deployer xml files should be as
>> self-explaining as possible.
>>
>> TIA,
>>
>> Adolfo
>>
>>
> I fully agree with the comments you make. The "only" problem right now
> is that these "semantic tags" (DATA, bufferSize,...) still have to be
> standardized, in the _community_, before the things you mention are
> _really_ solved. Some orocos people (myself included) are involved in such
> efforts, but it takes A LOT of time to get this "standardization" effort
> started, sigh... Personally, I will keep on trying to motivate the Leuven
> developers to not put such "magic numbers" in any code anymore...
>

Until no such "standardization" exists (we're using Orocos-specific
deployment xml files anyway) it seems a good idea to do away with magic
numbers and use some form of self-describing tokens.

> But you should not let others improve the situation: keep on sending
> similar messages to all projects where you experience these problems :-)
> (Or even better: start contributing to the efforts yourself :-) )
>

I agree, and I'm willing to collaborate whenever possible. Talk things over
is the first logical step. I don't want to go around breaking working code,
or changing something for the worse.

Best,

Adolfo

> Herman

Readability of ConnPolicy xml specification

On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:

>
> 2010/11/18 Herman Bruyninckx <Herman [dot] Bruyninckx [..] ...<mailto:Herman [dot] Bruyninckx [..] ...>>
> On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:
>
> Hello list,
>
> I just took a look at an example featured here
> http://www.ros.org/wiki/rtt_ros_integration
> and I have to say that it's nontrivial to understand part of its meaning:
>
> <struct name="ROSConMsg" type="ConnPolicy">
> <simple name="type" type="short"><value>0</value></simple> <!-- The meaning of the "0" value is not self-evident... -->
>
> <simple name="size" type="short"><value>1</value></simple>
> <simple name="transport" type="short"><value>3</value></simple> <!-- ...same applies to "3" here -->
>
> <simple name="name_id" type="string"><value>YourNodeName</value></simple>
> </struct>
>
> Without reading the docs (or very explicit comments), there is no way I
> can know that the connection type==0 means unbuffered, and that 1 means
> buffered. The mapping from index to value is not implicit. The same
> applies to the transport type: Why not use a string, like "DATA" in the
> former case, and "ROS"in the latter?. I think "size" is OK, but would
> prefer something more explicit like "bufferSize", YMMV. Is there some
> rationale for this convention?. Deployer xml files should be as
> self-explaining as possible.
>
> TIA,
>
> Adolfo
>
>
> I fully agree with the comments you make. The "only" problem right now
> is that these "semantic tags" (DATA, bufferSize,...) still have to be
> standardized, in the _community_, before the things you mention are
> _really_ solved. Some orocos people (myself included) are involved in such
> efforts, but it takes A LOT of time to get this "standardization" effort
> started, sigh... Personally, I will keep on trying to motivate the Leuven
> developers to not put such "magic numbers" in any code anymore...
>
> Until no such "standardization" exists (we're using Orocos-specific deployment xml files anyway) it seems a good idea to do away with magic numbers and use some form of self-describing tokens.

yes, but preferably while keeping in mind that these "self-describing
tokens" (which I call "semantic tags") should be defined in the context of
later use in the "complete" robotics world. In other words, names have to
be chosen carefully. Very carefully. Something like "DATA" or "BufferSize"
need extra "tagging" before they are really "universally" usable. (Maybe
universal use is not possible, but we should at least _try_ :-) )

>
> But you should not let others improve the situation: keep on sending
> similar messages to all projects where you experience these problems :-)
> (Or even better: start contributing to the efforts yourself :-) )
>
> I agree, and I'm willing to collaborate whenever possible. Talk things over is the first logical step. I don't want to go around breaking working code, or changing something for the worse.

I am very aware of your good intentions and, even better, your concrete
contributions, so please don't consider my previous answer in this thread
as a negative comment towards you :-)

>
> Best,
>
> Adolfo
>
>
> Herman
>
>
>
> --
> Adolfo Rodríguez Tsouroukdissian, Ph. D.
>
> Robotics engineer
> PAL ROBOTICS S.L
> http://www.pal-robotics.com
> Tel. +34.93.414.53.47
> Fax.+34.93.209.11.09
>
> CONFIDENTIALITY NOTICE: This e-mail and the accompanying document(s) may contain confidential information which is privileged and intended only for the individual or entity to whom they are addressed. If you are not the intended recipient, you are hereby notified that any disclosure, copying, distribution or use of this e-mail and/or accompanying document(s) is strictly prohibited. If you have received this e-mail in error, please immediately notify the sender at the above e-mail address.
>

Readability of ConnPolicy xml specification

2010/11/18 Herman Bruyninckx <Herman [dot] Bruyninckx [..] ...>

> On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:
>
>
>> 2010/11/18 Herman Bruyninckx <Herman [dot] Bruyninckx [..] ...<mailto:
>> Herman [dot] Bruyninckx [..] ...>>
>>
>> On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:
>>
>> Hello list,
>>
>> I just took a look at an example featured here
>> http://www.ros.org/wiki/rtt_ros_integration
>> and I have to say that it's nontrivial to understand part of its meaning:
>>
>> <struct name="ROSConMsg" type="ConnPolicy">
>> <simple name="type" type="short"><value>0</value></simple> <!-- The
>> meaning of the "0" value is not self-evident... -->
>>
>> <simple name="size" type="short"><value>1</value></simple>
>> <simple name="transport" type="short"><value>3</value></simple> <!--
>> ...same applies to "3" here -->
>>
>> <simple name="name_id" type="string"><value>YourNodeName</value></simple>
>> </struct>
>>
>> Without reading the docs (or very explicit comments), there is no way I
>> can know that the connection type==0 means unbuffered, and that 1 means
>> buffered. The mapping from index to value is not implicit. The same
>> applies to the transport type: Why not use a string, like "DATA" in the
>> former case, and "ROS"in the latter?. I think "size" is OK, but would
>> prefer something more explicit like "bufferSize", YMMV. Is there some
>> rationale for this convention?. Deployer xml files should be as
>> self-explaining as possible.
>>
>> TIA,
>>
>> Adolfo
>>
>>
>> I fully agree with the comments you make. The "only" problem right now
>> is that these "semantic tags" (DATA, bufferSize,...) still have to be
>> standardized, in the _community_, before the things you mention are
>> _really_ solved. Some orocos people (myself included) are involved in such
>> efforts, but it takes A LOT of time to get this "standardization" effort
>> started, sigh... Personally, I will keep on trying to motivate the Leuven
>> developers to not put such "magic numbers" in any code anymore...
>>
>> Until no such "standardization" exists (we're using Orocos-specific
>> deployment xml files anyway) it seems a good idea to do away with magic
>> numbers and use some form of self-describing tokens.
>>
>
> yes, but preferably while keeping in mind that these "self-describing
> tokens" (which I call "semantic tags") should be defined in the context of
> later use in the "complete" robotics world. In other words, names have to
> be chosen carefully. Very carefully. Something like "DATA" or "BufferSize"
> need extra "tagging" before they are really "universally" usable. (Maybe
> universal use is not possible, but we should at least _try_ :-) )

Yes, I agree with you

>
>
>
>> But you should not let others improve the situation: keep on sending
>> similar messages to all projects where you experience these problems :-)
>> (Or even better: start contributing to the efforts yourself :-) )
>>
>> I agree, and I'm willing to collaborate whenever possible. Talk things
>> over is the first logical step. I don't want to go around breaking working
>> code, or changing something for the worse.
>>
>
> I am very aware of your good intentions and, even better, your concrete
> contributions, so please don't consider my previous answer in this thread
> as a negative comment towards you :-)
>
> Not at all :)

>
>
>
>> Best,
>>
>> Adolfo
>>
>>
>> Herman
>>
>>
>>
>> --
>> Adolfo Rodríguez Tsouroukdissian, Ph. D.
>>
>> Robotics engineer
>> PAL ROBOTICS S.L
>> http://www.pal-robotics.com
>> Tel. +34.93.414.53.47
>> Fax.+34.93.209.11.09
>>
>> CONFIDENTIALITY NOTICE: This e-mail and the accompanying document(s) may
>> contain confidential information which is privileged and intended only for
>> the individual or entity to whom they are addressed. If you are not the
>> intended recipient, you are hereby notified that any disclosure, copying,
>> distribution or use of this e-mail and/or accompanying document(s) is
>> strictly prohibited. If you have received this e-mail in error, please
>> immediately notify the sender at the above e-mail address.
>>
>>
> --
> --
> K.U.Leuven, Mechanical Eng., Mechatronics & Robotics Research Group
> <http://people.mech.kuleuven.be/~bruyninc<http://people.mech.kuleuven.be/%7Ebruyninc>>
> Tel: +32 16 328056
> EURON Coordinator (European Robotics Research Network) <
> http://www.euron.org>
> Open Realtime Control Services <http://www.orocos.org>
> Associate Editor JOSER <http://www.joser.org>, IJRR <http://www.ijrr.org>

Ruben Smits's picture

Readability of ConnPolicy xml specification

On Thursday 18 November 2010 10:17:04 Herman Bruyninckx wrote:
> On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:
> > Hello list,
> >
> > I just took a look at an example featured here
> > http://www.ros.org/wiki/rtt_ros_integration
> > and I have to say that it's nontrivial to understand part of its meaning:
> >
> > <struct name="ROSConMsg" type="ConnPolicy">
> >
> > <simple name="type" type="short"><value>0</value></simple> <!--
> > The meaning of the "0" value is not self-evident... -->
> >
> > <simple name="size" type="short"><value>1</value></simple>
> > <simple name="transport" type="short"><value>3</value></simple> <!--
> > ...same applies to "3" here -->
> >
> > <simple name="name_id"
> > type="string"><value>YourNodeName</value></simple>
> >
> > </struct>
> >
> > Without reading the docs (or very explicit comments), there is no way I
> > can know that the connection type==0 means unbuffered, and that 1 means
> > buffered. The mapping from index to value is not implicit. The same
> > applies to the transport type: Why not use a string, like "DATA" in the
> > former case, and "ROS"in the latter?. I think "size" is OK, but would
> > prefer something more explicit like "bufferSize", YMMV. Is there some
> > rationale for this convention?. Deployer xml files should be as
> > self-explaining as possible.
> >
> > TIA,
> >
> > Adolfo
>
> I fully agree with the comments you make. The "only" problem right now
> is that these "semantic tags" (DATA, bufferSize,...) still have to be
> standardized, in the _community_, before the things you mention are
> _really_ solved. Some orocos people (myself included) are involved in such
> efforts, but it takes A LOT of time to get this "standardization" effort
> started, sigh... Personally, I will keep on trying to motivate the Leuven
> developers to not put such "magic numbers" in any code anymore...

They are magic numbers in XML, but not in the C++ code, there we have typedefs
and enums for them, that's why they appear to be magic in XML.

Ruben

> But you should not let others improve the situation: keep on sending
> similar messages to all projects where you experience these problems :-)
> (Or even better: start contributing to the efforts yourself :-) )
>
> Herman

Readability of ConnPolicy xml specification

On Thu, 18 Nov 2010, Ruben Smits wrote:

> On Thursday 18 November 2010 10:17:04 Herman Bruyninckx wrote:
>> On Thu, 18 Nov 2010, Adolfo Rodríguez Tsouroukdissian wrote:
>>> Hello list,
>>>
>>> I just took a look at an example featured here
>>> http://www.ros.org/wiki/rtt_ros_integration
>>> and I have to say that it's nontrivial to understand part of its meaning:
>>>
>>> <struct name="ROSConMsg" type="ConnPolicy">
>>>
>>> <simple name="type" type="short"><value>0</value></simple> <!--
>>> The meaning of the "0" value is not self-evident... -->
>>>
>>> <simple name="size" type="short"><value>1</value></simple>
>>> <simple name="transport" type="short"><value>3</value></simple> <!--
>>> ...same applies to "3" here -->
>>>
>>> <simple name="name_id"
>>> type="string"><value>YourNodeName</value></simple>
>>>
>>> </struct>
>>>
>>> Without reading the docs (or very explicit comments), there is no way I
>>> can know that the connection type==0 means unbuffered, and that 1 means
>>> buffered. The mapping from index to value is not implicit. The same
>>> applies to the transport type: Why not use a string, like "DATA" in the
>>> former case, and "ROS"in the latter?. I think "size" is OK, but would
>>> prefer something more explicit like "bufferSize", YMMV. Is there some
>>> rationale for this convention?. Deployer xml files should be as
>>> self-explaining as possible.
>>>
>>> TIA,
>>>
>>> Adolfo
>>
>> I fully agree with the comments you make. The "only" problem right now
>> is that these "semantic tags" (DATA, bufferSize,...) still have to be
>> standardized, in the _community_, before the things you mention are
>> _really_ solved. Some orocos people (myself included) are involved in such
>> efforts, but it takes A LOT of time to get this "standardization" effort
>> started, sigh... Personally, I will keep on trying to motivate the Leuven
>> developers to not put such "magic numbers" in any code anymore...
>
> They are magic numbers in XML, but not in the C++ code, there we have typedefs
> and enums for them, that's why they appear to be magic in XML.
>
And that's exactly the motivation for introducing "semantic APIs" into
software projects: if you have them, both the C++ code and the XML can
"include" these things, so that you have to write the documentation and the
"semantic code" only once :-)

On the roadmap for 3.0!

Herman

> Ruben
>
>> But you should not let others improve the situation: keep on sending
>> similar messages to all projects where you experience these problems :-)
>> (Or even better: start contributing to the efforts yourself :-) )
>>
>> Herman