Import upstream snapshot 57d13ead53206a6bf0db3d66f86506ae8c2ce01a

Upstream: https://github.com/pollen-robotics/bam
Upstream-Commit: 57d13ead53206a6bf0db3d66f86506ae8c2ce01a
Upstream-Branch: mjlab_frictionloss

docs/theory/dc_motor.rst

@@ -0,0 +1,61 @@
+DC Motor
+========
+
+In BAM, servomotor sources are modeled using DC motors dynamics. A DC motor turns current into torque, according
+to the following equation:
+
+.. math::
+
+    \tau = k_t i
+
+where :math:`\tau` is the torque, :math:`k_t` is the torque constant, and :math:`i` is the current. When a motor
+rotates at a velocity of :math:`\omega`, it generates a back electromotive voltage of :math:`k_t \omega`.
+
+As a result, if you apply a voltage :math:`V` to the motor, the current is given by:
+
+.. math::
+
+    i = \frac{V - k_t \omega}{R}
+
+where :math:`R` is the motor resistance. Thus, the torque generated by a DC motor is given by:
+
+.. math::
+
+    \tau = k_t \frac{V}{R} - k_t^2 \frac{\omega}{R}
+
+Torque vs speed limit
+---------------------
+
+There are typically two limits in play in a DC motor:
+
+* The maximum **voltage** you can apply, this is typically limited because of your battery that, for example,
+can only provide 12V
+* The maximum **current** you can apply, this is typically enforced by firmwares to avoid overheating the motor.
+
+Let's first look at the voltage limit, using above equation, we get:
+
+.. image:: ../_static/velocity_vs_torque.svg
+    :alt: Torque vs speed limit
+    :width: 400
+    :align: center
+
+The feasible green area here is depicting the limit caused by **voltage** limit. Note that the torque you can apply actually depends on the current speed of the motor. At a given velocity :math:`\omega_0`, you will not even be
+able to apply positive torque (this is the no-load speed of the motor). Conversely, at zero speed, there is a
+maximum torque :math:`\tau_{stall}` you can apply (this is the stall torque of the motor).
+
+It is in general a good idea to use voltages as high as possible. Firstly because it allows to use smaller wires,
+but also because it can make the voltage-related limit less restrictive. However, many servo-actuators run with
+low-voltage batteries and fall into that functioning regime.
+
+The second limit is the **current** limit, that is typically enforced by the firmware of the motor. Since the torque
+is proportional to current, this limit can be seen as a maximum torque limit :math:`\tau_{max}`:
+
+.. image:: ../_static/velocity_vs_torque_custom_tau_max.svg
+    :alt: Torque vs speed limit
+    :width: 400
+    :align: center
+
+Note that this is, however a *soft* limit. The firmware will *attempt* to limit the current, but it is not guaranteed that it will always be able to do so. 
+
+For example, if the motor rotates at a very high speed, the best strategy to provide the less torque is to provide
+as much volt as possible. However, your voltage supply is limited, and you might have no choice that to provide a voltage that will generate a current above the limit.