.. _control-stiffness:

Stiffness control
=================

.. toctree::
   :hidden:
   :maxdepth: 1

   control-stiffness-api


Overview | :ref:`API <control-stiffness-api>`


.. seealso::

    - :ref:`naoqi-motion`

------------

What it does
------------

| These API control the stiffness of one or several joints.
| The stiffness of the joint is equivalent to a torque limitation into the motors.
| If the joint stiffness is set to 0.0, the joint controller does nothing and the joint is free.
  Else with a value at 1.0 the joint is allowed to use full torque power to reach a given position.
  Between these two extremes, the joint is more or less compliant (try to reach a position but if
  torque need to move is higher than the limitation of stiffness, the joint doesn't reach the
  target position).

How it works
------------

These API just create a higher level of the :term:`DCM` hardness definition and provide
interpolation in order to have more smooth behavior.


Use Cases
---------

Case 1: Stiffness On
++++++++++++++++++++

When NAO is switched on, he initially has zero stiffness. When at
zero stiffness, you can send any commands to the motors, but he will not
move.

To give power to the motors, you can call one of Motion's stiffness methods:

:download:`motion_stiffnessOn.py </examples/python/motion/motion_stiffnessOn.py>`

.. literalinclude:: /examples/python/motion/motion_stiffnessOn.py
   :language: py


When changing stiffness away from zero, it is best to do it gently so
as to reduce the chance of a judder when powering up the motors.

Many tasks can be achieved at less than maximum stiffness (stiffness = 0.6),
but tasks such as "Get up" require all the power they can get (stiffness = 1.0).

Case 2: Stiffness Off
+++++++++++++++++++++

When you reduce the stiffness to zero, you cut all the power to the motors,
so you should be careful that NAO is in a self-stable pose, otherwise he
could fall.

:download:`motion_stiffnessOff.py </examples/python/motion/motion_stiffnessOff.py>`

.. literalinclude:: /examples/python/motion/motion_stiffnessOff.py
   :language: py


Case 2: Stiffness Trajectories
++++++++++++++++++++++++++++++

Should you wish to vary the stiffness of a joint over time, you can
request a 'trajectory' of stiffness.

.. code-block:: guess

  # Example showing a stiffness trajectory
  # Here the stiffness of the HeadYaw Joint, rises to
  # 0.8, then goes back to zero.
  pNames          = "HeadYaw"
  pStiffnessLists = [0.0, 0.8, 0.0]
  pTimeLists      = [0.5, 1.0, 1.5]
  proxy.stiffnessInterpolation(pNames, pStiffnessLists, pTimeLists)

Like angle interpolation commands, multiple trajectories can be specified
in the same command.

.. code-block:: guess

  # Example showing multiple stiffness trajectories
  # Here the stiffness of the HeadYaw Joint, rises to
  # 0.5, then goes back to zero, while the HeadPitch
  # joint rises to 1.0
  pNames          = ["HeadYaw", "HeadPitch"]
  pStiffnessLists = [[0.0, 0.5, 0.0], [0.0, 1.0, 0.0]]
  pTimeLists      = [[0.5, 1.0, 1.5], [0.5, 1.0, 1.5]]
  proxy.stiffnessInterpolation(pNames, pStiffnessLists, pTimeLists)