Revision history [back]

Is there anything that says "Thou shalt only use geometry_msgs/Twist on the /cmd_vel topic"? [..] I feel like I read a REP about this once before, but all I'm seeing today is REP-103.

While it's not strictly about cmd_vel itself (and it doesn't use the wording you used ;) ), there is a REP which describes part of the behaviour of the ubiquitous cmd_vel topic/interface: REP-119: Specification for TurtleBot Compatible Platforms:

Level 1

TurtleBot Node Core API

• Subscribed Topics

  • cmd_vel (geometry_msgs/Twist):

    The desired velocity of the robot. The type of this message is determined by the drive_mode parameter. Default is geometry_msgs/Twist.

[..]

Level 2

Software Requiremets

• The base moves based on geometry_msgs/Twist [10] on the "cmd_vel" topic

  If the base is not holonomic, only the components of the command which are achievable should be executed.

This REP also claims dependency on REP-103: Standard Units of Measure and Coordinate Conventions which (should) immediately fixe(s) cmd_vel to only accept Twists with SI units for all the fields (so no "unit scale" values, as some drivers actually do), establishes the use of a right-handed coordinate system for the base and the interpretation of Twists, and a dependency on REP-105: Coordinate Frames for Mobile Platforms, which establishes standardised frames (names and semantics) for such mobile platforms.

The REP even includes some minimal mention of "command timeout" functionality:

Expected Parameters

• ~cmd_vel_timeout (double, default: 0.6)

  If a new command isn't received within this many seconds, the base is stopped.

Quite a few drivers still do not have this.

As is clear from the excerpt however, this is only a very minimal specification of the syntax and semantics of cmd_vel (so it doesn't address all of the questions you raised), but there is some specification and it seems to have been fairly successful.

Not many drivers claim to comply with REP-119 though, as, as @stevemacenski writes, most developers mimic existing interfaces and their implementations, or simply reuse libraries which "force" them to comply, so you can expect fairly similar behaviour between different implementations. As the Turtlebot provided a pretty good example (or generalisation actually) of what it means for a robot to have a mobile base, many early ROS users started copying it (without being aware of the REP most likely).

Is there anything that says how a robot might indicate, "I have 2 wheels and can only move in the X direction or rotate about the Z axis"?

What should a robot do if it is commanded to move in the Y or Z axis and it is not capable of doing so? Should it halt and catch fire? Should it silently ignore such commands?

Oh yeah, how about some way to indicate "If you ask me to go 3e8 m/s, I'm not going to be able to achieve that. The best I can do is 1e-2 m/s, and that's only on a good day".

I would support a new REP which describes the cmd_vel topic and the associated semantics. As a start, this could simply extract (or repeat) the specification given in REP-119 and give it its own separate REP. That would have already avoided questions like yours (which is a good question, I'm not saying otherwise).

Is there anything that says "Thou shalt only use geometry_msgs/Twist on the /cmd_vel topic"? [..] I feel like I read a REP about this once before, but all I'm seeing today is REP-103.

While it's not strictly about cmd_vel itself (and it doesn't use the wording you used ;) ), there is a REP which describes part of the behaviour of the ubiquitous cmd_vel topic/interface: REP-119: Specification for TurtleBot Compatible Platforms:

Level 1

TurtleBot Node Core API

• Subscribed Topics

  • cmd_vel (geometry_msgs/Twist):

    The desired velocity of the robot. The type of this message is determined by the drive_mode parameter. Default is geometry_msgs/Twist.

[..]

Level 2

Software Requiremets

• The base moves based on geometry_msgs/Twist [10] on the "cmd_vel" topic

  If the base is not holonomic, only the components of the command which are achievable should be executed.

This REP also claims dependency on REP-103: Standard Units of Measure and Coordinate Conventions which (should) immediately fixe(s) cmd_vel to only accept Twists with SI units for all the fields (so no "unit scale" values, as some drivers actually do), establishes the use of a right-handed coordinate system for the base and the interpretation of Twists, and a dependency on REP-105: Coordinate Frames for Mobile Platforms, which establishes standardised frames (names and semantics) for such mobile platforms.

The REP even includes some minimal mention of "command timeout" functionality:

Expected Parameters

• ~cmd_vel_timeout (double, default: 0.6)

  If a new command isn't received within this many seconds, the base is stopped.

Quite a few drivers still do not have this.

As is clear from the excerpt however, this is only a very minimal specification of the syntax and semantics of cmd_vel (so it doesn't address all of the questions you raised), but there is some specification and it seems to have been fairly successful.

Not many drivers claim to comply with REP-119 though, as, as @stevemacenski writes, most developers mimic existing interfaces and their implementations, or simply reuse libraries which "force" them to comply, so you can expect fairly similar behaviour between different implementations. As the Turtlebot provided a pretty good example (or generalisation actually) of what it means for a robot to have a mobile base, many early ROS users started copying it (without being aware of the REP most likely).

Is there anything that says how a robot might indicate, "I have 2 wheels and can only move in the X direction or rotate about the Z axis"?

What should a robot do if it is commanded to move in the Y or Z axis and it is not capable of doing so? Should it halt and catch fire? Should it silently ignore such commands?

Oh yeah, how about some way to indicate "If you ask me to go 3e8 m/s, I'm not going to be able to achieve that. The best I can do is 1e-2 m/s, and that's only on a good day".

I would support a new REP which describes the cmd_vel topic and the associated semantics. As a start, this could simply extract (or repeat) the specification given in REP-119 and give it its own separate REP. That would have already avoided questions like yours (which is a good question, I'm not saying otherwise).