Franka Setup

Overview

Describes the setup for the Northwestern MS in Robotics program's Franka Emika Panda robots (since renamed to FER).
These setup instructions are for to configure the robots themselves: most students will want to follow Franka Notes

Workstation Computer

These instructions are for how our Franka workstation computers are setup.
Do NOT run these instructions on your personal computer, unless you want to turn it into a Realtime Linux system capable of directly plugging in to the Franka Robot (likely not what you want).

Operating System

Install Ubuntu according to the Computer Setup (skipping over System76-specific instructions and most desktop customization)
- The default user should be for the administrator of the system.
After installation create a student user:
- sudo adduser student
The realtime kernel is part of the NUMSR PPA.
- The package to install is linux-image-6.6.43-rt38numsr
- Instructions on how the package was built can be found at Minimal Ubuntu Setup

Permissions must be set for the user to start processes with realtime priority, as per Franka Installation Instructions:

# Create a realtime group
sudo addgroup realtime
# Add users to the realtime group
sudo usermod -a -G realtime $(whoami)
sudo usermod -a -G realtime student

Edit /etc/security/limits.conf

@realtime soft rtprio 99
@realtime soft priority 99
@realtime soft memlock 102400
@realtime hard rtprio 99
@realtime hard priority 99
@realtime hard memlock 102400

Edit /etc/defaults/grub and change the value of GRUB_DEFAULT to "1>2"
- This selects the 2nd grub menu option (Advanced Options for ubuntu) and then 3rd option, which should be the rt kernel )
- Run sudo update-grub
- Reboot and verify that the RT kernel was loaded (you should see PREEMPT_RT in the output of uname -a)

Create a new ROS 2 workspace:

sudo mkdir -p /opt/ros/franka/src
sudo chown -R $(whoami):$(whoami) # We will build everything as the current user
cd /opt/ros/franka
vcs import --input https://nu-msr.github.io/images/franka.repos src
rosdep install --from-paths src -y --ignore-src -r
colcon build --merge-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF
sudo chown -R root:root /opt/ros/franka # Make it all owned by root again

Users should source /opt/ros/franka/install/setup.bash to use the Franka code.
- This line is added to the .bashrc of the administrator and the student account
Add the following content to the .bashrc of user accounts
```
if [ -z "$DISPLAY"]; then
    export DISPLAY=:0
fi
```
- This is a workaround because MoveitConfigsUtils assumes that the DISPLAY variable is set.

Network Setup

Ethernet Connections

enp109s0: This is the 1Gb/s ethernet port built into the motherboard. It is used to connect to the laptop.
- In our computers it has the buggy r8169 driver.
- Upon reconnect, it will not bring the link up.
- A workaround is to ensure that /sys/bus/pci/devices/0000:6d:00.0/power/control contains the word "auto" instead of "on"
  - The bug is somewhat related to https://bugzilla.kernel.org/show_bug.cgi?id=207205
- Use systemd-tmpfiles to automatically write "auto" to that file on boot:
  - echo "w /sys/bus/pci/devices/0000\:6d\:00.0/power/control - - - - auto" > /etc/tmpfiles.d/r8169.conf
ens24f0: This is a 10Gb/S ethernet port that connects to a Franka Control box
ens24f1: This is a 10Gb/S ethernet port that connects to a Franka Control box (two Frankas can be connected to one station).

Bridge
- All connections are bridged on br0, which is given ip address 192.168.18.1.
  - Thus the robot and all connected computers are on the same subnet and can communicate
- The franka control boxes have static leases, based on their mac addresses.
- Create the bridge and slaves:
```
# Create the bridge
nmcli con add type bridge ifname br0
# Add the slaves
nmcli con add type ethernet con-name br-laptop ifname enp109s0 master br0
nmcli con add type ethernet con-name br-pandaX ifname ens24f0 master br0
nmcli con add type ethernet con-name br-pandaY ifname ens24f1 master br0
```
- Disable Spanning-Tree Protocol: nmcli con modify bridge-br0 bridge.stp no
- Static IP for station: nmcli con modify bridge-br0 ipv4.method manual ipv4.address "192.168.18.1/24" ipv4.dns 127.0.0.1

DNS

Install dnsmasq: sudo apt install dnsmasq
- Setup dnsmasq by copying ./images/franka_dnsmasq.conf to /etc/dnsmasq.conf on station
  - wget https://nu-msr.github.io/images/franka_dnsmasq.conf
  - sudo mv franka_dnsmasq.conf /etc/dnsmasq.conf
  - mkdir /etc/systemd/system/dnsmasq.service.conf
  = Copy dnsmasq_service.conf to /etc/systemd/system/dnsmasq.service.conf/dnsmasq.conf on station.
  - This service file causes dnsmasq to flush all leases when it starts. It seems that this makes the system more reliable in terms of making clients refresh their dns settings. There is probably something to fix the problem in a better way, but this seems to work.
  - It also ensures that dnsmasq starts after the network bridge br0 is created, enabling it to work when the station is restarted.
- Copy ./images/franka_route.sh to /usr/local/bin/franka_route.sh on station
  - This script executes when new machines get ip addresses
  - wget https://nu-msr.github.io/images/franka_route.sh
  - sudo mv franka_route.sh /usr/local/bin
  - sudo chmod 755 /usr/local/bin/franka_route.sh
- Disable systemd-resolved:
  - sudo systemctl disable --now systemd-resolved
- Restart dnsmasq: sudo systemctl restart dnsmasq
- /etc/resolv.conf can remain because dnsmasq is set to ignore it. This lets us easily get internet when needed.
This is setup so that everything connected to station is on the 192.168.18.0/24 subnet
- Some static addresses are created (see line 87 address in ./etc/dnsmasq.conf):
  - station, station.robot: Resolves to 192.168.18.1, Workstation computer
  - panda0, panda0.robot: Resolves to 192.168.18.10, primary robot
  - panda1, panda1.robot: Resolves to 192.168.18.11, secondary robot
  - robot.franka.de: Resolves to 192.168.18.10, primary robot
    - Need to access web interface at robot.franka.de to avoid SSL certificate errors
- IP Addresses are assigned by mac address (see line 249 dhcp-host).
  - All mac addresses of all panda robots are assigned to both 192.168.18.10 and 192.168.18.11
  - If there is a conflict of mac addresses with the first assignment, it falls through to the second. This is how both pandas can get an IP address
  - The IP address of the station computer is statically assigned to 192.168.18.1
dnsmasq also uses northwestern and cloudflare dns servers upstream so when there is internet access it can resolve domains.
Your laptop will be accessible via it's hostname, and via laptop

SSH

The station should have an ssh server:

sudo apt install ssh

NTP

The station computer is not usually connected to the internet.
It needs to be synchronized with the user's laptop time.
To avoid messing with the user's Laptop clock, the user will host an NTP server and the station will connect to it.
- See Franka Notes for details on how to setup the client.
Install chrony on the station (sudo apt install chrony)
Copy ./images/franka_chrony.conf to /etc/chrony/chrony.conf on station
- If your laptop is running chrony then the station will connect to laptop and synchronize it's time

Internet

The Franka robots are, by default, intentionally disconnected from the internet
To get internet on the Franka, it is easiest to route through the user's laptop:
- See https://serverfault.com/questions/564866/how-to-set-up-linux-server-as-a-router-with-nat (MohyedeenN answer) for details.
- wlan0 refers to the public interface on laptop (e.g., the wifi card that is connected to the internet)
- eth0 refers to the private ethernet interface connected to station
- See interface names using nmcli
- The script at ./images/franka_internet.sh can be used. The first argument is the interface connected to the internet, the second is the interface connected to the franka
The dnsmasq process should have created a default route on the station
- The route tells packets on the station to be sent to your laptop for dispatch to the WAN
- If needed, a route can be added manually: sudo ip route add default via <Your laptop's ip address>.
Another way to get internet is to plug in an ethernet cable to one the ports and remove that port from the bridge

ROS 2 Iron

A ROS 2 Iron docker container is available on dockerhub at https://hub.docker.com/repository/docker/reem17/franka_iron/general
Install docker on station: sudo apt install --no-install-recommends docker.io
Docker messes up network settings with network bridges. To fix, create /etc/docker/daemon.json with the following content:
```
{
    "bridge": "br0"
}
```
- See https://wiki.archlinux.org/title/Docker#Starting_Docker_breaks_KVM_bridged_networking (accessed on 10/31/2024) for more information.
To build the container: sudo docker build -t reem17/franka_iron images/franka_docker
- sudo docker push reem17/franka_iron
Get the franka_iron image sudo docker pull reem17/franka_iron
Create the container: sudo docker create --name iron-ssh --restart unless-stopped --privileged --network host reem17/franka_iron
Start the container and set the student password:
- sudo docker start iron-ssh
- sudo docker exec -it iron-ssh passwd student (then enter the password.
- Commit the changes to the container sudo docker commit iron-ssh
Copy the sudoers file docker_ssh to /etc/sudoers/docker_ssh on station.
- Change ownership chown root:root /etc/sudoers/docker_ssh
- Changer permissions: chmod 600 /etc/sudoers/docker_ssh

Building The Container

The docker file context is available here: Dockerfile.
The limits.conf file must be in the build context folder.
Copy both of the above folder into /path/to/build/context, then run sudo docker build -t reem17/franka_iron /path/to/build/context to build the container.

Final Touches

Make sure that in the bios setup, the option to need to "press F1 on boot failure" is disabled. Otherwise if power is cut the user will need a keyboard.
systemctl set-default multi-user.target to disable graphical boot, since there is no monitor.