ros2_torch_control workspace

This workspace is designed for inferring PyTorch control policies on Franka robots, with an integration into the ROS 2 Humble ecosystem. It shall run on a control PC attached directly to the robot for all low level control (ros2_control) and on one external PC for high level control (e.g. MoveIt 2 and inference).

The readme will be further improved in the future.
For now it contains the most important information to get started with this workspace.

Setup and Usage

High level steps

1. Setup the workspace on the control PC connected to the robot. This involves cloning the repo, building and starting the docker cotnainer and building the workspace inside the docker container.
2. Inside that docker cotnainer just start the control loop via single_control.
   Do not forget to configure the robot environment via the config file accessed by the conf alias.
3. Setup the workspace on the external PC. This involves cloning the repo, building and starting the docker cotnainer and building the workspace inside the docker container.
4. Inside that docker container just start MoveIt 2 via rv.
   Do not forget to configure the robot environment via the config file accessed by the conf alias. The config file shall not be different to the one on the control PC.

Do not forget to set the same ROS_DOMAIN_ID on both PCs. You can do this via the rdi alias or via the .env file before starting the docker container.

Detailed steps to setup this workspace

First Time Setup - You only need to do this once for every PC

1. Install the NVIDIA Container Toolkit on your host PC to be able to use a GPU. Follow the instructions here.
2. With ROS 2 we use CycloneDDS as a middleware with a custom configuration. As we partially transmit large messages (e.g. images) we need to increase the maximum Linux kernel receive buffer size and increase the maximum memory used to reassemble IP fragments.
   To do this just execute this command and reboot your machine:

   sudo tee /etc/sysctl.d/10-cyclone-max.conf > /dev/null << 'EOF'
   # IP fragmentation settings
   net.ipv4.ipfrag_time=3  # in seconds, default is 30 s
   net.ipv4.ipfrag_high_thresh=134217728  # 128 MiB, default is 256 KiB
   # Increase the maximum receive buffer size for network packets
   net.core.rmem_max=2147483647  # 2 GiB, default is 208 KiB
   EOF

   If you forget to do this, you will not be able to use the ROS2 network!
   More information can be found here.

Setup after every reboot

As we use GUI applications like RViz2 inside the docker, we need to allow the container to access the X11 socket of the host system. To do this just execute this command:

xhost +si:localuser:$(whoami)

If you do not do this, you will not be able to use the GUI applications inside the container. If you are trying to, a error message like this will be shown:

Authorization required, but no authorization protocol specified
qt.qpa.xcb: could not connect to display :1	qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, xcb.

You can make this command permanent by adding it to your .bashrc file:

echo "xhost +si:localuser:$(whoami)" >> ~/.bashrc

Repo setup

1. First clone this workspace:

   git clone https://github.com/Fraunhofer-IIS/ros2_torch_control.git

2. edit the .env file: Either edit it manually or use the provided script to set UID, GID and NETWORK_INTERFACE:

   ./env_setup.sh

   1. image_name: name of your docker image
   2. UID: usually this is 1000. Please check via id -u in your terminal. If different change accordingly.
   3. GID: usually the same as UID (1000). Please check via id -g in your terminal. If different change accordingly.
   4. ROS_DOMAIN_ID: If you are working in the lab choose a random number between 110 and 199. If you are mainly working at the office chosse a random number between 2 and 99.
      This is an environment variable used in ROS 2 to change the ports that ROS 2 processes use for communication. This effectively allows us to separate different ROS 2 processes from communicating with each other on the same network and thus avoiding that topics from different people are accidentally talking over each over. For a detailed explanation, click here.
   5. NETWORK_INTERFACE: By default this is set to docker0. You shall change this to the name of your network interface which is currently connected to the internet.
      You can find the names of your network interface by running iwconfig in your terminal. With ifconfig you can figure out which network interface is used. This is usually the one with an IP address of the form 10.4.119.XXX. The interface name is the first word in the list output of ifconfig.
      If not changed, you are only able to use ROS 2 on your local machine and will not be able to communicate with other machines.
   6. TORCH: If you want to use PyTorch inside the container, set this to true. This will install the latest version of PyTorch inside the container. If you do not need it, set it to false.

3. for the inital setup run ./setup.bash. This will also run ./env_setup.bash and builds the container once and the corresponding workspace.

4. continue with section "How to use"

---

How to use

1. Run docker container by executing

   docker compose up dev
   

   or if you want to use a GPU (needs NVIDIA Container Toolkit on the host PC):

   docker compose up dev_gpu
   

   Same works for the user_ws (or user_ws_gpu).
2. To develop or execute code inside the container attach to the container via VSCode (Docker Addon --> Containers --> Right click on running container --> Attach Visual Studio Code) or open a bash via docker compose exec dev bash

Inside the container:

• The main ROS 2 workspace is the src folder in the robotic_ws and is mapped from the src folder in the repository. Inside the container you can find the file structure of the ROS 2 workspace in the ROOT directory of the container: /robotic_ws/
• Build the workspace by executing colcon build --symlink-install or cb
  The ROS 2 build files will be mapped to the corresponding folders in the .colcon folder to keep build files and allow faster build times even after the docker container has been restarted.
• There are quite a few aliases defined. View them via the help command. You can also view/edit the aliases in the file .docker/entrypoint.bash of the repo on the host system.

---

How to update

1. If you want to update the workspace, just pull the latest version of the repository:

   git pull

2. If there are changes to the depenedencies or the dockerfile, you need to rebuild the docker container. This can be done by executing the following command in the root directory of the repository:

   docker compose build
   

---

More information

Installed Features/Packages (not complete)

• Image contains latest tagged release from MoveIt 2 main branch

External packages:

• trac_ik
• pymoveit2
• libfranka 0.9.2

Own developed packages:

• workcell_descriptions
• multipanda_ros2 (not self developed, but forked and modified from this repository from tenfoldpaper)
• safety_controller
• joint_trajectory_controller (not self developed, just a pinned version from ros2_controllers repository)
• control_utils
• robot_interfaces
• utilities

Configuration

The main configuration file is located at src/workcell_descriptions/panda_workcell/panda_workcell_description/config/workcell_config.yaml. This file contains parameters to configure the entire workcell. You can also access it via the conf alias.

Other configuration files for moveit and ros2_control are located in the src/workcell_descriptions/panda_workcell/panda_workcell_config/config folder.

Aliases

Can be used within the terminal. The aliases are defined in /entrypoint.bash or in the repo at .docker/entrypoint.bash.

Alias	Description
rdi <NUMBER>	Set ROS_DOMAIN_ID. If the argument is 0, ROS_LOCALHOST_ONLY is set to 1.
rdip <NUMBER>	Set ROS_DOMAIN_ID permanently. If the argument is 0, ROS_LOCALHOST_ONLY is set to 1.
src	Source the entrypoint.bash.
rd	Install dependencies via rosdep.
cb	Build workspace with symlink and release-type optimizations.
cbp <PACKAGE_NAME>	Build workspace with symlink and release-type optimizations for specific packages.
cc	Clean the entire colcon workspace.
ccp <PACKAGE_NAME>	Clean a specific package in the colcon workspace.
rtl	List all ROS 2 topics.
rte <TOPIC>	Listen to a specific ROS 2 topic.
rth <TOPIC>	Get the frequency of a specific ROS 2 topic with a window size of 60 messages.
conf	Open the main workcell config file in the editor.
full	Launch rviz2 with MoveIt and ros2_control.
rv	Launch only rviz2 with MoveIt.
ctrl	Launch only the ros2_control components.
single_ctrl	Launch control of only a single robot arm. Specify parameters via launch arguments or use default parameters in the launch file.
rcm	Launch rqt_controller_manager.

Structure

dependencies

• workspace.rosinstall contains all ros packages that should be cloned into base_ws. The description format is based on vcstool
• entrypoint.bash contains content which should be executed everytime you source a new shell --> if you have an extra ROS workspace you need to add the sourcing commands here

---

docker

• docker-compose.yaml describes and links the various build stages defined in the dockerfile --> Docker knowledge required to understand this.
  Current setup contains 3 basic stages: base_ws, user_ws, dev.
  • base_ws: basic underlying workspace for other ros workspaces in which you dont want to develop but are needed as dependencies. Repositories from workspace.rosinstall are imported here. Also all other (non) ros dependencies should be build and installed here.
  • user_ws: main workspace containing your sourcecode and your user_packages and _reuqirements. This stage should be able to run all code when deployed.
  • dev: Additional stage when you want to have a development environment for your user_ws stage. Do not install any dependencies here that are needed to run the code. Only change if really neccessary.
• dockerfile:
  • see comments inside dockerfile

Volumes

Volumes are used to persist data across Docker container restarts, such as build artifacts, logs, user settings, and development environment state.We use the following named volumes:

• bash_history: Persists terminal command history across container sessions for convenience during development.
• vscode-server: Keeps VS Code Server data (extensions, settings) for faster startup and consistent dev environment.
• build: Stores intermediate ROS 2 build files from colcon to speed up future builds.
• install: Contains installed ROS 2 packages after building, needed to run the workspace.
• log: Saves ROS 2 build logs for debugging and reference.

Sometimes you need to delete the (build, install, log) volumes to get a clean build. You can do this by executing:

docker volume rm <volume_name>

or delete all volumes by executing:

docker compose down -v

If you just want to clean the build, install, and log files execute inside the container the cc alias command.

License

This repository is licensed under the Software Copyright License for Academic Use of the Fraunhofer Software, Version 1.0. See the LICENSE file for more details.