mapsNrobots LISP Code Documentation

October 1, 2001

Contents

1 General Remarks 21.1 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 Loading the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3 Adding own Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.4 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Utility package 3

3 Extensions to MCL’s view classes 53.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Geometry Package geometry 104.1 Graphical display and EPS export . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Robot Communication Package robbi 185.1 Overview and Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.2 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.3 Functions, Data Structures, and Variables . . . . . . . . . . . . . . . . . . . 205.4 Implementation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.5 Avoiding “Open Transport” . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6 control Package for direct Robot Control 246.1 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246.2 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246.3 Functions, Data Structures, and Variables . . . . . . . . . . . . . . . . . . . 25

7 Robot Motion Behaviour Package motion-behaviours 277.1 Functions, Data Structures, and Variables . . . . . . . . . . . . . . . . . . . 277.2 Implementation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

8 Package simulator and the internal simulator 318.1 Using the simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318.2 Implementation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

8.2.1 (De-)Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338.2.2 Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338.2.3 Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338.2.4 Command Implementation . . . . . . . . . . . . . . . . . . . . . . . 33

1

1 General Remarks

This section is dedicated to those things you be aware of prior to using or modifying anyof the code covered by this documentation.

The code documented here is written in Macintosh Common Lisp (MCL), Version 4.2.In different parts of the program, operating system’s functionality is also needed. Thoseneeds are explained in the various parts of this documentation. Any PPC (or later) basedMacOS should be compatible with this framework. As MCL has many extensions toCommon LISP, which are essential for this implementation, porting to other LISP systemsis most likely to fail.

1.1 Documentation

The LISP code is documented in two ways. Besides this document, the packages them-selves contain comments. However, the aim of the source code documentation is to pro-vide a rather low-level understanding as needed for debugging and extending the code.Within this documentation, the documentation style is similar to that from MCL. AllLISP-expressions will be printed in a monospace typewriter font. The reader is as-sumed to be familiar with at least Common LISP. Special additions to LISP provided byMCL (and hence unfamiliar to the reader) only deal with a view specific (but large) topics:processes/concurrency, graphic I/O, and operating system interface. MCL’s documen-tation provides the necessary information. Special information on operating system callsis available online from Apple (http://www.apple.com).

1.2 Loading the Code

To load the framework presented here, a loader has been written to load the files in theright order. By loading the file “loader.lisp” all files are loaded. The loader assumes thesource files to be located within the same folder as the loader itself, the framework’sabsolute position on the disc does not matter. Note, that the loader can only be loaded,not evaluated, as to achieve independency of absolute path names the variable *load-pathname* is read, which will only be bound to a pathname when executing a load.

1.3 Adding own Code

To add your own code, you should add another loader to load both, the framework andyour code. It’s best to copy the framework’s loader, renaming it in something like “my-loader.lisp” and change it’s definition of files-to-load appropriately.

1.4 Debugging

Expect the unexpected! To help tracing bugs, most packages declare are private param-eter *debug*, which can be used to switching debugging output on or off. However,packages deal in different ways with this parameter. While in some any non-nil valuewill direct debugging output to the current listener, others expect *debug* to be thestream to write to. Hence, you are best of using only values t or nil.

2

2 Utility package

The utility package utils encapsulates some handy functions and macros used in manyplaces. Currently, it is imported by the packages geometry and control. Most of thefunctions and macros are taken from Paul Graham’s “On Lisp - Advanced techniques forCommon Lisp”.

with-gensyms [Macro]

Syntax with-gensyms syms &body body

Decsription Evaluates body with the symbols in list syms bound to gensyms.

condlet [Macro]

Syntax condlet clauses &body body

Arguments clauses (�(test (

�(variable value) � *)) � *)

Decsription Evaluates body with variables bound depending upon the condition,uninitialized variables read as nil, (see Graham, p. 147).

Example ? (condlet (((= 1 2) (x (princ ’a)) (y (princ ’b)))((= 1 1) (y (princ ’c)) (x (princ ’d)))(t (x (princ ’e)) (z (princ ’f))))

(list x y z))CD(D C NIL)

do-tuples [Macro]

Syntax do-tuples tuple list &body body

Decsription Evaluates body with a tuple of variables bound to successive subse-quences of a list. For example, given two parameters, do-tupleswill iterate by pairs (see Graham, p. 155).

Example ? (do-tuples (x y) ’(a b c d)(princ (list x y)))

(A B)(B C)(C D)NIL

do-tuples/c [Macro]

Syntax do-tuples/c tuple list &body body

Decsription Evaluates body with a tuple of variables bound to successive subse-quences of a list just like do-tuples, but wraps around to the front(see Graham, p. 155).

Example ? (do-tuples/c (x y) ’(a b c d)(princ (list x y)))

(A B)(B C)(C D)(D A)NIL

3

for [Macro]

Syntax for (var start stop) &body body

Decsription Evaluates body with var bound to integer start, start+1, ... while ( �var stop) does not hold, (see Graham, p. 155).

Example ? (for (x 0.1 2)(format t "˜w " x))

0.1 1.1NIL

Still to do: map0-n, mapa-b, map1-n, mapcars, map- � , rmapcar

4

3 Extensions to MCL’s view classes

The view extensions found in the file view-extensions.lisp extend the classes presentin MCL, they load into the built-in package CCL. The aim is to allow for features foundin CLIM without the need for the whole CLIM system. Therefore, the featured exten-sions do not require lots of memory and processing time. Additionally, the extensionsare fine-tuned for MCL and support the designing of a nice-looking user interface. Touse these extensions to your benefit you should be familiar with MCL and its support toviews, windows, and MacOS-related functionality. However, a detailed understandingis not needed. This documentation will provide not only the information necessary forusing the extensions, but also for extending them (or adding some bug-fixes). Those notneeding to know the details may skip the implementation notes.

3.1 Overview

A graph showing the new classes and their inheritance relationship should be shownhere. Some general information should follow, too.

Most of the classes extending MCL’s view class, have an generic update function(update obj), which updates instance slots needing a update, e.g. layout view con-tainers will rearrange their subviews. A redraw will then be forced. There should beno reason for calling this method directly. This update function will be invoked by callsto initialize-instance or set-view-size, to name but a view. If extending theclasses provided, you should follow this way of updating instance slots by specializingthe update method, as you will benefit from definitions like shown below, which willautomatically react to a change of view size:

(defmethod set-view-size :after (this simple-view) h &optional v)(declare (ignore h v))(update this))

3.2 Features

To provide a first glance at the features implemented and to help choosing the right class,a brief listing of implemented features is given here. The listing aims at guiding the userto the relevant parts of the documentation.

feature implemented in class

views with specific background colors colored-background-view

Displaying Values with automatic update display-value-viewget-display-valueset-display-value

Views that automatically adapt their size and posi-tion to a specified portion of their container’s size

simple-layout-viewlayout-viewcolored-background-layout-mixin

Views supporting setup facilities view-with-setup

Views providing an euclidean coordinate system coordinate-view

Views allowing for buffered output (increasingspeed)

buffered-view

5

simple-layout-view [Class]

Decsription This class extends the simple-view by adding slots for specifying lay-out parameters. The view will automatically set to specified size andposition (and rearranged if necessary) within any layout-view. Re-member, (re)arranging will only work if this view is a subview toa layout-view (or to any class derived from layout-view likewindow-layout-view-mixin for example). Class-specific validinitargs are:

:layout-size A Function (lambda (container-view-size)...) specifying this view’s size dependent on the size of theview’s container.

:layout-position Just like layout-size:, only specifying the view’sposition instead.

See also the MCL documentation on views and points.

layout-view [Class]

Decsription A view, which itself has the properties of a simple-layout-view, thatcontains simple-layout-views. These views will be positioned accord-ingly to their specifies position and size. For valid initargs see thedocumentation on simple-layout-views.

window-layout-view-mixin [Class]

Decsription Class derived from layout-view and window by (defclasswindow-layout-view-mixin (window layout-view) ()).That’s all.

colored-background-view [Class]

Decsription Class allowing for a specific background color within a single view.Class-specific valid initarg:

:bgcolor Specifies the desired color, e.g. *red-color*. See MCLdocumentation for details on colors.

view-with-setup [Class]

6

Decsription Basic functionality for providing views with setup dialogs. This viewcatches any Command-Click in its region and displays a setup dialog.A setup dialog consists of a fixed part containing “OK” and “Can-cel” buttons, and the like. A varying part is the so-called category-view, which are to be specified for any derived class. The pur-pose of a category view is to provide setup facility for a couple ofitems within one single view. Each category-view needs to imple-ment two methods: update-setup and update-view. See belowfor details on those methods. Having specified such category for aspecific view, one can make this setup available by pushing a consof name and view-class, e.g. (cons "transformation/grid"’coordinate-view-setup) onto view-setup-dialog-viewsof the derived class. This is best done within a initialize-instance :after method.

update-setup [Generic Function]

Syntax update-setup setup-dialog-view view-to-setup

Arguments setup-dialog-view The view containing the setup dialog items.view-to-setup The view whose parameters are to be changed.

Decsription This method is called to setup the parameters within a setup dialogview the very moment a setup dialog is requested. You should imple-ment functionality so set the controls within this view to correspondto current settings of view-to-setup by implementing a methodfor the classes you provide. Having done so, pressing the “OK” but-ton without changing any controls should not change any propertiesof view-to-setup.

setup-update [Generic Function]

Syntax setup-updatesetup-dialog-view view-to-setup

Arguments setup-dialog-view The view containing the setup dialog items.view-to-setup The view whose parameters are to be changed.

Decsription This method is called to apply the changes in parameters made insetup-dialog-view. Implement a specialized method for the cat-egories you provide.

buffered-view [Class]

Decsription Implements a picture buffer for the objects drawn in any view de-rived from this class. Derive a view from this class whenever draw-ing takes some time. Implement the usual view-draw-contentsmethods specialized for your view. Derived from buffered-view,any unnecessary calls to view-draw-contents are inhibited andthe previously saved picture is drawn instead. MacOS functionalityfor printing a hardcopy and for saving the view’s contents into anarbitrary formatted picture file should be easy to implement.

invalidate-buffer [Generic Function]

Syntax invalidate-buffer buffered-view

7

Arguments buffered-view Any view derived from buffered-view.

Decsription Call this function after you have changed the view’s content. A com-plete redraw is forced, saving the output of view-draw-contentsinside a picture object.

coordinate-view [Class]

Decsription A class for providing a view whose pixels can be accessed by aneuclidean coordinate system. This view provides a setup dialogwhich allows for changing grid display and coordinate range. Seethe function definitions of set-scale/origin, set-range, andset-grid below. Drawing to a coordinate-view is done by utiliz-ing the function coordinate-view-projection, which takes asarguments a coordinate-view, a x-, and an y-coordinate. It returns ascreen point, which can be used in any quicktime drawing calls likeline, move, etc.. Class-specific valid initargs of a coordinate-vieware:

:show-grid-p A predicate determining, whether a grid is to be drawn(t) or not (nil).

:grid-distance The distance between neighboured grid lines mea-sured in coordinate system’s units.

:grid-color The color of the drawn grid, see the MCL documentationon colors.

set-scale/origin [Generic Function]

Syntax set-scale/origin coordinate-view scale x0 y0

Arguments coordinate-view Any coordinate viewscale A number specifying the desired scale coordinate

system’s units to pixels on the screenx0 A number specifying the x-coordinate of the

view’s origin.x0 A number specifying the y-coordinate of the

view’s origin.

Decsription Sets the display characteristics of a coordinate-view to display at agiven scale. The origin will be displayed at view’s center.

set-range [Generic Function]

Syntax set-range coordinate-view xmin xmax ymin ymaxalign

Arguments coordinate-view Any coordinate viewxmin A number specifying the minimal x coordinate to

be displayedxmin A number specifying the maximal x coordinate to

be displayedxmin A number specifying the minimal y coordinate to

be displayedxmin A number specifying the maximal y coordinate to

be displayedalign A keyword :center or :bottom specifying the

alignment

8

Decsription Sets the display characteristics of a coordinate-view to display anypoints within the specified bounding box. The keyword determines,whether the bounding-box is to be aligned at the center of the view’ssize (:center), or at the bottom (:bottom).

3.3 ExamplesTo illustrate the use of the extensions provided, a small example is provided. Assuming,we would like to draw a polygonal line given by some coordinates in a green-coloredview, which itself is centered in a window. First, we need to design an appropriate classto fulfill our demands. So, we simply derive a class from a colored-background-view,a simple-layout-view, a coordinate-view, and - to accelerate - the screen update frombuffered-view:

(defclass tst-coor-view (simple-layout-view colored-background-viewcoordinate-view buffered-view)

())

Now, we need to specify a method for drawing. This is a specialization of the standardview-draw-contents, which will get called by the event handling system automati-cally. For the ease of this example, we will alway draw the same triangle. Usually, youwould add a slot to the derived class containing your object’s vertices. The drawingroutine might look like the following:

(defmethod view-draw-contents ((this tst-coor-view)); make a abbreviation for calls to the coordinate; view’s coordinate conversion function(flet ((convert (x y)

(funcall (coordinate-view-projection this) x y))); just to see when a complete redraw is requested(format t "drawing...˜%")(move-to this (convert -1 1))(line-to this (convert 1 1))(line-to this (convert 1 -1))(line-to this (convert -1 1))))

Now, let’s create a view, which takes half the size of its view container and is located inits center:

(setf tst-view (make-instance ’tst-coor-view:bgcolor *green-color*:show-grid-p nil ; we do not want to have a grid:layout-position #’(lambda (p)

(make-point (round (point-h p) 4)(round (point-v p) 4)))

:layout-size #’(lambda (p)(subtract-points

p(make-point (round (point-h p) 2)

(round (point-v p) 2))))))

Then, we can set it to the desired display characteristics:

(set-scale/origin tst-view 50 0 0)

Finally, we create a layout window containing our view.

(setf tst-win (make-instance ’window-layout-view-mixin:view-size #@(300 300):view-subviews (list tst-view)))

Figure 1 shows what we will end up with. Resize the window to observe how the viewresponds to it.

9

Figure 1: The window created by the example. Note, how the view is depended from thewindow size.

4 Geometry Package geometry

The geometry package geometry (with nickname geo defined) encapsulates as wellgeneral geometrical data types (e.g. vectors, lines) and functions as more sophisticatedfunctions from the field of computational geometry. The implementation is based uponthe utility package described earlier in this documentation. So far, the following classesare provided:

� 2d-vector1

� 2d-point2

� straight-line

� line

� poly-line,...

The depiction below shows the inheritance relationship. *** Add picture here ***

deg->rad [Function]

Syntax deg->rad deg

Decsription Converts an angle given in degrees into radians.

rad->deg [Function]

Syntax rad->deg rad

Decsription Converts an angle given in radians into degrees.

2d-vector [Type]

1these are really complex numbers and 2d-vector is an alias for these2It’s not named ”point”, as this might interfere with MCL’s point used screen locations

10

Decsription We introduce an alias 2d-vector for the complex numbers, this alsomeans that we are unable to modify these in-place (via e.g. (setf(x v))). As this a type alias, you are able to use the reader macroswhen denoting a vector, e.g. you can write #c(1 3) instead of(geo:make-vector 1 3)

make-2d-vector [Function]

Syntax make-2d-vector x y

Decsription constructs a vector with x and y components of x and y

scalar-product [Generic Function]

Syntax scalar-product vector1 vector2

Decsription Computes the scalar product from the given vectors.

add [Generic Function]

Syntax add vector1 vector2

Decsription Adds the two given vectors.

subtract [Generic Function]

Syntax subtract vector1 vector2

Decsription Subtracts the two given vectors.

multiply [Generic Function]

Syntax multiply scalar vector

Decsription Multiplies the vector’s components with the given number.

collinear? [Generic Function]

Syntax collinear? vector1 vector2

Decsription Checks for collinearity, as computational threshold geo::*eps* isdefined.

vector-transform [Function]

Syntax vector-transform v z

Decsription z having the form ���������

, it scales v by ��� and rotates it by .

right-normal [Function]

Syntax right-normal vector

11

Decsription Computes the normal vector corresponding to vector obtained byturning vectorto the right.

left-normal [Function]

Syntax left-normal vector

Decsription Just like left-normal, only this time a left-turn is performed.

vector-length [Function]

Syntax vector-length vector

Decsription Computes the Euclidean vector length.

normalize-vector [Function]

Syntax normalize-vector vector

Decsription Normalizes the vector, so its Euclidean length equals 1.

enclosing-angle [Function]

Syntax enclosing-angle vector1 vector2

Decsription Computes the angle enclosed by the two vectors.

geo [Class]

Decsription This is just a virtual class to allow for generic functions acting onall geometric objects. The function for writing a load- and evaluableform of a geo-object is an example.

distance-vector [Generic Function (abstract)]

Syntax distance-vector g1 g2

Decsription gives the distance vector from g1 to g2 and (eventually) the pointon g1 on which this vector lies. This is currently implemented for(point,linelike)

distance [Generic Function]

Syntax distance g1 g2

Decsription gives the distance from g1 to g2. The default implementation callsdistance-vector

translate [Generic Function (abstract)]

Syntax (translate g v)

Decsription returns g translated by v. This is implemented for 2d-point.

12

simple-transform [Generic Function (abstract)]

Syntax (simple-transform g z)

Decsription Does the same thing to a geometric object what vector-transform doesto a vector. This is implemented for 2d-point.

scale [Generic Function]

Syntax (scale g a)

Decsription scales g by the factor a. The default implementation calls simple-transform.

rotate [Generic Function]

Syntax (rotate g phi)

Decsription rotates g by phi. The default implementation calls simple-transform.

intersect [Generic Function (abstract)]

Syntax (intersect g1 g2)

Decsription gives the intersection of g1 and g2

geo= [Generic Function]

Syntax geo= obj1 obj2

Decsription To be used for testing equality of geometric objects.

2d-point [Class]

Decsription Represents a single point. A reader macro is introduced to allow foreasy notation. Instead of(geo:make-2d-point 2 4) you can sim-ply write #l(2 4). As the character p is already defined, I choose l— remember it as location.

make-2d-point [Generic Function]

Syntax make-2d-point x y

Decsription This function is to be used to create an instance of a 2d-point.

x [Generic Function]

Syntax x point

Decsription This is the accessor to a point’s x-coordinate.

13

y [Generic Function]

Syntax y point

Decsription This is the accessor to a point’s y-coordinate.

point-location [Generic Function/ settable]

Syntax (pointlocation point)

Decsription This is the accessor for the location vector of a point.

make-point-from-complex [Function]

Syntax make-point-from-complex c

Decsription Creates a 2d-point based on the coordinates of c.

point->vector [Function]

Syntax point->vector 2d-point

Decsription Interprets the point as vector.

vector->point [Function]

Syntax vector->point 2d-vector

Decsription Interprets 2d-vector as point.

linelike [Class]

Decsription this is a base class for line, straight-line and half-line, which all havethe form � ��� ��� ( � being the line anchor and � being the line direction).

line-anchor [Generic Function/settable]

Syntax line-anchor l

Decsription The line anchor of a linelike object. This is a location vector.

line-direction [Generic Function/settable]

Syntax line-direction l

Decsription The direction vector of a linelike object. Don’t rely on the length ofthis vector being 1.

line [Class]

14

Decsription represents a line segment. This means that for a point � of the line,����������� is valid.

make-line [Generic Function]

Syntax make-line start-point varend-point

Decsription This function is to be used to create instances of lines.

line-start [Generic Function/ settable]

Syntax line-start line

Decsription This is the accessor of a line’s starting point.

line-end [Generic Function/ settable]

Syntax line-end line

Decsription This is the accessor of a line’s ending point.

distance-vector [Generic Function]

Syntax distance-vector object1 object2

Decsription Computes the vector specifying the minimum distance between twogiven objects.

distance [Generic Function]

Syntax distance object1 object2

Arguments object Any geometric object.

Decsription This functions computes the (minimal) Euclidean distance betweentwo given objects. This function might be implemented as (vector-length (distance-vector object1 object2))

Note Currently, only some methods have been implemented (e.g. point/point, point/ line, and point/ straight-line.) Read the code for de-tails.

Example ? (distance (make-2d-point 0 0) (make-2d-point 3 4))5.0

? (distance (make-2d-point 0 0)(make-line (make-2d-point 4 -8)

(make-2d-point 4 8)))4.0

intersect [Generic Function]

Syntax intersect object1 object2

Decsription Tests, if the two objects intersect, returning the intersection.

15

Note Currently, only some methods have been implemented (e.g. point/point, point/ line, and point/ straight-line. Read the code for details.

Example ? (intersect (make-line (make-2d-point 0 0) (make-2d-point 2 2))

(make-2d-point 1 1))<2d-point 1/1>

bisector [Generic Function]

Syntax bisector object1 object2

Decsription Computes the bisector of two given geometric objects, that is the setof points being equally far away from object1 as from object2.

Note Currently, only some methods have been implemented. Hopefully,a good Voronoi implementation will available soon. Again, readthe code for details.

Still to do: a lot!

4.1 Graphical display and EPS export

For the use with the geometry package some graphical utilities are provided in the filevisualize.lisp implementing a package visualize with nickname vis. Utilizingthe view-extensions (see section 3 on page 5), a view class is provided to automaticallydisplay geometric objects. An update facility allows for file I/O. Displayed objects maybe saved to a file or read from a file. Furthermore, a postscript export (EPS files) is imple-mented. To use these I/O features, activate the setup dialog by command-clicking into itand selecting the “IN-/Export” category. Following functions and classes are providedby visualize.lisp:

geometry-view [Class]

Decsription This is the class for displaying arbitrary geometric objects. It isderived from buffered-view, coordinate-view, and simple-layout-view as described in section 3. It also provides a setup dia-log.

set-geometry-view-objects [Generic Function]

Syntax set-geometry-view-objects geometry-view objects

Arguments geometry-view Any instance of geometry-viewobjects A list of geometric objects

Decsription Use this function to set the objects of a particular geometry view. Aredraw will be forced afterwards automatically.

get-geometry-view-objects [Generic Function]

Syntax get-geometry-view-objects geometry-view

Arguments geometry-view Any instance of geometry-view

Decsription Use this function to get the list of objects stored in a particular geom-etry view.

16

set-color [Generic Function]

Syntax set-color geo-object color

Arguments geo-object Any geometric object

color A color, see the MCL documentation for detailsDecsription To attribute geometric objects by colors for screen display, you can

utilize this functions. Regular geometric classes are converted auto-matically to an attributed one, e.g. 2d-point into colored-point.

Note So far, this functionality is only provided for lines and 2d-points!

bounding-box [Generic Function]

Syntax bounding-box object

Arguments object Any geometric object or list of (list of. . . ) geomet-ric objects

Decsription Computes the bounding box of the specified objects, return asmultiple-values minimal x-, minimal y-, maximal x-, and maximaly-coordinate.

17

5 Robot Communication Package robbi

The file communicator.lisp provides the package robbi, which is responsible for allinteraction with the robot. This package only uses the packages ccl, common-lisp andsome networking rsp. hardware interface facilities from MCL’s library. Therefore, it isnecessary to have Apple’s “Open Transport” (which comes along with System 7.5 andlater) installed. Pre-OS7.5 systems should be extended to provide the Open Transportcommunication toolbox, details on this and how to make a workaround can be foundin the implementation notes section. Access to the robot and its sensors is granted in aconcurrent way. Using the methods and data structures provided is quite easy. A userinterface exists to allow for quick and easy direct control. For details concerning therobot’s interface please read the documentation of the control hardware.

This documentation is divided into three sections, the first giving an overview ofthe implementation as far as necessary. The second part covers the documentation offunctions and data structures available, whilst the third part provides more detailedimplementation-specific information only important when you consider carrying out anychanges in the code.

5.1 Overview and Quick Start

The communication with the robot is based on a command-line interface, which is de-scribed in detail elsewhere (well, hopefully). The data is communicated by a simple two-way-stream. All relevant data is stored inside an object of the class communicator, theone and only communicator instance needed is stored in the variable *communicator*.

Sending commands to the robot and receiving answers is done by creating a com-mand object (as described in the second section of this documentation) and enqueueingit to the communicator’s command queue. The command object has a slot describing thecommand’s current state. As soon as the command is processed by the robot, the resultis available in the command’s result slot.

In order to provide adequate access to sensors, a class sensor-server is providedwhich handles sending commands and receiving results, both, autonomously and con-currently. Access to sensor servers is given by requesting the latest sensor reading (seebelow for details), or by assigning to a specific sensor-server by means of callback func-tionality. Hence, it is possible to receive data, e.g. the robot’s position estimation, in aspecified interval. As the communication bandwidth is limited by the connection to therobot, sensor servers take also care not to stop up the communication link, e.g. you canonly receive 2 laser scans per second.

Together with their specialized data structures for the specific sensor data, the fol-lowing sensor servers exist: robot-status-server, robot-pose-server, robot-speed-server, and robot-scan-server.

In order to get started talking to the robot, load the file communicator.lisp andevaluate robbi:init. A window containing a log and a menu will appear. Use thisuser interface to connect to the robot. Then you can start sending commands using send-command and make-command. Reading sensors is done best by taking advantage of thesensor servers and their access functions get-latest-sensor-reading or assign-for-sensor.

5.2 User Interface

The user interface provided by this package is depicted in figure 2. It can be used toconnect to a specific robot and control this robot on the level of robot commands3. As

3See the documentation of the robot hardware for details.

18

command history

command sent

answer received

unecpected transmission

number of the line sent/received

incomming (<) /outgoing(>) messages

commands to be processed

sending commands manualy

Figure 2: The user interface provided by the communicator package and its controls.

most of the user interface does not need further information, only a few points will bementioned here.

The two counters for commands are used for checking, how many commands are be-ing handled. Passive commands are still to be send to the robot. The transmission willtake place as soon as possible. Active commands have been already been sent out, therobot’s answer is awaited. Note, that an active command like “LASSCN” will preventany following “LASSCN” commands from transmission, as only one command of thesame type is allowed to be active. The cancel-button can be used to remove all activecommands. This is useful for unblocking further transmissions of the same command.Note, that commands that are active for more than 10 seconds, will be aborted automati-cally.

The communication log inside the communicator-window is provided supervise thecommunication with the robot and for debugging purposes. Different colors are used toeasily distinguish between different states of transmissions. When turning on the loggingfacility (by choosing “start log” from the menu), each line written to the log file will alsobe marked with a special character. The following colors and chars are used for display:

black � no char � no special state

blue � command sent to the robot

green � answer to a command that was sent to the robot

red � an unexpected transmission from the robot.

As the log displayed truncates the lines, creating the log file is especially helpful, whendebugging the interpretation of long commands/answers like scanner readings.

19

5.3 Functions, Data Structures, and Variables

init [Function]

Syntax init

Decsription Call this function to initialize the communicator at startup.

exit [Function]

Syntax exit

Decsription Call this function to shut down the communicator functionality. Itis important to call this function as cleanup, as drivers are allocatedwhen initializing the communicator.

Note Not calling this function appropriately may prevent any further con-nection. Should connecting to the serial port fail, simply open thisport with z-term (or another terminal application) and quit z-term.Connections can now be opened again.

command [Structure]

Decsription The structure command is used whenever commands are send to therobot. It is a regular structure (with all their accessors) consisting ofthe slots name,parameter, result, and state. With exception ofthe last one, all slots are supposed to hold string values. The state-slotholds the current state and is updated by the communicator. State isone of the following:

:undone initial value

:cancelled aborted by the user or a call to communicator-flush-commands

:aborted aborted due to communication problems or reconfig-uring the connection (or a call to communicator-abort-active-commands).

:active The command has been sent to the robot, an answer hasnot been received yet.

:done The command was executed successfully, the result is avail-able in the slot result.

:failed The robot failed to execute the command or an error oc-curred during the command processing. Detailed informationis stored in the slot result.

Note It is important to use the command’s name slot only for the 6-letter-name, not for any parameters as the name is expected to be returnedby the robot when referring to this command.

20

Example ? (setf cmd (make-command :name "mottrn":parameter "+45"))

#S(COMMAND :NAME "mottrn" :PARAMETER "+45":STATE :UNDONE :RESULT NIL)

? (send-command cmd)<I don’t know...>? cmd#S(COMMAND :NAME "mottrn" :PARAMETER "+45"

:STATE :ACTIVE :RESULT NIL)? cmd#S(COMMAND :NAME "mottrn" :PARAMETER "+45"

:STATE :ACTIVE :RESULT NIL)? cmd#S(COMMAND :NAME "mottrn" :PARAMETER "+45"

:STATE :DONE :RESULT "+MOTTRN 2D")

send-command [Function]

Syntax send-command command

Decsription Enqueues command in the communicator’s command queue. If nocommunicator is present (*communicator* is nil), it returns nil. Seeabove for an example.

get-latest-sensor-reading [Generic Function]

Syntax get-latest-sensor-reading sensor-server &optionalmax-age

Decsription Receives the latest sensor reading from the given sensor server, if noreading is available or the latest reading is older than an age specifiedin milliseconds, a new reading is requested from the robot.

assign-for-sensor [Generic Function]

Syntax assign-for-sensor sensor-server function interval-time

Arguments sensor-server Any sensor-server available.function A function of one argument processing the sensor

value.Decsription From calling assign-for-sensor on, the specified function is

called concurrently by the sensor-server within the specified periodof time given in milliseconds. The return value of this function is aobject needed to discard the sensor, see discard-sensor below.

Note Right now, callbacks are handled as function calls. Therefore, theyshould not be time-consuming, as they run in the sensor-server’sprocess. If more time is needed, wrap a process-run-functionaround your code.

discard-sensor [Generic Function]

Syntax discard-sensor sensor-server callback

Decsription To stop further function calls of the function specified in assign-for-sensor, call this function on the corresponding sensor serverand the callback object obtained by the call to assign-for-sensor.

21

-X +X

+Y

+α -α

Figure 3: The robot’s coordinate system within this framework. The unit length is mil-limeter, angles are specified in radians. Note, that this coordinate system differs from therobot hardware, as the hardware implementation is rather confusing.

scan [Class]

Decsription The class scan is used to hold any information regarding a specificlaser scanner reading. The class consists of slots holding informationabout the depth vector, the time and estimated position of the sensorreading. Access to class is granted by the following accessors:

accessor scan-pose The corresponding slot is initialized with theestimated pose (see the documentation of poses below) fromwhich the scan has been taken.

reader get-scan-time This gives access to the time, the scan objecthas been instantiated (see MCL’s get-internal-real-timefor properties of this time slot.

reader get-scan-vector This is a function returning a vector con-taining all laser scanner measurements (typically 361) in mil-limeters.

reader get-scan-points This function returns a vector of geomet-ric points (see the documentation of the geometry package).These are the reflection points detected by the laser scanner re-specting the estimated pose. Reading this slot for the first timeforces the vector to be calculated.

reader get-local-scan-points Like get-scan-points, butwithout respecting the estimated pose. Points are located in theupper halfplane of a righthanded coordinate system.

pose [Structure]

Decsription The type used for representing a robot’s pose is a regular struc-ture with the two slots position and heading. Whereas pose-position returns a geometric point, pose-heading is a numberin ��������� � , direction � pointing towards a growing Y coordinate withgrowing direction values for turning counter-clockwise. See figure 3on the robot’s coordinate system.

22

speed [Structure]

Decsription Speed is represented as regular structure with the slots left-wheeland right-wheel, both containing the measured speed in mm/sec.

status [Structure]

Decsription Status structures are used to represent the robot’s status, right nowonly battery status is available. The battery voltage is stored in theslot named battery-voltage.

5.4 Implementation Notes

5.5 Avoiding “Open Transport”

The Open Transport functionality is used for TCP/IP network connections. If you do nothave Open Transport installed (e.g. on an old 68K-Mac), you have two possibilities inavoiding Open Transport. The easiest is not to use any TCP/IP features at all, then youmay remove the require-statement in the beginning of the communicator file and com-ment out the functions (and calls to them) with “tcp/ip” as part of their name. However,if you need TCP/IP network access, then you have to use mactcp, which can be requiredfrom the library with (require ’mactcp). To get it to work, you need to change somemethods a bit. Mainly, you need to rename any Open Transport types to their corre-sponding mactcp types. Be aware, that when using mactcp from within MCL there is notolerance to errors and hence it is a good way to crash MCL.

23

laser scanner reading

other sensor readings

sensor update controls

direct motion controls

Figure 4: The control package’s user interface.

6 control Package for direct Robot Control

The file control.lisp contains package definition for a control package, which pro-vides easy to use access to the robot. First of all, a graphical user interface displays therobot’s sensor readings and allows for direct control like commanding a remote con-trolled toy car.

6.1 Quick Start

After loading the file, initialization is achieved by evaluating (control:init). Closingthe window or calling (control:exit) deactivates the user interface. However, this does notaffect other functionality provided.

6.2 User Interface

The user interface provided by this package is shown in figure 4. Most of the controls areselfexplaining, just like the information displayed. This leaves not much to explain.

The sensor update mode displayed in the pull-down-menu can be set to one of thefollowing:

none The sensor readings will only be updated by pressing the update button.

24

live In live mode, sensor readings are requested continuously (consuming nearly allbandwidth available and slowing down older systems)

automatic Only switches to live update, when the robot moves. After stopping, no up-dates will be read unless the update button is pressed.

The radio-buttons for switching form steady to atomic movements are used to toggle be-tween using “MOTMOV”/”MOTTRN” commands for instructing the robot4 and “MOT-SET” commands when pressing any of the movement buttons. So, pressing turn in steadymode will start the robot to turn, while in atomic movement mode he will turn for thespecified angle. Note, that the external simulator cannot deal with steady motion, as hedoes not support “MOTSET” commands. For better manoeuvrability, pressing keys canalso be used to command the robot (when the control window is active). The followingkeys are defined:

Space stops the robot

Arrow left turns to the left

Arrow right turns to the right

Arrow up moves the robot forward

Arrow down moves the robot backward

6.3 Functions, Data Structures, and Variables

halt [Function]

Syntax halt

Decsription Calling this function will cause the robot to stop any movement in-stantly.

move-robot [Function]

Syntax move distance async?

Arguments distance Distance to move in mm.async? Truth value determining if the function may re-

turn before the movement has been finished.Decsription Use this function to move the robot forward/backward. Depending

on the value of async?, the function returns:

nil The function will return t, when the movement has been carriedout.

t The function will return instantly with a regular command ob-ject like described in the documentation of the package robbi.Reading the status slot provides information when the move-ment is finished.

Note If the robot gets stuck, he does not report it; this might prevent thisfunction from returning at all when using the synchronous move-ment.

turn-robot [Function]

4see the robot hardware’s documentation for details

25

Syntax turn angle

Arguments angle The angle to turn in degrees, positive values forturning left.

Decsription Use this function to turn the robot on the spot. As turning is prettyfast, there is in terms of move-robot only synchronous turning pos-sible.

set-speed [Function]

Syntax set-speed left right

Arguments left Speed of the left wheel in mm/secright Speed of the right wheel in mm/sec

Decsription When direct control of motion is desired, use this function. As therobot is not going to stop on its own (hitting walls does not count as“on its own” ;-)), be sure to guarantee that the robot will be stopped.A calling from within an unwind-protect form might be a goodidea.

26

outline of the spcae occupied by the robot

cells blocked by obstacles

marked cells showing a computed path

Figure 5: The local map window shown of the package motion-behaviours. Black cellsdenote obstacles. The red outline shows the size of the robot, the green ones are markedcells. These marked cells show a computed path which is going to follow. See the note inthe detail section on how to change path display

7 Robot Motion Behaviour Packagemotion-behaviours

The file motion-behaviours.lispdefines a package dealing with motion behaviours.Functionality is provided for moving the robot to a specific goal avoiding obstacles andfor exploration by following the right wall. Furthermore, the internal discretization of therobot’s local surrounding is made visible and accessible for designing other behaviours.

7.1 Functions, Data Structures, and Variables

To make the use of this package more convenient, the nicknames behave and motionhave been defined. So instead of writing (motion-behaviours:init) on can simplywrite (behave:init) or (motion:init).

init [Function]

Syntax init

Decsription Call this function to initialize the motion behaviours and the dis-cretization. The current discretization will be shown in a window.

exit [Function]

Syntax exit

Decsription Call this function to deinitialize the motion behaviour package, clos-ing the discretization window.

27

move-to-goal-directly [Function]

Syntax move-to-goal-directly goal &optional turn

Arguments goal A geometric point specifying the goal relative tothe robot’s current position. See also figure 3showing the robot’s coordinate system on page 22.

turn An angle, a number within ��� � � � �specifying any

additional turning of the robot.

Decsription Calling this function will move the robot to the specified goal relativeto it’s current pose. The robot’s heading in the moment of the call willbe restored after the movement. By specifying a value for turn therobot will turn the passed angle instead of returning it’s heading.

Example (behave:move-to-goal-directly(geo:make-2d-point 1000 1000))

will cause the following:

-X +X

+Y

1. 2.

3.

Whereas

(behave:move-to-goal-directly(geo:make-2d-point 1000 1000) 0)

will cause:

-X +X

+Y

1.2.

move-to-goal [Function]

Syntax move-to-goal goal

Arguments goal Ageometric point specifying the goal like in move-to-goal-directly

28

Decsription This realizes a movement of the robot to the specified goal avoidingobstacles. A scan is taken before planning any steps. Heuristic searchis utilized to search for a path to the goal. Any path found is sim-plified to reduce the number of sub-goals the robot has to reach on itsway to the goal. As the environment is only partially visible, the func-tion executes only a single step of the robot before sensing again, re-planning the path. The planned path is highlighted in the discretizedenvironment like shown in figure 5.

follow-right-wall [Function]

Syntax follow-right-wall

Decsription A call to this function will cause the robot to execute a single step inhis behaviour for following a wall to the right of him.

sense [Function]

Syntax sense

Decsription To request updates of the discretized local environment this functionshould be called. It requests a new scan and updates the local map.

coordinate->cell [Function]

Syntax coordinate->cell point

Arguments point A geometric point

Decsription As the discrete local map is addressed by cells, use this function whenyou need direct access to the discrete local map. It takes a coordinatein the robot’s coordinate system relative to the robot’s pose, returninga cell as consed pair (x . y).

cell->coordinate [Function]

Syntax cell->coordinate cell

Arguments cell A cell (x . y)

Decsription The counterpart to coordinate->cell.

free-robot-cellp [Function]

Syntax free-robot-cellp cell

Arguments cell A cell (x . y)

Decsription A predicate for determining if the robot can be positioned with itscenter on the specified cell without colliding with any obstacles cur-rently visible. This function takes the robot’s size into account as therobot occupies a couple of cells.

Note Cells out of the local map’s range are treated like occupied cells.

29

highlight-cells [Function]

Syntax highlight-cells cells

Arguments cells A list of cells

Decsription The passed cells are highlighted in the local map window like shownin figure 5.

Note Cells out of the local map’s range are treated like occupied cells.

7.2 Implementation Details

The paths displayed by calls to motion behaviours like follow-right-wall or move-to-goal can be displayed in two different ways. If the local variable *show-path-cellsp* is true (any non-nil value), the paths are displayed by highlighting all cellstouched by the robot’s center (line of pixels). If the variable is set to nil, only edges of apath (including start- and end-point) are highlighted.

30

simulated robot�(red)

estimated pose�(blue)

Figure 6: The window displayed by the simulator.

8 Package simulator and the internal simulator

The file simulator.lisp contains the internal robot simulator which defines its ownpackage simulator with nickname sim. The simulator will be activated automaticallywhenever the robot communicator connection is established to “local”. As the simulatoris a separated part within this framework, no detailed understanding of it is required.The functionality provided by it is described in the next section. For those wanting toextend the simulator, a short introduction to its internals are given in the last section ofthis chapter.

8.1 Using the simulator

The simulator’s interface behaves just like a real robot. This includes noisy sensors andreal-time motion behaviour like accelerating. So, nothing special needs to be taken intoaccount when using it instead of a real robot. When a “local” connection is established, asimulator is created. It displays a window like in figure 6 showing the robot in its world.Besides the real robot (marked in red), a blue robot is displayed in the pose of the robot’sposition estimation. Besides the robot commands available on a real robot, some addi-tional functionality is provided. Both, regular robot commands and special simulatorones are summarized in table 1. To change the simulator’s default world, please read thedocumentation of internal the internal functions below. As the simulator window is de-rived from a geometrical view (see 3 starting on page 5), command-clicking in its interiorregion generates a setup dialog, allowing to change display style.

31

command parameter description

piocon port Establishes a connection to the pioneer connected on portport (0 for disconnecting). Dummy implementation in thesimulator

lascon port Establishes a connection to a laser scanner on port port (0 fordisconnecting).

lasscn Requests a scan from the laser scanner. See the simulator fea-ture simcht

mottrn angle Turns the robot on the spot by the given angle (positive valuesfor counter-clockwise rotation)

motmov distance Moves the robot by distance forward. If distance is negative,the robot moves backward.

motset left right Sets the speed of the motors directly. The value left in mm/secis assigned to the left wheel, right to the right wheel.

motget Reads the speed of the wheels in mm/secposset x y h Sets the internal position estimation to the passed pose.

Whereas x and y are 16-bit values, h is (currently) a value be-tween 0 and 1023.

posget Reads the internal position estimation.sysrst Resets the robot.

simulator-specific commands

simset x y h Allows to set the robot to a specifies position, parameter likeposset.

simget Read the position of the robot (like posget)simsyn Synchronizes the robot’s pose estimation with the real robot’s

pose, by setting the position estimation once.simcht num Sets a cheat mode in computing the laser scans. By specifying

a number different from 1 (the default), only every numth rayis traced, interpolating the others. It is only meant for increas-ing computation speed on slow systems.

Table 1: Summary of the simulator commands. The format does not differ from the realrobot, so any parameter is assumed to be a 2s-complement hexadecimal 16-bit-number.Decimal numbers need to be prefixed by either “+” or “-”, parameters are separated by aspace.

32

8.2 Implementation details

The simulator is a closed part within this framework. Hence, it does not utilize muchfunctionality provided elsewhere within. This part of the documentation serves as pro-viding a short overview to the implementation, details are given by the comments in thesource code.

8.2.1 (De-)Initialization

A simulator object is created by a call to (sim:init), which returns a string-stream.This string-stream (referred to as the user-stream) is to be used for communicating withthe simulator. To deinitialize the simulator (and to close its window), call (sim:exituser-stream) with the user-stream obtained by the init call. Note, that it is possibleto use multiple simulators simultaneously. Closing a simulator window manually bypressing command-w when it is active will also cause the exit function to evaluate andclose the user stream.

8.2.2 Communication

The basic functionality for communicating is provided by special string-stream string-stream/cc defined inside simulator.lisp. This stream consists of two independentring buffers of fixed size. The “/cc” in the class name denotes that this is a concurrentlyaccessible object. A lock (see the MCL documentation) is used for serializing the access.To make the robot communicator aware of the simulator (which is load afterwards), eval-uating the file overrides the function definition stored in the variables robbi::*make-simulator-stream*and robbi::*discard-simulator-stream*with the init andexit functions. Creating a simulator object attached to a TCP/IP-stream should be allthere is to do to create a remote TCP/IP-simulator.

8.2.3 Simulation

The simulation is done by a simulator process (defined in simulator-process, whichreads commands from the communication stream and dispatched individual handlerprocesses. Processes moving the robot are stored in a specific slot motion-processof the simulator object, so it can be killed easily when the robot is halted for example.Note, that the visual update is not done automatically. Instead, any process changingthe (believed) robot’s pose or the simulator world, needs to request a redraw explicitly.request-redraw is specially designed to update the display around the robot’s currentpose not causing unnecessary screen flickering.

The current scan is cached inside the simulator object in case of multiple readingsfrom the same pose. Currently, discarding the cached scan vector has to be done man-ually by setting scan-vector-valid? in the simulator object to nil. For speed andcode reusability reasons, the internal world representation does not correspond to thisframework’s geometry package. Instead, the world is represented, as list of polygonallines. Each line is represented as list of vertices. Complex numbers are used as vertices.The initial simulator world is defined in the variable *world1*. To set a simulator’sworld, use the function set-simulator-world.

The real-time and noisy behaviour of the simulated robot is implemented directlyin the command implementation of the motion commands. Roughly, it is achieved byupdating a believed robot-pose and the real robot-pose both, independently and noisily.

8.2.4 Command Implementation

For the ease of defining robot commands, a handy macro defcommand has been de-signed. It creates the function for execution and enters the command in the internal listof commands. Furthermore, some bindings are established. See the comments by themacro definition for details. Reevaluation of commands is possible even at runtime. An-other macro, timed-until-loop, is designed for implementing real-time behaviour.

33

Just like the real robot, the simulator updates its internal variables every 100msec. Thiscan easily achieved by utilizing the timed-until-loop. For example, a process fordischarging the battery may be designed like the following:

(timed-until-loop 6 ; every 10 ticks, that’s every 100msec(setf battery-voltage (* 0.999 battery-voltage))(> 10 battery-voltage)) ; stop, if the voltage drops below 10V

34

Function Referenceccl

buffered-view, 7colored-background-view, 6coordinate-view, 8invalidate-buffer, 7layout-view, 6set-range, 8set-scale/origin, 8setup-update, 7simple-layout-view, 6update-setup, 7view-with-setup, 6window-layout-view-mixin, 6

controlhalt, 25move-robot, 25set-speed, 26turn-robot, 25

geometry2d-point, 132d-vector, 10add, 11bisector, 16collinear?, 11deg->rad, 10distance, 12, 15distance-vector, 12, 15enclosing-angle, 12geo, 12geo=, 13intersect, 13, 15left-normal, 12line, 14line-anchor, 14line-direction, 14line-end, 15line-start, 15linelike, 14make-2d-point, 13make-2d-vector, 11make-line, 15make-point-from-complex, 14multiply, 11normalize-vector, 12point->vector, 14point-location, 14rad->deg, 10right-normal, 11rotate, 13scalar-product, 11scale, 13simple-transform, 13subtract, 11

translate, 12vector->point, 14vector-length, 12vector-transform, 11x, 13y, 13

motion-behaviourscell->coordinate, 29coordinate->cell, 29exit, 27follow-right-wall, 29free-robot-cellp, 29highlight-cells, 29init, 27move-to-goal, 28move-to-goal-directly, 28sense, 29

robbiassign-for-sensor, 21command, 20discard-sensor, 21exit, 20get-latest-sensor-reading, 21init, 20pose, 22scan, 22send-command, 21speed, 22status, 23

utilscondlet, 3do-tuples, 3do-tuples/c, 3for, 3with-gensyms, 3

visualizebounding-box, 17geometry-view, 16get-geometry-view-objects, 16set-color, 16set-geometry-view-objects, 16

35