├── .devcontainer └── devcontainer.json ├── .editorconfig ├── .github └── workflows │ └── deploy.yml ├── .gitignore ├── .gitmodules ├── .travis.yml ├── CHANGELOG.md ├── Dockerfile ├── Jenkinsfile ├── LICENSE ├── Makefile ├── NOTICE ├── README.md ├── docker-compose.yml ├── entrypoint.sh ├── requirements.txt └── source ├── _static ├── FrankaUI_Settings_Bar.png ├── FrankaUI_Settings_Network.png ├── FrankaUI_System_ActivateFCI.png ├── FrankaUI_System_ActivateFCI_Confirm.png ├── FrankaUI_System_ActivateFCI_Done.png ├── accessing-admin.png ├── activate_fci.png ├── collision-coarse.png ├── collision-fine.png ├── compatibility_data.py ├── compatibility_data │ ├── FER.csv │ └── FR3.csv ├── control-static-ip.png ├── control.png ├── dh-diagram-frankarobotics.png ├── edit-connections.png ├── favicon.png ├── fci-architecture-non-realtime.png ├── fci-architecture.png ├── frames.svg ├── franka-gazebo-example-grasp.png ├── franka-gazebo-example.png ├── generate_compatibility_js.py ├── libfranka-architecture.png ├── logo.svg ├── move-groups.png ├── overview.png ├── pbv_equations_max.svg ├── pbv_equations_min.svg ├── pbv_limits_j1.svg ├── pbv_limits_j2.svg ├── pbv_limits_j3.svg ├── pbv_limits_j4.svg ├── pbv_limits_j5.svg ├── pbv_limits_j6.svg ├── pbv_limits_j7.svg ├── pop_up_fci.png ├── ros-architecture.png ├── rt-interfaces.png ├── rt-loop.png ├── static-ip-ubuntu.png ├── style_override.css ├── visual.png └── vscode.png ├── compatibility.rst ├── conf.py ├── control-parameters-joint-fr3-rectangular.csv ├── control-parameters-joint-fr3.csv ├── control-parameters-joint-panda.csv ├── control_parameters.rst ├── faq.rst ├── fr3-certification-remarks.csv ├── fr3-certification-remarks.rst ├── franka_matlab ├── CHANGELOG.md ├── _static │ ├── ai_companion_jetson_trouble.png │ ├── block_parameters_robot_control.png │ ├── board_parameters.png │ ├── cartesian_impedance_control_apps.png │ ├── cartesian_impedance_control_hardware.png │ ├── cartesian_impedance_control_overview.png │ ├── cartesian_impedance_control_run_on_hardware.png │ ├── coriolis.png │ ├── demos_files.png │ ├── duration.png │ ├── external_mode_background_thread.png │ ├── favicon.png │ ├── franka_matlab_toolbox_examples.png │ ├── franka_toolbox_uninstall.png │ ├── get_model.png │ ├── get_robot_state.png │ ├── get_robot_state_init.png │ ├── get_robot_state_init_settings.png │ ├── get_robot_state_settings.png │ ├── gravity.png │ ├── gripper_state.png │ ├── hardware_config_options.png │ ├── hardware_settings.png │ ├── init_script_install_libfranka.png │ ├── interface_pane.png │ ├── jacobian.png │ ├── jetson_config_c++11.png │ ├── jetson_deploy.png │ ├── linux_host_hardware_implementation.png │ ├── logo.svg │ ├── mass_matrix.png │ ├── matlab_pick_and_place_with_RRT_demo.png │ ├── model_settings_interface_mat_file_logging.png │ ├── model_settings_interface_non_reusable_function.png │ ├── pose.png │ ├── robot_control.png │ ├── select_nvidia_jetson.png │ ├── simulink_library_browser.png │ ├── simulink_model_apply_control_only.png │ ├── simulink_model_apply_control_only_build_error.png │ ├── simulink_model_apply_control_only_fix.png │ ├── simulink_view_diagnostics.png │ ├── style_override.css │ ├── terminal_error_message.png │ └── workspace_parameters.png ├── compatibility.rst ├── conf.py ├── franka_matlab_changelog.rst ├── getting_started.rst ├── index.rst ├── installation.rst ├── matlab_library.rst ├── simulink_library.rst ├── system_requirements.rst └── troubleshooting.rst ├── franka_ros.rst ├── franka_ros2.rst ├── getting_started.rst ├── index.rst ├── installation_linux.rst ├── libfranka.rst ├── overview.rst ├── redirects ├── requirements.rst └── troubleshooting.rst /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "GitHub Documentation Development Container", 3 | "privileged": true, 4 | "remoteUser": "user", 5 | "dockerComposeFile": "../docker-compose.yml", 6 | "service": "documentation", 7 | "workspaceFolder": "/workspace", 8 | "initializeCommand": "echo \"USER_UID=$(id -u $USER)\nUSER_GID=$(id -g $USER)\" > .env", 9 | "customizations": { 10 | "vscode": { 11 | "extensions": [ 12 | "ms-python.python", 13 | "ms-python.vscode-pylance" 14 | ], 15 | "settings": { 16 | "terminal.integrated.defaultProfile.linux": "bash", 17 | "terminal.integrated.profiles.linux": { 18 | "bash": { 19 | "path": "/bin/bash" 20 | } 21 | } 22 | } 23 | } 24 | } 25 | } -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | charset = utf-8 5 | end_of_line = lf 6 | indent_style = space 7 | insert_final_newline = true 8 | trim_trailing_whitespace = true 9 | 10 | [Makefile] 11 | indent_style = tab 12 | 13 | [*.py] 14 | indent_size = 4 15 | 16 | [*.rst] 17 | max_line_length = 150 18 | 19 | [compatibility.rst] 20 | max_line_length = 165 21 | 22 | [control_parameters.rst] 23 | max_line_length = 170 24 | 25 | [installation_linux.rst] 26 | max_line_length = 150 27 | 28 | [franka_ros2.rst] 29 | max_line_length = 151 30 | 31 | [troubleshooting.rst] 32 | max_line_length = 151 33 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: deploy 2 | 3 | # Controls when the workflow will run 4 | on: 5 | # Triggers the workflow on push events but only for the master branch 6 | push: 7 | branches: [ master ] 8 | 9 | # Allows you to run this workflow manually from the Actions tab 10 | workflow_dispatch: 11 | 12 | jobs: 13 | publish: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - 17 | name: Checkout 18 | uses: actions/checkout@v2 19 | with: 20 | submodules: recursive 21 | - 22 | name: Install 23 | run: pip install -r requirements.txt 24 | - 25 | name: Build 26 | run: make html 27 | - 28 | name: Nojekyll 29 | run: touch build/html/.nojekyll 30 | - 31 | name: Deploy to GitHub Pages 32 | if: success() 33 | uses: crazy-max/ghaction-github-pages@v2 34 | with: 35 | target_branch: gh-pages 36 | build_dir: build/html 37 | env: 38 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 39 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /build 2 | /node_modules 3 | .vscode 4 | package-lock.json 5 | .env 6 | __pycache__ 7 | source/_static/compatibility_data.js -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "libfranka"] 2 | path = libfranka 3 | url = https://github.com/frankaemika/libfranka 4 | [submodule "franka_ros"] 5 | path = franka_ros 6 | url = https://github.com/frankaemika/franka_ros 7 | [submodule "franka_ros2"] 8 | path = franka_ros2 9 | url = https://github.com/frankaemika/franka_ros2.git 10 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | 3 | python: 3.5 4 | 5 | install: 6 | - pip install -r requirements.txt 7 | - npm install eclint 8 | 9 | script: 10 | - node $(npm bin)/eclint check source/*.rst 11 | - make html 12 | 13 | after_success: 14 | - touch build/html/.nojekyll 15 | 16 | deploy: 17 | provider: pages 18 | skip_cleanup: true 19 | github_token: $GITHUB_TOKEN 20 | local_dir: build/html 21 | on: 22 | branch: master 23 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 0.5.0 4 | - Updated links to libfranka documenation 5 | - doc: update docu for 5.7.2 6 | - fix: update docker 7 | - doc: Update build instructions 8 | 9 | ## 0.4.0 10 | - Updated compatibility matrix for **5.7.x** + libfranka **0.14.x** 11 | - Updated **franka_ros2** version with adding content about Gazebo 12 | - Updated version of **franka_matlab** 13 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM ubuntu:22.04 2 | 3 | # Set environment variables 4 | ENV DEBIAN_FRONTEND=noninteractive \ 5 | LANG=C.UTF-8 \ 6 | LC_ALL=C.UTF-8 7 | 8 | ARG USER_UID=1001 9 | ARG USER_GID=1001 10 | ARG USERNAME=user 11 | 12 | RUN --mount=type=cache,target=/var/cache/apt \ 13 | apt-get update && \ 14 | apt-get install -y --no-install-recommends \ 15 | bash \ 16 | bash-completion \ 17 | git \ 18 | build-essential \ 19 | npm \ 20 | ssh-client \ 21 | sudo \ 22 | vim \ 23 | python3-pip \ 24 | python3-wheel \ 25 | python3-setuptools \ 26 | && apt-get clean \ 27 | && rm -rf /var/lib/apt/lists/* 28 | 29 | RUN pip3 install --ignore-installed --no-cache-dir \ 30 | sphinx==5.1.1 \ 31 | sphinx-rtd-theme==1.0.0 \ 32 | sphinx-reredirects==0.1.1 \ 33 | myst-parser==0.18.0 \ 34 | "docutils<0.18" 35 | 36 | WORKDIR /workspace 37 | 38 | # Setup user configuration 39 | RUN groupadd --gid $USER_GID $USERNAME \ 40 | && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME \ 41 | && echo "$USERNAME ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers \ 42 | && chown $USERNAME:$USERNAME /workspace 43 | 44 | USER $USERNAME 45 | 46 | COPY entrypoint.sh / 47 | CMD [ "/bin/bash" ] 48 | ENTRYPOINT [ "/entrypoint.sh" ] 49 | -------------------------------------------------------------------------------- /Jenkinsfile: -------------------------------------------------------------------------------- 1 | pipeline { 2 | agent { dockerfile true } 3 | triggers { 4 | pollSCM('H/5 * * * *') 5 | } 6 | stages { 7 | stage('Notify Stash') { 8 | steps { 9 | script { 10 | notifyBitbucket() 11 | } 12 | } 13 | } 14 | stage('Build & Check') { 15 | environment { 16 | HOME="${env.WORKSPACE}" 17 | } 18 | stages { 19 | stage('Install dependencies') { 20 | steps { 21 | sh 'npm install eclint@2.8.1' 22 | sh 'pip3 install --user --upgrade -r requirements.txt' 23 | sh 'make clean' 24 | } 25 | } 26 | stage('Build HTML') { 27 | steps { 28 | sh 'make html' 29 | publishHTML([allowMissing: false, 30 | alwaysLinkToLastBuild: false, 31 | keepAll: true, 32 | reportDir: 'build/html', 33 | reportFiles: 'index.html', 34 | reportName: 'FCI Documentation']) 35 | } 36 | } 37 | stage('Run linter') { 38 | steps { 39 | sh 'node $(npm bin)/eclint check source/*.rst' 40 | sh 'make linkcheck' 41 | } 42 | } 43 | } 44 | } 45 | } 46 | post { 47 | always { 48 | cleanWs() 49 | script { 50 | notifyBitbucket() 51 | } 52 | } 53 | } 54 | } -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = python3 -msphinx 7 | SPHINXPROJ = research-interface 8 | SOURCEDIR = source 9 | BUILDDIR = build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile clean html 16 | 17 | # Generate compatibility data JavaScript file 18 | generate-js: 19 | @chmod +x $(SOURCEDIR)/_static/generate_compatibility_js.py 20 | @$(SOURCEDIR)/_static/generate_compatibility_js.py 21 | 22 | # Clean build directory 23 | clean: 24 | rm -rf $(BUILDDIR)/* 25 | 26 | # Custom html target that first generates JS 27 | html: generate-js 28 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 29 | 30 | # Catch-all target: route all unknown targets to Sphinx using the new 31 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 32 | %: Makefile 33 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 34 | -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | docs 2 | 3 | Copyright 2023 Franka Robotics GmbH 4 | 5 | Licensed under the Apache License, Version 2.0 (the "License"); 6 | you may not use this file except in compliance with the License. 7 | You may obtain a copy of the License at 8 | 9 | http://www.apache.org/licenses/LICENSE-2.0 10 | 11 | Unless required by applicable law or agreed to in writing, software 12 | distributed under the License is distributed on an "AS IS" BASIS, 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | See the License for the specific language governing permissions and 15 | limitations under the License. 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # docs: Franka Control Interface (FCI) documentation source 2 | 3 | [![Build Status][travis-status]][travis] 4 | 5 | To build the documentation, first build the container, then execute: 6 | 7 | make html 8 | 9 | ## License 10 | 11 | The source code and generated documents are licensed under the [Apache 2.0 license][apache-2.0]. 12 | 13 | [apache-2.0]: https://www.apache.org/licenses/LICENSE-2.0.html 14 | [travis-status]: https://travis-ci.org/frankaemika/docs.svg?branch=master 15 | [travis]: https://travis-ci.org/frankaemika/docs 16 | -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | services: 2 | documentation: 3 | build: 4 | context: . 5 | dockerfile: Dockerfile 6 | args: 7 | - USER_UID=${USER_UID} 8 | - USER_GID=${USER_GID} 9 | container_name: documentation 10 | network_mode: "host" 11 | command: /bin/bash 12 | tty: true 13 | stdin_open: true 14 | volumes: 15 | - ./:/workspace 16 | - ~/.ssh:/home/user/.ssh 17 | - /tmp/.X11-unix:/tmp/.X11-unix 18 | environment: 19 | QT_X11_NO_MITSHM: 1 20 | DISPLAY: $DISPLAY 21 | cap_add: 22 | - SYS_NICE 23 | ulimits: 24 | rtprio: 99 25 | rttime: -1 26 | memlock: 8428281856 27 | -------------------------------------------------------------------------------- /entrypoint.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | git submodule update --init --recursive && \ 4 | make html 5 | 6 | if [ "$#" -gt 0 ]; then 7 | exec "$@" 8 | fi 9 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx==5.1.1 2 | sphinx-rtd-theme==1.0.0 3 | sphinx-reredirects==0.1.1 4 | myst-parser==0.18.0 5 | docutils<0.18 6 | -------------------------------------------------------------------------------- /source/_static/FrankaUI_Settings_Bar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/FrankaUI_Settings_Bar.png -------------------------------------------------------------------------------- /source/_static/FrankaUI_Settings_Network.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/FrankaUI_Settings_Network.png -------------------------------------------------------------------------------- /source/_static/FrankaUI_System_ActivateFCI.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/FrankaUI_System_ActivateFCI.png -------------------------------------------------------------------------------- /source/_static/FrankaUI_System_ActivateFCI_Confirm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/FrankaUI_System_ActivateFCI_Confirm.png -------------------------------------------------------------------------------- /source/_static/FrankaUI_System_ActivateFCI_Done.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/FrankaUI_System_ActivateFCI_Done.png -------------------------------------------------------------------------------- /source/_static/accessing-admin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/accessing-admin.png -------------------------------------------------------------------------------- /source/_static/activate_fci.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/activate_fci.png -------------------------------------------------------------------------------- /source/_static/collision-coarse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/collision-coarse.png -------------------------------------------------------------------------------- /source/_static/collision-fine.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/collision-fine.png -------------------------------------------------------------------------------- /source/_static/compatibility_data.py: -------------------------------------------------------------------------------- 1 | """Compatibility data for different robot versions.""" 2 | 3 | import os 4 | import csv 5 | from pathlib import Path 6 | 7 | 8 | def read_csv_data(file_path): 9 | """Read CSV file and return headers and data.""" 10 | print(f"Reading CSV file: {file_path}") 11 | with open(file_path, "r", encoding="utf-8") as f: 12 | reader = csv.reader(f) 13 | headers = next(reader) # First row contains headers 14 | data = [row for row in reader] 15 | print(f"Headers: {headers}") 16 | print(f"Data: {data}") 17 | return headers, data 18 | 19 | 20 | def load_compatibility_data(): 21 | """Load compatibility data from CSV files.""" 22 | data_dir = Path(__file__).parent / "compatibility_data" 23 | print(f"Looking for CSV files in: {data_dir}") 24 | compatibility_data = {} 25 | 26 | # Map of robot types to their CSV files 27 | robot_files = {"FR3": "FR3.csv", "FER": "FER.csv"} 28 | 29 | for robot, filename in robot_files.items(): 30 | file_path = data_dir / filename 31 | print(f"Checking for file: {file_path}") 32 | if file_path.exists(): 33 | print(f"Found file for {robot}") 34 | headers, data = read_csv_data(file_path) 35 | compatibility_data[robot] = {"headers": headers, "data": data} 36 | else: 37 | print(f"File not found for {robot}") 38 | 39 | print(f"Final compatibility data: {compatibility_data}") 40 | return compatibility_data 41 | 42 | 43 | # Load the compatibility data when the module is imported 44 | COMPATIBILITY_DATA = load_compatibility_data() 45 | -------------------------------------------------------------------------------- /source/_static/compatibility_data/FER.csv: -------------------------------------------------------------------------------- 1 | Robot System Version,libfranka Version,Robot/Gripper Server,franka_ros Version,Ubuntu / ROS 1 2 | >= 4.2.1,>= 0.9.1 < 0.10.0,5 / 3,>= 0.8.0,20.04 / noetic 3 | >= 4.0.0,>= 0.8.0,4 / 3,>= 0.8.0,20.04 / noetic 4 | >= 3.0.0,0.7.1,3 / 3,0.7.0,18.04 / melodic 5 | >= 1.3.0,0.5.0,3 / 2,0.6.0,16.04 / kinetic 6 | >= 1.2.0,0.3.0,2 / 2,0.4.0,16.04 / kinetic 7 | >= 1.1.0,0.2.0,2 / 1,, -------------------------------------------------------------------------------- /source/_static/compatibility_data/FR3.csv: -------------------------------------------------------------------------------- 1 | Robot System Version,libfranka Version,Robot/Gripper Server,franka_ros2 Version,Ubuntu / ROS 2,franka_ros Version 2 | >= 5.7.2,>= 0.15.0,9 / 3,>= v1.0.0,22.04 / humble,>= 0.10.0 3 | >= 5.7.0,">= 0.14.1 to < 0.15.0",8 / 3,>= v0.1.15,22.04 / humble,>= 0.10.0 4 | >= 5.5.0,">= 0.13.3 to < 0.14.1",7 / 3,">= v0.1.15",22.04 / humble,>= 0.10.0 5 | >= 5.2.0,">= 0.10.0 to < 0.13.3",6 / 3,">= v0.1.0 to >= v0.1.8",22.04 / humble,>= 0.10.0 -------------------------------------------------------------------------------- /source/_static/control-static-ip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/control-static-ip.png -------------------------------------------------------------------------------- /source/_static/control.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/control.png -------------------------------------------------------------------------------- /source/_static/dh-diagram-frankarobotics.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/dh-diagram-frankarobotics.png -------------------------------------------------------------------------------- /source/_static/edit-connections.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/edit-connections.png -------------------------------------------------------------------------------- /source/_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/favicon.png -------------------------------------------------------------------------------- /source/_static/fci-architecture-non-realtime.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/fci-architecture-non-realtime.png -------------------------------------------------------------------------------- /source/_static/fci-architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/fci-architecture.png -------------------------------------------------------------------------------- /source/_static/frames.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 5 | 6 | 7 | 22 | 24 | 25 | 27 | image/svg+xml 28 | 30 | 31 | 32 | 33 | 35 | 55 | 59 | G 61 | 67 | 68 | 71 | panda_link8 73 | 81 | <arm_id>_link8 90 | Flange Frame 98 | 99 | 100 | 103 | panda_hand 105 | 113 | <arm_id>_hand 122 | <arm_id>link8 rotated by -45 degree around Z-axis 130 | 131 | 132 | 135 | panda_link8->panda_hand 137 | 142 | 147 | transform defined in URDF 155 | 156 | 157 | 160 | panda_NE 162 | 170 | <arm_id>_NE 179 | Nominal End-Effector Frame 187 | 188 | 189 | 192 | panda_link8->panda_NE 194 | 199 | 204 | transform defined in Desk 212 | 213 | 214 | 217 | panda_hand_tcp 219 | 226 | <arm_id>_hand_tcp 235 | Frame between the fingers of the hand 243 | Is equal to <arm_id>_NE if the end-effector 251 | was set to 'Franka Hand' inside Desk 259 | 270 | (can be changed by passing 'tcp_xyz' & 'tcp_rpy') 276 | 277 | 278 | 281 | panda_hand->panda_hand_tcp 283 | 288 | 293 | transform defined in URDF 301 | 302 | 303 | 306 | panda_EE 308 | 316 | <arm_id>_EE 325 | End-Effector Frame 333 | Used for Cartesian Pose interface and inverse kinematics 341 | Equal to <arm_id>_NE by default 349 | 350 | 351 | 354 | panda_NE->panda_EE 356 | 361 | 366 |  transform defined via set_EE_frame 374 | 375 | 376 | 379 | panda_K 381 | 389 | <arm_id>_K 398 | Stiffness frame K 406 | Used for measuring forces 414 | Equal to <arm_id>_EE by default 422 | 423 | 424 | 427 | panda_EE->panda_K 429 | 434 | 439 |  transform defined via set_K_frame 447 | 448 | 449 | 450 | -------------------------------------------------------------------------------- /source/_static/franka-gazebo-example-grasp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/franka-gazebo-example-grasp.png -------------------------------------------------------------------------------- /source/_static/franka-gazebo-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/franka-gazebo-example.png -------------------------------------------------------------------------------- /source/_static/generate_compatibility_js.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Script to generate JavaScript compatibility data file from CSV files. 4 | This script reads CSV files containing compatibility information for different robot types 5 | and generates a JavaScript file with the data structured for use in the documentation. 6 | """ 7 | 8 | import os 9 | import csv 10 | import json 11 | from pathlib import Path 12 | 13 | 14 | def read_csv_file(file_path): 15 | """Read a CSV file and return headers and data.""" 16 | with open(file_path, "r") as f: 17 | reader = csv.reader(f) 18 | headers = next(reader) # First row contains headers 19 | data = [row for row in reader] 20 | return headers, data 21 | 22 | 23 | def generate_js(): 24 | """Generate JavaScript file with compatibility data.""" 25 | # Directory containing CSV files 26 | csv_dir = Path("source/_static/compatibility_data") 27 | 28 | # Dictionary to store compatibility data 29 | compatibility_data = {} 30 | 31 | # Map of file names to display names 32 | robot_display_names = {"FR3": "Franka Research 3", "FER": "FER"} 33 | 34 | # Read each CSV file in the directory 35 | for csv_file in csv_dir.glob("*.csv"): 36 | robot_type = csv_file.stem # Get filename without extension 37 | headers, data = read_csv_file(csv_file) 38 | display_name = robot_display_names.get(robot_type, robot_type) 39 | compatibility_data[display_name] = {"headers": headers, "data": data} 40 | 41 | # Robot descriptions 42 | robot_descriptions = { 43 | "Franka Research 3": "Latest generation Franka Robot with ROS 2 support", 44 | "FER": "Previous generation Franka Emika Robot", 45 | } 46 | 47 | # Generate JavaScript content 48 | js_content = f"""// Generated compatibility data 49 | const compatibilityData = {json.dumps(compatibility_data, indent=2)}; 50 | 51 | // Robot descriptions 52 | const robotDescriptions = {json.dumps(robot_descriptions, indent=2)}; 53 | """ 54 | 55 | # Write to JavaScript file 56 | js_file_path = Path("source/_static/compatibility_data.js") 57 | with open(js_file_path, "w") as f: 58 | f.write(js_content) 59 | 60 | 61 | if __name__ == "__main__": 62 | generate_js() 63 | -------------------------------------------------------------------------------- /source/_static/libfranka-architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/libfranka-architecture.png -------------------------------------------------------------------------------- /source/_static/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | -------------------------------------------------------------------------------- /source/_static/move-groups.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/move-groups.png -------------------------------------------------------------------------------- /source/_static/overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/overview.png -------------------------------------------------------------------------------- /source/_static/pop_up_fci.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/pop_up_fci.png -------------------------------------------------------------------------------- /source/_static/ros-architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/ros-architecture.png -------------------------------------------------------------------------------- /source/_static/rt-interfaces.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/rt-interfaces.png -------------------------------------------------------------------------------- /source/_static/rt-loop.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/rt-loop.png -------------------------------------------------------------------------------- /source/_static/static-ip-ubuntu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/static-ip-ubuntu.png -------------------------------------------------------------------------------- /source/_static/style_override.css: -------------------------------------------------------------------------------- 1 | .wy-table-responsive table td { 2 | white-space: normal !important; 3 | } 4 | 5 | /* Switch order of project name and logo in sidebar */ 6 | body > div > nav > div > div.wy-side-nav-search > a { 7 | display: flex !important; 8 | justify-content: center !important; 9 | flex-direction: column-reverse !important; 10 | } 11 | 12 | /* Smaller logo, adjust margins after reordering with project name */ 13 | body > div.wy-grid-for-nav > nav > div > div.wy-side-nav-search > a > img { 14 | width: 85% !important; 15 | margin-bottom: 0.85em !important; 16 | margin-top: 0 !important; 17 | } 18 | 19 | /* Remove home icon in sidebar */ 20 | body > div.wy-grid-for-nav > nav > div > div.wy-side-nav-search > a::before { 21 | content: "" !important; 22 | } 23 | 24 | /* Change style of search form in sidebar */ 25 | .wy-side-nav-search input[type="text"] { 26 | width: 90% !important; 27 | border: 0 !important; 28 | border-radius: 3px !important; 29 | } 30 | 31 | /* Use text font for headings */ 32 | h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { 33 | font-family: "Lato", "proxima-nova", "Helvetica Neue", Arial, sans-serif !important; 34 | } 35 | 36 | /* Use "Brand light blue" for ToC heading */ 37 | body > div.wy-grid-for-nav > nav > div > div.wy-menu.wy-menu-vertical > p > span { 38 | color: #00b9eb !important; 39 | } 40 | 41 | /* Use "Brand dark blue" for top of sidebar */ 42 | .wy-side-nav-search { 43 | background-color: #1a282d !important; 44 | } 45 | 46 | /* Use lighter colour derived from "Brand dark blue" for sidebar background */ 47 | .wy-nav-side { 48 | background-color: #233942 !important; 49 | } 50 | -------------------------------------------------------------------------------- /source/_static/visual.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/visual.png -------------------------------------------------------------------------------- /source/_static/vscode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/_static/vscode.png -------------------------------------------------------------------------------- /source/compatibility.rst: -------------------------------------------------------------------------------- 1 | Compatible versions 2 | =================== 3 | 4 | .. _compatibility-libfranka: 5 | 6 | Compatibility with libfranka 7 | ---------------------------- 8 | 9 | Various versions of compatible components are available. 10 | The table below offers an overview, with a recommendation to utilize up-to-date versions whenever possible. 11 | The symbol '>= ' indicates that compatibility with newer robot system versions has not been tested, 12 | implying that compatibility is not guaranteed (e.g., libfranka 0.2.0 may not be compatible with robot system version 4.0.0). 13 | 14 | The Robot system versions 2.x.x are not listed in the table below, but they are included as compatible with Robot system version >= 1.3.0. 15 | Therefore, they are compatible with libfranka versions 0.4.0 and 0.5.0. 16 | 17 | .. raw:: html 18 | 19 | 65 | 66 |
67 | 69 |
70 |
71 |
72 | 73 | 74 | 149 | 150 | `Robot version line 19 151 | `_ 152 | and `Gripper version line 17 153 | `_ 154 | are part of libfranka-common repository, a submodule of libfranka repository. 155 | 156 | Franka MATLAB® compatible versions are located :ref:`here`. 157 | 158 | .. caution:: 159 | Franka Robotics currently does not provide any support for Windows or Arm 160 | 161 | Compatibility with the kernel 162 | ----------------------------- 163 | 164 | There are different kernels, which are compatible with different Ubuntu system versions. 165 | The following table gives an overview of recommended Kernels. 166 | 167 | +----------------+-------------------------+ 168 | | Kernel version | Ubuntu | 169 | +================+=========================+ 170 | | Pro Kernel | 22.04 (Jammy Jellyfish) | 171 | +----------------+-------------------------+ 172 | | 5.9.1 | 20.04 (Focal Fossa) | 173 | +----------------+-------------------------+ 174 | | 5.4.19 | 18.04 (Bionic) | 175 | +----------------+-------------------------+ 176 | | 4.14.12 | 16.04 (Xenial Xerus) | 177 | +----------------+-------------------------+ -------------------------------------------------------------------------------- /source/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # FCI documentation build configuration file, created by 5 | # sphinx-quickstart on Wed May 24 14:40:52 2017. 6 | # 7 | # This file is execfile()d with the current directory set to its 8 | # containing dir. 9 | # 10 | # Note that not all possible configuration values are present in this 11 | # autogenerated file. 12 | # 13 | # All configuration values have a default; values that are commented out 14 | # serve to show the default. 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | import os 20 | import sys 21 | import json 22 | from pathlib import Path 23 | 24 | sys.path.insert(0, os.path.abspath("_static")) 25 | 26 | try: 27 | from compatibility_data import COMPATIBILITY_DATA 28 | 29 | print("Loaded compatibility data:", COMPATIBILITY_DATA) 30 | except ImportError as e: 31 | print("Error loading compatibility data:", e) 32 | COMPATIBILITY_DATA = {} 33 | 34 | # Make the data available to templates 35 | html_context = {"compatibility_data_json": COMPATIBILITY_DATA} 36 | 37 | # -- General configuration ------------------------------------------------ 38 | 39 | # If your documentation needs a minimal Sphinx version, state it here. 40 | # 41 | # needs_sphinx = '1.0' 42 | 43 | # Add any Sphinx extension module names here, as strings. They can be 44 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 45 | # ones. 46 | extensions = [ 47 | "sphinx.ext.mathjax", 48 | "sphinx.ext.todo", 49 | "sphinx_reredirects", 50 | "myst_parser", 51 | ] 52 | 53 | # TODO: set mathjax_path for offline support 54 | 55 | # Add any paths that contain templates here, relative to this directory. 56 | templates_path = ["_templates"] 57 | 58 | # The suffix(es) of source filenames. 59 | # You can specify multiple suffix as a list of string: 60 | # 61 | # source_suffix = ['.rst', '.md'] 62 | source_suffix = ".rst" 63 | 64 | # The master toctree document. 65 | master_doc = "index" 66 | 67 | # General information about the project. 68 | project = "Franka Control Interface (FCI)" 69 | copyright = "2023, Franka Robotics GmbH" 70 | author = "Franka Robotics GmbH" 71 | 72 | # The version of libfranka that the documentation refers to 73 | libfranka_version = "0.15.0" 74 | 75 | # The version info for the project you're documenting, acts as replacement for 76 | # |version| and |release|, also used in various other places throughout the 77 | # built documents. 78 | # 79 | # The short X.Y version. 80 | # version = '' 81 | # The full version, including alpha/beta/rc tags. 82 | # release = '' 83 | 84 | # The language for content autogenerated by Sphinx. Refer to documentation 85 | # for a list of supported languages. 86 | # 87 | # This is also used if you do content translation via gettext catalogs. 88 | # Usually you set "language" from the command line for these cases. 89 | language = "en" 90 | 91 | # List of patterns, relative to source directory, that match files and 92 | # directories to ignore when looking for source files. 93 | # This patterns also effect to html_static_path and html_extra_path 94 | exclude_patterns = [] 95 | 96 | # The name of the Pygments (syntax highlighting) style to use. 97 | pygments_style = "default" 98 | 99 | # If true, `todo` and `todoList` produce output, else they produce nothing. 100 | todo_include_todos = True 101 | 102 | 103 | # -- Options for HTML output ---------------------------------------------- 104 | 105 | # The theme to use for HTML and HTML Help pages. See the documentation for 106 | # a list of builtin themes. 107 | # 108 | html_theme = "sphinx_rtd_theme" 109 | 110 | # Theme options are theme-specific and customize the look and feel of a theme 111 | # further. For a list of options available for each theme, see the 112 | # documentation. 113 | # 114 | # html_theme_options = {} 115 | 116 | # Add any paths that contain custom static files (such as style sheets) here, 117 | # relative to this directory. They are copied after the builtin static files, 118 | # so a file named "default.css" will overwrite the builtin "default.css". 119 | html_static_path = ["_static"] 120 | 121 | html_css_files = ["style_override.css"] 122 | 123 | html_favicon = "_static/favicon.png" 124 | html_logo = "_static/logo.svg" 125 | 126 | # -- Options for HTMLHelp output ------------------------------------------ 127 | 128 | # Output file base name for HTML help builder. 129 | htmlhelp_basename = "fci-docs" 130 | 131 | 132 | # -- Options for LaTeX output --------------------------------------------- 133 | 134 | latex_elements = { 135 | # The paper size ('letterpaper' or 'a4paper'). 136 | # 137 | "papersize": "a4paper", 138 | # The font size ('10pt', '11pt' or '12pt'). 139 | # 140 | # 'pointsize': '10pt', 141 | # Additional stuff for the LaTeX preamble. 142 | # 143 | # 'preamble': '', 144 | # Latex figure (float) alignment 145 | # 146 | # 'figure_align': 'htbp', 147 | } 148 | 149 | # Grouping the document tree into LaTeX files. List of tuples 150 | # (source start file, target name, title, 151 | # author, documentclass [howto, manual, or own class]). 152 | latex_documents = [ 153 | (master_doc, "fci.tex", "Franka Control Interface Documentation", author, "manual"), 154 | ] 155 | 156 | 157 | # -- Options for manual page output --------------------------------------- 158 | 159 | # One entry per manual page. List of tuples 160 | # (source start file, name, description, authors, manual section). 161 | man_pages = [(master_doc, "fci", "Franka Control Interface Documentation", [author], 1)] 162 | 163 | 164 | # -- Options for Texinfo output ------------------------------------------- 165 | 166 | # Grouping the document tree into Texinfo files. List of tuples 167 | # (source start file, target name, title, author, 168 | # dir menu entry, description, category) 169 | texinfo_documents = [ 170 | ( 171 | master_doc, 172 | "fci", 173 | "Franka Control Interface Documentation", 174 | author, 175 | "fci", 176 | "Franka Control Interface", 177 | "Miscellaneous", 178 | ), 179 | ] 180 | 181 | from docutils import nodes 182 | 183 | 184 | def setup(app): 185 | """Set up the Sphinx application.""" 186 | # Add variables that can be used in RST files 187 | app.add_config_value("libfranka_version", libfranka_version, "env") 188 | 189 | # Add a function to generate API documentation URLs 190 | def api_url(text): 191 | """Generate a URL for the libfranka API documentation.""" 192 | return f"https://frankaemika.github.io/libfranka/{libfranka_version}/{text}" 193 | 194 | def api_role(name, rawtext, text, lineno, inliner, options={}, content=[]): 195 | """Handle :api: role in RST. 196 | 197 | The role can be used in two ways: 198 | 1. :api:`path_to_doc` - will use the path as both the URL and display text 199 | 2. :api:`display text|path_to_doc` - will use the path for URL but show display text 200 | """ 201 | parts = text.split("|", 1) 202 | if len(parts) == 2: 203 | text, target = parts 204 | else: 205 | target = text 206 | # Extract meaningful text from the target 207 | text = target.split(".")[-2].split("_")[-1].title() 208 | 209 | url = api_url(target) 210 | node = nodes.reference(rawtext, text, refuri=url, **options) 211 | return [node], [] 212 | 213 | app.add_role("api", api_role) 214 | 215 | # Add jinja2 filters 216 | app.add_config_value("compatibility_data_json", COMPATIBILITY_DATA, "html") 217 | -------------------------------------------------------------------------------- /source/control-parameters-joint-fr3-rectangular.csv: -------------------------------------------------------------------------------- 1 | Name, Joint 1, Joint 2, Joint 3, Joint 4, Joint 5 , Joint 6, Joint 7, Unit 2 | ":math:`q_{max}`", 2.3093, 1.5133, 2.4937, -0.4461, 2.4800, 4.2094, 2.6895, :math:`\text{rad}` 3 | ":math:`q_{min}`", -2.3093, -1.5133, -2.4937, -2.7478, -2.4800, 0.8521, -2.6895, :math:`\text{rad}` 4 | ":math:`\dot{q}_{max}`", 2, 1, 1.5, 1.25, 3, 1.5, 3, :math:`\frac{\text{rad}}{\text{s}}` 5 | -------------------------------------------------------------------------------- /source/control-parameters-joint-fr3.csv: -------------------------------------------------------------------------------- 1 | Name, Joint 1, Joint 2, Joint 3, Joint 4, Joint 5 , Joint 6, Joint 7, Unit 2 | ":math:`q_{max}`", 2.7437, 1.7837, 2.9007, -0.1518, 2.8065, 4.5169, 3.0159, :math:`\text{rad}` 3 | ":math:`q_{min}`", -2.7437, -1.7837, -2.9007, -3.0421, -2.8065, 0.5445, -3.0159, :math:`\text{rad}` 4 | ":math:`\dot{q}_{max}`", 2.62, 2.62, 2.62, 2.62, 5.26, 4.18, 5.26, :math:`\frac{\text{rad}}{\text{s}}` 5 | :math:`\ddot{q}_{max}`, 10, 10, 10, 10, 10, 10, 10, :math:`\frac{\text{rad}}{\text{s}^2}` 6 | :math:`\dddot{q}_{max}`, 5000, 5000, 5000, 5000, 5000, 5000, 5000, :math:`\frac{\text{rad}}{\text{s}^3}` 7 | ":math:`{\tau_j}_{max}`", 87, 87, 87, 87, 12, 12, 12, :math:`\text{Nm}` 8 | ":math:`\dot{\tau_j}_{max}`", 1000, 1000, 1000, 1000, 1000, 1000, 1000, :math:`\frac{\text{Nm}}{\text{s}}` 9 | -------------------------------------------------------------------------------- /source/control-parameters-joint-panda.csv: -------------------------------------------------------------------------------- 1 | Name, Joint 1, Joint 2, Joint 3, Joint 4, Joint 5 , Joint 6, Joint 7, Unit 2 | ":math:`q_{max}`", 2.8973, 1.7628, 2.8973, -0.0698, 2.8973, 3.7525, 2.8973, :math:`\text{rad}` 3 | ":math:`q_{min}`", -2.8973, -1.7628, -2.8973, -3.0718, -2.8973, -0.0175, -2.8973, :math:`\text{rad}` 4 | ":math:`\dot{q}_{max}`", 2.1750, 2.1750, 2.1750, 2.1750, 2.6100, 2.6100, 2.6100, :math:`\frac{\text{rad}}{\text{s}}` 5 | :math:`\ddot{q}_{max}`, 15, 7.5, 10, 12.5, 15, 20, 20, :math:`\frac{\text{rad}}{\text{s}^2}` 6 | :math:`\dddot{q}_{max}`, 7500, 3750, 5000, 6250, 7500, 10000, 10000, :math:`\frac{\text{rad}}{\text{s}^3}` 7 | ":math:`{\tau_j}_{max}`", 87, 87, 87, 87, 12, 12, 12, :math:`\text{Nm}` 8 | ":math:`\dot{\tau_j}_{max}`", 1000, 1000, 1000, 1000, 1000, 1000, 1000, :math:`\frac{\text{Nm}}{\text{s}}` 9 | -------------------------------------------------------------------------------- /source/control_parameters.rst: -------------------------------------------------------------------------------- 1 | .. _control_parameters_specifications: 2 | 3 | Robot and interface specifications 4 | =================================== 5 | Realtime control commands sent to the robot should fulfill *recommended* and *necessary* 6 | conditions. Recommended conditions should be fulfilled to ensure optimal operation of the 7 | robot. If necessary conditions are not met then the motion will be aborted. 8 | 9 | The final robot trajectory is the result of processing the user-specified trajectory ensuring 10 | that recommended conditions are fulfilled. As long as necessary conditions are met, the robot 11 | will try to follow the user-provided trajectory but it will only match the final trajectory 12 | if it also fulfills recommended conditions. If the necessary conditions are violated, an error 13 | will abort the motion: if, for instance, the first point of the user defined joint trajectory 14 | is very different from robot start position (:math:`q(t=0) \neq q_c(t=0)`) a ``start_pose_invalid`` error 15 | will abort the motion. 16 | 17 | Values for the constants used in the equations below are shown in the `Limits for Panda`_ and `Limits for Franka Research 3`_ section. 18 | 19 | Joint trajectory requirements 20 | ----------------------------- 21 | 22 | Necessary conditions 23 | ******************** 24 | 25 | - :math:`q_{min} < q_c < q_{max}` 26 | - :math:`-\dot{q}_{max} < \dot{q}_c < \dot{q}_{max}` 27 | - :math:`-\ddot{q}_{max} < \ddot{q}_c < \ddot{q}_{max}` 28 | - :math:`-\dddot{q}_{max} < \dddot{q}_c < \dddot{q}_{max}` 29 | 30 | Recommended conditions 31 | ********************** 32 | 33 | - :math:`-{\tau_j}_{max} < {\tau_j}_d < {\tau_j}_{max}` 34 | - :math:`-\dot{\tau_j}_{max} < \dot{\tau_j}_d < \dot{\tau_j}_{max}` 35 | 36 | At the beginning of the trajectory, the following conditions should be fulfilled: 37 | 38 | - :math:`q = q_c` 39 | - :math:`\dot{q}_{c} = 0` 40 | - :math:`\ddot{q}_{c} = 0` 41 | 42 | At the end of the trajectory, the following conditions should be fulfilled: 43 | 44 | - :math:`\dot{q}_{c} = 0` 45 | - :math:`\ddot{q}_{c} = 0` 46 | 47 | Cartesian trajectory requirements 48 | --------------------------------- 49 | 50 | Necessary conditions 51 | ******************** 52 | 53 | - :math:`T` is proper transformation matrix 54 | - :math:`-\dot{p}_{max} < \dot{p_c} < \dot{p}_{max}` (Cartesian velocity) 55 | - :math:`-\ddot{p}_{max} < \ddot{p_c} < \ddot{p}_{max}` (Cartesian acceleration) 56 | - :math:`-\dddot{p}_{max} < \dddot{p_c} < \dddot{p}_{max}` (Cartesian jerk) 57 | 58 | Conditions derived from inverse kinematics: 59 | 60 | - :math:`q_{min} < q_c < q_{max}` 61 | - :math:`-\dot{q}_{max} < \dot{q_c} < \dot{q}_{max}` 62 | - :math:`-\ddot{q}_{max} < \ddot{q_c} < \ddot{q}_{max}` 63 | 64 | Recommended conditions 65 | ********************** 66 | 67 | Conditions derived from inverse kinematics: 68 | 69 | - :math:`-{\tau_j}_{max} < {\tau_j}_d < {\tau_j}_{max}` 70 | - :math:`-\dot{\tau_j}_{max} < \dot{{\tau_j}_d} < \dot{\tau_j}_{max}` 71 | 72 | At the beginning of the trajectory, the following conditions should be fulfilled: 73 | 74 | - :math:`{}^OT_{EE} = {{}^OT_{EE}}_c` 75 | - :math:`\dot{p}_{c} = 0` (Cartesian velocity) 76 | - :math:`\ddot{p}_{c} = 0` (Cartesian acceleration) 77 | 78 | At the end of the trajectory, the following conditions should be fulfilled: 79 | 80 | - :math:`\dot{p}_{c} = 0` (Cartesian velocity) 81 | - :math:`\ddot{p}_{c} = 0` (Cartesian acceleration) 82 | 83 | Controller requirements 84 | ----------------------- 85 | 86 | Necessary conditions 87 | ******************** 88 | 89 | - :math:`-\dot{\tau_j}_{max} < \dot{{\tau_j}_d} < \dot{\tau_j}_{max}` 90 | 91 | Recommended conditions 92 | ********************** 93 | 94 | - :math:`-{\tau_j}_{max} < {\tau_j}_d < {\tau_j}_{max}` 95 | 96 | At the beginning of the trajectory, the following conditions should be fulfilled: 97 | 98 | - :math:`{\tau_j}_{d} = 0` 99 | 100 | .. _limit_table: 101 | 102 | Limits for Panda 103 | ---------------- 104 | 105 | Limits in the Cartesian space are as follows:\ 106 | 107 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 108 | | Name | Translation | Rotation | Elbow | 109 | +========================+===============================================+==================================================+============================================+ 110 | | :math:`\dot{p}_{max}` | 1.7 :math:`\frac{\text{m}}{\text{s}}` | 2.5 :math:`\frac{\text{rad}}{\text{s}}` | 2.1750 :math:`\frac{rad}{\text{s}}` | 111 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 112 | | :math:`\ddot{p}_{max}` | 13.0 :math:`\frac{\text{m}}{\text{s}^2}` | 25.0 :math:`\frac{\text{rad}}{\text{s}^2}` | 10.0 :math:`\;\frac{rad}{\text{s}^2}` | 113 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 114 | | :math:`\dddot{p}_{max}`| 6500.0 :math:`\frac{\text{m}}{\text{s}^3}` | 12500.0 :math:`\frac{\text{rad}}{\text{s}^3}` | 5000.0 :math:`\;\frac{rad}{\text{s}^3}` | 115 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 116 | 117 | Joint space limits are: 118 | 119 | .. csv-table:: 120 | :header-rows: 1 121 | :file: control-parameters-joint-panda.csv 122 | 123 | The arm can reach its maximum extension when joint 4 has angle :math:`q_{elbow-flip}`, where :math:`q_{elbow-flip} = -0.467002423653011\:rad`. 124 | This parameter is used to determine the flip direction of the elbow. 125 | 126 | Limits for Franka Research 3 127 | ---------------------------- 128 | 129 | Limits in the Cartesian space are as follows:\ 130 | 131 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 132 | | Name | Translation | Rotation | Elbow | 133 | +========================+===============================================+==================================================+============================================+ 134 | | :math:`\dot{p}_{max}` | 3.0 :math:`\frac{\text{m}}{\text{s}}` | 2.5 :math:`\frac{\text{rad}}{\text{s}}` | 2.620 :math:`\frac{rad}{\text{s}}` | 135 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 136 | | :math:`\ddot{p}_{max}` | 9.0 :math:`\frac{\text{m}}{\text{s}^2}` | 17.0 :math:`\frac{\text{rad}}{\text{s}^2}` | 10.0 :math:`\;\frac{rad}{\text{s}^2}` | 137 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 138 | | :math:`\dddot{p}_{max}`| 4500.0 :math:`\frac{\text{m}}{\text{s}^3}` | 8500.0 :math:`\frac{\text{rad}}{\text{s}^3}` | 5000.0 :math:`\;\frac{rad}{\text{s}^3}` | 139 | +------------------------+-----------------------------------------------+--------------------------------------------------+--------------------------------------------+ 140 | 141 | Joint space limits are: 142 | 143 | .. csv-table:: 144 | :header-rows: 1 145 | :file: control-parameters-joint-fr3.csv 146 | 147 | The arm can reach its maximum extension when joint 4 has angle :math:`q_{elbow-flip}`, where :math:`q_{elbow-flip} = -0.467002423653011\:rad`. 148 | This parameter is used to determine the flip direction of the elbow. 149 | 150 | 151 | .. important:: 152 | 153 | Note that the maximum joint velocity depends on the joint position. The maximum and minimum joint velocities at a certain joint position are calculated as: 154 | 155 | .. list-table:: 156 | :class: borderless 157 | 158 | * - .. figure:: _static/pbv_equations_max.svg 159 | :align: center 160 | :figclass: align-center 161 | 162 | Maximum velocities 163 | 164 | * - .. figure:: _static/pbv_equations_min.svg 165 | :align: center 166 | :figclass: align-center 167 | 168 | Minimum velocities 169 | 170 | In order to avoid violating the safety joint velocity limits, the Max/Min Joint velocity limits for FCI are more restrictive than those provided in the Datasheet. 171 | 172 | As most motion planners cannot deal with those functions for describing the velocity limits of each joint but they only deal with 173 | fixed velocity limits (rectangular limits), we are providing here a suggestion on which values to use for them. 174 | 175 | In the figures below the system velocity limits are visualized by the red and blue thresholds while the suggested 176 | "position-velocity rectangular limits" are visualized in black. 177 | 178 | .. list-table:: Visualization of the joint limits of FR3 179 | :class: borderless 180 | 181 | * - .. figure:: _static/pbv_limits_j1.svg 182 | :align: center 183 | :figclass: align-center 184 | 185 | Velocity limits of Joint 1 186 | 187 | - .. figure:: _static/pbv_limits_j2.svg 188 | :align: center 189 | :figclass: align-center 190 | 191 | Velocity limits of Joint 2 192 | 193 | * - .. figure:: _static/pbv_limits_j3.svg 194 | :align: center 195 | :figclass: align-center 196 | 197 | Velocity limits of Joint 3 198 | 199 | - .. figure:: _static/pbv_limits_j4.svg 200 | :align: center 201 | :figclass: align-center 202 | 203 | Velocity limits of Joint 4 204 | 205 | * - .. figure:: _static/pbv_limits_j5.svg 206 | :align: center 207 | :figclass: align-center 208 | 209 | Velocity limits of Joint 5 210 | 211 | - .. figure:: _static/pbv_limits_j6.svg 212 | :align: center 213 | :figclass: align-center 214 | 215 | Velocity limits of Joint 6 216 | 217 | * - .. figure:: _static/pbv_limits_j7.svg 218 | :align: center 219 | :figclass: align-center 220 | 221 | Velocity limits of Joint 7 222 | - 223 | 224 | 225 | Here are the parameters describing the suggested position-velocity rectangular limits: 226 | 227 | .. csv-table:: 228 | :header-rows: 1 229 | :file: control-parameters-joint-fr3-rectangular.csv 230 | 231 | .. important:: 232 | 233 | These limits are the values that are used by default in the rate limiter and in the URDF inside :doc:`franka_ros`. 234 | However, these are only a suggestion, you are free to define your own rectangles within the specification accordingly to your needs. 235 | 236 | Since FR3 does not inherently implement any restriction to the system limits (red and blue line in the plots above), you are also free 237 | to implement your own motion generator to exploit the HW capabilities of FR3 beyond the rectangular limits imposed by existing motion generators. 238 | 239 | 240 | Denavit–Hartenberg parameters 241 | ----------------------------- 242 | 243 | The Denavit–Hartenberg parameters for the Franka Research 3 kinematic chain are derived following Craig's convention and are as follows: 244 | 245 | .. figure:: _static/dh-diagram-frankarobotics.png 246 | :align: center 247 | :figclass: align-center 248 | 249 | Franka Research 3 kinematic chain. 250 | 251 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 252 | | Joint | :math:`a\;(\text{m})` | :math:`d\;(\text{m})` | :math:`\alpha\;(\text{rad})` | :math:`\theta\;(\text{rad})` | 253 | +=============+=======================+=======================+==============================+==============================+ 254 | | Joint 1 | 0 | 0.333 | 0 | :math:`\theta_1` | 255 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 256 | | Joint 2 | 0 | 0 | :math:`-\frac{\pi}{2}` | :math:`\theta_2` | 257 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 258 | | Joint 3 | 0 | 0.316 | :math:`\frac{\pi}{2}` | :math:`\theta_3` | 259 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 260 | | Joint 4 | 0.0825 | 0 | :math:`\frac{\pi}{2}` | :math:`\theta_4` | 261 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 262 | | Joint 5 | -0.0825 | 0.384 | :math:`-\frac{\pi}{2}` | :math:`\theta_5` | 263 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 264 | | Joint 6 | 0 | 0 | :math:`\frac{\pi}{2}` | :math:`\theta_6` | 265 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 266 | | Joint 7 | 0.088 | 0 | :math:`\frac{\pi}{2}` | :math:`\theta_7` | 267 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 268 | | Flange | 0 | 0.107 | 0 | 0 | 269 | +-------------+-----------------------+-----------------------+------------------------------+------------------------------+ 270 | 271 | 272 | .. note:: 273 | 274 | :math:`{}^0T_{1}` is the transformation matrix which describes the position and orientation of 275 | `frame 1` in `frame 0`. A kinematic chain can be calculated like the following: 276 | :math:`{}^0T_{2} = {}^0T_{1} * {}^1T_{2}` 277 | -------------------------------------------------------------------------------- /source/faq.rst: -------------------------------------------------------------------------------- 1 | FAQ 2 | === 3 | 4 | There is a robust and active community of users and developers who are ready to help you with any questions you may have. 5 | 6 | - `Franka Community `_ -------------------------------------------------------------------------------- /source/fr3-certification-remarks.csv: -------------------------------------------------------------------------------- 1 | Chapter,Content,Applicable for FR3,Comment 2 | 1,ABOUT Franka Robotics,fully, 3 | 2,RIGHTS OF USE AND PROPERTY RIGHTS,fully, 4 | 2.1,General,fully, 5 | 2.2,Identification,fully, 6 | 3,DECLARATION OF INCORPORATION AND CERTIFICATES,, 7 | 3.1,Declaration of Incorporation,not applicable,Research use not in scope according to article 1 2. (h) 8 | 3.2,Certificates,fully, 9 | 3.3,Further Statements,not applicable,Due to intended use partially applicable as stated in RoHS directive 2011/65/EU article 2 4 (j). Content regarding Battery Directive applies fully. 10 | 3.4,Labeling on the Equipment,fully, 11 | 4,SAFETY,, 12 | 4.1,Safety Instructions and General Indications,fully, 13 | 4.2,Notice of Liability,fully, 14 | 4.3,Intended Use,fully with remark,With the extension of use in research applications 15 | 4.4,Misuse,fully, 16 | 4.5,General Possible Dangers and Safety Measures when Working with Robots,fully, 17 | 4.6,Application Related Possible Dangers and Safety Measures,fully, 18 | 4.7,Installation of Safety Peripherals,fully, 19 | 4.8,Fail-safe Locking System,fully, 20 | 4.9,Manually Moving the Arm,fully, 21 | 4.10,Safety Concept,fully, 22 | 4.11,Safety Functionalities,with limitations for FCI Usage,As mentioned in Datasheet Franka Research 3 (120020) 23 | 4.12,Safety Settings and Watchman,fully, 24 | 5,ROLES AND PERSONAE,fully, 25 | 6,SCOPE OF DELIVERY AND ACCESSORIES,fully, 26 | 6.1,Equipment Overview,fully, 27 | 6.2,Scope of Delivery and Additional Equipment,fully with remark,As mentioned in FCI reference pager (120070) 28 | 6.3,Available Spare Parts and Accessories,fully, 29 | 7,TECHNICAL SPECIFICATIONS,partly applicable,Datasheet ( pages) replaced by Franka Research 3 Datasheet - Safety notice still valid 30 | 8,TRANSPORT AND HANDLING,fully, 31 | 8.1,Ambient Conditions for Delivery and Transport,fully, 32 | 9,MOUNTING AND INSTALLATION,fully, 33 | 9.1,Unpacking the Equipment,fully, 34 | 9.2,Correct Installation Site,fully, 35 | 9.3,Preparing the Installation Site,fully, 36 | 9.4,Mounting the Arm,fully, 37 | 9.5,Positioning the Control,fully, 38 | 9.6,Wiring and Electrical Installation,fully, 39 | 9.7,Mounting End Effectors,fully, 40 | 9.8,Practical Tips for Usage and Positioning of Franka Production 3,fully, 41 | 9.9,Re-packing the Arm,fully, 42 | 10,OPERATION,fully with remark,As mentioned in FCI documentation. 43 | 10.1,Switching On,fully, 44 | 10.2,Safety Relevant Tests of Franka Production 3,fully with remark,As mentioned in FCI documentation. 45 | 10.3,Connecting a User Interface Device,fully, 46 | 10.4,Software Setup,fully with remark,As mentioned in FCI documentation. 47 | 10.5,Switching Off and Restarting,fully , 48 | 11,WORKING WITH FRANKA PRODUCTION 3,fully with remark,As mentioned in FCI documentation. 49 | 11.1,Robotic Basics,fully, 50 | 11.2,Franka UI,fully with remark,As mentioned in FCI documentation. 51 | 11.3,Apps,fully, 52 | 11.4,Operating Modes,fully with remark,As mentioned in FCI documentation. 53 | 11.5,Single Point of Control,fully with remark,As mentioned in FCI documentation. 54 | 11.6,Teach a Task,fully, 55 | 11.7,Test & Jog,fully, 56 | 11.8,Work,fully with remark,As mentioned in FCI documentation. 57 | 11.09,Troubleshooting,fully with remark,As mentioned in FCI documentation. 58 | 12,MANAGING FRANKA PRODUCTION 3,fully, 59 | 12.1,Franka World,fully, 60 | 12.2,Managing Apps and Updates,fully, 61 | 12.3,Hub,fully, 62 | 12.4,Updates,fully, 63 | 13,MAINTENANCE AND DISPOSAL,fully, 64 | 13.1,Maintenance,fully, 65 | 13.2,Cleaning,fully, 66 | 13.3,System Lifetime,fully, 67 | 13.4,Disposal,fully, 68 | 14,SERVICE AND SUPPORT,fully, 69 | 15,APPENDIX,fully, 70 | 15.1,Stopping Times and Distances,fully, 71 | 15.2,Response times,fully, 72 | 15.3,Safe Position Accuracy,fully, 73 | 16,GLOSSARY,fully, 74 | 17,INDEX,fully, 75 | -------------------------------------------------------------------------------- /source/fr3-certification-remarks.rst: -------------------------------------------------------------------------------- 1 | FR3 certification remarks 2 | ========================= 3 | 4 | Congratulations on your new Franka Research 3. 5 | As part of the package you received the documentation including Product Manual Franka Production 3 (110010/1.5/EN). 6 | Even though its title indicates it is for the other Franka robot arm - FP3, 7 | it is in general also valid for Franka Research 3. 8 | We recommend reading this product manual before using the robot. Please be aware that especially 9 | when using the FCI and in general use cases in research applications there might be some deviations from this manual. 10 | Therefore, please consult the following table, where the applicability is stated and check the 11 | referred documentation like the datasheet. 12 | 13 | 14 | .. csv-table:: 15 | :header-rows: 1 16 | :file: fr3-certification-remarks.csv 17 | -------------------------------------------------------------------------------- /source/franka_matlab/CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog: 2 | 3 | ## 2.0.0 (20-11-2024) 4 | 5 | - **BREAKING** libfranka pre-built binaries now are contained in the project. No separate installation is required. 6 | - **BREAKING** New Simulink Model Blocks replacing the old single Model Block. 7 | - **BREAKING** Installation workflow and Simulink build system modification for supporting deployment to the Franka AI Companion. 8 | - **BREAKING** Toolbox renaming: Franka Toolbox for MATLAB. Scripts also now follow the shorter convention: franka_toolbox_<>.m 9 | - Cartesian impedance control example now includes UI elements as improved demo and better testing of the External Mode. 10 | - Dropping experimental support for native deployment in Windows host machines 11 | - Switch port matlab function for targeting custom docker images in AI Companion. 12 | 13 | ## 1.0.0 (11-03-2024) 14 | 15 | - **BREAKING** Robot Settings standardization with Matlab OOP. 16 | - **BREAKING** Adding the option to set the rate limiter and the cutoff frequency in the apply control simulink block. 17 | - **BREAKING** Removing the get initial robot state block from the simulink library. 18 | - **BREAKING** Enhanced modular building structure for the Franka Simulink Library. Easy incorporation to larger projects and Harware Support Packages. 19 | - **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. 20 | - **BREAKING** Removing all the "Panda" naming conventions. Replaced with "Franka Robot". 21 | - **BREAKING** Franka MATLAB is now distributed as a Toolbox Matlab Add-On. No installation script needed. 22 | - Fixing collision threshold setting bug. 23 | - Oldest supported Matlab version is now the R2021a. 24 | - Adding the option to set the Nominal End-Effector to End-Effector frame NE_T_EE in the Simulink Block "Apply Control". 25 | - 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. 26 | - Expansion of the Matlab API with the new method `joint_trajectory_motion()` for following precomputed joint trajectories. 27 | - Creation of the new demo `pick_and_place_with_RRT.mlx` showcasing a workflow approach for the new Matlab API. 28 | 29 | ## 0.3.1 (23-03-2023) 30 | 31 | - Bugfix. Properly setting the collision threshold values in Simulink. 32 | 33 | ## 0.3.0 (20-09-2022) 34 | 35 | - Windows 10 support (Experimental mainly due to the non-Real-Time nature of the default Windows system). 36 | - Project now relies on the leaner "Generic Real-Time" .tlc (grt.tlc) target framework. 37 | - Support for XCP communication protocol (vehicle network communication). Data inspector is now enabled! 38 | - Support for "Run on custom Hardware" Simulink App for controlling the "Build-deploy-execute-connect" workflow. 39 | - Project back-end overal simplification with modified rt_main.cpp for handling the external mode as a seperate thread. 40 | - **BREAKING** all the Franka MATLAB functions are starting with the "`franka_`" prefix. 41 | - Expansion of Matlab library with the functions `franka_communication_test()`, `franka_joint_poses()`, `franka_robot_state()` and `franka_joint_point_to_point_motion()`. 42 | - Addition of the Simulink demo, "joint_impedance_control.slx". 43 | - Fixing the bug when utilizing the Control Modes "Torque Control - X`. 44 | 45 | ## 0.2.1 (29-04-2022) 46 | 47 | - Adding supoort for all versions from Matlab2019a till Matlab2021a with libfranka 0.9.0. 48 | 49 | ## 0.2.0 (31-05-2021) 50 | 51 | - franka_matlab upgrade, supports Matlab2019a, Matlab2019b, Matlab2020a, Matlab2020b, Matlab2021a & libfranka 0.8.0. 52 | 53 | ## 0.1.1 (01-07-2020) 54 | 55 | - Any dependences that lead to source code linking for the Simulink Franka Library during mexing removed. That fixes the memory corruption 56 | bug when shutting down Matlab. 57 | - 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. 58 | 59 | ## 0.1.0 (21-01-2020) 60 | 61 | - Features: 62 | - **Simulink Library** for **Franka Robot**, includes the following blocks: 63 | - **Franka Simulink Iterface** for applying the desired control, plus additional parameters. 64 | - **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. 65 | - **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. 66 | - **Franka Model** for reading the values of all Model parameters of the Franka Robot during execution. 67 | - **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. 68 | - **Gripper Read State** for reading the current values out of the Franka Gripper. 69 | - **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). 70 | - **Matlab Library**(Experimental, limited support), includes the following command: 71 | - **automatic_error_recovery(robot_ip)**. Execute through a matlab command line for getting automatically out of an error state. 72 | - **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. -------------------------------------------------------------------------------- /source/franka_matlab/_static/ai_companion_jetson_trouble.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/ai_companion_jetson_trouble.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/block_parameters_robot_control.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/block_parameters_robot_control.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/board_parameters.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/board_parameters.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/cartesian_impedance_control_apps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/cartesian_impedance_control_apps.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/cartesian_impedance_control_hardware.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/cartesian_impedance_control_hardware.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/cartesian_impedance_control_overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/cartesian_impedance_control_overview.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/cartesian_impedance_control_run_on_hardware.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/cartesian_impedance_control_run_on_hardware.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/coriolis.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/coriolis.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/demos_files.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/demos_files.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/duration.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/duration.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/external_mode_background_thread.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/external_mode_background_thread.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/favicon.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/franka_matlab_toolbox_examples.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/franka_matlab_toolbox_examples.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/franka_toolbox_uninstall.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/franka_toolbox_uninstall.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/get_model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/get_model.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/get_robot_state.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/get_robot_state.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/get_robot_state_init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/get_robot_state_init.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/get_robot_state_init_settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/get_robot_state_init_settings.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/get_robot_state_settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/get_robot_state_settings.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/gravity.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/gravity.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/gripper_state.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/gripper_state.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/hardware_config_options.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/hardware_config_options.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/hardware_settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/hardware_settings.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/init_script_install_libfranka.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/init_script_install_libfranka.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/interface_pane.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/interface_pane.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/jacobian.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/jacobian.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/jetson_config_c++11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/jetson_config_c++11.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/jetson_deploy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/jetson_deploy.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/linux_host_hardware_implementation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/linux_host_hardware_implementation.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 7 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /source/franka_matlab/_static/mass_matrix.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/mass_matrix.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/matlab_pick_and_place_with_RRT_demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/matlab_pick_and_place_with_RRT_demo.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/model_settings_interface_mat_file_logging.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/model_settings_interface_mat_file_logging.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/model_settings_interface_non_reusable_function.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/model_settings_interface_non_reusable_function.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/pose.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/pose.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/robot_control.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/robot_control.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/select_nvidia_jetson.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/select_nvidia_jetson.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/simulink_library_browser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/simulink_library_browser.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/simulink_model_apply_control_only.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/simulink_model_apply_control_only.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/simulink_model_apply_control_only_build_error.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/simulink_model_apply_control_only_build_error.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/simulink_model_apply_control_only_fix.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/simulink_model_apply_control_only_fix.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/simulink_view_diagnostics.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/simulink_view_diagnostics.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/style_override.css: -------------------------------------------------------------------------------- 1 | .wy-table-responsive table td { 2 | white-space: normal !important; 3 | } 4 | 5 | /* Switch order of project name and logo in sidebar */ 6 | body > div > nav > div > div.wy-side-nav-search > a { 7 | display: flex !important; 8 | justify-content: center !important; 9 | flex-direction: column-reverse !important; 10 | } 11 | 12 | /* Smaller logo, adjust margins after reordering with project name */ 13 | body > div.wy-grid-for-nav > nav > div > div.wy-side-nav-search > a > img { 14 | width: 85% !important; 15 | margin-bottom: 0.85em !important; 16 | margin-top: 0 !important; 17 | } 18 | 19 | /* Remove home icon in sidebar */ 20 | body > div.wy-grid-for-nav > nav > div > div.wy-side-nav-search > a::before { 21 | content: "" !important; 22 | } 23 | 24 | /* Change style of search form in sidebar */ 25 | .wy-side-nav-search input[type="text"] { 26 | width: 90% !important; 27 | border: 0 !important; 28 | border-radius: 3px !important; 29 | } 30 | 31 | /* Use text font for headings */ 32 | h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { 33 | font-family: "Lato", "proxima-nova", "Helvetica Neue", Arial, sans-serif !important; 34 | } 35 | 36 | /* Use "Brand light blue" for ToC heading */ 37 | body > div.wy-grid-for-nav > nav > div > div.wy-menu.wy-menu-vertical > p > span { 38 | color: #00b9eb !important; 39 | } 40 | 41 | /* Use "Brand dark blue" for top of sidebar */ 42 | .wy-side-nav-search { 43 | background-color: #1a282d !important; 44 | } 45 | 46 | /* Use lighter colour derived from "Brand dark blue" for sidebar background */ 47 | .wy-nav-side { 48 | background-color: #233942 !important; 49 | } 50 | -------------------------------------------------------------------------------- /source/franka_matlab/_static/terminal_error_message.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/terminal_error_message.png -------------------------------------------------------------------------------- /source/franka_matlab/_static/workspace_parameters.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/frankaemika/docs/67ed9503000c2ddce5c0fb9810dd456b14fe5e15/source/franka_matlab/_static/workspace_parameters.png -------------------------------------------------------------------------------- /source/franka_matlab/compatibility.rst: -------------------------------------------------------------------------------- 1 | Compatible versions 2 | =================== 3 | 4 | .. _compatibility-franka-matlab: 5 | 6 | Compatibility with Matlab & libfranka 7 | ------------------------------------- 8 | 9 | +------------------------+-------------------+----------------------------+ 10 | | Franka MATLAB version | libfranka version | Matlab Version | 11 | +========================+===================+============================+ 12 | | 2.0.0 | 0.9.x & 0.14.x | :math:`\geq` R2022a | 13 | +------------------------+-------------------+----------------------------+ 14 | | 1.0.0 | 0.9.x & 0.13.x | :math:`\geq` R2021a | 15 | +------------------------+-------------------+----------------------------+ 16 | | 0.3.1 | 0.9.x & 0.10.x | :math:`\geq` R2019a | 17 | +------------------------+-------------------+----------------------------+ 18 | | 0.3.0 | 0.9.x & 0.10.x | :math:`\geq` R2019a | 19 | +------------------------+-------------------+----------------------------+ 20 | | 0.2.1 | 0.9.x | R2019a to R2021a | 21 | +------------------------+-------------------+----------------------------+ 22 | | 0.2.0 | 0.8.0 | R2019a to R2021a | 23 | +------------------------+-------------------+----------------------------+ 24 | | 0.1.1 | 0.7.1 | R2019a | 25 | +------------------------+-------------------+----------------------------+ 26 | | 0.1.0 | 0.7.1 | R2019a | 27 | +------------------------+-------------------+----------------------------+ 28 | 29 | `libfranka and robot system compatibility `_ 30 | 31 | .. important:: 32 | 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. 33 | 34 | .. important:: 35 | Make sure that you've installed and set up Matlab with a compatible compiler version! You can find the list of Matlab 36 | compatible compilers in `this link `_. -------------------------------------------------------------------------------- /source/franka_matlab/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # FCI documentation build configuration file, created by 5 | # sphinx-quickstart on Wed May 24 14:40:52 2017. 6 | # 7 | # This file is execfile()d with the current directory set to its 8 | # containing dir. 9 | # 10 | # Note that not all possible configuration values are present in this 11 | # autogenerated file. 12 | # 13 | # All configuration values have a default; values that are commented out 14 | # serve to show the default. 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | # 20 | # import os 21 | # import sys 22 | # sys.path.insert(0, os.path.abspath('.')) 23 | 24 | # -- General configuration ------------------------------------------------ 25 | 26 | # If your documentation needs a minimal Sphinx version, state it here. 27 | # 28 | # needs_sphinx = '1.0' 29 | 30 | # Add any Sphinx extension module names here, as strings. They can be 31 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 32 | # ones. 33 | extensions = [ 34 | 'sphinx.ext.mathjax', 35 | 'sphinx.ext.todo', 36 | 'sphinx_reredirects', 37 | 'myst_parser' 38 | ] 39 | 40 | # TODO: set mathjax_path for offline support 41 | 42 | # Add any paths that contain templates here, relative to this directory. 43 | templates_path = ['_templates'] 44 | 45 | # The suffix(es) of source filenames. 46 | # You can specify multiple suffix as a list of string: 47 | # 48 | # source_suffix = ['.rst', '.md'] 49 | source_suffix = '.rst' 50 | 51 | # The master toctree document. 52 | master_doc = 'index' 53 | 54 | # General information about the project. 55 | project = 'Franka MATLAB Toolbox' 56 | copyright = '2024, Franka Robotics GmbH' 57 | author = 'Franka Robotics GmbH' 58 | 59 | # The version info for the project you're documenting, acts as replacement for 60 | # |version| and |release|, also used in various other places throughout the 61 | # built documents. 62 | # 63 | # The short X.Y version. 64 | # version = '' 65 | # The full version, including alpha/beta/rc tags. 66 | # release = '' 67 | 68 | # The language for content autogenerated by Sphinx. Refer to documentation 69 | # for a list of supported languages. 70 | # 71 | # This is also used if you do content translation via gettext catalogs. 72 | # Usually you set "language" from the command line for these cases. 73 | language = 'en' 74 | 75 | # List of patterns, relative to source directory, that match files and 76 | # directories to ignore when looking for source files. 77 | # This patterns also effect to html_static_path and html_extra_path 78 | exclude_patterns = [] 79 | 80 | # The name of the Pygments (syntax highlighting) style to use. 81 | pygments_style = 'default' 82 | 83 | # If true, `todo` and `todoList` produce output, else they produce nothing. 84 | todo_include_todos = True 85 | 86 | 87 | # -- Options for HTML output ---------------------------------------------- 88 | 89 | # The theme to use for HTML and HTML Help pages. See the documentation for 90 | # a list of builtin themes. 91 | # 92 | html_theme = 'sphinx_rtd_theme' 93 | 94 | # Theme options are theme-specific and customize the look and feel of a theme 95 | # further. For a list of options available for each theme, see the 96 | # documentation. 97 | # 98 | # html_theme_options = {} 99 | 100 | # Add any paths that contain custom static files (such as style sheets) here, 101 | # relative to this directory. They are copied after the builtin static files, 102 | # so a file named "default.css" will overwrite the builtin "default.css". 103 | html_static_path = ['_static'] 104 | 105 | html_css_files = ['style_override.css'] 106 | 107 | html_favicon = '_static/favicon.png' 108 | html_logo = '_static/logo.svg' 109 | 110 | # -- Options for HTMLHelp output ------------------------------------------ 111 | 112 | # Output file base name for HTML help builder. 113 | htmlhelp_basename = 'fci-docs' 114 | 115 | 116 | # -- Options for LaTeX output --------------------------------------------- 117 | 118 | latex_elements = { 119 | # The paper size ('letterpaper' or 'a4paper'). 120 | # 121 | 'papersize': 'a4paper', 122 | 123 | # The font size ('10pt', '11pt' or '12pt'). 124 | # 125 | # 'pointsize': '10pt', 126 | 127 | # Additional stuff for the LaTeX preamble. 128 | # 129 | # 'preamble': '', 130 | 131 | # Latex figure (float) alignment 132 | # 133 | # 'figure_align': 'htbp', 134 | } 135 | 136 | # Grouping the document tree into LaTeX files. List of tuples 137 | # (source start file, target name, title, 138 | # author, documentclass [howto, manual, or own class]). 139 | latex_documents = [ 140 | (master_doc, 'fci.tex', 141 | 'Franka Control Interface Documentation', 142 | author, 'manual'), 143 | ] 144 | 145 | 146 | # -- Options for manual page output --------------------------------------- 147 | 148 | # One entry per manual page. List of tuples 149 | # (source start file, name, description, authors, manual section). 150 | man_pages = [ 151 | (master_doc, 'fci', 152 | 'Franka Control Interface Documentation', [author], 1) 153 | ] 154 | 155 | 156 | # -- Options for Texinfo output ------------------------------------------- 157 | 158 | # Grouping the document tree into Texinfo files. List of tuples 159 | # (source start file, target name, title, author, 160 | # dir menu entry, description, category) 161 | texinfo_documents = [ 162 | (master_doc, 'fci', 163 | 'Franka Control Interface Documentation', author, 164 | 'fci', 'Franka Control Interface', 165 | 'Miscellaneous'), 166 | ] 167 | -------------------------------------------------------------------------------- /source/franka_matlab/franka_matlab_changelog.rst: -------------------------------------------------------------------------------- 1 | Franka Toolbox for MATLAB changelog 2 | =================================== 3 | 4 | .. include:: ../franka_matlab/CHANGELOG.md 5 | :parser: myst_parser.sphinx_ 6 | :start-line: 2 7 | -------------------------------------------------------------------------------- /source/franka_matlab/getting_started.rst: -------------------------------------------------------------------------------- 1 | Getting started 2 | =============== 3 | .. _getting_started: 4 | 5 | Simulink 6 | -------- 7 | 8 | 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. 9 | 10 | To browse the available examples, use the following command: 11 | 12 | .. code-block:: matlab 13 | 14 | franka_toolbox_examples(); 15 | .. figure:: _static/franka_matlab_toolbox_examples.png 16 | :align: center 17 | :figclass: align-center 18 | 19 | Franka MATLAB Toolbox Examples Navigator. 20 | 21 | .. figure:: _static/cartesian_impedance_control_overview.png 22 | :align: center 23 | :figclass: align-center 24 | 25 | The Cartesian Impedance Control Example equiped with sliders as UI elements for controlling the End-Effector position. 26 | 27 | After opening, by double clicking, any of the Simulink models the robot settings will be loaded automatically in the 28 | workspace, in the form of the `frs` object. 29 | 30 | .. figure:: _static/workspace_parameters.png 31 | :align: center 32 | :figclass: align-center 33 | 34 | The Franka Robot Settings object. 35 | 36 | 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 37 | setup for your intended purposes. 38 | 39 | .. code-block:: matlab 40 | 41 | frs.robot_ip = 42 | 43 | You can modify the default settings for the FrankaRobotSettings with 44 | 45 | .. code-block:: matlab 46 | 47 | edit FrankaRobotSettings.m 48 | 49 | Simulink Solver Settings 50 | ~~~~~~~~~~~~~~~~~~~~~~~~ 51 | 52 | The requirements for the solver settings for the Simulink model should be: 53 | 54 | * Fixed-step 55 | * discrete (no continuous states) 56 | * With Fixed-step sixe (fundamental sample time) of `0.001`. 57 | 58 | Simulink Build & Deploy - Target PC: Franka AI Companion 59 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 | 61 | For building & deploying to the Franka AI Companion you can 62 | use the following recommended workflow: 63 | 64 | Start by clicking "Run on Hardware Board" in the Simulink APPS pane and select 65 | the "NVIDIA Jetson" option. 66 | 67 | .. figure:: _static/cartesian_impedance_control_run_on_hardware.png 68 | :align: center 69 | :figclass: align-center 70 | 71 | Run on Hardware Board - Select "NVIDIA Jetson". 72 | 73 | .. important:: 74 | 75 | In case this option is not visible make sure that the 76 | `MATLAB Coder Support Package for NVIDIA Jetson and NVIDIA DRIVE Platforms `_ 77 | is installed. 78 | 79 | We need to proceed with a couple of "Hardware Settings" before building & running the model. 80 | 81 | .. figure:: _static/hardware_settings.png 82 | :align: center 83 | :figclass: align-center 84 | 85 | Select the "Hardware Settings" 86 | 87 | Select the "NVIDIA Jetson" Hardware board 88 | 89 | Set the `Device Address`, `Username` and `Password` which correspond to your docker instance as it is running in the Franka AI Companion. 90 | 91 | .. figure:: _static/board_parameters.png 92 | :align: center 93 | :figclass: align-center 94 | 95 | "Board Parameters" 96 | 97 | 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. 98 | 99 | .. figure:: _static/jetson_config_c++11.png 100 | :align: center 101 | :figclass: align-center 102 | 103 | Select the "C++11" option. 104 | 105 | .. important:: 106 | 107 | For setting the specific port in which the ssh server is exposed by the currently targeted docker 108 | instance, please excecute the following MATLAB command: 109 | 110 | .. code-block:: shell 111 | 112 | franka_ai_companion_port_switch(); 113 | 114 | .. important:: 115 | 116 | If you are planning to utilize the External Mode for "Monitoring & Tuning" make sure 117 | that you've applied the settings descibed in the section bellow :ref:`external_mode_settings`. 118 | 119 | .. important:: 120 | 121 | Before executing make sure that the brakes of the robot are disengaged, the FCI mode is activated 122 | in Desk and that the robot is in execution mode (user-button is released)! 123 | 124 | You can now "Build and Deploy" or "Monitor and Tune" for running the Simulink Model! 125 | 126 | .. caution:: 127 | 128 | The robot will move! Make sure that you are monitoring the situation, ready to take action if necessary! 129 | 130 | .. figure:: _static/jetson_deploy.png 131 | :align: center 132 | :figclass: align-center 133 | 134 | "Build & Deploy" or "Monitor & Tune" for enabling the External Mode. 135 | 136 | Simulink Build & Deploy - Target PC: Linux Host 137 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 138 | 139 | .. important:: 140 | 141 | If you are planning to build, run & deploy the application to your linux host pc 142 | make sure that you've installed libfranka and a Real-Time kernel as described in the 143 | previous installation page. 144 | 145 | Let's start by selecting the `Run on Custom Hardware` App from the Apps pane in Simulink. 146 | Allow the grt.tlc target to be auto-selected, as prompted. 147 | 148 | .. figure:: _static/cartesian_impedance_control_apps.png 149 | :align: center 150 | :figclass: align-center 151 | 152 | "Run on custom hardware" Simulink App. 153 | 154 | Please proceed with the following necessary model checks before proceeding: 155 | 156 | * The Device vendor under "Hardware Implementation" is either "Intel" or "AMD" and device type "x86-64 (Linux 64)". 157 | * Code interface packaging options is set to "Nonreusable function". 158 | 159 | .. figure:: _static/linux_host_hardware_implementation.png 160 | :align: center 161 | :figclass: align-center 162 | :scale: 60% 163 | 164 | Hardware Implementation - Device vendor selection. 165 | 166 | .. figure:: _static/interface_pane.png 167 | :align: center 168 | :figclass: align-center 169 | :scale: 70% 170 | 171 | "Code interface packaging" options. 172 | 173 | .. important:: 174 | 175 | If you are planning to utilize the External Mode for "Monitoring & Tuning" make sure 176 | that you've applied the settings descibed in the section bellow :ref:`external_mode_settings`. 177 | 178 | .. important:: 179 | 180 | Before executing make sure that the brakes of the robot are disengaged, the FCI mode is activated 181 | in Desk and that the robot is in execution mode (user-button is released)! 182 | 183 | You can then select from the Hardware tab either `Monitor & Tune` in case monitoring through the external mode is 184 | desired or `Build, Deploy & Start` for just executing the application without monitoring. 185 | 186 | .. figure:: _static/cartesian_impedance_control_hardware.png 187 | :align: center 188 | :figclass: align-center 189 | 190 | Hardware Simulink App. 191 | 192 | .. caution:: 193 | 194 | The robot will move! Make sure that you are monitoring the situation, ready to take action if necessary! 195 | 196 | .. _external_mode_settings: 197 | 198 | Simulink External Mode ("Monitor & Tune") - Necessary Settings 199 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 200 | 201 | In case you are planning to execute with External Mode for "Monitor & Tuning", 202 | it is also necessary to apply the following settings: 203 | 204 | * "Run external mode in a background thread". 205 | * The Code interface packaging is "Nonreusable function". 206 | * "MAT-file logging" is unchecked. 207 | 208 | .. figure:: _static/external_mode_background_thread.png 209 | :align: center 210 | :figclass: align-center 211 | :scale: 50% 212 | 213 | "Run external mode in a background thread" is necessary so that the 1kHz loop won't get disturbed 214 | 215 | .. figure:: _static/model_settings_interface_non_reusable_function.png 216 | :align: center 217 | :figclass: align-center 218 | :scale: 70% 219 | 220 | "Nonreusable function option is required for building with External-Mode 221 | 222 | .. figure:: _static/model_settings_interface_mat_file_logging.png 223 | :align: center 224 | :figclass: align-center 225 | :scale: 50% 226 | 227 | "MAT-file logging" should be unchecked unchecked for building with External-Mode" 228 | 229 | MATLAB 230 | ------ 231 | 232 | Demo Pick & Place with RRT 233 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 234 | 235 | For familiarization with the Matlab API for the Franka Robot the `pick_and_place_with_RRT.mlx` demo is a good starting point. 236 | 237 | .. figure:: _static/matlab_pick_and_place_with_RRT_demo.png 238 | :align: center 239 | :figclass: align^center 240 | 241 | Live Matlab Script and Figure of the pick^and^place demo. 242 | 243 | Automatic error recovery 244 | ~~~~~~~~~~~~~~~~~~~~~~~~ 245 | If the robot encounters an error state and transitions to reflex mode, 246 | you may attempt a recovery by executing the automatic error recovery command in Matlab. 247 | 248 | .. code-block:: shell 249 | 250 | fr = FrankaRobot(); 251 | fr.automatic_error_recovery(); 252 | 253 | In case the command fails and the robot remains in the erroneous state try using the guiding mode to manually bring 254 | back the robot to a valid configuration. 255 | 256 | .. hint:: 257 | 258 | Checkout the :ref:`Franka library for MATLAB ` for a set of helper 259 | functions that can help to optimize your workflow. 260 | 261 | -------------------------------------------------------------------------------- /source/franka_matlab/index.rst: -------------------------------------------------------------------------------- 1 | Franka Toolbox for MATLAB 2 | ========================= 3 | 4 | The Franka Toolbox for MATLAB provides libraries and tools that integrate Franka robots with the MathWorks® software ecosystem. 5 | 6 | .. figure:: _static/hardware_config_options.png 7 | :align: center 8 | :figclass: align-center 9 | 10 | Hardware/Software configuration options for the Franka Toolbox for MATLAB. 11 | 12 | The toolbox comprises two main components: 13 | 14 | * ``Franka Library for Simulink``, a set of Simulink blocks for interfacing the Franka Robot through automatic C++ code gen with Simulink Coder. The library mainly aims at assisting with the rapid-development of advanced robot controllers. 15 | 16 | .. figure:: _static/simulink_library_browser.png 17 | :align: center 18 | :figclass: align-center 19 | 20 | Simulink Library for rapid-prototyping of controllers for the Franka Robot. 21 | 22 | * ``Franka Library for MATLAB``, which provides the `FrankaRobot()` MATLAB class for directly interfacing the Franka Robot. 23 | 24 | .. figure:: _static/matlab_pick_and_place_with_RRT_demo.png 25 | :align: center 26 | :figclass: align-center 27 | 28 | Example of a pick-and-place operation using RRT (Rapidly-exploring Random Tree) implemented in MATLAB Live Script. 29 | 30 | .. toctree:: 31 | :maxdepth: 2 32 | :caption: Contents: 33 | 34 | compatibility 35 | system_requirements 36 | installation 37 | getting_started 38 | simulink_library 39 | matlab_library 40 | troubleshooting 41 | -------------------------------------------------------------------------------- /source/franka_matlab/installation.rst: -------------------------------------------------------------------------------- 1 | Installation 2 | ============ 3 | 4 | Installation Methods 5 | -------------------- 6 | 7 | Option 1: Direct Installation 8 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9 | Drag and drop the ``franka_toolbox.mltbx`` file into your MATLAB Command Window and follow the installation prompts. 10 | 11 | Option 2: Programmatically 12 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ 13 | .. code-block:: matlab 14 | 15 | uiopen('', 1); 16 | 17 | License Management & Activation 18 | ------------------------------- 19 | 20 | 1. Generate System Identifier 21 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22 | Execute the following command in MATLAB to generate your system's unique identifier: 23 | 24 | .. code-block:: matlab 25 | 26 | franka_toolbox_uid_gen() 27 | 28 | 2. Obtain License 29 | ^^^^^^^^^^^^^^^^^ 30 | Contact Franka Robotics with your generated identifier to receive your license number. 31 | 32 | 3. Activate License 33 | ^^^^^^^^^^^^^^^^^^^ 34 | For Franka Research 3 robots: 35 | 36 | .. code-block:: matlab 37 | 38 | franka_toolbox_install(''); 39 | 40 | or for first-generation `FER` robots: 41 | 42 | .. code-block:: matlab 43 | 44 | franka_toolbox_install('', 'fer'); 45 | 46 | Uninstall Toolbox 47 | ----------------- 48 | 49 | 1. Clean-up local permanent installation artifacts: 50 | 51 | .. code-block:: matlab 52 | 53 | franka_toolbox_uninstall(); 54 | 55 | 2. Remove the toolbox using MATLAB Add-Ons Manager. 56 | 57 | .. figure:: _static/franka_toolbox_uninstall.png 58 | :align: center 59 | :figclass: align-center 60 | :scale: 60% 61 | 62 | Uninstalling the Franka Toolbox. 63 | 64 | .. _libfranka_handling_options: 65 | 66 | libfranka handling options for Target PC 67 | ---------------------------------------- 68 | 69 | libfranka pre-built binaries 70 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 71 | 72 | Starting with Franka Toolbox for MATLAB version 2.0.0, libfranka is included in the toolbox distribution. 73 | 74 | There are dynamic dependencies for the precompiled libfranka on the Target PC, which need to be installed on the Target PC: 75 | 76 | 1. :ref:`precompiled libfranka system dependencies for AI Companion` section. 77 | 2. :ref:`precompiled libfranka system dependencies for RT Linux Host` section. 78 | 79 | libfranka local (Toolbox scope) installation 80 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 81 | 82 | In case the system dependencies for the precompiled libfranka cannot be met, or if in case there are issues with the precompiled binaries, you can build and install libfranka from source, locally in the scope of the Franka Toolbox only. 83 | 84 | Start by installing the dependencies for the libfranka build: 85 | 86 | .. code-block:: bash 87 | 88 | sudo apt remove "*libfranka*" 89 | sudo apt install build-essential cmake git libpoco-dev libeigen3-dev 90 | 91 | Then the whole process can be handled automatically by the toolbox. 92 | 93 | You can execute the following command in MATLAB to start the auto-installation for the AI Companion: 94 | 95 | .. code-block:: matlab 96 | 97 | franka_toolbox_libfranka_install_remote(<'0.9.2' | '0.14.0'>,'','',''); 98 | 99 | or in case of an RT Linux Host: 100 | 101 | .. code-block:: matlab 102 | 103 | franka_toolbox_libfranka_install(<'0.9.2' | '0.14.0'>, true); 104 | 105 | libfranka system-wide installation 106 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 107 | 108 | libfranka can be also installed manually system-wide on the Target PC. For more details, please refer to the `libfranka README `_. 109 | 110 | In case you prefer to build against the system-wide libfranka installation, you can do so by executing: 111 | 112 | .. code-block:: matlab 113 | 114 | franka_toolbox_libfranka_system_installation_set(true); 115 | 116 | This will trigger the toolbox to build against the system-wide libfranka installation. 117 | 118 | For reverting back to the local installation in the scope of the toolbox, you can execute: 119 | 120 | .. code-block:: matlab 121 | 122 | franka_toolbox_libfranka_system_installation_set(false); 123 | -------------------------------------------------------------------------------- /source/franka_matlab/matlab_library.rst: -------------------------------------------------------------------------------- 1 | .. _matlab-library: 2 | 3 | Franka Library for MATLAB - Reference 4 | ===================================== 5 | 6 | .. important:: 7 | In it's current form, the MATLAB library is not officially 8 | supported for usage in combination with the Franka AI companion 9 | and it's mainly purposed to be executed natively, in Linux Host PC with 10 | Real-Time Kernel. 11 | 12 | FrankaRobot Class 13 | ----------------- 14 | 15 | .. code-block:: shell 16 | 17 | fr = FrankaRobot(); 18 | 19 | Automatic Error Recovery 20 | ^^^^^^^^^^^^^^^^^^^^^^^^ 21 | 22 | .. code-block:: shell 23 | 24 | fr.automatic_error_recovery(); 25 | 26 | Will attempt an automatic error recovery . 27 | 28 | Get Joint Poses 29 | ^^^^^^^^^^^^^^^ 30 | 31 | .. code-block:: shell 32 | 33 | jp = fr.joint_poses(); 34 | 35 | Will return a 7 element cell array with the current robot joint poses. 36 | 37 | Get Robot State 38 | ^^^^^^^^^^^^^^^ 39 | 40 | .. code-block:: shell 41 | 42 | rs = fr.robot_state(); 43 | 44 | Will return a struct will the current robot state. 45 | 46 | Joint Point to Point Motion 47 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 48 | 49 | .. code-block:: shell 50 | 51 | fr.joint_point_to_point_motion(<7 element double array with target configuration>, <0 to 1 scalar speed factor>); 52 | 53 | Will move the robot into a desired joint configuration. 54 | 55 | Joint Trajectory Motion 56 | ^^^^^^^^^^^^^^^^^^^^^^^^ 57 | 58 | .. code-block:: shell 59 | 60 | fr.joint_trajectory_motion(<7xn double array with desired joint trajectory>); 61 | 62 | Will move the robot based on the given desired joint trajectory. 63 | 64 | .. warning:: 65 | Make sure that the current configuration of the robot maches the initial trajectory element `q(1:7,1)` that is passed in the function! Additionally make sure that 66 | the given trajectory is sufficiently smooth and continuous. 67 | 68 | Gripper State 69 | ^^^^^^^^^^^^^ 70 | 71 | .. code-block:: shell 72 | 73 | gs = fr.gripper_state(); 74 | 75 | Will return a struct with the current gripper state. 76 | 77 | Gripper Homing 78 | ^^^^^^^^^^^^^^ 79 | 80 | .. code-block:: shell 81 | 82 | fr.gripper_homing(); 83 | 84 | Will perform a homing operation to the gripper and will return 1 if succesful. 85 | 86 | Gripper Grasp 87 | ^^^^^^^^^^^^^ 88 | 89 | .. code-block:: shell 90 | 91 | fr.ripper_grasp(width, speed, force, epsilon_inner, epsilon_outer); 92 | 93 | Will attempt a grasp and will return 1 if the object is grasped, 0 otherwise. 94 | 95 | Gripper Move 96 | ^^^^^^^^^^^^ 97 | 98 | .. code-block:: shell 99 | 100 | fr.gripper_move(width,speed); 101 | 102 | Will move the gripper to a desired width position. Will return 1 if succesful, 0 otherwise. 103 | 104 | Gripper Stop 105 | ^^^^^^^^^^^^ 106 | 107 | .. code-block:: shell 108 | 109 | fr.gripper_stop(); 110 | 111 | Will stop the current gripper operation. Will return 1 if succesful, 0 otherwise. -------------------------------------------------------------------------------- /source/franka_matlab/simulink_library.rst: -------------------------------------------------------------------------------- 1 | Fanka Library for Simulink - Reference 2 | ====================================== 3 | 4 | .. hint:: 5 | Regarding the input/output signal nomenclature, datatypes, and sizes, the libfranka definitions 6 | have been fully adopted. You can find the complete list of signals 7 | `here `_. 8 | The column-major format for signals has been adopted as well. 9 | 10 | Robot Control 11 | ------------- 12 | 13 | .. figure:: _static/robot_control.png 14 | :align: center 15 | :figclass: align-center 16 | 17 | Robot Control Simulink Block. 18 | 19 | This is the main block of the Franka Simulink Library. It is responsible for applying the desired robot parameters and control signals to the robot. 20 | 21 | The robot settings can be applied through the block parameters. 22 | 23 | .. figure:: _static/block_parameters_robot_control.png 24 | :align: center 25 | :figclass: align-center 26 | :width: 530px 27 | 28 | Robot Control Simulink Block Settings. 29 | 30 | .. hint:: 31 | If desired, an initial robot configuration can be applied **before** the main execution of the control loop. 32 | Namely, the robot will move to the desired configuration and only then the main execution of the Simulink model 33 | will take place. You can define that in the `Initial Configuration` section of the block settings. 34 | 35 | Robot State 36 | ----------- 37 | 38 | .. figure:: _static/get_robot_state.png 39 | :align: center 40 | :figclass: align-center 41 | 42 | Robot State Simulink Block. 43 | 44 | For reading the desired set of signals stemming from the current robot state, 45 | you can free-type the names of the signals in the `Parameters` pane of the block parameters. 46 | For the set of available signals and their namings --> `Robot State Attributes `_ 47 | 48 | .. figure:: _static/get_robot_state_settings.png 49 | :align: center 50 | :figclass: align-center 51 | 52 | Get initial robot state Simulink Block Settings. 53 | 54 | Duration Period 55 | --------------- 56 | 57 | .. figure:: _static/duration.png 58 | :align: center 59 | :figclass: align-center 60 | 61 | Get duration from last main callback(Sample Time) Simulink Block. 62 | 63 | This Simulink block outputs the duration from the last execution step in seconds. Ideally this should be always 64 | 0.001 seconds but due to lost packages during communication errors 0.002 secs or 0.003 secs could be seen. 65 | 66 | .. warning:: 67 | The step count of the Simulink model **does not change** during these communication mishaps. It continues to increment even though an execution step has been lost in reality. Therefore, special design considerations are necessary, especially for sensitive position motion generators. For example, refer to the `generate_cartesian_pose_motion.slx` demo to see how the main "clock" of the application has been designed. 68 | 69 | Gripper State 70 | ------------- 71 | 72 | .. figure:: _static/gripper_state.png 73 | :align: center 74 | :figclass: align-center 75 | 76 | Get current gripper state Simulink Block. 77 | 78 | The gripper state block will inform the application about the current gripper state. 79 | 80 | .. hint:: 81 | Highly recommended to have a look at the 82 | `GripperState Struct Reference `_ 83 | for the list of available signals and the demo `grasp_objects.slx` which is provided for getting started. 84 | 85 | Mass Matrix 86 | ----------- 87 | 88 | .. figure:: _static/mass_matrix.png 89 | :align: center 90 | :figclass: align-center 91 | 92 | Get the Mass Matrix of the Robot Model. 93 | 94 | Coriolis 95 | -------- 96 | 97 | .. figure:: _static/coriolis.png 98 | :align: center 99 | :figclass: align-center 100 | 101 | Get the Coriolis Matrix of the Robot Model. 102 | 103 | Gravity 104 | ------- 105 | 106 | .. figure:: _static/gravity.png 107 | :align: center 108 | :figclass: align-center 109 | 110 | Get the Gravity Vector of the Robot Model. 111 | 112 | 113 | Jacobian 114 | -------- 115 | 116 | .. figure:: _static/jacobian.png 117 | :align: center 118 | :figclass: align-center 119 | 120 | Get the Jabobian Matrix of the Robot. 121 | 122 | You can select between "zero" or "body" Jacobian as well as the desired 123 | frame inside the block parameters. 124 | 125 | Pose 126 | ---- 127 | 128 | .. figure:: _static/pose.png 129 | :align: center 130 | :figclass: align-center 131 | 132 | Get the Robot Pose. 133 | 134 | You can select the desired pose frame inside the block parameters. -------------------------------------------------------------------------------- /source/franka_matlab/system_requirements.rst: -------------------------------------------------------------------------------- 1 | System Requirements 2 | =================== 3 | 4 | Host PC Requirements 5 | -------------------- 6 | 7 | MATLAB Version - Host PC OS Compatibility 8 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9 | 10 | The Host PC is the machine responsible for running MATLAB and Simulink. 11 | 12 | +-------------------------+-------------------+----------------------------------------------------------------------------------------------------------+ 13 | | Franka Toolbox Version | MATLAB Version | Host PC OS / Ubuntu Version | 14 | +=========================+===================+==========================================================================================================+ 15 | | 2.0.0 | R2022a or newer | [`Matlab System Requirements `_] | 16 | +-------------------------+-------------------+----------------------------------------------------------------------------------------------------------+ 17 | 18 | MATLAB Toolbox Dependencies 19 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20 | 21 | The following Mathworks products are required: 22 | 23 | * `MATLAB `_ 24 | * `Simulink `_ 25 | * `Simulink Coder `_ 26 | * `Matlab Coder `_ 27 | 28 | Some of demos provided with the franka_matlab need the following toolboxes: 29 | 30 | * `Stateflow `_ (required for the Simulink Example grasp_object.slx) 31 | * `Matlab Robotics Toolbox `_ (required for the MATLAB example pick_and_place_with_RRT.mlx) 32 | 33 | MATLAB Coder Support Package for NVIDIA Jetson 34 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 35 | **For working with the Franka AI Companion & NVIDIA Jetson platforms** please download and install the `MATLAB Coder Support Package for NVIDIA Jetson and NVIDIA DRIVE Platforms `_. 36 | 37 | Target PC - AI Companion 38 | ------------------------ 39 | 40 | .. _system_dependencies_precompiled_ai_companion: 41 | 42 | The Franka Toolbox for MATLAB ships with prebuilt libfranka and other binaries which are built based on the following AI Companion Target PC Ubuntu version: 43 | 44 | +-------------------------+---------------------------------------------+ 45 | | Franka Toolbox Version | Target PC Ubuntu Version (recommended) | 46 | +=========================+=============================================+ 47 | | 2.0.0 | 20.04 LTS | 48 | +-------------------------+---------------------------------------------+ 49 | 50 | precompiled libfranka system dependencies 51 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 52 | 53 | +--------------+------------------------+--------------------------------------------------------------------------+ 54 | | Franka Robot | libfranka Version | System Dependency | 55 | +==============+========================+==========================================================================+ 56 | | FR3 | 0.14.0 | libpoco-dev (1.9.2-3ubuntu3 - Ubuntu-20.04 default), pinocchio (2.7.1) | 57 | +--------------+------------------------+--------------------------------------------------------------------------+ 58 | | FER | 0.9.2 | libpoco-dev (1.9.2-3ubuntu3 - Ubuntu-20.04 default) | 59 | +--------------+------------------------+--------------------------------------------------------------------------+ 60 | 61 | 62 | To install the required version of libpoco-dev on your system, you can use the following commands for Ubuntu-20.04: 63 | 64 | .. code-block:: shell 65 | 66 | sudo apt-get update 67 | sudo apt-get install libpoco-dev 68 | 69 | For installing the required version of pinocchio, please refer to the `Pinocchio installation documentation `_. 70 | 71 | .. warning:: 72 | 73 | In case the system dependencies cannot be met for libfranka, you can build and install libfranka from source, system-wide or locally in the scope of the Franka Toolbox only. 74 | For handling options, see :ref:`libfranka handling options for Target PC`. 75 | 76 | 77 | Target PC - RT Linux Host 78 | ------------------------- 79 | 80 | System requirements when the Host & Target PC are the same machine. 81 | 82 | System Requirements 83 | ^^^^^^^^^^^^^^^^^^^ 84 | 85 | Make sure that your target PC configuration complies with the following documentation. 86 | 87 | 1. `Franka Robot System Compatibility Documentation `_ . 88 | 2. `System Requirements `_ . 89 | 3. `Setting Up the Real-Time Kernel `_. 90 | 91 | The Franka Toolbox for MATLAB ships with prebuilt libfranka and other binaries which are built based on the following Target PC Ubuntu version: 92 | 93 | +-------------------------+-----------------------------------------------------+ 94 | | Franka Toolbox Version | Target AI Companion PC Ubuntu Version (recommended) | 95 | +=========================+=====================================================+ 96 | | 2.0.0 | 22.04 LTS | 97 | +-------------------------+-----------------------------------------------------+ 98 | 99 | MATLAB Support Package for Linux 100 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 101 | In case where there is a single Ubuntu Host & Target machine, please ensure that 102 | you have installed the `matlab-support package `_ 103 | in order for Matlab to reference the system dynamic libraries instead of the precompiled ones that it ships with: 104 | 105 | .. code-block:: shell 106 | 107 | sudo apt install matlab-support 108 | 109 | .. _system_dependencies_precompiled_rt_linux_host: 110 | 111 | precompiled libfranka system dependencies 112 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 113 | 114 | Franka Toolbox comes with prebuilt libfranka which requires the following system dynamic libraries: 115 | 116 | +--------------+------------------------+-------------------------------------------------------------------+ 117 | | Franka Robot | libfranka Version | System Dependency | 118 | +==============+========================+===================================================================+ 119 | | FR3 | 0.14.0 | libpoco-dev (1.11.0-3 - Ubuntu-22.04 default), pinocchio (3.2.0) | 120 | +--------------+------------------------+-------------------------------------------------------------------+ 121 | | FER | 0.9.2 | libpoco-dev (1.11.0-3 - Ubuntu-22.04 default) | 122 | +--------------+------------------------+-------------------------------------------------------------------+ 123 | 124 | To install the required version of libpoco-dev on your system, you can use the following commands for Ubuntu-22.04: 125 | 126 | .. code-block:: shell 127 | 128 | sudo apt-get update 129 | sudo apt-get install libpoco-dev 130 | 131 | For installing the required version of pinocchio, please refer to the `Pinocchio installation documentation `_. 132 | 133 | .. warning:: 134 | 135 | In case the system dependencies cannot be met for libfranka, you can build and install libfranka from source, system-wide or locally in the scope of the Franka Toolbox only. 136 | For handling options, see :ref:`libfranka handling options for Target PC`. 137 | 138 | -------------------------------------------------------------------------------- /source/franka_matlab/troubleshooting.rst: -------------------------------------------------------------------------------- 1 | Troubleshooting 2 | =============== 3 | 4 | .. hint:: 5 | Checkout the `Franka Community `_ and the 6 | `franka_matlab category `_ for relevant posts or for creating new ones! 7 | 8 | control_modes.h: No such file or directory error. 9 | ------------------------------------------------- 10 | 11 | .. figure:: _static/simulink_model_apply_control_only_build_error.png 12 | :align: center 13 | :figclass: align-center 14 | 15 | The build error message in simulink when only the "apply control is present". 16 | 17 | This is a known current limitation of the system, as the build process will fail if only 18 | the "apply control" block is present in a simulink model. 19 | 20 | .. figure:: _static/simulink_model_apply_control_only.png 21 | :align: center 22 | :figclass: align-center 23 | 24 | Example of a Simulink model with only "apply control". The build will fail. 25 | 26 | For fixing the issue just include any other block from the Franka Simulink Library, e.g 27 | with the terminal if it will be left unused. 28 | 29 | .. figure:: _static/simulink_model_apply_control_only_fix.png 30 | :align: center 31 | :figclass: align-center 32 | 33 | Fixing the "control_modes.h: No such file or directory error." by including any other 34 | block from the Franka Simulink Library. 35 | 36 | missing "MW_custom_RTOS_header.h" 37 | --------------------------------- 38 | 39 | When working with the AI Companion or a NVIDIA Jetson platform, if you encounter an error 40 | releated to missing "MW_custom_RTOS_header.h", you can try forcing the NVIDIA Simulink Code Generation settings to reset: 41 | 42 | .. figure:: _static/ai_companion_jetson_trouble.png 43 | :align: center 44 | :figclass: align-center 45 | 46 | Fixing the "missing MW_custom_RTOS_header.h" error by forcing the Simulink Jetson related 47 | settings to reset. 48 | 49 | libfranka reference 50 | ------------------- 51 | .. hint:: 52 | Same error messages and advised troubleshooting applies as `libfranka `_. 53 | 54 | Issues with the graphics driver in Linux 55 | ---------------------------------------- 56 | 57 | NVIDIA's graphics driver's are not officially supported in Linux with Real-Time Kernel. This could cause issues in graphics renderings in Matlab 58 | and Simulink, e.g with figures and scopes respectively. We would then recommend starting matlab with the `-softwareopengl` for avoiding these issues: 59 | 60 | .. code-block:: shell 61 | 62 | $ matlab -softwareopengl 63 | 64 | Issues with libstdc++.so and other system dynamic libraries 65 | ----------------------------------------------------------- 66 | 67 | Make sure that you have installed the `matlab-support package `_ for your system, in order for Matlab to reference the system dynamic libraries 68 | instead of the precompiled ones that it ships with: 69 | 70 | .. code-block:: shell 71 | 72 | sudo apt install matlab-support 73 | 74 | Franka Simulink library number of block instances 75 | ------------------------------------------------- 76 | 77 | .. important:: 78 | The Simulink library has been designed for rapid-prototyping of robot controllers with one-robot 79 | in mind. Multiple instances for the Apply Control block are not encouraged as this has not been tested. 80 | Multiple instances of all the other Simulink blocks, as long as they point to the same robot ip, can be 81 | utilized. -------------------------------------------------------------------------------- /source/getting_started.rst: -------------------------------------------------------------------------------- 1 | Getting started 2 | =============== 3 | 4 | After setting up the required software for :doc:`Linux `. 5 | It is time to connect to the robot and test the whole setup 6 | by using FCI to read the current robot state. 7 | 8 | Operating the robot 9 | ------------------- 10 | 11 | Before going further though, here are a few safety considerations. 12 | Always check the following things before powering on the robot: 13 | 14 | 1. Make sure that the Arm has been mounted on a stable base and cannot topple over, even 15 | when performing fast motions or abrupt stops. 16 | 17 | .. caution:: 18 | Only tabletop mounting is supported, i.e. the Arm must be mounted perpendicular to the 19 | ground! Other mountings will **void your warranty** and **might cause damage 20 | to the robot**! 21 | 22 | 2. Ensure that the cable connecting Arm and Control is firmly attached on both sides. 23 | 3. Connect the external activation device to Arm's base and keep it next to you in order to be 24 | able to stop the robot at any time. 25 | 26 | .. hint:: 27 | Activating the external activation device will disconnect the Arm from Control. 28 | The joint motor controllers will then hold their current position. 29 | **The external activation device is not an emergency stop!** 30 | 31 | This list is non-exhaustive! The manual delivered with your robot contains a chapter dedicated 32 | to safety. Please read it carefully and follow the instructions. The manual can also be found in 33 | our `Franka World Hub `_. 34 | 35 | .. important:: 36 | The workstation PC which commands your robot using the FCI must always be connected to the LAN 37 | port of Control (shop floor network) and **not** to the LAN port of the Arm (robot network). 38 | 39 | Installing the FCI Feature 40 | -------------------------- 41 | In order to be able to operate the robot through the Franka Control Interface, the corresponding 42 | Feature needs to be installed on your device. If it is already installed to the controller, it 43 | will be listed under Desk --> Settings --> System --> Installed Features. 44 | If FCI is not installed yet, you can synchronize it from your Franka World account to your 45 | controller. Therefore, you must have an available FCI license in your company/university account and have 46 | your controller registered in this account. The software (offline or online) synchronization 47 | process is described in more detail in the 48 | `Franka World user manual `_. 49 | 50 | 51 | .. _setting-up-the-network: 52 | 53 | Setting up the network 54 | ---------------------- 55 | 56 | Good network performance is crucial when controlling the robot using FCI. 57 | Therefore it is strongly recommended to use a direct connection between the 58 | workstation PC and Panda's Control. This section describes how to configure your 59 | network for this use case. 60 | 61 | .. figure:: _static/control.png 62 | :align: center 63 | :figclass: align-center 64 | 65 | Use Control's LAN port when controlling the robot through FCI. 66 | Do not connect to the port in Arm's base. 67 | 68 | The Control and your workstation must be configured to appear on the same 69 | network. Simplest way to achieve that is to use static IP addresses. Any two 70 | addresses on the same network would work, but the following values will be used 71 | for the purpose of this tutorial: 72 | 73 | +---------+----------------+------------+ 74 | | | Workstation PC | Control | 75 | +=========+================+============+ 76 | | Address | 172.16.0.1 | 172.16.0.2 | 77 | +---------+----------------+------------+ 78 | | Netmask | 24 | 24 | 79 | +---------+----------------+------------+ 80 | 81 | The Control's address (172.16.0.2) is called ```` in the following chapters. 82 | 83 | .. hint:: 84 | With this network configuration, Desk can be accessed via ``https://``, although 85 | you will see a certificate warning in your browser. 86 | 87 | The configuration process consists of two steps: 88 | 89 | * Configuring Control's network settings. 90 | * Configuring your workstation's network settings. 91 | 92 | Control network configuration 93 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 94 | 95 | For this step, the robot needs to be installed and tested. **Please read through 96 | the documents shipped with your robot and follow the setup instructions before 97 | continuing any further!** 98 | 99 | With system version >= 5.5.0, the Control's network can be configured in the settings interface. For 100 | the duration of this step you can connect to the robot through the port in the 101 | robot's base. For details, consult the `Connecting a user interface device` 102 | section in the manual delivered with your robot. 103 | 104 | .. figure:: _static/FrankaUI_Settings_Bar.png 105 | :align: center 106 | :figclass: align-center 107 | 108 | Accessing the Franka's settings interface through Desk. 109 | 110 | To set up a static address, enter the following values in the `Network` section: 111 | 112 | .. figure:: _static/FrankaUI_Settings_Network.png 113 | :align: center 114 | :figclass: align-center 115 | 116 | Setting a static IP for the Control's LAN port (Shop Floor network). 117 | DHCP Client option is deselected. 118 | 119 | Press `Apply`. After the settings are successfully applied, connect your 120 | workstation's LAN port to the robot's control unit. 121 | 122 | Linux workstation network configuration 123 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 124 | 125 | This section describes how to set up a static IP address on Ubuntu 16.04 126 | using the GUI. Follow the official Ubuntu guide_ if you prefer to use the 127 | command line. 128 | 129 | .. _guide: https://help.ubuntu.com/lts/serverguide/network-configuration.html 130 | 131 | .. caution:: 132 | The following steps will modify your network settings. If in doubt, 133 | contact your network's administrator. 134 | 135 | First, go to Network Connection widget. Select the wired connection you 136 | will be using and click edit. 137 | 138 | .. figure:: _static/edit-connections.png 139 | :align: center 140 | :figclass: align-center 141 | 142 | Edit the connection in the Ethernet section. 143 | 144 | Next, click on the IPv4 settings tab, set the method to Manual, and enter the 145 | following values: 146 | 147 | .. figure:: _static/static-ip-ubuntu.png 148 | :align: center 149 | :figclass: align-center 150 | 151 | Setting a static IP for the Workstation PC. Method is set to Manual. 152 | 153 | .. hint:: 154 | This step will disable DHCP, which means you will no longer obtain an address 155 | when connecting to a DHCP server, like the one in Arm's base. When you no 156 | longer use FCI, you can change the Method back to `Automatic (DHCP)`. 157 | 158 | Save the changes, and close the Network Connection window. Click on the 159 | connection name from the drop down menu. It should now be possible to connect to 160 | the robot from your workstation. To verify this, perform the 161 | :ref:`network-bandwidth-delay-test`. From now on, you can also access Desk 162 | through this address in your browser. 163 | 164 | .. _preparing_robot_in_desk: 165 | 166 | Preparing the robot for FCI usage in Desk 167 | ----------------------------------------- 168 | 169 | In order to verify the connection, the robot's brakes need to be unlocked in Desk and the activation 170 | device needs to be relased so that the robot is ready for execution indicated by blue LED mode. 171 | 172 | Activating the FCI mode 173 | ^^^^^^^^^^^^^^^^^^^^^^^ 174 | 175 | To activate FCI mode, open Desk, then release the robot brakes, and expand the menu in the top bar. Finally, click on 'Activate FCI'. 176 | 177 | .. figure:: _static/FrankaUI_System_ActivateFCI.png 178 | :align: center 179 | :figclass: align-center 180 | :width: 300px 181 | 182 | Activating the FCI mode in the Desk topbar menu (system version >= 5.5.0) 183 | 184 | 185 | FCI mode in Panda 186 | """"""""""""""""" 187 | 188 | After Activating the FCI mode, a pop-up as shown below is appearing. This pop-up indicates that the FCI mode 189 | is currently active and that Desk interactions are not allowed while it is active. This pop-up needs to 190 | remain open while working with FCI. Further information about Single Point of Control (SPoC) can be found 191 | in the manual shipped with the robot which can also be found in our 192 | `Franka World Hub `_. 193 | 194 | .. figure:: _static/pop_up_fci.png 195 | :align: center 196 | :figclass: align-center 197 | 198 | Pop-up when the FCI mode is activated 199 | 200 | FCI mode in Franka Research 3 201 | """"""""""""""""""""""""""""" 202 | 203 | After Activating the FCI mode, a pop-up appears, then the user needs to confirm. 204 | 205 | .. raw:: html 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 |
FrankaUI_System_ActivateFCI_ConfirmFrankaUI_System_ActivateFCI_Done
Sidebar is green when the FCI mode is activated
214 | 215 | Verifying the connection 216 | ------------------------ 217 | 218 | The previous sections described how to specify the IP address of the Control's 219 | LAN port. In the following sections that address is referred to as ````. 220 | 221 | In order to verify that everything is correctly set up, be sure :ref:`the robot is prepared for FCI 222 | usage in Desk ` and run the ``echo_robot_state`` 223 | example from ``libfranka``. If you decided to install ``franka_ros`` and ``libfranka`` from the ROS 224 | repository, you can instead read the instructions for 225 | :ref:`visualizing the robot in ros ` . 226 | 227 | Change to the build directory of ``libfranka`` and execute the example: 228 | 229 | .. code-block:: shell 230 | 231 | ./examples/echo_robot_state 232 | 233 | The program will print the current state of the robot to the console and terminate after a few 234 | iterations. The fields are explained in the :api:`RobotState|structfranka_1_1RobotState.html`. 235 | 236 | Example output: 237 | 238 | .. code-block:: json 239 | 240 | { 241 | "O_T_EE": [0.998578,0.0328747,-0.0417381,0,0.0335224,-0.999317,0.0149157,0,-0.04122,-0.016294, 242 | -0.999017,0,0.305468,-0.00814133,0.483198,1], 243 | "O_T_EE_d": [0.998582,0.0329548,-0.041575,0,0.0336027,-0.999313,0.0149824,0,-0.0410535, 244 | -0.0163585,-0.999023,0,0.305444,-0.00810967,0.483251,1], 245 | "F_T_EE": [0.7071,-0.7071,0,0,0.7071,0.7071,0,0,0,0,1,0,0,0,0.1034,1], 246 | "EE_T_K": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1], 247 | "m_ee": 0.73, "F_x_Cee": [-0.01,0,0.03], "I_ee": [0.001,0,0,0,0.0025,0,0,0,0.0017], 248 | "m_load": 0, "F_x_Cload": [0,0,0], "I_load": [0,0,0,0,0,0,0,0,0], 249 | "m_total": 0.73, "F_x_Ctotal": [-0.01,0,0.03], "I_total": [0.001,0,0,0,0.0025,0,0,0,0.0017], 250 | "elbow": [-0.0207622,-1], "elbow_d": [-0.0206678,-1], 251 | "tau_J": [-0.00359774,-5.08582,0.105732,21.8135,0.63253,2.18121,-0.0481953], 252 | "tau_J_d": [0,0,0,0,0,0,0], 253 | "dtau_J": [-54.0161,-18.9808,-64.6899,-64.2609,14.1561,28.5654,-11.1858], 254 | "q": [0.0167305,-0.762614,-0.0207622,-2.34352,-0.0305686,1.53975,0.753872], 255 | "dq": [0.00785939,0.00189343,0.00932415,0.0135431,-0.00220327,-0.00492024,0.00213604], 256 | "q_d": [0.0167347,-0.762775,-0.0206678,-2.34352,-0.0305677,1.53975,0.753862], 257 | "dq_d": [0,0,0,0,0,0,0], 258 | "joint_contact": [0,0,0,0,0,0,0], "cartesian_contact": [0,0,0,0,0,0], 259 | "joint_collision": [0,0,0,0,0,0,0], "cartesian_collision": [0,0,0,0,0,0], 260 | "tau_ext_hat_filtered": [0.00187271,-0.700316,0.386035,0.0914781,-0.117258,-0.00667777, 261 | -0.0252562], 262 | "O_F_ext_hat_K": [-2.06065,0.45889,-0.150951,-0.482791,-1.39347,0.109695], 263 | "K_F_ext_hat_K": [-2.03638,-0.529916,0.228266,-0.275938,0.434583,0.0317351], 264 | "theta": [0.01673,-0.763341,-0.0207471,-2.34041,-0.0304783,1.54006,0.753865], 265 | "dtheta": [0,0,0,0,0,0,0], 266 | "current_errors": [], "last_motion_errors": [], 267 | "control_command_success_rate": 0, "robot_mode": "Idle", "time": 3781435 268 | } 269 | 270 | .. hint:: 271 | 272 | If an error occurs at this point, perform the 273 | :ref:`ping test ` and ensure that the robot's fail-safe 274 | safety locking system is opened. Further information are provided in the manual shipped with 275 | the robot. 276 | -------------------------------------------------------------------------------- /source/index.rst: -------------------------------------------------------------------------------- 1 | Franka Control Interface Documentation 2 | ====================================== 3 | 4 | .. note:: 5 | 6 | The software and its documentation support two different robots, the 7 | `Franka Research 3 (FR3) `_ and an older Franka Robotics Robot (FER or Panda). 8 | 9 | .. todolist:: 10 | 11 | The Franka Control Interface (FCI) can be accessed via several open source components which we 12 | provide on `GitHub `_. We welcome contributions and suggestions 13 | for improvements. 14 | 15 | These components are: 16 | 17 | * ``libfranka``, a C++ library that provides low-level control of Franka Robotics research robots. 18 | Its source code is available at https://github.com/frankaemika/libfranka. API documentation is 19 | available at https://frankaemika.github.io/libfranka. 20 | * ``franka_ros``, our `ROS integration `_, including support for 21 | ROS Control and MoveIt!. It also contains ``franka_description``, a collection of URDF models and 22 | 3D meshes that can be useful outside of ROS. 23 | The repository is available at https://github.com/frankaemika/franka_ros. 24 | * ``franka_ros2`` The repository is available at https://github.com/frankaemika/franka_ros2. 25 | * ``Franka MATLAB®`` provides a Simulink and a Matlab API, together with helper functions and tools, 26 | for rapid-prototyping in Real-Time on the Franka Robot" 27 | Franka MATLAB® artifacts can be obtained at `Franka World `_. 28 | 29 | The source code of this documentation is also `available online 30 | `_. 31 | 32 | .. important:: 33 | Before you start using the FCI, please read through the documents shipped with the robot and 34 | the :doc:`requirements` chapter. 35 | 36 | .. note:: 37 | Using a robot with system version 4.2.0 or higher requires to enable the FCI mode. To do that 38 | open Desk -> expand the menu in the sidebar -> press `'Activate FCI'`. Further information 39 | about Single Point of Control (SPoC) can be found in the manual shipped with the robot. 40 | 41 | .. toctree:: 42 | :maxdepth: 2 43 | :caption: Contents: 44 | 45 | overview 46 | requirements 47 | compatibility 48 | installation_linux 49 | getting_started 50 | libfranka 51 | franka_ros 52 | franka_ros2 53 | franka_matlab/index 54 | franka_matlab/franka_matlab_changelog 55 | control_parameters 56 | fr3-certification-remarks 57 | troubleshooting 58 | faq 59 | -------------------------------------------------------------------------------- /source/installation_linux.rst: -------------------------------------------------------------------------------- 1 | Installation on Linux 2 | ===================== 3 | 4 | This chapter describes how to install ``libfranka`` and ``franka_ros``, either 5 | as binary packages or by building from source, and how to install a real-time 6 | Linux kernel. ``franka_ros`` is only required if you want to control your robot 7 | using `ROS `_. 8 | 9 | .. note:: 10 | 11 | While ``libfranka`` and the ``franka_ros`` packages should work on different Linux distributions, 12 | official support is currently only provided for: 13 | 14 | * Ubuntu 18.04 LTS `Bionic Beaver` and ROS `Melodic Morenia` (requires at least ``libfranka`` 0.6.0) 15 | * Ubuntu 20.04 LTS `Focal Fossa` and ROS `Noetic Ninjemys` (requires at least ``libfranka`` 0.8.0) 16 | 17 | The following instructions are exemplary for Ubuntu 20.04 LTS system and ROS `Noetic Ninjemys`. 18 | They only work in the supported environments. 19 | 20 | .. warning:: 21 | We do not offer support for Ubuntu 16.04 LTS `Xenial Xerus` and ROS `Kinetic Kame` anymore, as they have reached their 22 | end-of-life. 23 | 24 | Installing from the ROS repositories 25 | ------------------------------------ 26 | 27 | .. hint:: 28 | 29 | These packages might not always be up-to-date, as they are only synced at certain intervals. 30 | Read the changelog at https://frankaemika.github.io to find out which ``libfranka`` version is required for 31 | a particular robot software version. If this doesn't match the ``ros-noetic-libfranka`` version from the 32 | repositories, you need to :ref:`build from source `. 33 | 34 | Binary packages for ``libfranka`` and ``franka_ros`` are available from the ROS repositories. 35 | After `setting up ROS Noetic `__, execute:: 36 | 37 | sudo apt install ros-noetic-libfranka ros-noetic-franka-ros 38 | 39 | .. _installation-build-from-source: 40 | 41 | Building from source 42 | -------------------- 43 | 44 | Refer to the `README.md `_ 45 | 46 | Building the ROS packages 47 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 48 | 49 | After `setting up ROS Noetic `__, create a Catkin 50 | workspace in a directory of your choice: 51 | 52 | .. code-block:: shell 53 | 54 | cd /path/to/desired/folder 55 | mkdir -p catkin_ws/src 56 | cd catkin_ws 57 | source /opt/ros/noetic/setup.sh 58 | catkin_init_workspace src 59 | 60 | Then clone the ``franka_ros`` repository from `GitHub `__:: 61 | 62 | git clone --recursive https://github.com/frankaemika/franka_ros src/franka_ros 63 | 64 | By default, this will check out the newest release of ``franka_ros``. If you want to build a particular version of 65 | ``franka_ros`` instead, check out the corresponding Git tag:: 66 | 67 | git checkout 68 | 69 | Install any missing dependencies and build the packages: 70 | 71 | .. code-block:: shell 72 | 73 | rosdep install --from-paths src --ignore-src --rosdistro noetic -y --skip-keys libfranka 74 | catkin_make -DCMAKE_BUILD_TYPE=Release -DFranka_DIR:PATH=/path/to/libfranka/build 75 | source devel/setup.sh 76 | 77 | .. warning:: 78 | If you also installed ``ros-noetic-libfranka``, ``libfranka`` might be picked up from ``/opt/ros/noetic`` 79 | instead of from your custom ``libfranka`` build! 80 | 81 | .. _preempt: 82 | 83 | Setting up the real-time kernel 84 | ------------------------------- 85 | 86 | In order to control your robot using ``libfranka``, the controller program on 87 | the workstation PC must run with `real-time priority` under a ``PREEMPT_RT`` 88 | kernel. This section describes the procedure of patching a kernel to support 89 | ``PREEMPT_RT`` and creating an installation package. 90 | 91 | .. note:: 92 | 93 | NVIDIA drivers are not officially supported on ``PREEMPT_RT`` kernels, but the installation might work anyway by passing the environment variable ``IGNORE_PREEMPT_RT_PRESENCE=1`` to the installation command. 94 | 95 | First, install the necessary dependencies:: 96 | 97 | sudo apt-get install build-essential bc curl debhelper dpkg-dev devscripts fakeroot libssl-dev libelf-dev bison flex cpio kmod rsync libncurses-dev 98 | 99 | Then, you have to decide which kernel version to use. To find the one you are 100 | using currently, use ``uname -r``. Real-time patches are only available for 101 | select kernel versions, see 102 | https://www.kernel.org/pub/linux/kernel/projects/rt/. We recommend choosing the 103 | version closest to the one you currently use. If you choose a 104 | different version, simply substitute the numbers. Having decided on a version, 105 | use ``curl`` to download the source files: 106 | 107 | .. note:: 108 | For Ubuntu 16.04 tested with the kernel version 4.14.12: 109 | 110 | .. code:: 111 | 112 | curl -LO https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.12.tar.xz 113 | curl -LO https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.12.tar.sign 114 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/4.14/older/patch-4.14.12-rt10.patch.xz 115 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/4.14/older/patch-4.14.12-rt10.patch.sign 116 | 117 | .. note:: 118 | For Ubuntu 18.04 tested with the kernel version 5.4.19: 119 | 120 | .. code:: 121 | 122 | curl -LO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.4.19.tar.xz 123 | curl -LO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.4.19.tar.sign 124 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/5.4/older/patch-5.4.19-rt10.patch.xz 125 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/5.4/older/patch-5.4.19-rt10.patch.sign 126 | 127 | .. note:: 128 | For Ubuntu 20.04 tested with the kernel version 5.9.1: 129 | 130 | .. code:: 131 | 132 | curl -LO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz 133 | curl -LO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.sign 134 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/5.9/patch-5.9.1-rt20.patch.xz 135 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/5.9/patch-5.9.1-rt20.patch.sign 136 | 137 | .. note:: 138 | For Ubuntu 22.04, we recommend using the `Ubuntu Pro real-time kernel `_. After enabling it, you can skip directly to :ref:`installation-real-time`. 139 | In case you do not want to use Ubuntu Pro, you can proceed as for the other versions (tested with the kernel version 6.8.0): 140 | 141 | .. code:: 142 | 143 | curl -LO https://www.kernel.org/pub/linux/kernel/v6.x/linux-6.8.tar.xz 144 | curl -LO https://www.kernel.org/pub/linux/kernel/v6.x/linux-6.8.tar.sign 145 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/6.8/older/patch-6.8-rt8.patch.xz 146 | curl -LO https://www.kernel.org/pub/linux/kernel/projects/rt/6.8/older/patch-6.8-rt8.patch.sign 147 | 148 | And decompress them with:: 149 | 150 | xz -d *.xz 151 | 152 | Verifying file integrity 153 | ^^^^^^^^^^^^^^^^^^^^^^^^ 154 | 155 | .. note:: 156 | This step is optional but recommended! 157 | 158 | The ``.sign`` files can be used to verify that the downloaded files were not 159 | corrupted or tampered with. The steps shown here are adapted from the 160 | `Linux Kernel Archive `_ , see the 161 | linked page for more details about the process. 162 | 163 | You can use ``gpg2`` to verify the ``.tar`` archives:: 164 | 165 | gpg2 --verify linux-*.tar.sign 166 | gpg2 --verify patch-*.patch.sign 167 | 168 | If your output is similar to the following:: 169 | 170 | $ gpg2 --verify linux-*.tar.sign 171 | gpg: assuming signed data in 'linux-4.14.12.tar' 172 | gpg: Signature made Fr 05 Jan 2018 06:49:11 PST using RSA key ID 6092693E 173 | gpg: Can't check signature: No public key 174 | 175 | You have to first download the public key of the person who signed the above 176 | file. As you can see from the above output, it has the ID ``6092693E``. You can 177 | obtain it from the key server:: 178 | 179 | gpg2 --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 6092693E 180 | 181 | Similarly for the patch:: 182 | 183 | gpg2 --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 2872E4CC 184 | 185 | Note that keys for other kernel version might have different IDs, you will have to 186 | adapt accordingly. 187 | 188 | Having downloaded the keys, you can now verify the sources. Here is an example of 189 | a correct output:: 190 | 191 | $ gpg2 --verify linux-*.tar.sign 192 | gpg: assuming signed data in 'linux-4.14.12.tar' 193 | gpg: Signature made Fr 05 Jan 2018 06:49:11 PST using RSA key ID 6092693E 194 | gpg: Good signature from "Greg Kroah-Hartman " [unknown] 195 | gpg: aka "Greg Kroah-Hartman " [unknown] 196 | gpg: aka "Greg Kroah-Hartman (Linux kernel stable release signing key) " [unknown] 197 | gpg: WARNING: This key is not certified with a trusted signature! 198 | gpg: There is no indication that the signature belongs to the owner. 199 | Primary key fingerprint: 647F 2865 4894 E3BD 4571 99BE 38DB BDC8 6092 693E 200 | 201 | See `Linux Kernel Archive `_ 202 | for more information about the warning. 203 | 204 | 205 | 206 | Compiling the kernel 207 | ^^^^^^^^^^^^^^^^^^^^ 208 | 209 | Once you are sure the files were downloaded properly, you can extract the source 210 | code and apply the patch:: 211 | 212 | tar xf linux-*.tar 213 | cd linux-*/ 214 | patch -p1 < ../patch-*.patch 215 | 216 | Next copy your currently booted kernel configuration as the default config for the new real time kernel:: 217 | 218 | cp -v /boot/config-$(uname -r) .config 219 | 220 | Exclude the debug information from the kernel files to save space:: 221 | 222 | scripts/config --disable DEBUG_INFO 223 | scripts/config --disable DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT 224 | scripts/config --disable DEBUG_KERNEL 225 | 226 | Disable the system-wide ring of trusted keys:: 227 | 228 | scripts/config --disable SYSTEM_TRUSTED_KEYS 229 | scripts/config --disable SYSTEM_REVOCATION_LIST 230 | 231 | Activate the Fully Preemptible Kernel (Real-Time):: 232 | 233 | scripts/config --disable PREEMPT_NONE 234 | scripts/config --disable PREEMPT_VOLUNTARY 235 | scripts/config --disable PREEMPT 236 | scripts/config --enable PREEMPT_RT 237 | 238 | Now you can use this config as the default to configure the build:: 239 | 240 | make olddefconfig 241 | 242 | Afterwards, you are ready to compile the kernel. As this is a lengthy process, set the 243 | multithreading option ``-j`` to the number of your CPU cores:: 244 | 245 | make -j$(nproc) deb-pkg 246 | 247 | Finally, you are ready to install the newly created package. The exact names 248 | depend on your environment, but you are looking for ``headers`` and ``images`` 249 | packages without the ``dbg`` suffix. To install:: 250 | 251 | sudo IGNORE_PREEMPT_RT_PRESENCE=1 dpkg -i ../linux-headers-*.deb ../linux-image-*.deb 252 | 253 | Verifying the new kernel 254 | ^^^^^^^^^^^^^^^^^^^^^^^^ 255 | 256 | Restart your system. The Grub boot menu should now allow you to choose your 257 | newly installed kernel. To see which one is currently being used, see the output 258 | of the ``uname -a`` command. It should contain the string ``PREEMPT RT`` and the 259 | version number you chose. Additionally, ``/sys/kernel/realtime`` should exist and 260 | contain the the number ``1``. 261 | 262 | .. note:: 263 | If you encounter errors that you fail to boot the new kernel see :ref:`troubleshooting_realtime_kernel` 264 | 265 | .. _installation-real-time: 266 | 267 | Allow a user to set real-time permissions for its processes 268 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 269 | 270 | After the ``PREEMPT_RT`` kernel is installed and running, add a group named 271 | `realtime` and add the user controlling your robot to this group:: 272 | 273 | sudo addgroup realtime 274 | sudo usermod -a -G realtime $(whoami) 275 | 276 | Afterwards, add the following limits to the `realtime` group in 277 | ``/etc/security/limits.conf``:: 278 | 279 | @realtime soft rtprio 99 280 | @realtime soft priority 99 281 | @realtime soft memlock 102400 282 | @realtime hard rtprio 99 283 | @realtime hard priority 99 284 | @realtime hard memlock 102400 285 | 286 | The limits will be applied after you log out and in again. 287 | -------------------------------------------------------------------------------- /source/overview.rst: -------------------------------------------------------------------------------- 1 | Overview 2 | ======== 3 | 4 | .. figure:: _static/fci-architecture.png 5 | :align: center 6 | :figclass: align-center 7 | 8 | 9 | Schematic overview. 10 | 11 | The Franka Control Interface (FCI) allows a fast and direct low-level bidirectional connection 12 | to the Arm and Hand. It provides the current status of the robot and enables its direct control 13 | with an external workstation PC connected via Ethernet. 14 | By using ``libfranka``, our open source C++ interface, you can send real-time control values 15 | at 1 kHz with 5 different interfaces: 16 | 17 | * Gravity & friction compensated joint level torque commands. 18 | * Joint position or velocity commands. 19 | * Cartesian pose or velocity commands. 20 | 21 | At the same time, you get access to 1 kHz measurements of: 22 | 23 | * Measured joint data, such as the position, velocity and link side torque sensor signals. 24 | * Estimation of externally applied torques and forces. 25 | * Various collision and contact information. 26 | 27 | You also get access to the robot model library which provides: 28 | 29 | * Forward kinematics of all robot joints. 30 | * Jacobian matrix of all robot joints. 31 | * Dynamics: inertia matrix, Coriolis and centrifugal vector and gravity vector. 32 | 33 | In addition, ``franka_ros`` connects Franka Robotics research robots with the entire ROS ecosystem. 34 | It integrates ``libfranka`` into `ROS Control `_. 35 | Additionally, it includes `URDF `_ models and detailed 3D meshes of our 36 | robots and end effectors, which allows visualization (e.g. RViz) and kinematic simulations. 37 | `MoveIt! `_ integration makes it easy to move the robot and control 38 | the gripper, and the provided examples show you how to control your robot using ROS. 39 | 40 | .. important:: 41 | 42 | Data is sent over the network with a frequency of 1 kHz. Therefore, a good network connection 43 | is required! 44 | 45 | .. important:: 46 | 47 | While the FCI is active you have full, exclusive control of the Arm and Hand. This means that 48 | you `cannot` use Desk or Apps at the same time as the FCI. 49 | -------------------------------------------------------------------------------- /source/redirects: -------------------------------------------------------------------------------- 1 | installation.rst installation_linux.rst 2 | install_linux.rst installation_linux.rst 3 | -------------------------------------------------------------------------------- /source/requirements.rst: -------------------------------------------------------------------------------- 1 | Minimum system and network requirements 2 | ======================================= 3 | 4 | This page only specifies the requirements for running the Franka Control Interface (FCI). 5 | Additional requirements are specified in the documents that you have received with your robot. 6 | 7 | Workstation PC 8 | -------------- 9 | 10 | +---------------------------------------------------------+ 11 | | Minimum System Requirements | 12 | +===================+=====================================+ 13 | | Operating System | Linux with PREEMPT_RT patched kernel| 14 | +-------------------+-------------------------------------+ 15 | | Network card | 100BASE-TX | 16 | +-------------------+-------------------------------------+ 17 | 18 | Since the robot sends data at 1 kHz frequency, it is important that the workstation PC is configured 19 | to minimize latencies. For example, we recommend to 20 | :ref:`disable CPU frequency scaling `. Other possible optimizations 21 | will depend on your particular system. 22 | 23 | .. _requirement-network: 24 | 25 | Network 26 | ------- 27 | If possible, directly connect your workstation PC to the LAN port of Control, i.e. avoid any 28 | intermediate devices such as switches. 29 | 30 | .. important:: 31 | The workstation PC which commands your robot using the FCI must always be connected to the LAN 32 | port of Control (shop floor network) and **not** to the LAN port of the Arm (robot network). 33 | 34 | Having relays in between could lead to delay, jitter or packet loss. This will decrease the 35 | performance of your controller or make it unusable. 36 | 37 | .. hint:: 38 | The best performance can be achieved when connecting directly to the LAN port of Control. 39 | This requires setting up a static IP for the shop floor network in the administrator's interface 40 | beforehand. See :ref:`setting-up-the-network`. 41 | 42 | To control the robot, it must be guaranteed that the sum of the following time measurements is 43 | less than 1 ms: 44 | 45 | * Round trip time (RTT) between the workstation PC and FCI. 46 | * Execution time of your motion generator or control loop. 47 | * Time needed by the robot to process your data and step the internal controller. 48 | 49 | .. caution:: 50 | If the **<1 ms constraint** is violated for a cycle, the received packet is dropped by 51 | FCI. After 20 consecutively dropped packets, your robot `will stop` with the 52 | ``communication_constraints_violation`` error. Current measure of communication quality 53 | can be read from the ``RobotState::control_command_success_rate`` field. 54 | 55 | If a **motion generator command packet is dropped**, the robot takes the previous waypoints and 56 | performs a linear extrapolation (keep acceleration constant and integrate) for the missed 57 | time step. If more than 20 packets are lost or dropped in a row, your robot `will stop`. 58 | 59 | If a **controller command packet is dropped**, FCI will reuse the torques of the last successful 60 | received packet. Again, more than 20 consecutive lost or dropped packets will cause your robot to 61 | `stop`. 62 | 63 | .. hint:: 64 | Measure the performance of your network (see :ref:`network-bandwidth-delay-test`) and the 65 | control or motion generator loop beforehand. 66 | -------------------------------------------------------------------------------- /source/troubleshooting.rst: -------------------------------------------------------------------------------- 1 | Troubleshooting 2 | =============== 3 | This section lists solutions to a set of possible errors which can happen when using the FCI. 4 | 5 | .. hint:: 6 | 7 | Further help is provided in the troubleshooting page of the manual shipped with your robot. 8 | 9 | .. _troubleshooting_realtime_kernel: 10 | 11 | Cannot boot realtime kernel because of "Invalid Signature" 12 | ---------------------------------------------------------- 13 | 14 | When you have successfully installed the real-time kernel and try to boot it you might encounter 15 | that Linux is not booting at all. This can happen when you have installed Ubuntu alongside with 16 | Windows (e.g. Dual Boot). Usually then the UEFI boot loader will have *Secure Boot* activated, 17 | which will not allow the unsigned real-time kernel to load. 18 | 19 | The easiest solution is to **disable "Secure Boot"** in your boot loader. This highly depends on your 20 | system, but usually you can enter the boot loader by pressing F2, F3, F12 or DEL key during boot. 21 | 22 | 23 | .. _troubleshooting_connection_timeout: 24 | 25 | Running a libfranka executable fails with "Connection timeout" 26 | ---------------------------------------------------------------- 27 | 28 | This error occurs if ``libfranka`` cannot connect to the robot at all. Please check that: 29 | 30 | * Using a robot with system version 4.2.0 or higher requires to enable the FCI mode. To do that 31 | open Desk -> expand the menu in the sidebar -> press `'Activate FCI'`. Further information 32 | about Single Point of Control (SPoC) can be found in the manual shipped with the robot. 33 | * Your workstation is directly connected to Control, not the LAN port of the Arm (see 34 | :ref:`requirement-network`). 35 | * The robot can be reached from your workstation (see :ref:`troubleshooting_robot_not_reachable`). 36 | * The FCI feature file is installed on the robot (see "Settings -> System -> Installed Features"). 37 | If you do not have this feature, please install it. Please reach out to `support@franka.de` with 38 | your serial number if you need to obtain the feature. 39 | 40 | .. _motion-stopped-due-to-discontinuities: 41 | 42 | Motion stopped due to discontinuities or ``communication_constraints_violation`` 43 | -------------------------------------------------------------------------------- 44 | 45 | If the difference between commanded values in subsequent time steps is too large, then the motion is 46 | stopped with a discontinuity error such as ``joint_motion_generator_velocity_discontinuity``. See if 47 | the commanded values do not exceed the :ref:`limits `. 48 | 49 | Discontinuities can occur if your code commands actual jumps to the robot, but also because of 50 | network packet losses. This is also the reason for ``communication_constraints_violation`` errors. 51 | If the issue occurs even when using the provided examples, the problem is most likely related to 52 | overall communication quality. To ensure best performance, please check the following: 53 | 54 | * All source code is compiled with optimizations (``-DCMAKE_BUILD_TYPE=Release``). If you installed 55 | ``libfranka`` and ``franka_ros`` from the ROS repositories, this is already the case for these 56 | projects. However, your own source code needs to be compiled with optimizations as well. 57 | * Connect your PC directly to Control, without using any intermediate switches. The 58 | :ref:`network setup instructions ` describe how to do this. 59 | * Verify your network connection by executing the `network bandwidth, delay and jitter test`_. 60 | * ``franka::Robot`` is instantiated with ``RealtimeConfig::kEnforce``. This is the default if no 61 | ``RealtimeConfig`` is explicitly specified in the constructor. 62 | * Power saving features are disabled (cpu frequency scaling, power saving mode, 63 | laptop on battery, BIOS power saving features, etc.). See `Disabling CPU frequency scaling`_. 64 | 65 | .. _disable_cpu_frequency_scaling: 66 | 67 | Disabling CPU frequency scaling 68 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 69 | 70 | CPUs are often configured to use a lower operating frequency when under a light load in order to 71 | conserve power. We recommend to disable this feature as it leads to higher latencies when using 72 | ``libfranka``. To check and modify the power saving mode, install the ``cpufrequtils`` package: 73 | 74 | .. code-block:: shell 75 | 76 | sudo apt install cpufrequtils 77 | 78 | Run ``cpufreq-info`` to see available "governors" and the current CPU frequency. Here is an example 79 | output: 80 | 81 | .. code-block:: shell 82 | 83 | $ cpufreq-info 84 | ... 85 | analyzing CPU 0: 86 | driver: intel_pstate 87 | CPUs which run at the same hardware frequency: 0 88 | CPUs which need to have their frequency coordinated by software: 0 89 | maximum transition latency: 0.97 ms. 90 | hardware limits: 400 MHz - 3.00 GHz 91 | available cpufreq governors: performance, powersave 92 | current policy: frequency should be within 400 MHz and 3.00 GHz. 93 | The governor "powersave" may decide which speed to use 94 | within this range. 95 | current CPU frequency is 500 MHz. 96 | ... 97 | 98 | In this example, the maximum frequency is 3 GHz, but the current one is 500 Mhz due to the 99 | ``powersave`` policy. In this case we can benefit by setting the governor to ``performance``. 100 | 101 | To change this setting using the Ubuntu GUI, install the ``indicator-cpufreq`` package. A widget in 102 | the top bar of the Unity user interface should allow you to set the current policy. 103 | 104 | To change this setting using the terminal, execute the following commands: 105 | 106 | .. code-block:: shell 107 | 108 | sudo systemctl disable ondemand 109 | sudo systemctl enable cpufrequtils 110 | sudo sh -c 'echo "GOVERNOR=performance" > /etc/default/cpufrequtils' 111 | sudo systemctl daemon-reload && sudo systemctl restart cpufrequtils 112 | 113 | They will disable the ``ondemand`` CPU scaling daemon, create a ``/etc/default/cpufrequtils`` 114 | configuration file, and then restart the ``cpufrequtils`` service. 115 | 116 | After enabling the ``performance`` governor, the ``cpufreq-info`` results are: 117 | 118 | .. code-block:: shell 119 | 120 | $ cpufreq-info 121 | ... 122 | analyzing CPU 0: 123 | driver: intel_pstate 124 | CPUs which run at the same hardware frequency: 0 125 | CPUs which need to have their frequency coordinated by software: 0 126 | maximum transition latency: 0.97 ms. 127 | hardware limits: 400 MHz - 3.00 GHz 128 | available cpufreq governors: performance, powersave 129 | current policy: frequency should be within 400 MHz and 3.00 GHz. 130 | The governor "performance" may decide which speed to use 131 | within this range. 132 | current CPU frequency is 2.83 GHz. 133 | ... 134 | 135 | Now the example output shows a CPU frequency close to the maximum one. You can 136 | also directly verify the current governor using the ``cpufreq-info -p`` command. 137 | 138 | .. _troubleshooting_robot_not_reachable: 139 | 140 | Robot is not reachable 141 | ---------------------- 142 | 143 | Try to ping the robot using the following command: 144 | 145 | .. code-block:: shell 146 | 147 | ping 148 | 149 | If this command fails, the robot is not properly connected to the network, or the IP address 150 | is not correctly assigned during the setup phase. Please set up the network according to the 151 | documents sent with your robot. 152 | 153 | .. _troubleshooting_udp_timeout: 154 | 155 | Running a libfranka executable fails with "UDP receive: Timeout" 156 | ---------------------------------------------------------------- 157 | 158 | This error occurs if the robot state can not be received by ``libfranka``. Please check that 159 | your workstation's firewall does not block incoming UDP packets (see ``sudo iptables -L``). 160 | 161 | .. _network-bandwidth-delay-test: 162 | 163 | Network bandwidth, delay and jitter test 164 | ---------------------------------------- 165 | 166 | In order to evaluate the network performance of your (possible) control PC we've developed two 167 | tests. The first, a ping test, can be executed without the need of libfranka or franka_ros 168 | installed on your system. If your system passes the first ping test, you can run the 169 | advanced UDP network performance analysis. 170 | 171 | .. _network-ping-test: 172 | 173 | Simple ping tests 174 | ^^^^^^^^^^^^^^^^^ 175 | 176 | The following command will simulate a network load which is equivalent to a scenario where the 177 | robot is controlled by the FCI: 178 | 179 | .. code-block:: shell 180 | 181 | sudo ping -i 0.001 -D -c 10000 -s 1200 182 | 183 | Example output: 184 | 185 | .. code-block:: shell 186 | 187 | PING 1200(1228) bytes of data. 188 | [1500982522.977579] 1208 bytes from : icmp_seq=1 ttl=64 time=0.279 ms 189 | [1500982522.978423] 1208 bytes from : icmp_seq=2 ttl=64 time=0.224 ms 190 | [1500982522.979434] 1208 bytes from : icmp_seq=3 ttl=64 time=0.196 ms 191 | [1500982522.980482] 1208 bytes from : icmp_seq=4 ttl=64 time=0.243 ms 192 | .... 193 | [1500982533.034267] 1208 bytes from : icmp_seq=9999 ttl=64 time=0.236 ms 194 | [1500982533.035211] 1208 bytes from : icmp_seq=10000 ttl=64 time=0.203 ms 195 | 196 | --- ping statistics --- 197 | 10000 packets transmitted, 10000 received, 0% packet loss, time 10057ms 198 | rtt min/avg/max/mdev = 0.147/0.240/0.502/0.038 ms 199 | 200 | 201 | The example result shows an average round-trip time of 0.24 ms and a maximum round-trip time of 0.5 202 | ms. The standard deviation `mdev` is around 0.04 ms. As explained in the 203 | :ref:`network requirements section` it must be guaranteed that the sum of the 204 | round-trip time and the execution time of the motion generator or control loop is 205 | **less than 1 ms**. If this constraint is violated for a cycle, the received packet is dropped by 206 | the FCI. 207 | 208 | If the round-trip time is long even with a direct connection, consider 209 | purchasing a separate, high performance PCI-Express network card for your 210 | workstation PC. See if there are dedicated drivers for your network card, 211 | these usually offer better performance. Lastly, the CPU can also be a limiting 212 | factor for network performance. 213 | 214 | 215 | Advanced network performance analysis 216 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 217 | 218 | The ``communication_test`` executable, which is part of the ``libfranka`` examples since 219 | version 0.5, executes a control loop and provides feedback about the lost robot 220 | states as well as the maximum, minimum and average control command success rate. 221 | 222 | If you installed the ``ros-noetic-libfranka`` package or installed ``libfranka`` from source, you can execute the test with: 223 | 224 | .. code-block:: shell 225 | 226 | source /opt/ros/noetic/setup.sh # only needed when installed with ROS 227 | communication_test 228 | 229 | If you do not want to install ``libfranka`` system-wide you can execute the following command inside your build folder after compiling ``libfranka`` 230 | from source: 231 | 232 | .. code-block:: shell 233 | 234 | ./examples/communication_test 235 | 236 | Running a libfranka executable fails with "Incompatible Library Version" 237 | ------------------------------------------------------------------------ 238 | 239 | This happens when your version of libfranka is incompatible with the system version of your robot. 240 | The error contains the server version of the robot. You can use that number to 241 | :ref:`choose the correct libfranka version for your robot`. 242 | 243 | Running a libfranka executable fails with "command rejected due to activated safety function!" or "command preempted due to activated safety function!" 244 | ------------------------------------------------------------------------------------------------------------------------------------------------------- 245 | 246 | This error occurs when a safety function defined in Watchman (the safety configurator area of the Desk webpage) is active. 247 | For example, there could be an active safety function limiting the robot's speed to 0.2 m/s. As this cannot be guaranteed when using FCI, the 248 | robot will not move. However, you can still read the robot state. In order to command movements to the robot again, 249 | you either need to disable the safety function or delete the corresponding safety rule in Watchman. 250 | --------------------------------------------------------------------------------