¶ FRI robot communication
Before you do anything here, make sure that you have read and understood the hardware tutorial for basic configuration and usage.
¶ Installation
¶ Installation - Host
There are two pojects that you need. FRI is the Fast Researh Interface which allows a connection between the robotic arm and your computer. The ROS package is used to be able to move the robotic arm through ROS.
In the README of both projects you will find the installation instructions.
- FRI-stanford: A library by Stanford University with the Fast Research Interface.
- ROS package: A package that provides all the required low-level tools to connect the arm to ROS.
Older version of FRI depend on YARP, so if you are unfortunate enough to use the older version, you will have to compile and install YARP with python bindings enabled. Good luck.
¶ Installation - KRC
KRC: Kuka Robot controller
FRI is already installed, if that is not the case something went terribly wrong. You can use official documentation by KUKA. You will need an installation key, ask Federico for it.
¶ Check FRI installation
- On the left menu select FRI (the red globe of pain)
- THen select FRISHOW on the bottom menu
- This should pirnt a line like the following. If that is the case, FRI is installed correctly.
frihost <ip address> ss <number> sr <number>
¶ Configuration
¶ Configuration - KRC
The KRC has two network interfaces. One is connected to the windows operating system (we don't care about this one) and the other one is connected to the QNX virtual machine for the LWR controller. In ARCOS-Lab the windows interface has the ip 192.168.3.10, the QNX interface is the one used for FRI (robot-computer communication), so it depends on what side it is being used.
In C:\krc\roboter\init\Dlrrc.ini you will find the configuration for the host (In our case the humanoid robot server). The KRC will attempt to connect to the host using this configuration. You need to login as administrator to edit it.
In C:\windows\vxwin.ini you will find the configuration for KRC. This particular file is not accesible from the teach pendant (even if you are administrator), you will have to connect a mouse, and keyboard to access the Windows operating system, and change it there.
Remember to reboot the robot for the changes to fully apply
¶ Configuration right arm
C:\windows\vxwin.ini.
[Boot]
Bootline=elPci(0,1)pc:vxworks h=192.0.1.2 b=192.0.1.1 e=192.168.36.250 u=target pw=vxworks
C:\krc\roboter\init\Dlrrc.ini
[DLRRC]
TIMEOUT=25
IMMEDIATE_STARTUP=1
FRIHOST=192.168.36.13
FRISOCK=49938,0
FRIKEY=(use provided key)
¶ COnfiguration left arm
C:\windows\vxwin.ini.
[Boot]
Bootline=elPci(0,1)pc:vxworks h=192.0.1.2 b=192.0.1.1 e=192.168.37.250 u=target pw=vxworks
C:\krc\roboter\init\Dlrrc.ini
[DLRRC]
TIMEOUT=25
IMMEDIATE_STARTUP=1
FRIHOST=192.168.37.13
FRISOCK=49938,0
FRIKEY=(use provided key)
¶ KRC network card config
We had troubles using an Intel Giga network controller. The 3Com one works correctly. To check that windows is properly detecting and using the FRI network controller, go to the windows "Device Manager" and check that the 3Com network controller is assigned as part of a "Realtime OS Devices" section and not inside "Network adapters" section. Remember that you can connect a USB keyboard and USB mouse to the KRC
¶ Connecting your computer to the FRI network
The host computer (your computer) must have the IP address that you configured in C:\krc\roboter\init\Dlrrc.ini in the previous section.
- Connect the host computer (your computer) to the same physical network as the KRC.
- Run the host computer (your computer):
sudo ip address add eth0 192.168.x.x/24
- Test the connection to the robot. Use the IP address you configured in
C:\windows\vxwin.ini
ping 192.168.y.y
- It must respond with packages with low latency
¶ ARCOS-Lab Humanoid Robot
In the particular case of our Humanoid robot, both arms are connected to the main server CRP1, Physical ports enp5s0 and enp6s0.
Our Humanoid robot the configuration is as follows:
[Right arm]
Host: 192.168.36.13
KRC: 192.168.36.250
[Left arm]
Host: 192.168.37.13
KRC: 192.168.37.250
¶ Connecting your computer with the KRC windows operating system
This is not required for normal opperation, only in very special cases.
You can also connect to the same network of the KRC windows OS. This may be useful for editing or copying files:
- Configure your network interface to be also in the same network of this windows computer:
sudo ifconfig eth0:1 192.168.3.113 netmask 255.255.255.0
- Test the connection to the windows OS:
ping 192.168.3.10
Access the KRC windows files in your computer
- Create a mount directory for the KRC windows files:
mkdir -p /mnt/krc
- mount the windows files in a local host directory (password: user):
sudo mount -t cifs //192.168.3.10/krc /mnt/krc/ -o user=user,vers=1.0
Now you can access the KRC windows files in your linux computer.
¶ Install FRI and ROS2 node
We maintain a modified version of the Stanford Fast Research Interface implementation available here.
-
First configure your computer for local intallation using xstow here
-
Clone the FRI repo, compile and install
# clone
cd ~/local/src
git clone git@gitlab.com:arcoslab/robot-hardware-firmware/fri-stanford.git
cd fri-stanford
./update-config.sh
# compile
cd ~/local/src/fri-stanford/Linux
make all_debug_x64 all_release_x64 -j5
# install
cd ~/local/src/fri-stanford/Linux
./install.sh
cd ~/local/DIR/
stow fri
- Install the ARCOS-Lab humanoid robot simulator, follow this tutorial.
- Clone, compile and install the ROS2 node.
cd ~/wsr2/src/
git clone git@gitlab.com:arcoslab/robot-hardware-firmware/kuka-lwr4plus.git
cd
source ros2_setup.sh
cd ~/wsr2
colcon build
To work with FRI you need real-time capabilities. We have found that a preemptive kernel works well.
- Install the PREEMPT_RT kernel
- Create a group and add your user to it
sudo addgroup realtime
sudo usermod -a -G realtime $(whoami)
- Afterwards edit
/etc/security/limits.conf, add the following
@realtime soft rtprio 99
@realtime soft priority 99
@realtime soft memlock 102400
@realtime hard rtprio 99
@realtime hard priority 99
@realtime hard memlock 102400
¶ Testing FRI communication
An effective way to test if FRI is working in both places (KRC and your PC) is to use the test provided by FRI-stanford. When you compile FRI-stanford, you should also compile the tester by default. It can be found in fri-stanford/Linux/x64/debug/bin. For some reason the release version is not working, or sometimes failing with a segmentation fault. The program is called FastResearchInterfaceTest.
- Turn ON the Robot. Wait until it is set-up.
- Set the base and tool.
- In your computer run:
sudo su
cd <user_home>local/src/fri-stanford/Linux/x64/debug/bin
./FastResearchInterfaceTest
The Fast reserach interface from the host (your computer) must be running before tou set-up the KRC
- Move the selection key to the spiral without dot, as shown in the picture in yellow.
- Press the power on robot. This will disable the contactors to allow movement. The brakes of the robot will not be disabled until you send a movment command. In this mode, the button is equivalent to be pressing the dead man switch from manual opperation.
- In the teach pendant select a program to unlock the joints. A good option is to use
reset_pos, as this one will move the robot to "safe" positions.
Be careful as this program uses position control. The robot will move without soft protections.
- Deselect the program.
- Open FRI, this will put the robot in monitor mode.
- The computer should start to get data from the robot. Press the key P to get a general status of the robot. Make sure that it says that the robot is in monitor mode, and that the brakes are off.
- On your computer press S, this will get the computer ready for command mode. Select position control.
- Quickly (around 0.5 second interval) start FRI on the tech pendant of the robot. Make sure that the "start" happens in the host before it happpens on the robot.
- Wait for the process in the host (your computer) to finish. Then press P. You should see that the robot is in command mode. At the same taime, the teach pendant should show that it is in command mode.
- The robot is ready to receive commands from FRI.
- Press C to move the robot to the candle position, this means to move all joints to 0. Be careful, this movement is done with position control so it is insecure.
¶ Using FRI host software
¶ Notes:
For FRI communication: The Fast Research Interface expects certain values of latency, the control loop must work at 1 kHz. If this cycle time is not respected, there will be communication errors. Most commonly you will see
Communication quality unacceptableandInterpolation error. In order to avoid these type of problems you must use a full real time kernel, of atleast have the Scheduler configured to be Full preemptive. Depending on how you have configured the permisions in your computer, you will need super-user permision to create threads of certain priority. We recomend to configure your computer such that using root is not required.
¶ KRC
On the Kuka Robot Controller side, you have to the following program KRC/R1/Program/FRIDemo/FRIControl.src. This program will do the following:
- Set up the robot
- Stop FRI. This is done in case someone or something was running FRI before, there could be fulty configurations or intructions, so we just close it.
- Set the Tool (Hand) and Base. Make sure to set the correct ones! (2:hand/1:B)
- Set the gravitation vector
This program
FRIControl.srcwill change the gravitation vector internally.
- Set up other stuff, like the IP address of the master (your computer)
- Open FRI. This step will open the Interface and get it ready in Monitor mode.
- Start FRI. This will put the robot in Command mode.
- Then there is an endless while that hears the interface waiting for commands from the master. It will execute any given commands.
¶ Running instructions
- Start the humanoid robot here
- Turn the KRC controller box on here
- Wait until the KRC controller software is completely on
- Select arm controller to "position" (using arm picture)
- Pendant key to above picture
- Press the "Power on robot" button (above picture)
- Wait until "S" and "I" are green ("Contactors off" should disappear)
- "Select" "reset_pos" program (to take it to a nice starting position)
- Press and hold the left green clockwise button. The robot will start to move. The robot will move to a nice "safe" position.
This movement can be dangerous, keep away from the robot, with stop button ready.
- Close the program. "Program"->"Cancel Program"
- With the file manager, go to:
R1/Program/FRIDemo/. Select fileFRIControl - Press the left green button until the program moves the robot (
PTPinstruction) - KRC will enter a loop, and should enter the FRI Monitor mode.
- Execute the Node.
<side>is eitherrightorleft, but you can use any node name if the arms are not in the ARCOS-Lab humanoid robot. The IP address is whatever you configured in KRC, in the particular case of the ARCOS-Lab humanoid robot the ip for right is192.168.36.13and for left is192.168.37.13
ros2 run kuka_lwr4plus_robot fri_node --ros-args -r __ns:=/humanoid -r __name:=kuka_lwr4plus_<side> -p host_ip_address:=192.168.<36/37>.13
- On the KRC the message "LR:FRI Command Mode" should appear. If it doesn't. Try everything again.
- The robot starts disabled by default. To enable the arm run
ros2 service call /humanoid/kuka_lwr4plus_<side>/control impedance_control_msgs/srv/Modes "enable: [True, True, True, True, True, True, True]
mode: 0"
If you want to send the joint information to TF to visualize it in rviz, you should run this command instead of the one above. Where <r/l> is either r for the right arm or l for the left one.
ros2 run kuka_lwr4plus_robot fri_node --ros-args -p robot_name:=<r/l>_klwr4p -r __ns:=/humanoid -r __name:=kuka_lwr4plus_<side> --remap /humanoid/kuka_lwr4plus_<side>/joint_states:=/joint_states -p host_ip_address:=192.168.<36/37>.13
¶ tester nodes (optional)
There is an optional program you can run to make quick tests of FRI-ROS2 integration. It is an interactive program that allows you to move and configure the robot with your keyboard.
ros2 run kuka_lwr4plus_tester lwr4plus_keyboard --ros-args -p side:=<side> -r __ns:=/humanoid
It is also possibel to execute a list of joint positions stored in a json.
ros2 run kuka_lwr4plus_tester lwr4plus_exec --ros-args -p side:=<side> -p file_name:=<filename> -r __ns:=/humanoid
¶ Best Practices
¶ Safe positions
When you use the robotic arm for manipulation it is a good practive to take the robot to a safe position outside of the field of view of the camera. And then take it to a safe position inside view.
FOr the particular case of the right arm of the HUmanoid robot, those safe positions could be (in joint space)
outside_view:
- -1.58955
- -0.60383
- -0.22540
- 0.87165
- -0.51897
- -0.14759
- 0.62064
inside_view:
- -1.63941
- -1.22432
- -0.22330
- 1.18661
- -0.51190
- 0.53653
- 0.62981
¶ Troubleshooting
¶ Network communication errors
Network errors can cause a message that says
interpolation error.
In case that there are network communication problems some times there is a problem with the network card installation. The KRC has two network cards, one for Windows and one for VXworks. To be sure that the one for VXWorks is properly installed, go to control-panel->System->Hardware->Device Manager, and check that the PCI network controller is listed under "Realtime OS Devices" and not under "Network Adapters". If it is under "Network Adapters" it means windows has "claimed" it. To reassign it to VXWorks, insert the FRI installation CD and go to INTERNAT\KRCUPD directory and run "KsNetCfg.exe". This will install again the VXWorks network adapter card. This is usually a problem with the Intel Pro1000 GT card. Reboot and reconfigure FRI ini files.
¶ Interpolation error
Message: LR:FRI Interpolation error!
This message happens when there is not a good communication quality between the robot and the host. SOme messages were lost, the connection is not considered secure anymore and the robot fails. When you get this error, the brakes activate and the robot will stop FRI returning to monitor-mode.
This error happens when you try to start command-mode. It is difficult to determine the real factors that trigger this error, so far seems to be random. The fix is just to retry.
This also happens when you already have the robot in command mode, and try o send command from the pendant. There is going to be aconflict in the commands that the arm gets and the interpolation error is going to be triggered.
In order to avoid it, make sure that the host is already running the FRI interface when the robot attempts to start FRI.
¶ Cartesian Deviation
Message: Computation of Cartesian Deviation impossile
Sometimes, depending on how you end a process in the KRC, the arm may be left in a weird state. The interpolation error, will prevent the arm from moving in stiffness mode (no impedance control), because the error between the commanded position and the current position is too big.
To fix this, put the arm in position control and execute a program called reset_pos.
This will move the robot using position control, so it is unsave to have humans around.
The program has two parts, the first one moves the arm to a safe positon away from the robot's body and the second puts the arm in a nice position for stiffness control. Just for documentation these are the specific poses:
P1 = {A1 88.598, A2 130.275, A3 -34.838, A4 120.000, A5 19.994, A6 54.997, E1 -20.30}
P2 = {A1 88.615, A2 146.201, A3 -73.305, A4 130.000, A5 19.994, A6 54.997, E1 -20.30}
When you get the message Programmed path reached (BCO) menas that the robot has been able to reach the commanded position. The interpolation error issue should be solved once you get that message.
¶ Loaddata incorrect ERR FRI
The merror message is: Loaddata incorrect FRI Active: Fix erroneous dynamic mode
This message wil trigger the brakes.
- First make sure that the tool and base are configured corretly
- Then reboot the contactors.
- Execute a simple program in position control, so that the robot will forget about the loaddata
- Try to go back to what you were doing (which is probably suffering with these arms tbh)
¶ Restarting in case of bad communication quality
- Ackknowled all messages in Pendant
- Press black button with circle to denergize the drives
- Press the white button with vertical bar next to the key to reenergize the drives
- Press the green button with "+" several times until FRI switches to joint impedance control. During this the arm moves to the starting position and then to the last commanded position. Beware!!!!
¶ Service not responding
There are some cases when services in ROS2 are unable to send a response back to the client. You may get a message similar to:
[fri_node-1] [WARN] [1742577766.521549993] [humanoid.kuka_lwr4plus_left.rclcpp]: failed to send response to /humanoid/kuka_lwr4plus_left/control (timeout): client will not receive response, at ./src/rmw_response.cpp:154, at ./src/rcl/service.c:314
In this case, the Server (FRI-node) was able to receive the enable/disable request and executed it. But when it tried to send the response back to the client, it failed. The result is that the arm is enabled/disabled as requested but the client is never notified.
Right now there is no workaround.
¶ Legacy YARP Stuff
¶ Running the FRI-yarp bridge (Legacy)
This is only useful if you are using the old version, with YARP. If you are using ROS, please ignore this section.
- If you configured LWR_yarp_arcos with suid:
cd ~/local/src/fri_stanford/Linux/x64/release/bin
./LWR_yarp_arcos
- If you didn't use suid:
cd ~/local/src/fri_stanford/Linux/x64/release/bin
sudo su
cd
export HOME=/home/my_user
. /home/my_user/.bashrc
export HOME=/root/
cd -
./LWR_yarp_arcos
¶ Running the FRI KRC KRL client controller code (optional)
In most cases you won't need to do this. This is just to run the demos given by Stanford. If you are using the ARCOS-Lab packages, you can ignore this.
KRL: KUKA robot language
- Turn on the KRC box (big black switch CW 90 degrees)
- In the Kuka Pendant:
- Rotate the key on top of the Kuka Pendant to the spiral without dot position.
- Select Position Control with LWR button
- Press the Button next to the key (the one with a vertical bar)
- Configure->Set tool/base-> Tool no: 1(empty) 2(hand) 3(L link), base no: 1
- With the file manager, go to: R1/Program/FRIDemo/
- Select file FRIControl (this file is in the KRL/ARCOS-Lab_KRC1/FRIDemo/ repository directory. You must internally check for the gravity vector and the tool number to be correct)
- Select Position Control with LWR button
- Monitor->Variable->Single->Name: $torque_tcp_est (check that torques and forces don't exceed a value of 2)
- Close Monitor window
- Press green + button several times until no more advancing happens in the code
- Press enter in the LWR_yarp_arcos console
- Press green + button more times until no more advancing happens in the pendant code