Previous Page TOC Index Next Page

BeeSoft User's Guide and Reference

2.7 BeeSoft™ Utilities and Example Applications


In the following sections, you’ll learn how to run the special utilities (the BeeSoft Commander™ and the BeeSoft Simulator™) and the example applications (the BeeSoft Mapper™ and the BeeSoft Planner™, along with sonarint and laserint) supplied with BeeSoft™: To run any of these programs, you need a working knowledge of the X-Window System, and you need to have the X-Window System up and running on your workstation.

Remember: RWI, Inc., does not recommend, and will not support, running an X-Windows server on your robot’s internal computers.

Before running the Commander, Mapper or Planner programs, you need to establish an IP connection to your robot. (You don’t need to do this to run the Simulator, though.) Please note that the exact procedure for doing this is determined by the specific terminal program you are running.

1.Free up the serial console and serial port. To do this, log out from the serial console if you are logged on. Then, quit any terminal emulator program or any program you have attached to the serial port, for example, minicom.(Use <CTRL-A> <CTRL-Q> for minicom.)

2. Establish a PPP connection. Copy the script /etc/ppp/pppconnect from the robot onto your workstation. If you don’t know how to do this, ask the system administrator at your site. Run the script on your workstation. NOTE: Do NOT run this script on your robot!

This script will run on Linux workstations, and will also most likely run on any UNIX™ workstation. If your environment differs, or the script will not run, you’ll need to find out how to establish a PPP connection in your environment before proceeding. Ask your system administrator. This is the general procedure, though: Login as user ppp. The password you’ll need is aa6bb7cc.

Upon successful running of the script, you have established an IP connection to the robot.

3. Establish three windows:

Window#1: In this window, log in as demo, password aa1bb2cc. Then, telnet to <your-computer-name> (whatever name has been assigned to the computer on board your robot). Once telnetted to the robot, you’ll run bWatch (~bee/bin/bWatch), a program that allows you to monitor server activity, in this window. bWatch displays, every few seconds, a list of all processes running, and does so continually until you terminate it. To see the display of running processed at any given time displayed just once, use the program bCheck (~bee/bin/bCheck) instead.
Window#2: In this window, log in as demo, password aa1bb2cc. Then,telnet to <your-computer-name> (whatever name has been assigned to the computer on board your robot). Once telnetted to the robot, you’ll type commands in this window.
Window #3: In the third window, you’ll run the BeeSoft Commander, Mapper or Planner program.

2.7.1 The BeeSoft Commander


If you are using a UNIX™ system that does NOT have BeeSoft pre-installed, see the Reference sections in the back of this Manual that tell you, 1) how to set up your environment to run BeeSoft; and 2) how to install BeeSoft.

RWI’s BeeSoft Commander graphical user interface gives you complete control over a broad, flexible repertoire of robotic behaviors. The BeeSoft Commanderis a fully-supported utility package, supplied as part of BeeSoft™ to assist you in your robotic research and development activities.

To run the BeeSoft Commander, you need a working knowledge of the X-Window System, and you need to have the X-Window System up and running on your workstation. RWI, Inc., does not recommend, and will not support, running X-Windows on your robot’s internal computers.

You can run the BeeSoft Commander from either :

The local console, that is the laptop or notebook computer mounted on the top of your robot, IF you have a B21 robot with the console computer installed;
               OR
On your own X-Windows workstation, connected to your robot via an Ethernet radio link, or radio modem and PPP. The Ethernet connection is highly recommended.

To fire up the BeeSoft Commander, start up each of these programs:

In the window in which you are logged into the ROBOT (window#2):

 tcxServer
 baseServer
 colliServer 

In the window in which you are logged into your WORKSTATION (window#3):

 commander -TCXHOST=<your-computer-name>

You’ll see the BeeSoft Commander interface display window.

NOTE: If, at any time, the Commander does not respond properly, do the following steps:

1. Type killall tcxServer to kill all running servers.
2. Reset the robot’s base (On the B14, the system reset is the second toggle from the left on the top of the robot; on the B21, the system reset is located on the base control panel (See Figure 2-2.).
3. Cycle the MSPs. On the B14, flip the leftmost toggle off briefly; then flip it back on. On the B21, flip the left middle toggle on the B21 Switch Panel, behind the robot’s right reardoor. (See Figures 1-3D and 1-3E.)
4. Restart all servers
5. Restart the BeeSoft Commander™

Undisplayed Graphic

Figure 2-4 - The BeeSoft Commander™ Interface Display

The BeeSoft Commander™ Interface Display

Let’s take a quick tour of the display. Just a reminder: To quit at any time, just click on the Quit Program box under the large circle.

On the very left edge is a vertical bar indicating the robot’s current battery voltage. Next, moving rightwards, you’ll see the Navigation Window. Here, you can set the robot’s velocity and acceleration and observe its location and motions as it moves about its environment. The large circle delimits the range of possible target points (this is usually three meters, but you can change it.). The symbol at the circle’s center is your robot; radiating outwards are blue lines that represent the latest sonar readings, and yellow beams representing input from the optional laser rangefinder. This initial target point mode is the default; the other mode is joystick emulation.

Along the left edge of the Navigation Window are vertical bars tell you the robot’s actual translation velocity and rotation velocity. These indicators show the actual values reported by the robot. Along the right edge pf the Navigation Window are similar bars, showing the translation and rotation velocities you’ve specified.

Just to the upper left of the large circle, the two stacks of small buttons correspond to the four colored buttons on the top of your robot. A button in the left stack is shaded when the corresponding button on the robot is currently lit. A button in the right stack is shaded when the corresponding button on the robot is currently pushed. An asterisk in any of the buttons means the corresponding button on the robot is blinking. Toggle these buttons with your left mouse button. (NOTE: This button feature is not currently supported. Future releases of the BeeSoft Commander will support this feature.)

At the upper middle part of the display, you’ll see the Pan/Tilt Window. Horizontal and vertical bars at the lower and left edges indicate the pan/tilt head’s current position. When you first start up the BeeSoft Commander, this window shows a test pattern; during robot operation — if your robot carries one or two cameras — you’ll see here a coarse greyscale image of what your robot is seeing. Underneath the display area is a 3 position toggle for pan/tilt head motion speed. The default is normal speed; other values are high and low.

At the upper right, the Map Window displays a bird’s eye view of your robot’s path as it explores its surroundings. Later on, you’ll learn about the colliServer parameter file called colli_modes.ini, in which you can define the scale represented by the map, as well as several other variables of interest.

Arrayed along the lower part of the display are a collection of control buttons and indicators that tell you which robot hardware and software subsystems are active.

Beneath the Pan/Tilt Window, you’ll see a button labeled colliServer. This button lets you toggle among three modes of collision-avoidance motion offered by colliServer: default, fast and random. In fast mode, the robot has a higher maximum speed, and is slightly moreaggressive in its movements. See the Section on the colliServer, in Chapter 4, Making Your Robot Move for more details on colliServer modes and how to use them.

Teleoperating Your Robot

W A R N I N G...
Before running the experiments described in this section, make sure you have prepared a safe, clear area in which your robot can move about. The area must be indoors, flat, dry, level, smooth, free of potential hazards such as cables across the floor and bulky floor mats, well away from small children, casual passerby and people who may not be paying attention. Your test area must be away from any stairwell, ramp or other hazard where your robot might tip over or fall. Be sure you know where your robot’s kill switch is.
Before starting experiments in which your robot actually moves around, you might want to set up an enclosed, protected area for it to navigate within. Surround a large, clear space in your lab with cardboard cartons or the like. Make sure they are at least as tall as the height of the robot’s sonars.
Remember: Keep yourself, your colleagues and your robot safe!

Now, take a few minutes to experiment with using the BeeSoft Commander to teleoperate your robot. There are two modes of operation while in the navigation window: target point mode and joystick emulation mode. These determine how mouse clicks are interpreted while in the navigation window. To switch modes, point to the mode button (the one that says mode: target point) right underneath the navigation window, and click the left mouse button.

Click on the button labeled mode: target point in the Navigation Window to try joystick emulation. You’ll find it takes a bit of practice to control the robot smoothly and confidently!

Safety Note:
You can stop robot motion at any time simply by clicking on the right mouse button anywhere in the BeeSoft Commander interface display, OR by clicking the left mouse button on the button labeled stop robot.

Here are some other teleoperation experiments you can try in the BeeSoft Commander:

1.Toggle the bar beneath the Pan/Tilt Window to change pan/tilt speed. Click on the vertical bar along the left edge to swivel the pan/tilt head up or down; Similarly, click on the horizontal bar at the lower edge to swivel the head from side to side.
2. The vision/camera setup procedure is beyond the scope of this section. But, if you already have the stereo (twin) cameras operating, point your mouse to a location within the camera image area and click the left mouse button to move the pan/tilt head so that it will point the cameras at that location. Use the control buttons labeled left camera and right camera to toggle between view from each of the twin (stereo) cameras.

If you are using a UNIX™ system that does NOT have BeeSoft pre-installed, see the Reference sections in the back of this Manual that tell you, 1) how to set up your environment to run BeeSoft; and 2) how to install BeeSoft.

2.7.2 The BeeSoft Simulator


The BeeSoft Simulator utility lets you simulate robot motion and sensing without using an actual robot. The BeeSoft Simulatoris a fully-supported utility package, supplied as part of BeeSoft™ to assist you in your robotic research and development activities.

To run the BeeSoft Simulator, you need a working knowledge of the X-Window System, and you need to have the X-Window System up and running on your workstation. RWI, Inc.,does not recommend, and will not support, running X-Windows on your robot’s internal computers.

Great care has been taken to make the BeeSoft Simulator as realistic and accurate as possible, it is still no substitute for actually working with a real, physical robot. The BeeSoft Simulator offers an easy-to-use graphical user interface and is a valuable learning and research tool. It’s especially nice for those occasions when you have some programming magic you just have to try, but somebody else in your lab is hogging the robot!

The BeeSoft Simulator is a multi-window system, based on the use of multiple xterm windows. It is designed for use with either a BeeSoft-supplied demonstration program such as wander or with an example program of your own devising. The buttons on the graphical interface display are designed for the construction of simulated environments, through which your demonstration program, or wander, can navigate the simulated robot.

Starting the BeeSoft Simulator

simulator, the command you’ll type to start up the BeeSoft Simulator gives you the choice of using optional command line arguments to specify various run-time parameters. These are:

-help : Displays help messages
-map{filename}: Loads the description of the environment you want your simulated robot to operate in.
-ini: Loads an initialization file.
-view: Activates/deactivates X-Window System displays (deactivation of the display helps speed up computation.)
-laser: Enables simulation of the laser range finder. (Don’t use this feature if your real robot isn’t equipped with a laser range finder; the Simulator runs more efficiently without this feature.)

Remember, these arguments are all optional. After selecting which command line arguments you want to specify, fire up the BeeSoft Simulator by starting up each of these programs:

 tcxServer
 simulator
 baseServer -simulator 

with your chosen arguments following "simulator" on the second line. You’ll see the BeeSoft Simulator display window.

Undisplayed Graphic

Figure 2-5 - The BeeSoft Simulator™ Interface Display

Let’s go over the features of this display. In the main window, called the "playground," the simulated robot is represented by a small red circle. A line from the center to the perimeter indicates the robot’s heading. When the robot "hits" an obstacle, the red circle turns orange.

Help: Displays a window with a short explanation of some of the BeeSoft Simulator’s features. If you’re new to the Simulator, click this button first to see lots of useful information about how to best use the Simulator’s features.
Zoom In: Lets you zoom into the "playground" environment.
Zoom Out: Lets you zoom out of the environment.
Grid: Lets you switch on display of the background grid that will help you accurately position the objects and obstacles you create in developing a realistic simulated environment. Each cell in the grid represents approximately one square meter. Seeing the grid is very useful, because the active playground may not be as large as the window itself. The grid display is a quick and easy way to keep track of the edges of the environment, as well as a good guide for accurate placement of obstacles and other features in your simulated robot’s world. It’s a good idea to work with grid displayed.
Delete: Lets you remove an existing obstacle. Point to the obstacle you want to delete and click the left mouse button.
Deactivate: This is a toggle. It makes an existing obstacle become either invisible or visible to the virtual robot. To make an obstacle "invisible" without deleting it, point to it and click on (De)activate. To make the obstacle visible again, point to it again and click this button.
Control: Lets you reposition obstacles you’ve created. Click on control, click on an obstacle with your left mouse button, move it, then click again.
Insert: Lets you inset an obstacle into the "playground" environment. Rectangle: This lets you create a rectangular obstacle in the simulated robot’s environment. First, specify the upper left corner of the rectangle, then the lower right corner.
Trace On/Off: Lets you see a visual representation of the robot’s path, or track as it navigates throughout its environment.
Sonar On/Off: Lets you activate / deactivate the display of sonar readings. (Note: in any case, you will see only those readings reflected by an obstacle in the environment.)
Laser On/Off: Lets you activate/deactivate display of the readings from the laser rangefinder. (Don’t click this button on if your real robot isn’t equipped with a laser range finder; the BeeSoft Simulator runs more efficiently without this feature.)
Load: Lets you initialize your environment with a map file you previously built.
Save: Lets you save, in a file, the virtual environment-- the map-- you’ve built. When you click on this button, you’ll see a menu that lets you specify where you want the map file saved.
Quit: Exits the BeeSoft Simulator.

Along the bottom of the display window, you’ll see indicators, in coordinates, of the current cursor position and the current position of the virtual robot.

Creating and Refining The Simulated Environment

On the BeeSoft Simulator display, you’ll see your virtual robot represented as a red circle. A black line through the circle indicates the robot’s current heading, or orientation.

You can create a realistic virtual environment in which your simulated robot can wander and navigate. You can also save this environment in a file, and load it automatically the next time you run the BeeSoft Simulator.

You can create hallways, walls, doorways, corners, traps, obstacles and other environmental features to test your simulated robot’s navigational ability.

Running wander in the Simulator Environment

For an enlightening demonstration of the BeeSoft Simulator’s capabilities, you can run the BeeSoft-supplied demonstration program wander using the Simulator instead of an actual robot. Or, you can run a demonstration program of your own. First, start up the Simulator:

 tcxServer
 simulator
 baseServer -simulator 

If your demonstration program requires the colliServer obstacle avoidance routines, start up colliServer right after baseServer

(IMPORTANT NOTE: If you are running wander, do not start up colliServer.) When the Simulator has started up, open another xterm window, go to the directory that contains your demonstration program, and run it. To run wander, type:
 cd ~
 cp -r ~bee/src/beeExamples .
 cd ~/beeExamples
 make
 ./wander 

Remember, wander gives you the choice of including any of the following optional command line arguments:

-safetyMargin=X : Try to go no closer than X cm to the closest obstacle
-exploreRange=X : Wander no further than X cm from the start point.
-transSpeed=X : Go no faster than X cm per second.
-transAccel=X : Accelerate and decelerate at X cm per second squared.
-rotSpeed=X : Rotate no faster than X degrees per second. (wander will convertthe degrees per second to radians per second.)
-rotAccel=X : Accelerate and decelerate the rotate axis at X degrees per second squared.

To terminate the wander program, just type <CTRL-C>.

(When you’re all through testing, or want to take a break before going on to the next section, be sure to shut down the servers by typing:

 killall tcxServer

Placing the Simulated Robot

To position your simulated robot at any desired point in your virtual environment, simply point your mouse at that point and click your left mouse button.

If, as the robot maneuvers around, it hits an obstacle, the small red circle representing the robot turns orange.

Saving and Reading Map Files

When you have built up a virtual environment using the BeeSoft Simulator’s graphical interface, you might want to save that environment description, or map, in order to use it for further study or research, or to refine it to make it more precise. To do this, click on the Save button. You’ll be asked to specify a filename of a file in which you’d like your map saved. Then, when you run the Simulator at a later time, use the run time parameter -map {filename} and that map will automatically be loaded and displayed.

2.7.3 The BeeSoft Planner


The BeeSoft Planner, the BeeSoft Mapperand the subsidiary tools sonarint™ and laserint™, are example applications, supplied as a part of the BeeSoft™ package to assist you in your robotic research and development activities. These tools are not officially supported by RWI, Inc. To run these example applications, you need a working knowledge of the X-Window System, and you need to have the X-Window system up and running on your workstation. RWI, Inc., does not recommend, and will not support, running X-Windows on your robot’s internal computers.

You now have a fair idea of the scope, power and flexibility of control the BeeSoft Commander™ gives you over teleoperating your robot, you’ve discovered how to simulate robotic behavior using the BeeSoft Simulator™. Now, let’s see what your robot can do all by itself! Its time to go autonomous with the BeeSoft Planner.The Planner is BeeSoft’s robot motion management and exploration package. It helps your robot plan globally optimal motion, and uses occupancy maps to plan these optimal paths.

You can run the BeeSoft Planner from either :

The local console, that is the laptop or notebook computer mounted on the top of your robot, IF you have a B21 robot with the console computer installed;
               OR
On your own X-Windows workstation, connected to your robot via an Ethernet radio link, or radio modem and PPP. The Ethernet connection is highly recommended.

To fire up the BeeSoft Planner™, start up each of these programs:

In the window in which you are logged into the robot (window#2):

 tcxServer
 baseServer
 colliServer
 sonarint -nodisplay
 map -nodisplay 

In the window in which you are logged into your workstation (window#3):

 plan -TCXHOST=<your-computer-name>

You’ll see the BeeSoft Planner interface display window.

Undisplayed Graphic

Figure 2-7 - The BeeSoft Planner™ Interface Display

Let’s take a brief tour of the Planner’s display. On the left, taking up most of the display,

is the plan window, showing the current occupancy map, over which planning information will be superimposed. Arrayed vertically along the right are a collection of control buttons.

Autonomous Goal-Directed Planning

Point your mouse at a location within the plan window and click the left mouse button to set a goal point. It will show up as a yellow spot. You can set multiple goal points, if you wish. Now, observe as your robot proceeds towards your goal point(s).

To remove a goal point at any time, just point to it on the map and click the left mouse button.

As your robot travels along, globally navigating; detecting, avoiding and recording the locations of obstacles; planning minimum cost paths as it heads towards its goal point, you’ll want to keep up with its progress, as displayed in the plan window. To update the display at any time, click your left mouse button on the control button labeled map. As the robot explores andmaps, be sure to update the display often.

To stop the robot’s motion and exit the BeeSoft Planner, click your left mouse button on the box labeled quit. When you’re all through testing, don’t forget to shut down all the running servers by typing:

 killall tcxServer

To start to get an intuitive feel of the decisions the robot is making, and why, click your left mouse button on these control buttons:

costs: This shows you a map-like display of the cost, or difficulty, of taking a particular path. Black, or occupied areas, have a high cost; white, or free, areas have a low cost. You’ll see that the shortest or straightes tpath is not always the optimal, or minimum cost path.
utility: This shows the cumulative costs to the nearest unexplored area. The robot follows a "greedy" algorithm, trying to reach territory with maximum reward. White, free areas, offer maximum reward; black, or occupied areas, offer the minimum reward.

Click your left mouse button on the button labeled new plan. The BeeSoft Planner will compute the shortest path to the nearest goal point and displays that path in the plan window.

As the robot explores, it is continuously updating its plan, its estimate of the best, or minimum cost, maximum reward path to the next goal point, or the next unexplored area. You’ll see these paths represented superimposed on the map in these colors:

aqua: the minimum cost path to the next unexplored area.
blue: indicates the first action the robot will take along this path.
red: indicates the path with maximized clearance. This is often extremely close to blue, and often hidden under the blue line.

pink: represents a possible collision point.

Experiment with goal-based path planning for a while. Observe carefully how the robot makes its decisions. Select multiple goal points and note how your robot decides which one to head for first. Note how the BeeSoft Planner™ deletes each goal point as it is reached.

Expert’s Tip
To make your planning tests more realistic and instructive, try configuring your test area with obstacles in various patterns to simulate such common navigational situations as corridors, doorways, corners, etc. If your test area is a large, clear open space, you might try arranging large cardboard cartons in realistic configurations. Observe how the robot navigates among these obstacles and constructs its map.

Autonomous Exploring

Now, point your mouse at the button labeled autonomous and click the left mouse button. The robot now begins moving about, exploring and mapping its environment. By default, it is using guarded motion and heading toward the nearest unexplored, that is, unmapped, area. Remember, "nearest" area really means nearest reachable area. After all, a tantalizing unmapped area may lie only centimeters away — but behind a wall!

As with goal point planning, uncharted territory is shown in white, while known obstacles are displayed in black.

Remember to click your left mouse button on the control buttons labeled costs and utility to keep up to the minute on the robot’s decision-making process. Watch as the colored path lines appear.

These experiments will give you a solid, hands-on feel for your robot’s navigational capabilities, limitations and quirks.

When you’re all through experimenting with the BeeSoft Planner, point your mouse at the control button labeled quit and press the left mouse button. If you’re all done running BeeSoft™ programs, be sure to shut down the servers by typing:

 killall tcxServer

Congratulations!
You’ve completed the BeeSoft™ Quick Startup Guide.
.....You’ve learned how to power up, log on, test and operate your Real World Interface, Inc., robot. You’ve seen some of what your robot can do, and started to gain a solid, hands-on feel for directing and analyzing its behavior. You’ve even written your first simple robot program.
.....You’ve been introduced to the BeeSoft Commander, the graphical user interface that lets you teleoperate your robot, and the BeeSoft Simulator™, the graphical control interface that lets you simulate many facets of robot behavior and operation without using an actual robot.
.....You’ve also learned about goal-based and autonomous exploration using the BeeSoft Planner™ and the BeeSoft Mapper™.
By now, you’re probably just bursting with ideas for writing your own robot programs. The detailed reference information in this User’s Guide and Software Reference will help you to do just that.
Good luck, and have fun!

Previous Page Page Top TOC Index Next Page