diff --git a/docs/source/_static/img/opened_chain.png b/docs/source/_static/img/opened_chain.png new file mode 100644 index 0000000..abf02a5 Binary files /dev/null and b/docs/source/_static/img/opened_chain.png differ diff --git a/docs/source/design.rst b/docs/source/design.rst index b197314..5e89355 100644 --- a/docs/source/design.rst +++ b/docs/source/design.rst @@ -56,18 +56,6 @@ frames on standard output. Here is a `link `_ of a document that can be used as a frame (note: the center cube is 5mm side, so you might need 2.5mm offset to center it). -Closing frames --------------- - -If your robot includes closing loop, those can't be handled in the URDF file directly since the robot has to have -a kinematics structure that is a tree. - -However, it is possible to add multiple frames, and to make constraints out of them during your simulation. - -If you add a relation with ``closing_something`` as name, two frames will be added to your URDF -(``closing_something_1`` and ``closing_something_2``) that will be attached to the two parts mated. -It's up to you to handle it further by adding proper constraints. - Joint frames ------------ @@ -77,3 +65,4 @@ Thus, they are always revolving around the z axis, or translating along the z ax .. image:: _static/img/zaxis.png :align: center + : diff --git a/docs/source/index.rst b/docs/source/index.rst index d60d526..648da12 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,5 +21,6 @@ to descriptions format like **URDF** or **SDF**, so that you can use them for ph installation commands design + kinematic_loops config pure-shapes diff --git a/docs/source/kinematic_loops.rst b/docs/source/kinematic_loops.rst new file mode 100644 index 0000000..a1e43e6 --- /dev/null +++ b/docs/source/kinematic_loops.rst @@ -0,0 +1,55 @@ +Handling kinematic loops +======================== + +Some robots have *kinematic loops*, meaning that the kinematic chain is not a tree but a graph. +Here is an example: + +Introduction +------- + +Here is a 2D planar robot with kinematic loop, we assume the two first joints to be actuated and the others to +be passive: + +.. raw:: html + +
+ +
+
+ + +Here, the two branches are connected together, thus this can't be represented as a tree. +URDF doesn't allow to directly represent this type of structure. We need to break it down in a tree, and enforce the +closing constraints in software during execution. +To enforce the constraints, frames can be placed at relevant positions, here is an example for the above robot: + +.. image:: _static/img/opened_chain.png + :width: 200px + :align: center + +Using onshape-to-obot +--------------------- + +The above mentionned example can be achieved by adding :ref:`frames `. However, this would require to +manually place two frames at each closing position. Onshape-to-robot comes with a more convenient way to achieve this, +by using mate connectors. + +If you add a relation with ``closing_something`` as name, two frames will be added to your URDF +(``closing_something_1`` and ``closing_something_2``) that will be attached to the two parts mated. + +This way, the closure is handled in onshape exactly the way it should appear in the final mechanism, and will result +in the two frames being placed at the correct position in the URDF. + +Here is the complete `Onshape assembly `_ for the above example robot. +The onshape-to-robot export is available `here `_. + +Handling constraints on execution time +-------------------------------------- + +Here are some ressources on how to handle kinematic loops in software: + +* In MuJoCo, you can add an `equality `_ constraint in your XML model. +* In `pyBullet `_, you can use `createConstraint` method to add the relevant constraint. +* In the `PlaCo `_ solver, you can create a `RelativePositionTask`. See the `kinematics loop documentation section `_ for more details. Some examples created with onshape-to-robot can be found in the `example gallery `_.