Note: This tutorial assumes that you have completed the previous tutorials: Creating a CRAM package, Roslisp Basic Usage.
(!) Please ask about problems and questions regarding this tutorial on Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Controlling turtlesim from Lisp

Description: In this tutorial you will learn how to control a turtle in turtlesim with CRAM Fluents

Tutorial Level: BEGINNER

Next Tutorial: Implementing simple plans

Updating the dependencies

In this tutorial we will re-use the package cram_tutorial that you have created in the previous tutorial. For controlling turtlesim, we need to depend on its package since it contains the message definitions we will use. Further, we will have to deal with poses. For that, we want to use the package cl_transforms. Open manifest.xml and add the lines

  <depend package="turtlesim"/>
  <depend package="cl_transforms"/>

Now open cram-tutorial.asd and update the system dependencies to include the system turtlesim-msg and cl-transforms. The systems that correspond to the messages of a package are always named like the package name with a -msg suffix. Your system should now look like this:

(defsystem cram-tutorial
  :depends-on (roslisp cram-language turtlesim-msg cl-transforms)
  ((:module "src"
            ((:file "package")
             (:file "tutorial" :depends-on ("package"))))))

Updating the the Lisp Package

We also need to add cl-transforms as a dependency in the file package.lisp.

(defpackage cram-tutorial
  (:nicknames :tut)
  (:use #:cpl #:roslisp #:cl-transforms))

Writing the communication glue code

Now it's time to use roslisp to connect to turtlesim. Turtlesim creates one namespace per turtle. For each turtle name turtle1, turtle2, etc. it publishes the pose of the turtles on a ~/pose topic, publishes the color value under the turtle on a ~/color_sensor topic. For each turtle subscribes to a ~/command_velocity topic waiting for commands to move the turtle.

The code

Open the file tutorial.lisp and add the following code.

(in-package :tut)

(defvar *color-value* (make-fluent :name :color-value) "current color of turtle")
(defvar *turtle-pose* (make-fluent :name :turtle-pose) "current pose of turtle")

(defvar *color-sub* nil "color subscription client")
(defvar *pose-sub* nil "pose subscription client")
(defvar *cmd-vel-pub* nil "command velocity subscription client")

(defun init-ros-turtle (name)
  "subscribes to topics for a turtle and binds callbacks. `name' specifies the name of the turtle."
  (setf *color-sub* (subscribe (format nil "~a/color_sensor" name)
  (setf *pose-sub* (subscribe (format nil "~a/pose" name)
  (setf *cmd-vel-pub* (advertise (format nil "~a/command_velocity" name)

(defun color-cb (msg)
  "Callback for color values"
  (setf (value *color-value*) msg))

(defun pose-cb (msg)
  "Callback for pose values"
  (setf (value *turtle-pose*) msg))

(defun send-vel-cmd (lin ang)
  "function to send velocity commands"
  (publish *cmd-vel-pub* (make-message "turtlesim/Velocity"
                                       linear lin
                                       angular ang)))

The code explained

In (defun init-ros-turtle ...) we subscribe to the pose and the color sensor topic and create a function that can publish the command_velocity topic. The topic clients are stored in global variables we defined before.

We use callback function ...-cb for all updates on the pose of the turtle and the color sensor value to a fluent in order to be able to use those values in a reactive control program.

A fluent is a proxy around a value with support for notification on change. Further, fluents can be combined to so-called fluent networks.

Experimenting in the REPL

Now let's try it out. Open your Lisp REPL and make sure that you loaded the system cram-tutorial and switched to the package tut, hint:

CL-USER> (ros-load:load-system "cram_tutorial" :cram-tutorial)
CL-USER> (in-package :tut)

For experiments in the REPL, we want to initialize a Lisp ROS node and then call init-ros-turtle.

Make sure roscore is running in a terminal. Else we cannot create ros nodes.

Enter the following commands:

TUT> (start-ros-node "cram_tutorial_client")
[(ROSLISP TOP) INFO] 1292688669.674: Node name is cram_tutorial_client
[(ROSLISP TOP) INFO] 1292688669.687: Namespace is /
[(ROSLISP TOP) INFO] 1292688669.688: Params are NIL
[(ROSLISP TOP) INFO] 1292688669.689: Remappings are:
[(ROSLISP TOP) INFO] 1292688669.691: master URI is
[(ROSLISP TOP) INFO] 1292688670.875: Node startup complete

The name of the node is arbitrary, we need to call start-ros-node before we can use the functions subscribe and advertise.

TUT> (init-ros-turtle "/turtle1")

This calls our function init-ros-turtle, with the name that the turtlesim uses for the first turtle spawned.

Now we should start up turtlesim in a new terminal:

$ rosrun turtlesim turtlesim_node

You will see the turtlesim window:

  • turtlesim.png

Notice that thanks to ROS, we could subscribe to the topics even before they had been advertised by the turtlesim.

We are ready for experiments now. Let's see if the fluents are containing the right values:

TUT>  (value *turtle-pose*)

TUT>  (value *color-value*)


You see that the value of the fluents contain structured data, which contains the pose and color information as provided by the turtlesim simulator.

Let's see if the pose changes if we move the turtle. Start up turtle_teleop_key and move the turtle a little bit:

$ rosrun turtlesim turtle_teleop_key

Try evaluating *turtle-pose* in the REPL again:

TUT>  (value *turtle-pose*)


As the pose fluent has been updated, the subscribers seem to work.


Now let's play around with fluents a little bit more.

Notice how in the checks before, we used the function (value *turtle-pose*), instead of accessing the variable directly. This is because fluents are proxies, and to get the values we need to use the value function.

Fluents allow us to wait for specific events. For instance, we can wait for the x coordinate of the turtle being smaller than 5:

TUT> (wait-for (< (fl-funcall #'turtlesim-msg:x *turtle-pose*)

The code above constructs a fluent network. The expression

(fl-funcall #'turtlesim-msg:x *turtle-pose*)

returns a new fluent that contains the x-value of the turtle pose. So from a proxy that wrapped the whole pose of a turtle, we got a new proxy that wraps just the x coordinate. The expression

(< (fl-funcall #'turtlesim-msg:x *turtle-pose*)

returns a fluent that is either T or NIL indicating if the x-coordinate is either smaller or bigger than 5.0. Finally, wait-for waits for the fluent to become T.

Execute the above expression. If the turtle's x position is already smaller than 5, the expression should return T immediately. If not, the expression should block until you move the turtle far enough to the left using the teleop.

Moving the turtle

Let's see if we can also move the turtle from LISP. Try the following:

TUT> (dotimes (i 10) (send-vel-cmd 1 1) (sleep 1))

We use the send-vel-cmd function that we defined in tutorial.lisp. We send the same command 10 times, once every second. The turtle should now move along a circle.


Now that we have functions and fluents to connect to the turtlesim, let's implementing some simple plans.

Wiki: cram_core/Tutorials/ControllingTurtlesimFromLisp (last edited 2012-07-18 11:26:14 by Lorenz Mösenlechner)