.. _force-mode:

Force Mode
==========

In this tutorial we will demonstrate use of the force control mode of ORCA motors. 

Prerequisites
-------------

 - :ref:`motor-modes`
 - :ref:`motor-error-handling`
 - :ref:`command-stream`
  
----

We'll start with the following code, which is a modified example from the command stream tutorial displaying force instead of position. We recommend using command streaming when controlling the motor via force mode.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. literalinclude:: shared/boilerplate-streaming-force.cpp
			:language: cpp
			
	.. tab-item:: Python
		:sync: python

		.. literalinclude:: shared/boilerplate-streaming-force.py
			:language: python

Command a Force
---------------

To begin, let's set the motor into force mode.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			...
			motor.enable_stream();

			motor.set_mode(MotorMode::ForceMode);
			...

	.. tab-item:: Python
		:sync: python

		.. code-block:: python

			from pyorcasdk import MotorMode
			...
			motor.enable_stream()

			motor.set_mode(MotorMode.ForceMode)
			...

At this point the motor is ready to receive force commands. Let's give it one.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			...
			motor.enable_stream();

			motor.set_mode(MotorMode::ForceMode);

			motor.set_streamed_force_mN(10000);
			...

	.. tab-item:: Python
		:sync: python

		.. code-block:: python

			...
			motor.enable_stream()

			motor.set_mode(MotorMode.ForceMode)

			motor.set_streamed_force_mN(10000)
			...

Try running the program, you should notice that the shaft moves. Try opening IrisControls. It should display that you are in force mode, and that it's detecting a force of around 10 newtons.

Timeout Error
-------------

Now close your program and run it again. This time you may notice that the shaft does not move. Take a look again at IrisControls. It should be displaying that an error has occurred, particularly a "comms timeout". Some ORCA modes, including force mode, require that regular communication happens with the motor, else it will stop exerting force. This is a safety feature. When actively giving a motor commands, any stops in communication are interpreted as a failure or shutdown of the system at large.

In order to resolve this issue, lets clear errors before beginning. This will allow the program to run again.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			...
			motor.set_mode(MotorMode::SleepMode);

			motor.set_mode(MotorMode::ForceMode);
			...

	.. tab-item:: Python
		:sync: python

		.. code-block:: python

			...
			motor.set_mode(MotorMode.SleepMode)

			motor.set_mode(MotorMode.ForceMode)
			...

After adding this command in, your program should run as normal again.

----

Complete Example
----------------

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. literalinclude:: Force-Mode/main.cpp
			:language: cpp
			
	.. tab-item:: Python
		:sync: python

		.. literalinclude:: Force-Mode/main.py
			:language: python