Define ABB specific naming rules/guidelines

[gavanderhoorn]

Split of from ros-industrial/abb_experimental#21.

Current suggestion:

---

Appendix A: Vendor specific naming

ABB

Variant names for ABB manipulators may include a modifier (indicating support for a particular feature, or a physical characteristic of the variant), a payload specification (one or more digits, indicating maximum supported payload in kg) and finally a specification of the reach of the arm (in meters). Examples: IRB 1600 - 10 / 1.2 and IRB 4400L - 10.

All ABB support packages shall be named using the following template:

  abb_irbMODEL_support

Note that this template omits the modifier, payload and reach components included in the actual product name.

Where appropriate, artefacts within ABB support, MoveIt configuration and plugin packages shall be named using the following template (refer to the Naming section for more information):

  irbMODEL[MODIFIER]_PAYLOAD_REACH_[VARIANT]

Where MODEL is a numeric string, MODIFIER is a string (optional), PAYLOAD is a numeric string (max payload in kg), REACH is a numeric string (reach converted to centimetres, avoiding fractional numbers) and VARIANT may be an alphanumeric string (optional).

If a particular model does not have variants based on reach, the REACH component should be omitted from the ROS-Industrial name as well.

Examples: irb1600_10_120 and irb4400l_10_255.

[gavanderhoorn]

Last comment by @Levi-Armstrong on ros-industrial/abb_experimental#21:

@gavanderhoorn, in reference to the vendor specific naming, I would suggest that the naming always include the reach. In the case of the irb 4400l there is two payloads variants 10kg and 30kg and they actual have different reaches; the 10kg is 2.55m and the 30kg is 2.43m. The suggest naming for the variants would be abb_irb4400l_10_255 and 4400l_30_243. Do you agree?

[gavanderhoorn]

@Levi-Armstrong, @Samsagax, @culletom, @shaun-edwards: opinions?

[culletom]

I'm sure the others are in a better position to comment on this than me, but in my opinion I would be inclined to keep the naming as short as possible, as long as it still uniquely identifies each variant. In that sense, reach would only be added if needed to separate two manipulators of same model, modifier, and payload (as suggested at the end of @gavanderhoorn's first comment). So referring to @Levi-Armstrong's comment, reach does not need to be included in the naming of the two robot variants as modifier and payload alone identify each variant i.e. abb_irb4400l_10 and abb_irb4400l_30. Reach will then be clarified when the user looks at the specific technical data sheet.

Also (from personal experience!), I would rephrase the proposed appendix to clarify that the naming of most artifacts within the ABB support package (bar the robot element defined within the macro / urdf) do not include the manufacturer's prefix, as this is already established from the support package name.

[gavanderhoorn]

Re: clarify / remove "all artefacts": you're right, and I should've done that before posting this issue.

As to always including the reach vs leaving it out: what I'm worried about is that we can't know at this time whether there will ever be 'reach variants' of the IRB 4400L-30 (or other future models). It might actually make sense then to add it.

I think @Levi-Armstrong also wanted to include it because that's "how RobotStudio does it", which would be convenient for users of both ROS and RobotStudio.

[Samsagax]

I think there are good points about length in the naming. It should be short. But the shortest it can get is how ABB name their manipulators. They follow a schema like this: xxxx-yyy/zz-vv. Where xxxx is the series of the manipulator, yyy is the reach of the manipulator, zz is the payload and optionally there is vv, the variant (that could be "paint", "hollow wrist", "turbo") and all of them are necessary. Take for example the 1600 manipulator. It has 1.2 and 1.55 reach variants, both combined with 5 or 20 kg payload and there are variants for "ID" and paint. So the longest name for that one could be: 1600_155_20_ID and that is not that long (!)

tl;dr; We could just use the RobotStudio naming.

[gavanderhoorn]

@Samsagax: is that pattern documented somewhere? Because fi the IRB4400-L10 seems to violate it (from here). Is the slash optional as well? Or is that site not using the official naming?

In any case, it seems to make the most sense to always include model/series, payload, reach and variant (term used by @Samsagax) in the name. Is there an official definition of reach in ABB robots (I can't find it in the documentation I have)?

[Levi-Armstrong]

This is also my concern, and I assume this may be why in RobotStudio the reach is always included to avoid the possibility of naming issues later.

As to always including the reach vs leaving it out: what I'm worried about is that we can't know at this time whether there will ever be 'reach variants' of the IRB 4400L-30 (or other future models). It might actually make sense then to add it.

As for the official definition of reach in ABB robot: I can not find where it is explicitly defined. After reviewing a few of the robots, it appears to be defined as the furthest the robot can reach along the x-axis (in front of the robot) measured relative to the base frame. In the robots working range figure , the robot can reach further in the z-axis than in the x-axis but the x-axis is stated as the reach.

[gavanderhoorn]

Ok. Then I suggest the following:

  abb_irbMODEL[MODIFIER]_REACH_PAYLOAD_[VARIANT]

Where:

• MODEL is the base model nr (or series), ie: 1600, 4400
• MODIFIER is an optional string, encoding some characteristic of the specific model. An example would be the L for the 4400L-30
• REACH is defined as "the furthest the robot can reach along the x-axis (in front of the robot) measured relative to the base frame" (@Levi-Armstrong). We list it in centimetres, to avoid having to include fractional nrs in the name. So 1.35m becomes 135.
• PAYLOAD is the maximum supported payload. In kg.

Two things I'm not sure about:

1. are there any robots for which PAYLOAD can be a fractional nr? If so, we might need to specify payload in either tenths/hundreths-of-kg or even grams.
2. including VARIANT (+) seems like a sensible thing to do, but I'm wondering whether the other components of the name not already uniquely identify such a specific variant. If that is the case, including it would be redundant. @Samsagax: are there models that have both hollow wrist and non hollow wrist variants fi?

IIUC, this would closely follow RobotStudio's naming scheme, which I think is a good thing (less ambiguity, familiar, etc).

(+) the word variant is already used to mean a slightly different thing in ros-i, so suggestions for alternative names are welcomed

[Samsagax]

Yes. There is the 1600 that has all variants. Incluing: hollow wrist, plain (as in plain text), paint variant, absolute accuracy variant. I can show you a full detail of all abb robots (i know most of them) but can't publish them for copyright issues.

And about reach: the x coordinate is correct, but is part of the name in abb specification.

Joaquín Aramendía

[Levi-Armstrong]

@gavanderhoorn: I would swap the PAYLOAD and REACH in the naming convention to match RobotStudio and ABB documentation. Also, I have only seen the payload represented as an integer with units kg, but I have not reviewed all of ABB robots. I will reach out to ABB and see if they can provide a definitive answer.

@Samsagax: Can you provide a link to the product specification for the 1600 that includes the different variants? The one I have found does not include the variants you described nor are they an option for the 1600 in RobotStudio.

[gavanderhoorn]

re: payload & reach: I swapped them based on @Samsagax input. We can easily swap them around again.

[gavanderhoorn]

One other thing: do we actually want to discriminate between (and provide files for) all the different variants (term used as in @Samsagax comment)?

For Fanucs, options like hollow wrist and paint mostly influence joint limits and max joint velocities. If we start creating urdfs for every variant that exists, we'll quickly end up with a lot of files.So I've sort-of decided that I'll only model the 'base variant', and clearly state which one that is. Users with non-default joint limits should then update a local copy of that urdf.

[gavanderhoorn]

I've updated the first post with the result of the discussion so far.

[gavanderhoorn]

See also #29 for some earlier discussion.

[Samsagax]

Here is an example product specification of the IRB-1600

Look at page 3 the naming scheme. There the ID version is the hollow wrist one and differs a lot with respect to the others (note page 14 of pdf).

I think the only part we can ommit is the load of the robot as only changes the wrist. We can use the largest wrist of both and keep ir there. The motion of robot is only limited when it's wall mounted for different load versions (page 40 of pdf). The reach can be viewed in page 41 of the pdf for the 1.2 version. Look that measurement is from the centerline of the robot (axis 1), to pos 3 (the maximum X coordinate the robot can reach), the robot work envelope is much larger.

Hope this helps. I found that spec just googling around, so I'm not sure about copyright issues here

[Samsagax]

I have to notice that in time the load parameter changes for the same manipulator. Here is the 10Kg IRB1600 brochure not specified in the above specification

[Samsagax]

And here is the 1600 "paint" version, branded IRB-52 so no problem there i think.

[gavanderhoorn]

Hm. Ok.

May I suggest we then always include the VARIANT bit, but only if it's actually defined? The proposed naming guidelines in the first post of this issue already allow for that, but I wanted to be clear.

We should still be careful I think to not start creating URDFs for every (minor) variant out there.

Opinions?

[Samsagax]

Maybe we can arrange a correct set of includes in xacro files to manage complexity

Joaquín Aramendía

[Levi-Armstrong]

@gavanderhoorn: I updated this section of the naming guideline, removing the abb_ for artifacts within the ABB support package. I believe this was discussed at some point but had not been updated, is this correct?

from:

abb_irbMODEL[MODIFIER]_PAYLOAD_REACH_[VARIANT]

to:

irbMODEL[MODIFIER]_PAYLOAD_REACH_[VARIANT]

[gavanderhoorn]

If with artefacts we actually only mean files and directories, then you're correct. Names of xacro macros fi should still include the abb_ prefix.

[Levi-Armstrong]

Names of xacro macros should still include the abb_ prefix.

Is this correct? Currently the xacro for all support packages do not include the abb_. This is also the same for the fanuc repo.

[gavanderhoorn]

The macros, not the files they are defined in (so: fanuc_m10ia, which is defined in m10ia_macro.xacro).

The xacro macro may be used in a composite xacro, where the namespacing of the package (fanuc_m10ia_support) does not protect against clashes (as all macros live in the same scope (at least in xacro < Jade)). The files however do not need the fanuc_ prefix, as they can only be referenced using something like package://fanuc_m10ia_support/..., which makes an additional prefix on the file redundant.

[Levi-Armstrong]

Oh, ok.

[Levi-Armstrong]

@gavanderhoorn: Is this ready to be moved to the README.md and close this issue?

[gavanderhoorn]

I did not actually intend for this be added to a readme, but as an appendix to a (yet to be created / finalised) REP (or less formal wiki page) on support repository layout and artefact naming (something like Industrial/Tutorials/SuggestedPackageLayoutNewRepositories).

I suggest we re-add the abb_ prefix to the 'artefact naming' bit of text, clarify that it should only be added when there is no mfg prefix in the path leading up to a file already, and that names of macros (so the entities themselves, not the files) etc should always include the prefix.

Are we satisfied with the rules for naming robots now? So payload before reach, etc? I understand that this is basically what RobotStudio does?

[Samsagax]

Completely agreed I guess.

Sent from my Android device with K-9 Mail. Please excuse my brevity.

[Samsagax]

Sorry, not intended to confuse anyone:
I agree to the naming change as last described by @Levi-Armstrong with the clarification @gavanderhoorn did on macros inside files.

wrt the wiki page about naming convention I also agree. We probably don't need a REP for this, as long as the guideline in the wiki is followed, because other manufacturers don't have the same scheme.

And yes, RobotStudio does exactly that to name each manipulator. We should use the same as well to ease the user experience.

[Jmeyer1292]

What do you want to do about model's with different payloads but the same geometry?

For example, the 2600 family has three variants: a 12kg 165cm, a 20kg 165cm, and a 12kg 185cm model. I'm most interested in whether we want multiple moveit configs for each model.

[gavanderhoorn]

@Jmeyer1292: I think we should strive to create as few packages as possible. So for the situation you describe, two packages would be enough (ie: one for 165cm, and one for 185cm reach).

'(maximum) payload' is not a concept that is supported in any of the configuration files or planners, so would be application specific (ie: an additional parameter descartes would care about or something). MoveIt certainly doesn't care, so a pkg for the 12kg variant would be identical to the 20kg one.

If however, the payload also influences maximum joint velocities (which it often does), then we should create separate packages, as those parameters do change the behaviour of planners.

For the Fanuc LR Mate 200iC and all its variants I've done something similar (see fanuc_lrmate200ic_support: the support package supports all variants, but some urdfs are re-used for variants that have differences in areas that do not 'matter' (ie: colours, special environment coatings, etc):

This package contains configuration data, 3D models and launch files for Fanuc LR Mate 200iC manipulators. This includes the base model (/5C, /5WP), /5H, /5L (/5LC), /5F and the /5HS. Variants in brackets are supported by the files for the referenced model.

I could see such parameters / characteristics become more important in the future though, so perhaps we should think about adding a yaml to the config dir of support packages that captures such additional information.

[gavanderhoorn]

@Samsagax wrote:

wrt the wiki page about naming convention I also agree. We probably don't need a REP for this, as long as the guideline in the wiki is followed, because other manufacturers don't have the same scheme.

What we discussed in this issue would only apply to ABB robots. As you note, other vendors use different naming schemes, so we cannot re-use this for them.

[gavanderhoorn]

Looking at the recent PRs submitted against abb_experimental, it looks like having PAYLOAD before REACH is a little less convenient when there are variants with the same reach, but different payload.

With the current rules, you get (taken from the abb_irb2600 pkg submitted by @Jmeyer1292): abb_irb2600_12_165 and abb_irb2600_20_165. These two variants share everything (kinematics, limits, meshes, etc), except for the maximum payload. Now the payload is currently somewhat of a non-issue (as it does not influence anything right now, but that could change), but there are now only two ways to share things between the variants:

1. keep only the dir for the lowest max payload variant, and refer to that in all other variant macros
2. remove the PAYLOAD bit from the directory name - so you get irb2600_165 - and refer to that from all macros

Option 1 is a bit weird: if doing that, why have two different macros in the first place?

Option 2 is also strange: if you don't know there are PAYLOAD variants of this model with the same REACH, the 165 could be interpreted as a maximum payload. Which sort-of negates what we're trying to do: make naming as intuitive and context-free as possible.

---

Now as I said: payload is not a 'real thing' in ROS at the moment, but I imagine there is a higher chance of having multiple payload variants of a model with a certain reach than the other way around. It's a pity RobotStudio uses this naming scheme, as it is probably intuitive for people using that.

[Levi-Armstrong]

@gavanderhoorn: What about allowing each support package to have a directory (ex: meshes/irb2600_common/visual and meshes/irb2600_common/collision) and this directory includes geometry that is common to all variants. If there are portions of the geometry that is different they go in the variant specific directory.

[gavanderhoorn]

Somehow I missed your latest comment @Levi-Armstrong. My apologies.

Yes, creating a common directory for shared meshes seems like a good way to handle this. If we do this, we can probably do away with the model/series prefix entirely, so the directory could just be called common.

But +1 to the idea.

[Levi-Armstrong]

@gavanderhoorn, Do you think this naming convention is OK to move to the readme file?

[gavanderhoorn]

@Levi-Armstrong: after going through the discussion again I decided to put all of this in a ROS-I REP.

While working on that, I wanted to include some examples for how ABB Robotics product names should be converted into ROS compatible names (ie: no spaces, adhering to what we came up with in this thread, etc). One of the examples I wanted to include was the YuMi, and that particular robot poses a problem. I was unsure in #75 (comment), but it turns out there are (now) robots with below 1 Kg payloads: YuMi. The full product name of that model is ABB IRB 14000-0.5/0.5.

With the current guidelines, that would convert to abb_irb14000_?_50. It would seem we would need to come up with something here.

Should we list payloads in grams? In that case it would become: abb_irb14000_500_50. Not as intuitive anymore for RobotStudio users, but we can't put dots in ROS names.

[Samsagax]

What about converting the 0.5 in a 05 in the ROS-I name? Like: ABB IRB 14000-0.5/0.5 -> abb_irb14000_05_05 Meaning "When you see a zero it means less than a kilogram"

[Levi-Armstrong]

This is a great point. I like the adding a leading 0 to for payloads that are less than a kilogram. We could use grams but for the larger robots the naming could get very long.

ABB IRB 14000-0.5/0.5 -> abb_irb14000_05_50

[gavanderhoorn]

Yes, that would be a nice way to do it. Could still be confusing, but I can't come up with something better for now.

[gavanderhoorn]

Captured the current state of this discussion in a ROS-I REP. See abb_naming/rep-ixxxx.rst.

Proper review should probably wait till I open a PR, but I wanted to see whether you agree that it corresponds to what we agreed upon in this issue.

[Levi-Armstrong]

How should the case when there is multiple variants with the same data (Geometry, joint velocities, etc.) be handled. As far as I can tell the IRB2400/10 (12kg payload) and IRB2400/16 (20kg payload) have the same CAD, joint velocities and reach. I would assume max acceleration to be different but this is not published data. It is estimated based on the max joint velocity. Example implementation below.

Mesh folder: irb2400_XX_155
Macro xacro: irb2400_XX_155_macro.xacro
Xacro: irb2400_12_155.xacro & irb2400_20_155.xacro

[gavanderhoorn]

have the same CAD

I think we discussed that earlier (#75 (comment)). You suggested to use a common folder for variants that share (parts of their) meshes (#75 (comment)).

How should the case when there is multiple variants with the same data (Geometry, joint velocities, etc.) be handled

And I think the particular example you give we have covered in #75 (comment): models that are basically identical could use each others URDFs. So the 20 kg payload version would use the 12 kg payload URDF.

have the same [..] joint velocities [..]. I would assume max acceleration to be different but this is not published data. It is estimated based on the max joint velocity.

This has me slightly confused: how would you estimate that they have different acceleration based on joint velocities if their joint velocity limits are identical?

[gavanderhoorn]

So with identical URDFs, we don't need copies of the meshes either.

Note that this is not specific to ABB support packages btw: I have the same 'problem' with Fanucs (as noted in #75 (comment).

[Levi-Armstrong]

This has me slightly confused: how would you estimate that they have different acceleration based on joint velocities if their joint velocity limits are identical?

Sorry for the confusion. I would assume the max acceleration for the two variants to be different, but they do not publish this data because I believe it is dynamic. I think it changes based on various parameters (configuration, joint values, etc.). Since we are unable to identify this information, it is currently estimated in the moveit_config package. I believe it is estimated for a given using 0.2 * max_joint_velocity, basically means it is assumed that it takes 5 second to reach max velocity. @shaun-edwards

[gavanderhoorn]

Ah, right. Yes, that is true (re: max accel being based on runtime parameters). The 1/5th of max joint velocity is actually what the old MSA did. I don't believe there is an actual justification for it.

But it'll just mean that the robot won't be able to reach maximum performance.

As we currently have no way to distinguish between the two payload-only variants and it doesn't / can't affect our planning, I feel it's justified to re-use the 12 kg urdf with the 20 kg variant.

[Levi-Armstrong]

Example folder structure:

• config/
  joint_names_irb2400_12_155.yaml Should this be variant specific?
• launch/
  load_irb2400_12_155.launch
  robot_interface_download_irb2400_12_155.launch
  robot_state_visualize_irb2400_12_155.launch
  test_irb2400_12_155.launch
  test_irb2400_20_155.launch
• meshes/
  irb2400_common
  irb2400_12_155 If required
  irb2400_20_155 If required
• tests/
  roslaunch_test_irb2400_12_155.xml
  roslaunch_test_irb2400_20_155.xml
• urdf/
  irb2400_12_155_macro.xacro
  irb2400_12_155.xacro
  irb2400_20_155.xacro

[gavanderhoorn]

We could potentially include some top-level artefacts even for models for which we re-use xacros etc from other models, but I'm not entirely convinced what that gets us.

The top-level xacro will never be used outside of the support package (as it cannot be used in a composite xacro), and the same goes for the test launch file. So there would seem to be little utility in including that.

My suggestion would be to completely re-use the artefacts for the IRB 2400-12/1.55, and thoroughly document that in the readme. That is basically what I did for the LR Mate 200iC and all its variants.

[Levi-Armstrong]

@gavanderhoorn; I have created a PR implementing both variants of the irb2400 that have common geometry. Please let me know your thoughts.

[gavanderhoorn]

@Levi-Armstrong: unless you disagree, I suggest we close this one as resolved as I've just merged ros-industrial/rep#16.

[Levi-Armstrong]

I agree.

[ywen27G]

@Levi-Armstrong Sir, does any ABB robot supports joint velocity control in real-time? That is we can change its velocity in each time step. I couldn't find too much information online. Really appreciate any help.

[gavanderhoorn]

@mitch1044444: could I please ask you to not cross-post the same question to multiple fora/issue trackers? You already posted this on ROS Answers. Let's keep discussions centralised.

Also: please don't post comments on random threads on issue trackers. It's not very nice.