Merge pull request #22 from kvasios/dev-franka-matlab-toolbox-1.0.0

Dev franka matlab toolbox 1.0.0
frankaemika · Mar 11, 2024 · d82ae14 · d82ae14
2 parents 89c6e3b + d0169f0
commit d82ae14
Show file tree

Hide file tree

Showing 38 changed files with 344 additions and 302 deletions.
diff --git a/source/compatibility.rst b/source/compatibility.rst
@@ -41,7 +41,7 @@ and `Gripper version line 17
 <https://github.com/frankaemika/libfranka-common/blob/master/include/research_interface/gripper/types.h>`_
 are part of libfranka-common repository, a submodule of libfranka repository.
 
-Franka Matlab compatible versions are located :ref:`here<compatibility-franka-matlab>`.
+Franka MATLAB® compatible versions are located :ref:`here<compatibility-franka-matlab>`.
 
 .. caution::
     Franka Robotics currently does not provide any support for Windows or Arm

diff --git a/source/franka_matlab/CHANGELOG.md b/source/franka_matlab/CHANGELOG.md
@@ -1,46 +1,62 @@
-# Franka Matlab changelog
-
-## 0.3.1 (07-06-2023)
+# Changelog:
+
+## 1.0.0 (11-03-2024)
+
+   - **BREAKING** Robot Settings standardization with Matlab OOP.
+   - **BREAKING** Adding the option to set the rate limiter and the cutoff frequency in the apply control simulink block.
+   - **BREAKING** Removing the get initial robot state block from the simulink library.
+   - **BREAKING** Enhanced modular building structure for the Franka Simulink Library. Easy incorporation to larger projects and Harware Support Packages.
+   - **BREAKING** New Matlab object oriented API expressed based on the new `FrankaRobot()` class. Incorporation of existing Franka MATLAB functions as methods of the new API Class.
+   - **BREAKING** Removing all the "Panda" naming conventions. Replaced with "Franka Robot".
+   - **BREAKING** Franka MATLAB is now distributed as a Toolbox Matlab Add-On. No installation script needed.
+   - Fixing collision threshold setting bug.
+   - Oldest supported Matlab version is now the R2021a.
+   - Adding the option to set the Nominal End-Effector to End-Effector frame NE_T_EE in the Simulink Block "Apply Control".
+   - Expansion of the Matlab API with the new methods `gripper_state()`, `gripper_homing()`, `gripper_grasp()`, `gripper_move()` and `gripper_stop()` for controlling the Franka Gripper.
+   - Expansion of the Matlab API with the new method `joint_trajectory_motion()` for following precomputed joint trajectories.
+   - Creation of the new demo `pick_and_place_with_RRT.mlx` showcasing a workflow approach for the new Matlab API.
+
+## 0.3.1 (23-03-2023)
 
    - Bugfix. Properly setting the collision threshold values in Simulink.
 
-## 0.3.0 (31-09-2022)
+## 0.3.0 (20-09-2022)
 
-   - Windows 10 support (Experimental mainly due to the non Real-Time nature of the default Windows system).
+   - Windows 10 support (Experimental mainly due to the non-Real-Time nature of the default Windows system).
    - Project now relies on the leaner "Generic Real-Time" .tlc (grt.tlc) target framework.
    - Support for XCP communication protocol (vehicle network communication). Data inspector is now enabled!
-   - Support for "Run on custom Hardware" Simulink App for controlling the "Build-deploy-execute-connect" workflow.
-   - Project back-end overall simplification with modified rt_main.cpp for handling the external mode as a separate thread.
-   - **BREAKING** all the Franka Matlab functions are starting with the `franka_` prefix.
+   - Support for "Run on custom Hardware" Simulink App for controlling the "Build-deploy-execute-connect" workflow. 
+   - Project back-end overal simplification with modified rt_main.cpp for handling the external mode as a seperate thread.
+   - **BREAKING** all the Franka MATLAB functions are starting with the "`franka_`" prefix.
    - Expansion of Matlab library with the functions `franka_communication_test()`, `franka_joint_poses()`, `franka_robot_state()` and `franka_joint_point_to_point_motion()`.
    - Addition of the Simulink demo, "joint_impedance_control.slx".
-   - Fixing the bug when utilizing the Control Modes "Torque Control - X".
+   - Fixing the bug when utilizing the Control Modes "Torque Control - X`.
 
 ## 0.2.1 (29-04-2022)
 
-   - Adding support for all versions from Matlab2019a till Matlab2021a with libfranka 0.9.0.
+   - Adding supoort for all versions from Matlab2019a till Matlab2021a with libfranka 0.9.0.
 
 ## 0.2.0 (31-05-2021)
 
    - franka_matlab upgrade, supports Matlab2019a, Matlab2019b, Matlab2020a, Matlab2020b, Matlab2021a & libfranka 0.8.0.
 
 ## 0.1.1 (01-07-2020)
 
-   - Any dependencies that lead to source code linking for the Simulink Franka Library during mexing removed. That fixes the memory corruption
+   - Any dependences that lead to source code linking for the Simulink Franka Library during mexing removed. That fixes the memory corruption
      bug when shutting down Matlab.
-   - Simulink Franka Library sFunctions C++ and tlc implementations decoupled from src code necessary for automatic code gen. SRC Folder can be treated separately as a C++ project.
+   - Simulink Franka Library sFunctions C++ and tlc implementations decoupled from src code necessary for automatic code gen. SRC Folder can be treated seperately as a C++ project.
 
 ## 0.1.0 (21-01-2020)
-
+  
   - Features:
-    - **Simulink Library** for **Panda Robot**, includes the following blocks:
-        - **Franka Simulink Interface** for applying the desired control, plus additional parameters.
+    - **Simulink Library** for **Franka Robot**, includes the following blocks:
+        - **Franka Simulink Iterface** for applying the desired control, plus additional parameters.
         - **Read Initial Robot State** for reading initial values during the first execution step for any desirable signal. The set of the desired signals can be set through the mask in free text form.
         - **Read Robot State** for reading the values of any desirable signal during execution. The set of the desired signals can be set through the mask in free text form.
-        - **Panda Model** for reading the values of all Model parameters of the Panda Robot during execution.
+        - **Franka Model** for reading the values of all Model parameters of the Franka Robot during execution.
         - **Duration Period** for reading the current step, sample time. If communication is not secured during the 1ms, the block will return the value of 2ms or 3ms etc.
-        - **Gripper Read State** for reading the current values out of the Panda Gripper.
-    - **franka_emika_panda.tlc** & **franka_emika_panda_shrlib.tlc** custom linux targets, based on ert, that offer ext mode that is real time capable(package drop in case of main step frame loss).
+        - **Gripper Read State** for reading the current values out of the Franka Gripper.
+    - **franka_robot.tlc** & **franka_robot_shrlib.tlc** custom linux targets, based on ert, that offer ext mode that is real time capable(package drop in case of main step frame loss).
     - **Matlab Library**(Experimental, limited support), includes the following command:
         - **automatic_error_recovery(robot_ip)**. Execute through a matlab command line for getting automatically out of an error state.
     - **Simulink Library misc**(Experimental, limited support) that includes a set of UI buttons with callback scripts with the potential to automate some of the dev. workflow.
diff --git a/source/franka_matlab/_static/apply_control.png b/source/franka_matlab/_static/apply_control.png
diff --git a/source/franka_matlab/_static/apply_control_settings.png b/source/franka_matlab/_static/apply_control_settings.png
diff --git a/source/franka_matlab/_static/block_parameters_apply_control.png b/source/franka_matlab/_static/block_parameters_apply_control.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_hardware.png b/source/franka_matlab/_static/cartesian_impedance_control_hardware.png
diff --git a/source/franka_matlab/_static/demos_files.png b/source/franka_matlab/_static/demos_files.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/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_model.png b/source/franka_matlab/_static/get_model.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/get_robot_state_init.png b/source/franka_matlab/_static/get_robot_state_init.png
diff --git a/source/franka_matlab/_static/get_robot_state_settings.png b/source/franka_matlab/_static/get_robot_state_settings.png
diff --git a/source/franka_matlab/_static/matlab_command_window_error_message.png b/source/franka_matlab/_static/matlab_command_window_error_message.png
diff --git a/source/franka_matlab/_static/matlab_pick_and_place_with_RRT_demo.png b/source/franka_matlab/_static/matlab_pick_and_place_with_RRT_demo.png
diff --git a/source/franka_matlab/_static/simulink_apps_pane.png b/source/franka_matlab/_static/simulink_apps_pane.png
diff --git a/source/franka_matlab/_static/simulink_hardware_pane.png b/source/franka_matlab/_static/simulink_hardware_pane.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/_static/simulink_model_apply_control_only.png b/source/franka_matlab/_static/simulink_model_apply_control_only.png
diff --git a/source/franka_matlab/_static/simulink_model_apply_control_only_build_error.png b/source/franka_matlab/_static/simulink_model_apply_control_only_build_error.png
diff --git a/source/franka_matlab/_static/simulink_model_apply_control_only_fix.png b/source/franka_matlab/_static/simulink_model_apply_control_only_fix.png
diff --git a/source/franka_matlab/_static/simulink_view_diagnostics.png b/source/franka_matlab/_static/simulink_view_diagnostics.png
diff --git a/source/franka_matlab/_static/simulink_view_errors.png b/source/franka_matlab/_static/simulink_view_errors.png
diff --git a/source/franka_matlab/_static/workspace_parameters.png b/source/franka_matlab/_static/workspace_parameters.png
diff --git a/source/franka_matlab/compatibility.rst b/source/franka_matlab/compatibility.rst
@@ -3,22 +3,32 @@ Compatible versions
 
 .. _compatibility-franka-matlab:
 
-+-----------------------+-------------------+----------------------------+
-| Franka Matlab version | libfranka version | Matlab Version             |
-+=======================+===================+============================+
-| 0.3.0                 | 0.9.x & 0.10.x    | :math:`\geq` R2019a        |
-+-----------------------+-------------------+----------------------------+
-| 0.2.1                 | 0.9.x             | R2019a to R2021a           |
-+-----------------------+-------------------+----------------------------+
-| 0.2.0                 | 0.8.0             | R2019a to R2021a           |
-+-----------------------+-------------------+----------------------------+
-| 0.1.1                 | 0.7.1             | R2019a                     |
-+-----------------------+-------------------+----------------------------+
-| 0.1.0                 | 0.7.1             | R2019a                     |
-+-----------------------+-------------------+----------------------------+
+Compatibility with Matlab & libfranka
+-------------------------------------
+
++------------------------+-------------------+----------------------------+
+| Franka MATLAB version  | libfranka version | Matlab Version             |
++========================+===================+============================+
+| 1.0.0                  | 0.9.x & 0.13.x    | :math:`\geq` R2021a        |
++------------------------+-------------------+----------------------------+ 
+| 0.3.1                  | 0.9.x & 0.10.x    | :math:`\geq` R2019a        |
++------------------------+-------------------+----------------------------+ 
+| 0.3.0                  | 0.9.x & 0.10.x    | :math:`\geq` R2019a        |
++------------------------+-------------------+----------------------------+ 
+| 0.2.1                  | 0.9.x             | R2019a to R2021a           |
++------------------------+-------------------+----------------------------+
+| 0.2.0                  | 0.8.0             | R2019a to R2021a           |
++------------------------+-------------------+----------------------------+
+| 0.1.1                  | 0.7.1             | R2019a                     |
++------------------------+-------------------+----------------------------+
+| 0.1.0                  | 0.7.1             | R2019a                     |
++------------------------+-------------------+----------------------------+
 
 `libfranka and robot system compatibility <https://frankaemika.github.io/docs/compatibility.html>`_
 
 .. important::
-    Make sure that you've installed and set up Matlab with a compatible compiler version! You can find the list of
-    compatible compilers to Matlab in `this link <https://www.mathworks.com/support/requirements/supported-compilers.html>`_.
+    The `pick_and_place_with_RRT.mlx` Matlab demo is compatible with Matlab :math:`\geq` R2021b, as the required libraries from the Matlab Robotics Toolbox have only introduced since then.
+
+.. important::
+    Make sure that you've installed and set up Matlab with a compatible compiler version! You can find the list of Matlab 
+    compatible compilers in `this link <https://www.mathworks.com/support/requirements/supported-compilers.html>`_.
diff --git a/source/franka_matlab/conf.py b/source/franka_matlab/conf.py
@@ -43,7 +43,7 @@
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffixes as a list of string:
+# You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
@@ -52,8 +52,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'Franka Control Interface (FCI)'
-copyright = '2023, Franka Robotics GmbH'
+project = 'Franka MATLAB Toolbox'
+copyright = '2024, Franka Robotics GmbH'
 author = 'Franka Robotics GmbH'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -74,7 +74,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This patterns also affect to html_static_path and html_extra_path
+# This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.

diff --git a/source/franka_matlab/franka_matlab_changelog.rst b/source/franka_matlab/franka_matlab_changelog.rst
@@ -1,2 +1,6 @@
-.. include:: ./CHANGELOG.md
+Franka MATLAB Toolbox changelog
+================================
+
+.. include:: ../franka_matlab/CHANGELOG.md
    :parser: myst_parser.sphinx_
+   :start-line: 2
diff --git a/source/franka_matlab/getting_started.rst b/source/franka_matlab/getting_started.rst
@@ -4,93 +4,85 @@ Getting started
 Overview
 --------
 
-In the demos folder a set of Simulink examples with various implementations is located. Feel free to experiment, adjust
+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!
 
-.. figure:: _static/demos_files.png
+You can navigate through the examples by typing: 
+
+.. code-block:: shell
+
+    >> franka_matlab_toolbox_examples();
+
+.. figure:: _static/franka_matlab_toolbox_examples.png
     :align: center
     :figclass: align-center
 
-    Simulink Demos from franka_matlab.
+    Franka MATLAB Toolbox Examples Navigator.
 
 Initialization
 --------------
 
-After opening, double clicking on any of the simulink models a set of parameters will be loaded automatically in the
-workspace.
+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`.
 
 .. hint::
 
-    The Simulink models are delivered in R2019a version. They will convert automatically to your Matlab version
-    when you try to save the model.
+    The Simulink models are delivered in R2021a version. They will convert automatically to your Matlab version 
+    when you try to save the model. 
 
 .. figure:: _static/workspace_parameters.png
     :align: center
     :figclass: align-center
 
-    Working space after loading a Simulink demo.
+    The Franka Robot Settings object.
 
-The robot_ip is set to 172.16.0.2 by default after loading the demos. Make sure that the robot_ip parameters matches your
-setup, either by modifying it in the `demos/demos_common_config.m` matlab script file or from the cmd line after the
-simulink demo is loaded, like:
+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
 
-    >> robot_ip = <your robot ip string>
+    >> frs.robot_ip = <your robot ip string>
 
-At this point we can start the building & deployment of the Simulink model.
+You can modify the default settings for the FrankaRobotSettings with
 
-Execution
----------
+.. code-block:: shell
 
-.. hint::
+    >> edit FrankaRobotSettings.m
 
-    The current workflow presented is utilizing the "Run on Custom Hardware" Simulink App, present in Matlab versions
-    :math:`\geq` R2020a. In case of Matlab 2019a you can build the model normally by using the "Build Model" button.
-    You then need to run the executable from a terminal as described below.
+Execution
+---------
 
 Let's start by selecting the `Run on custom hardware` App from the Apps pane in Simulink.
 
-.. figure:: _static/simulink_apps_pane.png
+.. figure:: _static/cartesian_impedance_control_apps.png
     :align: center
     :figclass: align-center
 
-    Run on custom hardware Simulink App.
+    "Run on custom hardware" Simulink App.
 
 .. important::
 
-    Before executing make sure that the brakes of the robot are disengaged and that the robot is in execution mode!
+    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 then select from the Hardware tab either `Monitor & Tune` in case monitoring through the external mode is
+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.
 
-.. figure:: _static/simulink_hardware_pane.png
+.. figure:: _static/cartesian_impedance_control_hardware.png
     :align: center
     :figclass: align-center
 
     Hardware Simulink App.
 
-For running the generated executable manually from a terminal make sure that you've first exported the full libfranka
-build path, in case of Linux:
-
-.. code-block:: shell
-
-    >> $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<libfranka build folder full path>
-
-or in case of Windows, that you've included the full path of libfranka build directory in the PATH environment variable.
-
-.. hint::
-
-    As a reminder, in case of a robot with system version 4.2.0 or greater, the FCI control mode needs to be explicitly enabled through Desk --> Sidebar menu --> Activate FCI.
-
 .. caution::
 
     The robot will move! Make sure that you are monitoring the situation, ready to take action if necessary!
 
-You can then run the executable, which is located in the current working space.
+Alternatively you can run the auto-generated executable located in the current working space manually from a terminal:
 
 In case of Linux:
 
+
 .. code-block:: shell
 
     $ ./<simulink_model_name>
@@ -101,45 +93,20 @@ or in case of Windows:
 
     > <simulink_model_name>.exe
 
-You can manually choose the simple tcpip from the Simulink model settings.
-
 Automatic error recovery
 ------------------------
-
-.. figure:: _static/simulink_view_diagnostics.png
-    :align: center
-    :figclass: align-center
-
-    View diagnostic messages during runtime in Simulink.
-
-.. figure:: _static/simulink_view_errors.png
-    :align: center
-    :figclass: align-center
-
-    View error messages in Simulink.
-
-.. figure:: _static/matlab_command_window_error_message.png
-    :align: center
-    :figclass: align-center
-
-    Error message displayed in Matlab Command Window.
-
-.. figure:: _static/terminal_error_message.png
-    :align: center
-    :figclass: align-center
-
-    Error message displayed in terminal in case of manual execution.
-
-If the robot encounters an error state and transitions to reflex mode, you may attempt to recover by executing the `franka_automatic_error_recovery` command in Matlab.
+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
 
-    >> franka_automatic_error_recovery(<robot ip string>);
+    >> 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.
+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:`matlab library <matlab-library>` for a set of helper 
     functions that can help to optimize your workflow.