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, except 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.

Prerequisites

Follow the Ubuntu Installation and add the Launchpad repository 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-0.7.0. In this directory, you find several subdirectories with robot and scenario models. 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-0.7.0/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-0.7.0/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 model (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-0.7.0/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-0.7.0/examples/rlsg/unimation-puma560_boxes.xml /usr/share/rl-0.7.0/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 myMdlDemo for the example in your home directory. In this directory, create 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)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(RL COMPONENTS MDL REQUIRED)
add_executable(myMdlDemo myMdlDemo.cpp)
target_link_libraries(myMdlDemo ${RL_LIBRARIES})

This file controls the build process and will be processed by CMake. RL requires the C++11 standard and enabled math constants. find_package looks for the CMake config files included in RL's installation. add_executable creates a new program with corresponding *.cpp source files. 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;
	std::shared_ptr<rl::mdl::Model> model(factory.create("/usr/share/rl-0.7.0/examples/rlmdl/unimation-puma560.xml"));
	rl::mdl::Kinematic* kinematics = dynamic_cast<rl::mdl::Kinematic*>(model.get());
	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;
}

First, the build files are created. Open a terminal and navigate to the myMdlDemo folder. Create a folder build inside it and run

cmake ..

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

make

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 myViewDemo for the example in your home directory. In this directory, create 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)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt4 COMPONENTS QtCore QtGui QtOpenGL REQUIRED)
include(${QT_USE_FILE})
find_package(RL COMPONENTS SG REQUIRED)
add_executable(myViewDemo myViewDemo.cpp)
target_link_libraries(
	myViewDemo
	${QT_QTCORE_LIBRARY}
	${QT_QTGUI_LIBRARY}
	${QT_QTOPENGL_LIBRARY}
	${RL_LIBRARIES}
	/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-0.7.0/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 myViewDemo folder. Create a folder build inside it and run

cmake ..
make
./myViewDemo

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