PyroDeveloper - Emergent Wiki

1. Pyro Developer

This page documents the Pyro system for the Python coders and developers.

1.1. Your Own Pyro

You may be somewhere that has your own version of Pyro installed for general use. That is usually in /usr/local/pyrobot/. But, as a developer, you might want to have your own version to make changes, and then send them back to the main repository. This section of the User's Manual will tell you how to do that.

1.1.1. The Repository

See also PyroDeveloperCVS for more information on CVS and Pyro

There is a single place where all of the developers of Pyro keep their code: bubo.brynmawr.edu. Here are the rules for coding on the Pyro project:

Don't check your code in until it is in a functioning state.
Always have a series of checks (sometimes called unit tests).
Feel free to edit any code. No one "owns" any particular code.
Add comments using the docstring method to class definitions and all methods and functions.

You can get write access to the repository by emailing dblank@brynmawr.edu.

We use a system called CVS for our repository. Briefly, here are the types of commands. First, check out the files:

cvs -d dblank@compscitest.brynmawr.edu:/usr/local/CVS checkout pyrobot

This will create your own copy of pyrobot in the current directory. To use it, you'll need to change two environment variables. You should replace PYROBOT-DIRECTORY with the location of your installation:

export LD_LIBRARY_PATH=PYROBOT-DIRECTORY/lib:$LD_LIBRARY_PATH
export PATH=PYROBOT-DIRECTORY/bin:$PATH

Before you can run your own version, you'll need to "make" it. Assuming that your system admin has all of the pieces installed, you'll just need to issue a single command:

cd pyrobot
make

See PyroInstallation for more information.

Now, you can simply type "pyrobot" (or bin/pyrobot) at the prompt, and you should get your version.

If you make changes to Pyro that will be generally useful to the Pyro community at large, then you'll want to "commit" those changes. Before you do that, check to see if you have any conflicts with other changes:

cd pyrobot
cvs -d dblank@compscitest.brynmawr.edu:/usr/local/CVS update -d

Look for lines that begin with C. You may see lines that start with other characters. Here is the legend:

? - A file that CVS doesn't know anything about
P - A file that CVS just downloaded for you
C - A file that you and someone else have both changed (conflict)
M - A file that you have modified

Finally, when you have fixed any conflicts, you can commit your changes:

cd pyrobot
cvs -d dblank@bubo.brynmawr.edu:/usr/local/CVS commit

You'll be asked to make some comments on what you have changed. Please make some.

HINT: to use a different editor to make your comments, use the EDITOR environment variable:

export EDITOR=emacs
export EDITOR=vi
export EDITOR=pico

2. Classes and Methods

You can now browse the entire Pyro class files on-line at Pyrobot Class Files.

2.1. Robot

When writing code in the brain, you can access the robot with the method getRobot(). It returns a robot object.

Most robots have a method getMin() and getMax(). These methods return a vector (a distance and a direction). The direction is provided in a manner that is easy to use for fuzzy logic controls. Direction is given in radians, with 0 straight ahead, and positive to the left side, negative to the right. Straight back is PI (or negative PI).

To use as fuzzy variable, divide by PI. That gives you a value between 0 and 1, with direction the same that rotate takes (i.e., negative to the right, positive to the left).

The vector object has two fields: distance, and angle. For example:

        close_dist = self.getRobot().getMin().distance 
        close_angl = self.getRobot().getMin().angle

In general, it isn't a good idea to have your controller based on sensor specific positions because the controller will only work on this type of robot. Better to use something more abstract.

FIX: someone needs to add method(s) to robot that will allow a more abstract interface. Suggestions? How about:

>>> s.get('area', 'left')
>>> s.get('area', 'left-front')

which would return the closest hit in one of the eight quadrants (left, right, front, back, left-front, left-back, right-front, right-back). This could be based on angles, or on specific range sensors. There are also front-all and back-all sensor groups too.

Once you have your interface figured out, then you can begin to write your contoller. Here is a simple, direct controller:

# A bare brain

from pyrobot.brain import Brain

class SimpleBrain(Brain):
   # Only method you have to define is the step method:

   def step(self):
      print self.getRobot().get('sonar', 0)
      self.getRobot().move(.3, .2)

# -------------------------------------------------------
# This is the interface for calling from the gui engine.
# Takes one param (the robot), and returns a Brain object:
# -------------------------------------------------------

def INIT(engine):
   return SimpleBrain('SimpleBrain', engine)

In the above example, the move() method has these parameters:

self.getRobot().move(TRANSLATE_AMT, ROTATE_AMT)

This is only used if you want to directly control the robot. Normally, you would use some other method, for example that of the BehaviorBasedControl.

2.2. Classes

The entire Pyro library is now documented on-line at Pyro Class Files.

2.2.1. Object Hierarchy

robot
 |
 +-- SaphiraRobot
 |
 +-- KheperaRobot

brain
 |
 +-- BehaviorBasedBrain
 
engine