├── .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 |
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 |
--------------------------------------------------------------------------------
/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 |
--------------------------------------------------------------------------------
/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 |
Sidebar is green when the FCI mode is activated
213 |
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 |
--------------------------------------------------------------------------------