diff --git a/manifest.xml b/manifest.xml index 8c3e3d8..94a2e03 100644 --- a/manifest.xml +++ b/manifest.xml @@ -273,6 +273,17 @@ advanced + + mimic_constraint/proposal.md + + Proposal for a mimic constraint between joint axes to replace the Gearbox joint type. + + + joint + + advanced + + @@ -325,6 +336,7 @@ composition_merge_proposal better_pose_proposal added_mass_proposal + mimic_proposal diff --git a/mimic_constraint/proposal.md b/mimic_constraint/proposal.md new file mode 100644 index 0000000..c4d627e --- /dev/null +++ b/mimic_constraint/proposal.md @@ -0,0 +1,315 @@ +# Proposal for Mimic Joint Actuation Constraint + +* **Authors**: +Steve Peters``, +Aditya Pande `` +* **Status**: *Draft* +* **SDFormat Version**: *1.11+* +* **`libsdformat` Version**: *14* + +## Introduction + +This proposal suggests adding a new joint actuation constraint called the Mimic +constraint that enforces a linear relationship between the output position +of two joint axes. + +Currently, the Gearbox joint type provides equivalent functionality for +three specified links along specified axis directions if the three links are +also connected by two revolute joints with matching axis directions. +This is an issue because it requires duplication of axis definitions, and it is +nonintuitive to specify three links instead of two joints. + +The Mimic constraint will simplify the definition of this constraint by +specifying the joint axes to which it applies instead of links so +that the joint axis information does not need to be duplicated. +It will be more flexible than the Gearbox joint by +allowing constraints on the output of prismatic joints and other +joints with translational outputs. + +## Document summary + +* *Syntax*: description of XPath syntax used in this proposal. +* *Motivation*: +* *Proposed changes*: +* *Examples*: + +## Syntax + +The proposal uses [XPath syntax](https://www.w3schools.com/xml/xpath_syntax.asp) +to describe elements and attributes concisely. +For example, `` tags are referred to as `//model` using XPath. +XPath is even more concise for referring to nested tags and attributes. +In the following example, `` elements inside `` tags are +referenced as `//model/link` and model `name` attributes as `//model/@name`: + + + + + +## Motivation + +Currently, a Gearbox joint is specified by the following SDFormat parameters: + +* 3 links + * `//joint/gearbox_reference_body` + * `//joint/parent` + * `//joint/child` +* 2 axis directions + * `//joint/axis/xyz` + * `//joint/axis2/xyz` +* 1 scalar + * `//joint/gearbox_ratio` + +The relative rotation of the `child` link with respect to the +`gearbox_reference_body` about the `//joint/axis/xyz` direction is defined as +`angle_C`, and similarly for the `parent` link with respect to the +`gearbox_reference_body` about the `//joint/axis2/xyz` direction as `angle_P`. +The Gearbox joint creates a proportional equality constraint: + +`angle_C = -gearbox_ratio * angle_P` + +The Gearbox joint is typically used in conjunction with a pair of +revolute joints with identical axes, so the axis definitions must be duplicated +between the revolute joints and the gearbox joint. +The Gearbox joint only constrains the rotational motion of revolute joints, +so it cannot model constraints involving translational motion, +such as a rack and pinion mechanism. + +The proposed Mimic constraint will simplify the specification of joint output +constraints by eliminating the need for redundant information. +This simplification is achieved by specifying the pair of joint axes to which +a Mimic constraint applies instead of specifying a group of three links, +a pair of axis directions, and a separate pair of revolute joints with +redundant axis information. +The Mimic constraint will also be more flexible than the gearbox joints +expanding the number of joint types that are supported, such as prismatic +joints and other joints with translational outputs. + +## Proposed changes + +This section defines the Mimic constraint mathematically and then explains +how to specify it in an SDFormat `//joint` element. + +### Definition of Mimic constraint + +A Mimic constraint encodes a linear equality constraint on the position of +two joint axes. One joint axis is labelled as the *leader* and the other as the +*follower*. The `multiplier`, `offset`, and `reference` parameters determine +the linear relationship according to the equation below. + +`follower_position = multiplier * (leader_position - reference) + offset` + +The `multiplier` parameter represents the ratio between changes in the +*follower* joint axis position relative to changes in the *leader* joint axis +position. + +`multiplier = (follower_position - offset) / (leader_position - reference)` + +Note that the `multiplier` and `offset` parameters match the parameters of the +[URDF mimic](https://wiki.ros.org/urdf/XML/joint#Elements) +tag if the `reference` parameter is `0`. + +### New SDFormat tags: `//axis/mimic` and `//axis2/mimic` + +To specify the Mimic constraint between two joint axes, an optional `//mimic` +tag is added to the `//joint/axis` and `//joint/axis2` elements. +The `//mimic` tag should be added to the *follower* joint axis, and +the *leader* joint axis is specified using the `//mimic/@joint` and +`//mimic/@axis` attributes. The `multiplier`, `offset`, and `reference` +parameters are specified as child elements of `//mimic`. + +An alternative was to add a new joint type called a Mimic joint, +but since URDF already supports the `//joint/mimic` tag (see +[URDF documentation](https://wiki.ros.org/urdf/XML/joint) and +[ros/robot\_state\_publisher#1](https://github.com/ros/robot_state_publisher/issues/1)) +it would be more consistent to add a new sdf tag called ```` inside +the ``//joint/axis/`` tag. + +### Details of `//mimic` + +When added to a `//joint/axis` or `//joint/axis2` element, the `//mimic` tag +causes that joint axis to be treated as the *follower* in a Mimic constraint. +The `//mimic` tag must have a `@joint` attribute that specifies the name of a +joint accessible from the current scope and may optionally specify an `@axis` +attribute as well. The `@axis` attribute has a default value of `axis`, and +its only valid values are `axis` and `axis2`. Together, the `@joint` and +`@axis` attributes specify the *leader* joint axis for the mimic constraint. +Note that the `@axis` attribute may only take a value of `axis2` if `@joint` +refers to a multi-axis joint. +The `multiplier`, `offset`, and `reference` parameters are specified in the +`//mimic/multiplier`, `/mimic/offset`, and `/mimic/reference` child elements, +respectively. + +~~~ + + 1.0 + 0.0 + 0.0 + +~~~ + +### Deprecation of `gearbox` joint type + +Since the `mimic` joint provides equivalent functionality to the gearbox joint +but with more flexibility and less repeated information, the `gearbox` joint +type and the associated `//joint/gearbox_reference_body` and +`//joint/gearbox_ratio` elements are deprecated. + +## Examples + +### Alternative to gearbox joint type + +There is an example `gearbox` joint in the +[demo\_joint\_types](https://github.com/osrf/gazebo_models/blob/master/demo_joint_types/model.sdf#L156-L328) +model, consisting of three links, + +~~~ + + -.49 0 0.35 0 0 0 + + + + -.38 -0.075 0.55 0 0 0 + + + + + 0.1 0.25 0.1 + + + + + + -.3 0.0 0.55 0 1.5708 0 + + + + 0.1 + 0.05 + + + + +~~~ + +two `revolute` joints, + +~~~ + + + gearbox_base + gearbox_input + + 1 0 0 + + 0 0.075 0 0 0 0 + + + gearbox_base + gearbox_output + + 0 0 1 + + 0 0 0 0 0 0 + +~~~ + +and one `gearbox` joint. + +~~~ + + gearbox_input + gearbox_output + gearbox_base + 5 + + + 0 0 1 + + + + 0 0 1 + + +~~~ + +The `gearbox` joint could be replaced equivalently by adding the `` +tag to joint axes : + +~~~ + + + gearbox_base + gearbox_input + + 1 0 0 + + 0 0.075 0 0 0 0 + + + gearbox_base + gearbox_output + + 1 0 0 + + 5 + 0 + 0 + + + +~~~ + +### Example of rack and pinion constraint + +Another advantage of the Mimic constraint compared to the Gearbox joint is +support for translational joints. The following example shows a rack and +pinion mechanism with the translation of a prismatic "rack" joint coupled +to the rotation of the revolute "pinion" joint. + +~~~ + + + + 0 0 -0.03 0 0 0 + + + + 0.4 0.03 0.03 + + + + + + 0 0 0.02 90 0 0 + + + + 0.03 + 0.02 + + + + + + world + pinion + + 0 1 0 + + + + world + rack + + 1 0 0 + + 0.02 + 0.0 + 0.0 + + + + + +~~~