VIKI documentation¶

Requirements¶

VIKI uses ROS for all its main functionality and therefore builds on top of those dependencies. In line with ROS, VIKI only supports Ubuntu as its platform and is tested on LTS versions 12.04 and 14.04. Other Ubuntu (and even Linux) distributions may work just as well, but are not supported.

Installation¶

Installation is as easy as pulling the repository into your (or a new) catkin_workspace. The repository can be found on https://github.com/UT-RAM/viki/. VIKI is a standalone tool and therefore, by default, does not live in your catkin workspace. We recommend installing it in your home folder, but you’re free to install it where you like.

cd ~
git clone https://github.com/UT-RAM/viki

This will create a new folder /home/<user>/viki, where all the VIKI magic lives.

Configuring VIKI¶

VIKI has a self-configuring tool, which setups the folder directories for you. This is done by launching the configure application from the terminal.

cd <viki_dir>
./viki configure

Running this will install some extra dependencies, setup a config.json file for the right directories and setup a .desktop file such that you can launch VIKI from the Unity Dash.

Module repositories¶

To be able to really use VIKI, a module repository needs to be added. VIKI works with module repositories, such that you can get started quickly by automatically adding a set of packages. Using the command line, you can add the default repository as follows

./viki add-module-repository

This will pull the repository and automatically install all dependencies that might be needed for the modules so they can be launched. Furthermore, VIKI should be able to run catkin_make instantly, but this does not work as well,

ROS package dependencies¶

If you followed the steps above, you should be all set. VIKI tries to handle all its ROS package dependencies by using the rosdep tool. However, since this is not optimized for different ROS versions, this may sometimes not work that well. To get an overview of what your missing packages are, run

./viki check-packages

based on this, you might find out you’re missing the libuvc_camera package when using ROS jade. Since this package is not available for jade, it may not automatically install. To install this by hand, you can run

sudo apt-get install ros-indigo-libuvc-camera

as the package is available for ROS indigo. It should not be that hard to figure this out for your packages and we are working to find a way to neatly resolve this. In the meantime, if you’re still experiencing any problems, please do not hesitate to contact The developers

Launching VIKI¶

First off, you will have to start VIKI. Open a terminal, navigate to the installation folder of viki (usually ~/catkin_ws/src/viki) and execute

./viki run

You should see a screen pop up with the interface of VIKI.

A quick look at the interface¶

After launching VIKI, we can take a look at the interface and the elements that the interface provides:

1. Canvas: This is where you will build your project.
2. Module Palette: This shows all the modules that are available.
3. Module specifics: Once a module is selected, this pane shows all the parameters that are available for this module. Furthermore, there are three buttons to edit arguments, prefixes and select the machine that this module will run on.
4. Toolbar: Here are the basic actions that you will need during use. Hover over each button to see its purpose
5. Run button: Press this button to run the setup you created.
6. Status pane: This shows some status information, which can basically be used for debugging.

People that are familiar with for example Simulink probably recognize this layout. You can search for modules that you need in your project in the palette, when you have found a module that you need, you can drop it to the canvas, connect it with other modules and run your project to see all the magic happen. During the next few steps, we will guide you through your first launch.

Launching your first project¶

In this quick guide, I will guide you through launching your first project with VIKI using the turtlesim. We need two modules for this setup: the turtle simulator and a module that interprets input from your keyboard and sends it to the simulator. Below the VIKI-logo you can search for modules by clicking in the textbox and entering turtle. You will see two modules called:

• turtle_teleop_key
• turtlesim node

You need both of these. Click and drag each of these modules to the canvas. You should now see two loose modules visible on your canvas.

Now that we have the two modules, we need to connect them. We will need to connect the output of turtle_teleop_key to the input of turtlesim node. You can do this by dragging the teleop’s output node to the turtle’s input node. An arrow will appear that indicates the direction of information. Notice that you can not start dragging at the turtle’s input node: you need to follow the direction of information.

Your setup is now ready. Hit the green run button on top of the screen. A new terminal should open that gives some text feedback. This terminal is used to open your complete setup. More importantly, you should also see a window with a turtle in it. If you focus your input on the text window (click somewhere on it) then you can use your arrow keys to control the turtle in the other window.

When you’re done playing around with the turtlebot, you can select the terminal window and press Ctrl + C, which will kill its processes. After gracefully shutting down, the terminal window will disappear, and you’re free to again run your canvas setup.

Where to move from here?¶

Know that you know the basic functionality of VIKI, you’re basically ready to go! Probably, you’ll want to write some own specific functionality by adding your own modules. If this is the case, you can go to the Contributor page to see more information about writing your own module. For more functionality, you can check out the Features page or take a look at Distributed systems (SSH documentation) functionality. If you want to learn more about the vision, background and core of VIKI, or want to contribute to the core, you can visit the Developer documentation page.

Currently supported¶

VIKI supports a wide set of features

• Build a graphical model of your robot software with modules based on ROS
• Save/Open build canvas models
• Add extra commandline options to modules on the canvas
• Extend functionality by easily creating your own modules
• Export your build model to a launch file
• Automatically launch nodes on a different machine with SSH

Of course, VIKI supports (at least the basic) functionality of ROS features.

• Supply parameters for launch, which can be edited directly in the GUI as well
• Dependency management on the modules, based on rosdep, rospack and git repositories
• Many2Many communication between modules, also to be edited easily in the GUI

Future goals¶

VIKI is continuing to be improved and different features get added constantly. Functionality that has not made it yet to its release includes

• Communication via services
• Communication via topics that are not created by nodes in VIKI
• ROS multimaster support

We’re working on bringing these features into VIKI as well! If there’s any functionality you would like to see, contact The developers and we will (most likely) help you out quickly!

Setting up the network¶

ROS works by running a ros master, or roscore, on one system. All other systems connect to it via it’s location that is saved in the ROS_MASTER_URI environment variable. Other computers on the network are found by using their name. Furthermore all ports need to be open as ROS opens a new connection for every topic on a random port.

First we make sure we can communicate bidirectionally between systems. As an example take a computer named Ash and a computer named Pikachu. Ash will be the main computer where we run VIKI. Pikachu will be the remote computer (with ROS, but possibly without VIKI). There can be more computers like Pikachu (with different names!) but in this guide we will describe just one.

hostname

ifconfig

sudo gedit /etc/hosts

127.0.0.1      localhost

127.0.0.1               localhost
192.168.1.10    Ash
192.168.1.20    Pikachu

ping 192.168.1.20

ping Pikachu

Setting up SSH¶

ROS uses the SSH protocol to run things on other systems. For it we need a username and password on the machine on which we want to run things. These are the username and password you would normally use to log in on the computer.

If it is not yet previously installed you need to install openssh-client on the main PC (Ash) and openssh-server on the remote. You can do this by running one of the following two lines and accepting the questions

sudo apt-get install openssh-client
sudo apt-get install openssh-server

ssh username@Pikachu

exit

ssh-keygen -R [hostname]
ssh-keygen -R [ip_address]
ssh-keygen -R [hostname],[ip_address]
ssh-keyscan -H [hostname],[ip_address] >> ~/.ssh/known_hosts
ssh-keyscan -H [ip_address] >> ~/.ssh/known_hosts
ssh-keyscan -H [hostname] >> ~/.ssh/known_hosts

gedit ~/.viki_env

#!/bin/bash
. /opt/ros/jade/setup.sh
DISPLAY=:0; export DISPLAY
exec "$@"

Testing the setup (tutorial)¶

Everything should now be set up. We can test the setup with a simple configuration of VIKI. For instance:

1. Start VIKI
2. Add a turtle sim node
3. Add a turtle teleop node
4. Connect them
5. Click the ‘machin list’ icon (top of screen in VIKI)
6. change the localhost to the name of the computer running VIKI (Ash in above example)
7. add a machine, give it a name and fill in the adresses/username and password. In our case: name Pikachu, adress Pikachu
8. Save and close
9. Click the turtlesim node, and in the properties screen (right side) use select screen to make it run on Pikachu rather then default (local)
10. Select the teleop node and add a prefix xterm -e to make it open in a new terminal
11. Click run

This setup will open a roscore on the current machine, a turtlesim node on Pikachu, and a teleop node on Ash. Run RQT to see everything works (remember to refresh after the you have sent a few messages) or just run around with your turtle trying to draw a Pikachu.

General outline¶

Every module file starts out with:

<!-- VIKI_MODULE -->

This line makes sure the module is found by VIKI during the scan of files. Not implementing this line makes your module invisible to VIKI. The second line starts the module description:

<module type="sensor" id="camera_source">

This line specifies the type and id of the module. The type is a string on which VIKI groups its modules. You are free to choose anything you like here, but to be able to ingerate with VIKI better it is recommended to choose one of the following:

• Controller
• Middleware
• Rosdefaults
• Sensor
• Userinput
• Vehicle
• Views

The id is a string that is unique for every module. Make sure it is not too generic! If you make a module called ‘camera’, the chance is big that such a module already exists and causes conflicts with other modules. Preferably, use a prefix for your specific project modules.

After the opening lines, the important stuff happens. There are 5 types of XML nodes you can add here:

• meta
• inputs
• outputs
• executable
• configuration

Meta¶

As the name suggests, this is the place to add the meta information of your package. This looks like

<meta>
    <name>USB camera</name>
    <author>Robin Hoogervorst</author>
    <icon>icon.png</icon>
    <description>
        Wrapper for the USB cam package within ros
    </description>
</meta>

These tags basically speak for themselves, but for completeness sake:

• name: This is the name of the module as VIKI shows it in the list
• author: This is the name of the Author of the module. If you’re writing it, it would be you.
• icon: The icon that VIKI uses to show it in the list. For more options, see below
• description: The description shown in the interface of VIKI

Dependencies¶

To be able to automatically let VIKI install the ROS packages, you need to specify which you are using. This is simply done by specifying the name of the ROS package inside the dependency tags.

<dependencies>
    <depends>libuvc_camera</depends>
</dependencies>

This can now be automatically installed using the VIKI command line tool. If there is no apt-get package available for your package, you can specify the repository of the package. Set a ‘type’ and ‘src’ attribute in the depends tag like such:

<dependencies>
            <depends type="git" src="https://github.com/ros-drivers/mocap_optitrack">mocap_optitrack</depends>
    </dependencies>

Inputs and Outputs¶

<inputs>
    <input type="ros_topic" name="image_view_input" link="image_view/image" message_type="sensor_msgs/Image" required="true" />
</inputs>

<outputs>
    <output type="ros_topic" name="image" link="usb_cam/image_raw" message_type="sensor_msgs/Image" required="true" />
    <output type="ros_topic" name="image2" link="usb_cam_2/image_raw" message_type="sensor_msgs/Image" required="true" />
    <output type="ros_topic" name="<name>" link="<executable_id>/<topic_name>" message_type="<ros_type>" required="<boolean>" />
</outputs>

The inputs and outputs come after the meta information. These specify the module in- and outputs, not executable specific ones. As can be seen, these blocks consist of a group XML node and (a set of) XML node(s) for each in/output. Attributes available for each specific in/output:

• type: This is the type of input for the module. Currently, only ‘ros_topic’ is supported.
• name: This is the name of the output, which will be shown in VIKI.
• link: This specifies to which ROS executable topic this links. It is of the format ‘<executable_id>/<topic_name>’.
• message_type: A ROS topic type: (e.g. sensor_msgs/Image, geometry_msgs/PoseStamped, std_msgs/Empty). VIKI makes sure you only can connect topics of the same type. So it’s important to specify!
• required: Indicates whether the topic is required to be connected. Is currently not used in the interface, but will probably be implemented in the future.

Executables¶

An executable in a ROS node specifies a ROS node that is to be executed.

<executable id="usb_cam" pkg="libuvc_camera" exec="camera_node">
    <params>
        <param name="vendor" type="str" default="null" />
        <param name="product" type="str" default="null" />
        <param name="width" type="str" default="640" />
        <param name="height" type="str" default="480" />
        <param name="frame_rate" type="str" default="15.0" />
    </params>

    <outputs>
        <output type="ros_topic" name="image" message_type="sensor_msgs/Image" required="false" />
    </outputs>
</executable>

The first line has three attributes:

• id: This is the id used in the configuration to specify this executable. The module inputs and outputs are linked to executable inputs and outputs using this id.
• pkg: The package from which to run the node
• exec: The node that is to be run

The pkg and exec parameters correspond to running the node with

rosrun <package> <executable>

The params block corresponds to the parameters that can be set for each executable. The type corresponds to the types of ros parameters. Since this module file is basically an template for what will be runned, only a default option can be set and no definite value. These default options can be changed by the user using VIKI before launch.

Modularity¶

VIKI aims at creating and maintaining a highly modular environment. This means we highly encourage you to write your modules as modular as possible. It is good to really think beforehand what you want the module to do and keep it as general as possible.

Location¶

If you want to add your own module, you can place this in your own folder in the viki_modules directory. If you have installed VIKI properly, you should have a viki_modules directory inside the src directory in your workspace. In there, there is the core directory that supplies the basic modules for VIKI. You can place a directory next to that, where your own modules and packages will live. You can place the viki.xml for VIKI in the same folder as you create your ROS package with.

+--- catkin_ws/src
|------ viki/
|------ viki_modules/
|       |--- core/
|       |--- <user>
|       |    |--- <your_module>
|       |    |   |--- src/
|       |    |   |--- package.xml
|       |    |   |--- viki.xml
|       |    |--- <your_second_module>
|       |        |--- src/
|       |        |--- package.xml
|       |        |--- viki.xml

Since VIKI does have good dependency management, you can also just put your ROS package in its own seperate repository and define the dependency in the module file.

Checklist¶

When writing a (ROS package for a) VIKI module you must:

• Use catkin to build your package
• Specify the right dependencies in the package.xml file (from ROS)
• Specify your name and contact information within the viki.xml file
• Specify your own package name in the dependency in the viki.xml file

Your module must:

• Publish its topics in its base namespace (so no ‘/’ at the start of your topic name). (For more information about namespaces, see http://wiki.ros.org/Names ) If you use python, this is done automatically, but if you’re using C++, make sure you have the right nodehandle.

Your module should

• Have a clear (and preferably short) answer to the question: ‘What is the task of this module?’

Your ROS package/node should:

• Live in the same folder as the viki.xml file
• Have clear documentation within the code

Workflow¶

Hotfixing¶

When a hotfix needs to be made, make sure to checkout to the commit before the bumpversion has run. Based on that commit

1. Create a new hotfix branch
2. Make your changes and commit (only the neccessary changes)
3. Follow the release step 2-6 to publish this hotfix immediately

Core¶

The core of the framework is the actual part doing the work. The core provides functionality and a GUI but is rather stupid: it knows of no ROS nodes, executables or anything else you actually want to run. To create a useful experience the core needs the following additions.

Documentation¶

Documentation consists of technical information and user guides. This page is also part of the documentation and you have probably already seen home.

Updating documentation¶

Once you have made changes please update the documentation by editing the .rst files in VIKI/doc/ and re-build the documentation by running the following the the VIKI root directory

sphinx-apidoc -f -o docs core; cd docs; make html; cd ..

Modules¶

A module is a collection of ROS packages or nodes, with some configuration added so that it provides one simple function. A module is the smallest building block of the framework. You can write your own modules and put it in a dedicated folder so that you and others can use it. If you are a RAM member the developers provide a list of useful modules in an actively maintained repository at http://www.github.com/UT-RAM/viki-modules .

A more elaborate description (much more technical) can be found in description of module attributes and tags