Summary

The purpose of this lab is to introduce you to the robot hardware and get you thinking about how to control the robots in a precise and effective manner. For the first several tasks you will test and debug your programs using the Nomadic 2D robot simulator, which provides a good testing platform for your code without endangering the actual robots.

Setup

The robot simulator, Nserver is installed on the engin server. You will need two files in order to run it: world.setup and robot.setup. You can copy them from /usr/local/etc. These two files need to be located in your working directory when you start up Nserver.

The manuals for the Nomad robots and the Nomadic API--which you use for the simulator as well--are located on the engin server in /usr/local/doc/. The Magellan low-level interface, Mage, uses a virtually identical API for communicating with and controlling the Magellan robots.

Controlling Robots

When controlling a robot, your code is always running in a main loop, checking the state of the robot each time through the loop. Having your loop run a million times per second is useless computation since the state of the physical robot does not change that fast. The sonar sensors, for example, won't fire more than a few times per second. Given the Nyquist criterion, your main loop needs to run no more than either twice as fast as your fastest sensor firing rate, or twice as fast as the frequency of any change you need to observe in the position of the robot. The usleep() function gives you the ability to control how fast your main loop runs.

Each time through your main loop, your program needs to figure out what the robot should be doing now. If it is in the middle of a turn, for example, it needs to figure out if it should speed up, slow down, or stop, depending upon how far away it is from the goal orientation. One way to manage this type of information is to give your robot a current state variable that specifies what action the robot is trying to achieve. This way the robot stays on task unless something comes up that ought to interrupt its activity.

Since robot code is always running, and always figuring out what the robot should do next, there are two important rules it must obey.

  1. The code cannot crash. If it does, your robot is dead.
  2. The code cannot leak memory. If it does, your robot will eventually die.

There are a number of tools you can use to identify memory leaks, with the simplest one being to run top while your programming is running to see if the amount of memory it is using is stable. You can also use electric fence or other memory analysis utilities to identify segmentation faults or other places where memory is being incorectly accessed.

Robot API

The basic API through which you access and control the robots is the same for both the Magellan robots and the Nomad Scout. To see examples of the Nomad API, you can checkout the nomad directory on the engin server using cvs.

cvs -d engin.swarthmore.edu:/usr/local/cvs checkout nomad

Note, you may need to set the CVS_RSH environment variable first. For a bash shell, use:

> CVS_RSH=ssh
> export CVS_RSH

In the nomad directory are some example programs showing how the API works. For both types of robots, there is a daemon running that handles communication with the robots. Each time through the main loop, you should call the function gs() which gets the most current state of the robot's odometry and sensors. This information is stored in the array State. You can access all of the information in the State array by using the constants defined in the Nomad programming manual. For example, to access the robot's current orientation, use State[STATE_CONF_STEER], and to get the robot's current (x, y) position using State[STATE_CONF_X] and State[STATE_CONF_Y].

On the Magellans, while the overall structure and API is the same, you will need a different library, Mage. You can download the Mage directory from the cvs repository on engin. If you then make the Mage library, you can include it when you compile your code using the -lMage flag for gcc. You do not use either the Nclient.c or Ndirect.c with the Magellans, although you will use Nclient.c for running simulations. There is a short description of the Magellan API specifics in the doc subdirectory. There are not as many functions available to you, and the sonar and IR setups are somewhat simplified. To make your code portable between the simulator and the Magellans, you may want to create simplified sensor start and stop functions for the simulator that mimic the Mage API.

Tasks

For each of the tasks below, implement the algorithm first in the simulator, then on the robot. Keep track of the relationship between the parameters you use in the simulator and the ones that work on the robot. For tasks 1-4, assume the robot is in open space with no obstacles. However, you may want to implement an emergency stop condition if the robot perceives any obstacles in front of it. You can do this by watching the front three sonars and reducing the velocity of the robot as it senses an obstacle getting close. Such a feature is often called a safe mode.

The overall design of your main routine should have two parts. In the first part, your routine should interpret the command line arguments and set up the robot's action. In the second part, your routine should enter a loop and monitor the robot's state until the action is complete. To make the robot execute a series of operations, you can simply run your program from the command line multiple times with different arguments.

The arguments your

  1. The first task is to implement the capability to orient the robot to face a particular direction as quickly as possible without overshooting. It is recommended that you start with simple proportional control, and then move to something a bit more complex. Note that you will have to take into account the minimum and maximum velocity limitations on the robot when designing your control scheme.

    Make the command for this task be turn with an argument indicating the number of degrees to turn left (positive angle) or right (negative angle).

  2. Implement a the capability to move the robot forward a specified distance as quickly as possible without overshooting.

    Make the command for this task be forward with an argument indicating the number of centimeters to move. If you wish, you can give the robot the ability to move backwards for a negative argument.

  3. Implement the capability to move from the robot's current location to an arbitrary location and orientation as quickly as possible without overshooting. You may want to use the control method specified in Seigwart and Nourbakhsh, Chapter 3.

    Make the command for this task be achieve with relative x (positive forward cm), y (positive left cm), and theta (angle in degrees) values.

  4. Implement the capability to move the robot through a series of waypoints specified by (x, y, theta). The robot may stop at each waypoint.

    Make the command for this task be waypoints with each waypoint specified by an x, y, theta triplet.

  5. Implement a wall-following algorithm. For this task, we will be testing the robots in a maze configuration with 90 degree angles.

    Make the command for this task be follow with an optional argument specifying the maximum length of time in seconds to follow the command before stopping.

  6. Implement a free-space following algorithm. The test areas for this task will be the 3rd floor corridor and the maze.

    Make the command for this task be wander with an optional argument specifying the maximum length of time in seconds to follow the command before stopping.

In summary, the following table gives the commands and arguments your program ought to support.

CommandargumentsDescription
turnangleRobot turns the specified angle, in degrees
forwarddistanceRobot goes forward the specified distance in cm
achievex y thetaRobot goes to the location and orientation specified relative to its current position.
waypointsx0 y0 theta0 ...Robot moves through the series of locations. Each location is specified relative to the starting location.
followtimeRobot wall follows for at most the specified amount of time.
wandertimeRobot wanders for at most the specified amount of time.

Signals

Sometimes it's nice to be able to cntl-c your programs, but that doesn't disconnect from the robot/Nserver. In order to correctly handle that case, your program needs to catch signals like cntl-c and terminate properly.

The following.c code includes an example of how to handle signals properly. The program itself implements keeping the robot a constant distance from a wall directly in front of it (one of the demos from class). Compile it using:

gcc -o following following.c Nclient.c

Then run it. In Nserver, you should have a wall in front of the robot. As you move the wall, the robot should maintain a constant distance from the wall.

Extensions

Writeup

All of the writeups will be submitted as web pages. When you are ready to submit your lab, use the on-line submission form. Code should be kept on an isolated link or be password protected and linked to the lab writeup. The writeups should be well-written, complete, concise, and organized. Images and pictures should be integrated with the text of the writeup in an effective manner and should not dominate the page. The best writeups make good tutorials on the topic, explaining the algorithms and providing examples of them working. Ten percent of the lab grade will be based on the quality of the writeup.

All writeups should contain at least the following elements.