.. _reflexes-smart-stiffness:

Smart Stiffness
===============

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

   reflexes-smart-stiffness-api

Overview | :ref:`API <reflexes-smart-stiffness-api>`

.. seealso::

    - :ref:`almotion`

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

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

A unique feature that allows to adapt automatic engine power to the posture of the robot.
This result to an optimized resources drive, energy savings for battery: NAO is less tiring.

By default, the smart stiffness is active on NAO.

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

The main idea is to limit the torque of NAO joints, so the robot will become more compliant and
will save energy.

As the :ref:`stiffness <control-stiffness>` is a torque limitation, the result of the smart
stiffness will be a stiffness command for every joint at every **ALMotion** cycle.

To determine the good torque to apply for each joint, we use the inverse dynamics equation:

.. math:: \tilde{M}(q)(\ddot{q} - G) + N(q,\dot{q}) = \tau+J^T(q)W

where:
  - :math:`(q, \dot{q}, \ddot{q})` position, velocity and acceleration of all joints
  - :math:`\tilde{M}(q)` the inertial matrix of each body
  - :math:`G` the gravity vector
  - :math:`N(q,\dot{q})` the matrix associated with the Coriolis and centrifuge force
  - :math:`\tau` the joint torque is the value that we want compute.
  - :math:`J(q)` the jacobian matrix of all joints
  - :math:`W` the forces apply on each body (joint friction, contact and external force)


For reason of CPU consumption, we have decided to only compute static torque (:math:`\ddot{q}`
and :math:`N(q,\dot{q})` are null) and to ignore external force (no sensor for external force).

So, we only have to compute torque due to
  - inertial matrix and gravity.
  - contact force.

.. math:: \tilde{M}(q) \: G + \tau + J^T(q) \: W_{\text{contact}} = 0


Getting started
---------------

The user command have always the priority over the smart stiffness. For example, if you ask a
stiffness of 0.2 on the HeadYaw joint and that the smart stiffness computation give 0.38. The
stiffness in the HeadYaw joint will be 0.2.

When the reflexe is active
++++++++++++++++++++++++++

The smart stiffness reflex is activated in any static posture of NAO (stand, sti, lift,
lying down..).

If at least one joint move, the user stiffness command is apply on the joint.


How to disable this reflexe
+++++++++++++++++++++++++++

You can simply disable the smart stiffness reflex by calling the **ALMotion** API.

.. code-block:: python

  motionProxy.setSmartStiffnessEnabled(False)