Robotics Library

First Steps with RL on Linux

The following tutorial assumes the Ubuntu build of the Robotics Library has been set up. Other linux builds are fairly similar, expect for some paths that may be different. Even though the Robotics Library API is identical for Windows, the command line and the build process behave differently, and therefore the steps in the tutorials will vary.

One of the demo programs included in the installation that can be used to solve path planning queries in an example scenario with a typical industrial robot manipulator.

Prerequisites

Follow the Ubuntu Installation and add the Launchpad respository to your list of subscribed repositories, install the latest version within your package manager. If Ubuntu is not installed, we recommend setting up a virtual machine for trying out RL and following these tutorials.

Pre-installed examples and robot model files

Open a terminal and navigate to /usr/share/rl. In this directory, you find several directories with robot and scenario models as well as the Doxygen documentation. You can find all the example models in the source tree in the folder examples.

rlViewDemo

Our first example program is rlViewDemo. You may for instance run

/usr/bin/rlViewDemo /usr/share/rl/examples/rlsg/unimation-puma560_boxes.xml

rlViewDemo is a very simple program that opens a static graphical scene and shows it using the SoQt Examiner Viewer. The scene is defined by rlsg/unimation-puma560_boxes.xml, which follows the RL scene graph format. It only adds names (links 0 to 10) to the 11 rigid bodies of the robot and to the two models, the robot and the environment. The actual scene with its triangles and colors is defined by VRML files, which are linked by the XML file.

Optional: Edit rlsg/unimation-puma560_boxes.wrl and comment out the environment model with # signs at the start of the corresponding lines, then run rlViewDemo again. Undo the changes.

rlCollisionDemo

rlCollisionDemo is a very simple program that allows you to translate a model in the environment and check for collisions.

Run

/usr/bin/rlCollisionDemo /usr/share/rl/examples/rlsg/scene.xml

This will a simple scene, but the second model--the environment--will be selected for collision checking. The "robot" is only treated as a graphical models (as given in rlsg/scene.wrl), for now, its kinematics are unknown. You can translate the first model. When it intersects the model of the environment, the window will turn red.

rlPlanDemo

Finally, we consider the kinematics of a robot and run rlPlanDemo. The rlkin directory contains the Denavit-Hartenberg parameters of several robots. For robot path planning, both the kinematics, as well as the scene graph with collision objects are needed.

Run

/usr/bin/rlPlanDemo /usr/share/rl/examples/rlplan/unimation-puma560_boxes_rrtConCon.xml

Hit F4 to choose a random pose, and Ctrl+F2 to set it as an end position. Then, hit space to find a collision-free path, which will be visualized.

This example uses a RL planning XML file rlplan/unimation-puma560_boxes_rrtConCon.xml, which in turn includes the kinematics in rlkin/unimation-puma560.xml and the scene graph in rlsg/unimation-puma560.convex/unimation-puma560.convex.xml.

Optional: You may edit rlkin/unimation-puma560.xml and set much smaller min/max angle ranges for several joints. Then, path planning will become more difficult or even impossible for many poses. Undo all changes.

rlCoachKin & rlCoachMdl

RL installation also includes two very simple "virtual robot" visualization socket server programs. rlCoachKin is for Denavit-Hartenberg kinematic chains (as defined in rlkin/*.xml files), rlCoachMdl is the equivalent tool for arbitrary geometric chains (allowing branches).

Run the program by specifying a scene file and a corresponding kinematics description

/usr/bin/rlCoachKin /usr/share/rl/examples/rlsg/unimation-puma560_boxes.xml /usr/share/rl/examples/rlkin/unimation-puma560.xml

The socket server now displays the robot in the scene and listens for commands at port 11235. The usual way how to test a simple robot control program is to use this visualization server, connecting through the RL class rl::hal::Coach.

Now, in a second terminal, establish a socket connection to the visualization server

telnet localhost 11235

Usually, the coach visualization servers will only be used behind a transparent interface rl::hal::JointPositionActuator, and you do not need to write any socket commands yourself. Setting joint angles is rather straightforward however: enter 2 followed by the ID of the scene model (in this case 0) and 6 values for the joint angles in radians.

2 0 1.57 0.31 0 0 1.57 0

Writing your first applications

Forward kinematics calculation for a robot manipulator

In the following steps, we develop a very simple kinematics application using the Robotics Library.

Create a directory for the example in your home directory. In this directory, create a folder build and two files, a CMakeLists.txt and a myMdlDemo.cpp file.

Add the following content to your CMakeLists.txt file.

cmake_minimum_required(VERSION 2.8.11)
project(myMdlDemo)
find_package(RL COMPONENTS MDL REQUIRED)
if(CMAKE_SIZEOF_VOID_P EQUAL 4)
	add_definitions(-DEIGEN_DONT_ALIGN)
endif(CMAKE_SIZEOF_VOID_P EQUAL 4)
add_executable(
	myMdlDemo
	myMdlDemo.cpp
)
target_link_libraries(
	myMdlDemo
	${RL_LIBRARIES}
)

This file controls the build process and will be processed by CMake. find_package calls a known script, this is especially useful for libraries at non-standard locations with additional binary tools. add_executable creates a new program, following the *.cpp files to be compiled for that program. target_link_libraries defines which libraries a program is to be linked against.

Add the following contents to the file myMdlDemo.cpp and save both files.

#include <iostream>
#include <rl/math/Transform.h>
#include <rl/math/Unit.h>
#include <rl/mdl/Kinematic.h>
#include <rl/mdl/Model.h>
#include <rl/mdl/XmlFactory.h>

int
main(int argc, char** argv)
{
	rl::mdl::XmlFactory factory;
	rl::mdl::Kinematic* kinematics = dynamic_cast< rl::mdl::Kinematic* >(factory.create("/usr/share/rl/examples/rlmdl/unimation-puma560.xml"));
	rl::math::Vector q(6);
	q << 10, 10, -20, 30, 50, -10;
	q *= rl::math::DEG2RAD;
	kinematics->setPosition(q);
	kinematics->forwardPosition();
	rl::math::Transform t = kinematics->getOperationalPosition(0);
	rl::math::Vector3 position = t.translation();
	rl::math::Vector3 orientation = t.rotation().eulerAngles(2, 1, 0).reverse();
	std::cout << "Joint configuration in degrees: " << q.transpose() * rl::math::RAD2DEG << std::endl;
	std::cout << "End-effector position: [m] " << position.transpose() << " orientation [deg] " << orientation.transpose() * rl::math::RAD2DEG << std::endl;
	return 0;
}

Now, the first makefiles are created. Open a terminal and navigate to the build folder. Run

cmake ..

This will process the CMakeLists.txt in the parent directory and generate the first makefiles. You then may run

cmake --build .

Run your program with the following command. The console should output a position and orientation. This verifies that the Robotics Library is properly installed.

./myMdlDemo

You have successfully set up your own project to use the kinematics component of the Robotics Library.

Visualization of a robot manipulator

In the following steps, we develop a very simple visualization example using the Robotics Library.

Create a directory for the example in your home directory. In this directory, create a folder build and two files, a CMakeLists.txt and a myViewDemo.cpp file.

Add the following content to your CMakeLists.txt file.

cmake_minimum_required(VERSION 2.8.11)

project(myViewDemo)

find_package(RL COMPONENTS SG REQUIRED)
find_package(Qt4 REQUIRED)

if(CMAKE_SIZEOF_VOID_P EQUAL 4)
	add_definitions(-DEIGEN_DONT_ALIGN)
endif(CMAKE_SIZEOF_VOID_P EQUAL 4)

add_executable(
	myViewDemo
	myViewDemo.cpp
)
target_compile_definitions(
	myViewDemo
	PUBLIC
	"" ${QT_DEFINITIONS}
)
target_include_directories(
	myViewDemo
	PUBLIC
	${QT_INCLUDES}
)
target_link_libraries(
	myViewDemo
	${QT_QTCORE_LIBRARY}
	${QT_QTGUI_LIBRARY}
	${QT_QTOPENGL_LIBRARY}
	${RL_LIBRARIES}
	/usr/lib/libSoQt.so # or /usr/lib/x86_64-linux-gnu/libSoQt.so
)

Add the following contents to the file myViewDemo.cpp and save both files.

#include <iostream>
#include <QWidget>
#include <Inventor/SoDB.h>
#include <Inventor/Qt/SoQt.h>
#include <Inventor/Qt/viewers/SoQtExaminerViewer.h>
#include <rl/sg/so/Scene.h>

int
main(int argc, char** argv)
{
	SoDB::init();

	QWidget* widget = SoQt::init(argc, argv, argv[0]);
	widget->resize(800, 600);

	rl::sg::so::Scene scene;
	scene.load("/usr/share/rl/examples/rlsg/unimation-puma560_boxes.xml");

	SoQtExaminerViewer viewer(widget, NULL, true, SoQtFullViewer::BUILD_POPUP);
	viewer.setSceneGraph(scene.root);
	viewer.setTransparencyType(SoGLRenderAction::SORTED_OBJECT_BLEND);
	viewer.show();

	SoQt::show(widget);
	SoQt::mainLoop();

	return 0;
}

Open a terminal and navigate to the build folder. Run

cmake ..
cmake --build .
./myViewDemo

You have successfully set up your own project to use the scene graph component of the Robotics Library.