Merge pull request #27 from kvasios/feature/franka-ai-companion

Docs for Franka Toolbox for MATLAB upcoming release
frankaemika · Nov 27, 2024 · 630b7cb · 630b7cb
2 parents 0fc33d5 + 974f6b3
commit 630b7cb
Show file tree

Hide file tree

Showing 45 changed files with 545 additions and 232 deletions.
diff --git a/franka_ros b/franka_ros
diff --git a/franka_ros2 b/franka_ros2
diff --git a/libfranka b/libfranka
diff --git a/source/franka_matlab/CHANGELOG.md b/source/franka_matlab/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog:
 
+## 2.0.0 (20-11-2024)
+
+   - **BREAKING** libfranka pre-built binaries now are contained in the project. No separate installation is required.
+   - **BREAKING** New Simulink Model Blocks replacing the old single Model Block.
+   - **BREAKING** Installation workflow and Simulink build system modification for supporting deployment to the Franka AI Companion.
+   - **BREAKING** Toolbox renaming: Franka Toolbox for MATLAB. Scripts also now follow the shorter convention: franka_toolbox_<>.m
+   - Cartesian impedance control example now includes UI elements as improved demo and better testing of the External Mode.  
+   - Dropping experimental support for native deployment in Windows host machines
+   - Switch port matlab function for targeting custom docker images in AI Companion.
+
 ## 1.0.0 (11-03-2024)
 
    - **BREAKING** Robot Settings standardization with Matlab OOP.

diff --git a/source/franka_matlab/_static/ai_companion_jetson_trouble.png b/source/franka_matlab/_static/ai_companion_jetson_trouble.png
diff --git a/source/franka_matlab/_static/apply_control.png b/source/franka_matlab/_static/apply_control.png
diff --git a/...static/block_parameters_apply_control.png → ...static/block_parameters_robot_control.png b/...static/block_parameters_apply_control.png → ...static/block_parameters_robot_control.png
diff --git a/source/franka_matlab/_static/board_parameters.png b/source/franka_matlab/_static/board_parameters.png
diff --git a/source/franka_matlab/_static/cartesian_impedance_control_apps.png b/source/franka_matlab/_static/cartesian_impedance_control_apps.png
diff --git a/source/franka_matlab/_static/cartesian_impedance_control_overview.png b/source/franka_matlab/_static/cartesian_impedance_control_overview.png
diff --git a/source/franka_matlab/_static/cartesian_impedance_control_run_on_hardware.png b/source/franka_matlab/_static/cartesian_impedance_control_run_on_hardware.png
diff --git a/source/franka_matlab/_static/coriolis.png b/source/franka_matlab/_static/coriolis.png
diff --git a/source/franka_matlab/_static/duration.png b/source/franka_matlab/_static/duration.png
diff --git a/source/franka_matlab/_static/external_mode_background_thread.png b/source/franka_matlab/_static/external_mode_background_thread.png
diff --git a/source/franka_matlab/_static/franka_matlab_toolbox_examples.png b/source/franka_matlab/_static/franka_matlab_toolbox_examples.png
diff --git a/source/franka_matlab/_static/franka_toolbox_uninstall.png b/source/franka_matlab/_static/franka_toolbox_uninstall.png
diff --git a/source/franka_matlab/_static/get_duration.png b/source/franka_matlab/_static/get_duration.png
diff --git a/source/franka_matlab/_static/get_gripper_state.png b/source/franka_matlab/_static/get_gripper_state.png
diff --git a/source/franka_matlab/_static/get_robot_state.png b/source/franka_matlab/_static/get_robot_state.png
diff --git a/source/franka_matlab/_static/gravity.png b/source/franka_matlab/_static/gravity.png
diff --git a/source/franka_matlab/_static/gripper_state.png b/source/franka_matlab/_static/gripper_state.png
diff --git a/source/franka_matlab/_static/hardware_config_options.png b/source/franka_matlab/_static/hardware_config_options.png
diff --git a/source/franka_matlab/_static/hardware_settings.png b/source/franka_matlab/_static/hardware_settings.png
diff --git a/source/franka_matlab/_static/interface_pane.png b/source/franka_matlab/_static/interface_pane.png
diff --git a/source/franka_matlab/_static/jacobian.png b/source/franka_matlab/_static/jacobian.png
diff --git a/source/franka_matlab/_static/jetson_config_c++11.png b/source/franka_matlab/_static/jetson_config_c++11.png
diff --git a/source/franka_matlab/_static/jetson_deploy.png b/source/franka_matlab/_static/jetson_deploy.png
diff --git a/source/franka_matlab/_static/linux_host_hardware_implementation.png b/source/franka_matlab/_static/linux_host_hardware_implementation.png
diff --git a/source/franka_matlab/_static/mass_matrix.png b/source/franka_matlab/_static/mass_matrix.png
diff --git a/source/franka_matlab/_static/model_settings_interface_mat_file_logging.png b/source/franka_matlab/_static/model_settings_interface_mat_file_logging.png
diff --git a/source/franka_matlab/_static/model_settings_interface_non_reusable_function.png b/source/franka_matlab/_static/model_settings_interface_non_reusable_function.png
diff --git a/source/franka_matlab/_static/pose.png b/source/franka_matlab/_static/pose.png
diff --git a/source/franka_matlab/_static/robot_control.png b/source/franka_matlab/_static/robot_control.png
diff --git a/source/franka_matlab/_static/select_nvidia_jetson.png b/source/franka_matlab/_static/select_nvidia_jetson.png
diff --git a/source/franka_matlab/_static/simulink_library_browser.png b/source/franka_matlab/_static/simulink_library_browser.png
diff --git a/source/franka_matlab/compatibility.rst b/source/franka_matlab/compatibility.rst
diff --git a/source/franka_matlab/franka_matlab_changelog.rst b/source/franka_matlab/franka_matlab_changelog.rst
@@ -1,5 +1,5 @@
-Franka MATLAB Toolbox changelog
-================================
+Franka Toolbox for MATLAB changelog
+===================================
 
 .. include:: ../franka_matlab/CHANGELOG.md
    :parser: myst_parser.sphinx_

diff --git a/source/franka_matlab/getting_started.rst b/source/franka_matlab/getting_started.rst
@@ -1,34 +1,31 @@
 Getting started
 ===============
+.. _getting_started:
 
-Overview
+Simulink
 --------
 
-A set of Simulink & Matlab examples is included within the Franka MATLAB Toolbox. Feel free to experiment, adjust 
-them and expand them to fit your project needs!
+The Franka MATLAB Toolbox includes a comprehensive set of Simulink and MATLAB examples. These examples are designed to help you understand the toolbox's capabilities and can be customized to meet your project requirements.
 
-You can navigate through the examples by typing: 
+To browse the available examples, use the following command:
 
-.. code-block:: shell
-
-    >> franka_matlab_toolbox_examples();
+.. code-block:: matlab
 
+    franka_toolbox_examples();
 .. figure:: _static/franka_matlab_toolbox_examples.png
     :align: center
     :figclass: align-center
 
     Franka MATLAB Toolbox Examples Navigator.
 
-Initialization
---------------
-
-After opening, double clicking on any of the simulink models the robot settings will be loaded automatically in the 
-workspace, in the form of the object `frs`.
+.. figure:: _static/cartesian_impedance_control_overview.png
+    :align: center
+    :figclass: align-center
 
-.. hint::
+    The Cartesian Impedance Control Example equiped with sliders as UI elements for controlling the End-Effector position.
 
-    The Simulink models are delivered in R2021a version. They will convert automatically to your Matlab version 
-    when you try to save the model. 
+After opening, by double clicking, any of the Simulink models the robot settings will be loaded automatically in the 
+workspace, in the form of the `frs` object.
 
 .. figure:: _static/workspace_parameters.png
     :align: center
@@ -39,31 +36,149 @@ workspace, in the form of the object `frs`.
 The robot_ip is set to 172.16.0.2. Make sure that the robot_ip, as well as all the other parameters matches your 
 setup for your intended purposes.
 
-.. code-block:: shell
+.. code-block:: matlab
 
-    >> frs.robot_ip = <your robot ip string>
+    frs.robot_ip = <your robot ip string>
 
 You can modify the default settings for the FrankaRobotSettings with
 
-.. code-block:: shell
+.. code-block:: matlab
+
+    edit FrankaRobotSettings.m
+
+Simulink Solver Settings
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The requirements for the solver settings for the Simulink model should be:
+
+* Fixed-step
+* discrete (no continuous states)
+* With Fixed-step sixe (fundamental sample time) of `0.001`.
+
+Simulink Build & Deploy - Target PC: Franka AI Companion  
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For building & deploying to the Franka AI Companion you can 
+use the following recommended workflow:
+
+Start by clicking "Run on Hardware Board" in the Simulink APPS pane and select
+the "NVIDIA Jetson" option.
+
+.. figure:: _static/cartesian_impedance_control_run_on_hardware.png
+    :align: center
+    :figclass: align-center
+
+    Run on Hardware Board - Select "NVIDIA Jetson".
+
+.. important::
+
+    In case this option is not visible make sure that the 
+    `MATLAB Coder Support Package for NVIDIA Jetson and NVIDIA DRIVE Platforms <https://www.mathworks.com/matlabcentral/fileexchange/68644-matlab-coder-support-package-for-nvidia-jetson-and-nvidia-drive-platforms>`_ 
+    is installed.
+
+We need to proceed with a couple of "Hardware Settings" before building & running the model.
 
-    >> edit FrankaRobotSettings.m
+.. figure:: _static/hardware_settings.png
+    :align: center
+    :figclass: align-center
+
+    Select the "Hardware Settings"
+
+Select the "NVIDIA Jetson" Hardware board
+
+Set the `Device Address`, `Username` and `Password` which correspond to your docker instance as it is running in the Franka AI Companion.
+
+.. figure:: _static/board_parameters.png
+    :align: center
+    :figclass: align-center
+
+    "Board Parameters"
 
-Execution
----------
+It is recommended to select the "C++11" option in order to ensure compatibility with the MATLAB Coder Support Package for NVIDIA Jetson and NVIDIA DRIVE Platforms.
+
+.. figure:: _static/jetson_config_c++11.png
+    :align: center
+    :figclass: align-center
 
-Let's start by selecting the `Run on custom hardware` App from the Apps pane in Simulink.
+    Select the "C++11" option.
+
+.. important::
+
+    For setting the specific port in which the ssh server is exposed by the currently targeted docker
+    instance, please excecute the following MATLAB command:
+
+    .. code-block:: shell
+
+        franka_ai_companion_port_switch(<desired port number>);
+
+.. important::
+
+    If you are planning to utilize the External Mode for "Monitoring  & Tuning" make sure
+    that you've applied the settings descibed in the section bellow :ref:`external_mode_settings`.
+
+.. important::
+
+    Before executing make sure that the brakes of the robot are disengaged, the FCI mode is activated
+    in Desk and that the robot is in execution mode (user-button is released)!
+
+You can now "Build and Deploy" or "Monitor and Tune" for running the Simulink Model!
+
+.. caution::
+
+    The robot will move! Make sure that you are monitoring the situation, ready to take action if necessary!
+
+.. figure:: _static/jetson_deploy.png
+    :align: center
+    :figclass: align-center
+
+    "Build & Deploy" or "Monitor & Tune" for enabling the External Mode.
+
+Simulink Build & Deploy - Target PC: Linux Host
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+
+    If you are planning to build, run & deploy the application to your linux host pc 
+    make sure that you've installed libfranka and a Real-Time kernel as described in the 
+    previous installation page.
+
+Let's start by selecting the `Run on Custom Hardware` App from the Apps pane in Simulink. 
+Allow the grt.tlc target to be auto-selected, as prompted.
 
 .. figure:: _static/cartesian_impedance_control_apps.png
     :align: center
     :figclass: align-center
 
     "Run on custom hardware" Simulink App.
 
+Please proceed with the following necessary model checks before proceeding:
+
+ * The Device vendor under "Hardware Implementation" is either "Intel" or "AMD" and device type "x86-64 (Linux 64)".
+ * Code interface packaging options is set to "Nonreusable function".
+
+.. figure:: _static/linux_host_hardware_implementation.png
+    :align: center
+    :figclass: align-center
+    :scale: 60%
+
+    Hardware Implementation - Device vendor selection.
+
+.. figure:: _static/interface_pane.png
+    :align: center
+    :figclass: align-center
+    :scale: 70%
+
+    "Code interface packaging" options.
+
+.. important::
+
+    If you are planning to utilize the External Mode for "Monitoring  & Tuning" make sure
+    that you've applied the settings descibed in the section bellow :ref:`external_mode_settings`.
+
 .. important::
 
     Before executing make sure that the brakes of the robot are disengaged, the FCI mode is activated
-    in Desk and that the robot is in execution mode(user button is released)!
+    in Desk and that the robot is in execution mode (user-button is released)!
 
 You can then select from the Hardware tab either `Monitor & Tune` in case monitoring through the external mode is 
 desired or `Build, Deploy & Start` for just executing the application without monitoring.
@@ -78,35 +193,68 @@ desired or `Build, Deploy & Start` for just executing the application without mo
 
     The robot will move! Make sure that you are monitoring the situation, ready to take action if necessary!
 
-Alternatively you can run the auto-generated executable located in the current working space manually from a terminal:
+.. _external_mode_settings:
 
-In case of Linux:
+Simulink External Mode ("Monitor & Tune") - Necessary Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+In case you are planning to execute with External Mode for "Monitor & Tuning", 
+it is also necessary to apply the following settings:
 
-.. code-block:: shell
+ * "Run external mode in a background thread".
+ * The Code interface packaging is "Nonreusable function".
+ * "MAT-file logging" is unchecked.
 
-    $ ./<simulink_model_name>
+.. figure:: _static/external_mode_background_thread.png
+    :align: center
+    :figclass: align-center
+    :scale: 50%
 
-or in case of Windows:
+    "Run external mode in a background thread" is necessary so that the 1kHz loop won't get disturbed
 
-.. code-block:: shell
+.. figure:: _static/model_settings_interface_non_reusable_function.png
+    :align: center
+    :figclass: align-center
+    :scale: 70%
 
-    > <simulink_model_name>.exe
+    "Nonreusable function option is required for building with External-Mode
+
+.. figure:: _static/model_settings_interface_mat_file_logging.png
+    :align: center
+    :figclass: align-center
+    :scale: 50%
+
+    "MAT-file logging" should be unchecked unchecked for building with External-Mode"
+
+MATLAB
+------
+
+Demo Pick & Place with RRT 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For familiarization with the Matlab API for the Franka Robot the `pick_and_place_with_RRT.mlx` demo is a good starting point. 
+
+.. figure:: _static/matlab_pick_and_place_with_RRT_demo.png
+    :align: center
+    :figclass: align^center
+
+    Live Matlab Script and Figure of the pick^and^place demo.
 
 Automatic error recovery
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 If the robot encounters an error state and transitions to reflex mode, 
 you may attempt a recovery by executing the automatic error recovery command in Matlab.
 
 .. code-block:: shell
 
-    >> fr = FrankaRobot(<robot ip as string>);
-    >> fr.automatic_error_recovery();
+    fr = FrankaRobot(<robot ip as string>);
+    fr.automatic_error_recovery();
 
 In case the command fails and the robot remains in the erroneous state try using the guiding mode to manually bring 
 back the robot to a valid configuration. 
 
 .. hint::
 
-    Checkout the :ref:`matlab library <matlab-library>` for a set of helper 
+    Checkout the :ref:`Franka library for MATLAB <matlab-library>` for a set of helper 
     functions that can help to optimize your workflow.
+