From 152bd9fe18df7461d97785f6b216304b521177d8 Mon Sep 17 00:00:00 2001 From: Fatma-Dhaoui Date: Mon, 9 Sep 2024 14:43:31 +0200 Subject: [PATCH 1/5] doc: add README.md --- README.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 168 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9eff1a5f..ecbcc056 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,175 @@ -# ROS 2 integration for Franka Robotics research robots +# ROS 2 Integration for Franka Robotics Research Robots [![CI](https://github.com/frankaemika/franka_ros2/actions/workflows/ci.yml/badge.svg)](https://github.com/frankaemika/franka_ros2/actions/workflows/ci.yml) -See the [Franka Control Interface (FCI) documentation][fci-docs] for more information. +**Note:** franka_ros2 is not supported on Windows. -## License +See the [Franka Control Interface (FCI) documentation](https://frankaemika.github.io/docs) for more information. -All packages of `franka_ros2` are licensed under the [Apache 2.0 license][apache-2.0]. +## Table of Contents +- [About](#about) +- [Caution](#caution) +- [Prerequisites](#prerequisites) +- [Optional .bashrc Settings](#optional-bashrc-settings) +- [Setup](#setup) + - [Install From Source](#install-from-source) + - [Use VSCode DevContainer](#use-vscode-devcontainer) +- [Troubleshooting](#troubleshooting) + - [Error: Docker Unable to Access /tmp/.X11-unix](#error-docker-unable-to-access-tmpx11-unix) +- [Contributing](#contributing) +- [License](#license) +- [Contact](#contact) -[apache-2.0]: https://www.apache.org/licenses/LICENSE-2.0.html +## About +The **franka_ros2** repository provides a **ROS 2** integration of **libfranka**, allowing efficient control of the Franka Robotics arm within the ROS 2 framework. This project is designed to facilitate robotic research and development by providing a robust interface for controlling the research versions of Franka Robotics robots. -[fci-docs]: https://frankaemika.github.io/docs +## Caution +This package is in rapid development. Users should expect breaking changes and are encouraged to report any bugs via [GitHub Issues page](https://github.com/frankaemika/franka_ros2/issues). + +## Prerequisites +Before installing **franka_ros2**, ensure you have the following prerequisites: +- **ROS 2 Humble Installation:** You can install `ros-humble-desktop` or use VSCode IDE with DevContainer. +- **PREEMPT_RT Kernel (optional but recommended):** A real-time kernel is necessary for the cartesian_pose, joint_position, and elbow_position command interfaces. +- **System-wide libfranka Installation:** Minimum supported version: 0.13.2. Refer to the [libfranka repository](https://github.com/frankaemika/libfranka) for build steps. + +## Optional .bashrc Settings +Enhance your development experience by adding the following lines to your `.bashrc` file: + +```bash +# Enable colorized warn and error messages +export RCUTILS_COLORIZED_OUTPUT=1 + +# Set system language to American English to avoid issues in RViz +export LC_NUMERIC=en_US.UTF-8 +``` + +## Setup + +### Install From Source + +1. **Install Required Packages:** + ```bash + sudo apt install -y \ + ros-humble-ament-cmake \ + ros-humble-ament-cmake-clang-format \ + ros-humble-angles \ + ros-humble-ros2-controllers \ + ros-humble-ros2-control \ + ros-humble-ros2-control-test-assets \ + ros-humble-controller-manager \ + ros-humble-control-msgs \ + ros-humble-control-toolbox \ + ros-humble-generate-parameter-library \ + ros-humble-joint-state-publisher \ + ros-humble-joint-state-publisher-gui \ + ros-humble-moveit \ + ros-humble-pinocchio \ + ros-humble-realtime-tools \ + ros-humble-xacro \ + ros-humble-hardware-interface \ + ros-humble-ros-gz \ + python3-colcon-common-extensions + ``` + + +2. **Create a ROS 2 Workspace:** + ```bash + mkdir -p ~/franka_ros2_ws/src + ``` +3. **Clone the Repositories and Build Packages:** + ```bash + source /opt/ros/humble/setup.bash + cd ~/franka_ros2_ws + git clone https://github.com/frankaemika/franka_ros2.git src/franka_ros2 + git clone https://github.com/frankaemika/franka_description.git src/franka_description + colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release + source install/setup.sh + ``` + +### Use VSCode DevContainer + + +The `franka_ros2` package includes a `.devcontainer` folder, which allows you to use Franka ROS 2 packages without manually installing ROS 2 or `libfranka`. For detailed instructions, follow the setup guide from [VSCode devcontainer_setup](https://code.visualstudio.com/docs/devcontainers/tutorial). + +1. **Create a ROS 2 Workspace:** + ```bash + mkdir franka_ros2_ws + cd franka_ros2_ws + ``` + +2. **Clone the Repositories:** + ```bash + git clone https://github.com/frankaemika/franka_ros2.git src/franka_ros2 + git clone https://github.com/frankaemika/franka_description.git src/franka_description + ``` + +3. **Move the .devcontainer Folder:** + ```bash + mv src/franka_ros2/.devcontainer . + ``` + +4. **Open VSCode:** + ```bash + code . + ``` +5. **Open the Current Folder in DevContainer:** + + Press Ctrl + Shift + P and type: `Dev Containers: Rebuild and Reopen in Container`. + + +6. **Open the Terminal in VSCode:** + + Press Ctrl + (backtick). + +7. **Install the Franka ROS 2 Packages:** + ```bash + source /opt/ros/humble/setup.sh + ``` +8. **Install the Franka ROS 2 Packages:** + ```bash + colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release + source install/setup.sh + ``` +## Troubleshooting +### Error: Docker Unable to Access /tmp/.X11-unix + +If you encounter the following error after running **Rebuild and Reopen in Container**: + +Error response from daemon: Mounts denied: +The path /tmp/.X11-unix is not shared from the host and is not known to Docker. + + +This occurs because Docker cannot access the `/tmp/.X11-unix` directory on the host system. Follow these steps to fix it: + +1. **Allow Docker to Access /tmp/.X11-unix:** + + If you are using Docker Desktop, navigate to: + + 1. `Docker Desktop` -> `Settings` -> `Resources` -> `File Sharing` + 2. Add `/tmp/.X11-unix` to the list of shared directories. + 3. Apply the changes and restart Docker. + +2. **Verify Sharing Path on Linux:** + + Ensure that Docker has the correct permissions for /tmp/.X11-unix: + ```bash + sudo chmod +x /tmp/.X11-unix + ``` + + +3. **Restart Docker and re-run the container.** + + +## Contributing + +Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/frankaemika/franka_description/blob/d722358a418126296a7ad0d79a53c2ba7f6da46c/CONTRIBUTING.md#L4) for more details on how to contribute to this project. + + +## License + +All packages of franka_ros2 are licensed under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html). + + +## Contact + +For questions or support, please open an issue on the [GitHub Issues](https://github.com/frankaemika/franka_ros2/issues) page. From 90d719a37761bd5c2ca1f6d4a86c060e1bbe21e9 Mon Sep 17 00:00:00 2001 From: Fatma-Dhaoui Date: Tue, 17 Sep 2024 16:55:33 +0200 Subject: [PATCH 2/5] doc: add CONTRIBUTING.md specific to franka_ros2 repository --- CONTRIBUTING.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..09362a28 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,18 @@ +Any contribution that you make to this repository will +be under the Apache 2 License, as dictated by that +[license](http://www.apache.org/licenses/LICENSE-2.0.html): + +~~~ +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. +~~~ + +Contributors must sign-off each commit by adding a `Signed-off-by: ...` +line to commit messages to certify that they have the right to submit +the code they are contributing to the project according to the +[Developer Certificate of Origin (DCO)](https://developercertificate.org/). \ No newline at end of file From e2fe958572aad07c2ffe07c7980bad799d52f404 Mon Sep 17 00:00:00 2001 From: Fatma-Dhaoui Date: Tue, 17 Sep 2024 17:15:29 +0200 Subject: [PATCH 3/5] update readme --- README.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ecbcc056..bb5f604f 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ [![CI](https://github.com/frankaemika/franka_ros2/actions/workflows/ci.yml/badge.svg)](https://github.com/frankaemika/franka_ros2/actions/workflows/ci.yml) -**Note:** franka_ros2 is not supported on Windows. +**Note:** franka_ros2 is not officially supported on Windows. + -See the [Franka Control Interface (FCI) documentation](https://frankaemika.github.io/docs) for more information. ## Table of Contents - [About](#about) @@ -28,9 +28,13 @@ This package is in rapid development. Users should expect breaking changes and a ## Prerequisites Before installing **franka_ros2**, ensure you have the following prerequisites: -- **ROS 2 Humble Installation:** You can install `ros-humble-desktop` or use VSCode IDE with DevContainer. +- **ROS 2 Humble Installation:** You can install [`ros-humble-desktop`](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html) or use VSCode IDE with DevContainer. - **PREEMPT_RT Kernel (optional but recommended):** A real-time kernel is necessary for the cartesian_pose, joint_position, and elbow_position command interfaces. -- **System-wide libfranka Installation:** Minimum supported version: 0.13.2. Refer to the [libfranka repository](https://github.com/frankaemika/libfranka) for build steps. +- **System-wide libfranka Installation:** + - If you plan to **install from source**, a libfranka installation is required. Please refer to the [libfranka repository](https://github.com/frankaemika/libfranka) for detailed build steps. + - If you are **using the DevContainer**, you do not need to install libfranka system-wide, as it will be included in the container. + + Regardless of your setup, it is important to check the compatibility of your Robot OS version with libfranka to avoid potential errors. For detailed compatibility information, please consult the [libfranka compatibility matrix](https://frankaemika.github.io/docs/compatibility.htmlk-to-matrix). ## Optional .bashrc Settings Enhance your development experience by adding the following lines to your `.bashrc` file: @@ -103,10 +107,11 @@ The `franka_ros2` package includes a `.devcontainer` folder, which allows you to git clone https://github.com/frankaemika/franka_description.git src/franka_description ``` -3. **Move the .devcontainer Folder:** +3. **Copy the .devcontainer Folder:** ```bash - mv src/franka_ros2/.devcontainer . + cp -r src/franka_ros2/.devcontainer . ``` + This step ensures that both the `franka_ros2` and `franka_description` folders are accessible within the DevContainer environment. 4. **Open VSCode:** ```bash @@ -121,7 +126,7 @@ The `franka_ros2` package includes a `.devcontainer` folder, which allows you to Press Ctrl + (backtick). -7. **Install the Franka ROS 2 Packages:** +7. **Source the Environment:** ```bash source /opt/ros/humble/setup.sh ``` @@ -162,7 +167,7 @@ This occurs because Docker cannot access the `/tmp/.X11-unix` directory on the h ## Contributing -Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/frankaemika/franka_description/blob/d722358a418126296a7ad0d79a53c2ba7f6da46c/CONTRIBUTING.md#L4) for more details on how to contribute to this project. +Contributions are welcome! Please see [CONTRIBUTING.md]() for more details on how to contribute to this project. ## License @@ -173,3 +178,5 @@ All packages of franka_ros2 are licensed under the [Apache 2.0 license](https:// ## Contact For questions or support, please open an issue on the [GitHub Issues](https://github.com/frankaemika/franka_ros2/issues) page. + +See the [Franka Control Interface (FCI) documentation](https://frankaemika.github.io/docs) for more information. From 5a3e0d917221a0cdb913321e402bbd597265f208 Mon Sep 17 00:00:00 2001 From: Fatma-Dhaoui Date: Thu, 19 Sep 2024 11:53:15 +0200 Subject: [PATCH 4/5] update readme --- README.md | 29 +++-------------------------- 1 file changed, 3 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index bb5f604f..b0383f0a 100644 --- a/README.md +++ b/README.md @@ -136,34 +136,11 @@ The `franka_ros2` package includes a `.devcontainer` folder, which allows you to source install/setup.sh ``` ## Troubleshooting -### Error: Docker Unable to Access /tmp/.X11-unix +### `libfranka: UDP receive: Timeout error` -If you encounter the following error after running **Rebuild and Reopen in Container**: - -Error response from daemon: Mounts denied: -The path /tmp/.X11-unix is not shared from the host and is not known to Docker. - - -This occurs because Docker cannot access the `/tmp/.X11-unix` directory on the host system. Follow these steps to fix it: - -1. **Allow Docker to Access /tmp/.X11-unix:** - - If you are using Docker Desktop, navigate to: - - 1. `Docker Desktop` -> `Settings` -> `Resources` -> `File Sharing` - 2. Add `/tmp/.X11-unix` to the list of shared directories. - 3. Apply the changes and restart Docker. - -2. **Verify Sharing Path on Linux:** - - Ensure that Docker has the correct permissions for /tmp/.X11-unix: - ```bash - sudo chmod +x /tmp/.X11-unix - ``` - - -3. **Restart Docker and re-run the container.** +If you encounter a UDP receive timeout error while communicating with the robot, avoid using Docker Desktop. It may not provide the necessary real-time capabilities required for reliable communication with the robot. Instead, using Docker Engine is sufficient for this purpose. +A real-time kernel is essential to ensure proper communication and to prevent timeout issues. For guidance on setting up a real-time kernel, please refer to the [Franka installation documentation](https://frankaemika.github.io/docs/installation_linux.html#setting-up-the-real-time-kernel). ## Contributing From 172f779307516a3e6e57e25dddb63439b51d7ab2 Mon Sep 17 00:00:00 2001 From: Fatma-Dhaoui Date: Thu, 19 Sep 2024 14:42:39 +0200 Subject: [PATCH 5/5] readme final version --- README.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b0383f0a..66499ed0 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,9 @@ - [Setup](#setup) - [Install From Source](#install-from-source) - [Use VSCode DevContainer](#use-vscode-devcontainer) + - [Test the Setup](#test-the-setup) - [Troubleshooting](#troubleshooting) - - [Error: Docker Unable to Access /tmp/.X11-unix](#error-docker-unable-to-access-tmpx11-unix) + - [libfranka: UDP receive: Timeout error](#libfranka-udp-receive-timeout-error) - [Contributing](#contributing) - [License](#license) - [Contact](#contact) @@ -37,14 +38,11 @@ Before installing **franka_ros2**, ensure you have the following prerequisites: Regardless of your setup, it is important to check the compatibility of your Robot OS version with libfranka to avoid potential errors. For detailed compatibility information, please consult the [libfranka compatibility matrix](https://frankaemika.github.io/docs/compatibility.htmlk-to-matrix). ## Optional .bashrc Settings -Enhance your development experience by adding the following lines to your `.bashrc` file: +Enhance your development experience by adding the following line to your `.bashrc` file: ```bash # Enable colorized warn and error messages export RCUTILS_COLORIZED_OUTPUT=1 - -# Set system language to American English to avoid issues in RViz -export LC_NUMERIC=en_US.UTF-8 ``` ## Setup @@ -135,6 +133,17 @@ The `franka_ros2` package includes a `.devcontainer` folder, which allows you to colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release source install/setup.sh ``` + + +### Test the Setup + +To verify that your setup works correctly without a robot, you can run the following command to use dummy hardware: + +```bash +ros2 launch franka_moveit_config moveit.launch.py robot_ip:=dont-care use_fake_hardware:=true +``` + + ## Troubleshooting ### `libfranka: UDP receive: Timeout error` @@ -144,7 +153,7 @@ A real-time kernel is essential to ensure proper communication and to prevent ti ## Contributing -Contributions are welcome! Please see [CONTRIBUTING.md]() for more details on how to contribute to this project. +Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/frankaemika/franka_ros2/blob/humble/CONTRIBUTING.md) for more details on how to contribute to this project. ## License