[Documentation] [TitleIndex] [WordIndex

Note: This tutorial assumes familiarity with Fanuc controller cabinets, the Teach Pendant (iPendant) and the Roboguide environment. For more information on any of the steps in this tutorial, consult the documentation on these subjects provided by Fanuc Robotics.
(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Installation of ROS-Industrial on Fanuc controllers

Description: This tutorial guides you through an installation of the ROS-Industrial programs on Fanuc controllers.

Keywords: Fanuc, Roboguide, Industrial, R-30iA, R-J3iC, KAREL, TP

Tutorial Level: INTERMEDIATE

Next Tutorial: Running the ROS Industrial programs

There are two main steps in setting up a Fanuc manipulator for use with ROS Industrial: 1) building and installing the necessary KAREL and TPE programs, and 2) configuring the controller for use with these programs.


In order to be able to complete this tutorial, you should have access to the following:

In all cases, the following software options should be present on your robot in addition to basic networking and TCP/IP support:

Information on the installed software options can be found by consulting the documentation that came with your robot. Alternatively, the Version ID submenu of the STATUS screen can be used. On the TP: MenuNEXTSTATUSVersion ID, then CONFIG (or F3). The same information is available on the Summary Configuration/Status webpage, which should be accessible if your controller has the web server option installed.

Finally: this tutorial assumes the use of an iPendant. For users with old (legacy) pendants, this may mean that key sequences given in the text, and screenshots of windows and menus will not match completely. Due to the lower resolution of legacy pendants, many key sequences need either an additional NEXT inserted, or (sub)menus should be opened using TYPE.

Make sure your controller has a correctly configured and working network setup. Verify you can ping the controller from your ROS pc. Refer to the relevant documentation for instructions on how to configure networking on a Fanuc industrial robot controller.

Building and installing the programs

Before the ROS Industrial KAREL programs can be transferred to the robot controller, they need to be compiled into binaries. In this tutorial we'll use Fanuc Roboguide for compiling, and in the next as a simulator, to use as a test environment.

Creating a workcell

First, create a new workcell in Roboguide, either by using the wizard or by creating a copy from your actual robot controller. When using the wizard, be sure to select the correct Application package, as well as the correct robot type. On the software options screen, also make sure to select at least options R632 - KAREL and R648 - User Socket Messaging.

New workcell wizard: KAREL and USM options

After completing the wizard, you should end up with an empty workcell with just your robot in the middle of it. If you chose to create a copy of the controller, the Cell Browser might show programs and files that were already present on the robot under the Programs and Files sections. As long as they do not conflict with the ROS-Industrial KAREL programs, they can be ignored.

Importing the sources

In the Cell Browser, import the KAREL and TPE sources into the workcell using the ProjectAdd Files menu option. Browse to your local fanuc_driver package and select all *.kl files in the karel subdirectory not ending in _h.kl or _t.kl. After clicking the Open button, the Files section in the Cell Browser should contain at least these files:

Now add the *.ls files in the TPE subdirectory as well. The Cell Browser should now also show the following files:

Picking free Server Tags

The ros_state and ros_relay programs make use of the User Socket Messaging (USM) software option, and expect two Server Tags to be available. By default, tags 3 and 4 are used. On the real TP, open the Host Comm setup screen, and then go to the SETUP Servers listing using [SHOW]Servers. If you have no other programs making use of USM, three and four should be available.

If not, find two others and note their tag numbers. Now open the ros_relay.kl file in Roboguide and update the MOTION_TAG constant: enter the first of the two free tag numbers. Do the same for ros_state.kl and the STATE_TAG constant, but use the second free number. Save both files and close them.

For more information on User Socket Messaging and tags, see [3, Chapter 11].

Checking flag and register usage

The ros_relay and ros_movesm programs make use of several registers and flags. By default, flags 1 & 2, integer registers 1 & 2 and position registers 1 & 2 are used. Make sure these are not used by any other programs present on the controller2.

If any of the flags or registers are currently being used, find some alternatives, and note their numbers. Now open ros_relay.kl in Roboguide and update the MOVE_PREG, MOVE_SPD_REG, MOVE_CNT_REG, RI_MSM_RDY and RI_MSM_DRDY constants accordingly. Save the file and close it. Open ros_movesm.ls and update all indices of the flags and registers with their new values. Again, save and close the file.

Incorrect configuration of the flags, integer or position registers can result in damage to your robot, you and / or your workcell. Please make sure they are free to use, before continuing with the next steps. If you are unsure about register or flag usage by other programs, ask the operator of the robot to assist you.

Motion Speed and Segment Termination

By default, the ros_relay program uses a hardcoded CNT value of 50% and a fixed joint velocity of 20% for all motion commands. Depending on the precision required during trajectory execution, these values can be changed. The relevant constants can be found in ros_relay.kl, and can be changed using the procedure explained in the previous section.

For more information on the influence of these two values on trajectory execution, see the Improving ROS-Industrial motion on an Industrial Robot tutorial.

In MoveIt, all motion plans are planned using the real velocity limits found in the URDF, and the MoveIt Trajectory Execution Manager will frequently abort the execution due to the fixed velocity used by ros_relay (resulting in Trajectory stop messages on the User Menu on the TP). Execution monitoring can either be disabled, or the allowed time can be increased by setting the relevant parameters. See the The Trajectory Execution Manager section on the Executing Trajectories with MoveIt! page on the MoveIt wiki for more information.


Now build all files by selecting ProjectBuildAll in Roboguide (if you have other source files under Files, build only those listed under Importing the sources). No errors or warnings should be reported, and the Programs section in the Cell Browser should show the compiled binaries.

Copying the programs to the real controller

Finally, the binaries need to be transferred to the controller. This can be done by direct transfer over a network connection (FTP) or by using a mass storage device (such as a USB stick or PCMCIA memory card). Refer to [1, Chapter 8] for information on how to copy files using removable media. Refer to the Roboguide help files for information on how to perform network transfers of files to robots3.

After copying the binaries onto the robot controller, open the Program Select window by pressing the Select button on the real TP, then [TYPE]KAREL Progs. Make sure the following programs are listed:

Also check to make sure the necessary TPE programs are present by pressing [TYPE]TP Programs. You should see entries for:

Configuring the controller

Some additional configuration of the controller is required in order for the ROS Industrial programs to work correctly. This should be done on both the virtual TP (in Roboguide) as well as on the real controller.

Maximum concurrent task number

Changing system variables can result in an unstable or non-functioning system. Before making any changes, be sure to have a recent backup of the controller and consult with the robot operator in case you are unsure about any of these steps.

By default, the controller can only run a small number of concurrent user tasks, which could prevent the ROS Industrial KAREL programs from starting. The currently configured number of allowed tasks is stored in the $SCR.$MAXNUMTASK system variable. Any number above 6 should be enough to start the ROS KAREL programs, but higher may be necessary if the controller also starts other tasks.

To change the number, start the controller using a controlled start. Then open the Program Limits screen using MenuNEXTPROGRAM SETUP. Then input a new value for the User Tasks entry. Now restart the controller using FctnSTART (COLD).

Refer to [1, Section B.1.3] for more information on how to perform a controlled start.

Server Tags

The two tags chosen in the Picking free Server Tags section need to be configured. This section assumes tags 3 and 4 are used, but be sure to configure the correct tags in case you changed them in the KAREL sources earlier.

On the TP, again open the SETUP Servers listing on the Host Comm setup screen. Select tag three and press DETAIL, now configure the tag as follows (the comment is not required):

Server Tag configuration example (Tag number could be different)

The rest of the fields should be empty or at their defaults. Do the same for tag four.

Go back to the SETUP Servers listing and verify that the chosen Tags are in state STARTED. If not, start each tag with [ACTION]DEFINE, then [ACTION]START, or restart the control cabinet. Make sure they have been started by re-opening the SETUP Servers screen (if necessary) and checking the Current State of both tags: it should say STARTED.

Server Tag state example (Tag numbers could be different)

Refer to [3, Section 11.3.2] for more information on configuring server tags.

Payload settings, Tool and User frames

Three additional configuration items influence the behaviour of the robot when used with the ROS Industrial nodes: the selected user and tool frames and the arm payload schedule.

For the payload schedule, input the correct information using the TP on the Motion/Payload Set setup screen. This screen can be found via MenuNextSystemMotion. Be sure to configure and select the correct schedule. For more information, see [1, Section 9.14].

Configured user and tool frames are (currently) ignored in the ROS Industrial nodes as motion trajectories are specified at joint coordinate (and velocity) level. This is also true for robot state reporting. The use of a user frame coincident with the world frame is however recommended as it helps in debugging and verifying the motion of the arm and the location of the TCP.

Tool frames configured at the robot controller side are also not taken into account by the ROS motion planners, as tools should be represented by an appropriate URDF. The combination of the arm and tool URDFs provides similar information to the planning libraries (see also the Create a URDF for an Industrial Robot tutorial). It is however recommended to manually verify the correct tool frame setup on the TP, as the robot controller also uses this information in its safety algorithms.

Go to MenuSetupFrames and use the [OTHER] function key to switch between the Tool and User Frame listings. Disable the user frame: use the Next button, then press the CLRIND function key (alternatively, configure an all zeros user frame) 4. Verify the tool frame setup in the Tool Frame screen.

For more information on user and tool frame setup, see [1, Section 3.9].


This concludes this tutorial. Continue to the next to find out how to run the programs.


  1. As an alternative to Roboguide, WinOLPC / OlpcPRO or even the KCL console could be used to compile the KAREL sources into p-code binaries. These alternatives are not documented in this tutorial, and only the use of Roboguide is described. (1)

  2. Note that the list of flags can be accessed via MenuI/ONEXTFlag. The F[] array on the TP corresponds to the FLG[] array in the Karel programs. (2)

  3. If you're setting up a virtual controller, FTP to localhost can be used, or you can copy the binaries to the Robot_N\MC directory (where N is the index of the robot controller). This directory is a subdirectory of the workcell directory under My Workcells. For a workcell named ROS-I Test, this directory would by default be at %USERPROFILE%\(My) Documents\My Workcells\ROS-I Test\Robot_N\MC. (3)

  4. Depending on the configuration and mounting of the arm, an 'all-zeros' user frame may not be the best choice. In those situations, be sure to configure a more suitabe frame. (4)


  1. FANUC Robot Series, R-30iA, Handling Tool, Operator's Manual, B-82594EN-2/02
  2. FANUC Robot series, R-30iA/R-30iA Mate Controller, KAREL Function, Operator's Manual, B-83144EN/01
  3. FANUC Robotics SYSTEM, R-30iA Controller, KAREL Reference Manual, MARRC75KR07091E Rev C

2019-03-16 12:47