Included Programs
Hardware tests
The ERSP software comes with some very useful programs to test how well the hardware is working. All of them are command-line utilities located in /opt/evolution_robotics/bin. The most useful of these are:
- test_battery
- test_range_sensors
- test_camera
If these three tests execute successfully, all hardware is properly connected.
Navtool
Navtool is an included application useful for testing that the ERSP software is working properly. It demonstrates object avoidance and map-building.
To use it, execute the following two commands in separate consoles:
$ run_slam_explore $ run_client_gui
The program will cause the robot to wander around the room and create a map using its camera. Much more information on navtool is in the Getting Started Guide.
The script that starts the server (run_slam_explore) is essentially a shell script which runs the command:
behave /opt/evolution_robotics-3.1.3004-20060627030002/behavior_networks/slam_explore.xml
Theoretically, modifying the behavior network slam_explore.xml (using composer.sh) will modify the behavior of the navtool GUI application.
Calibration
The camera and drive system of the robot need to be calibrated. Instructions for doing so are in the Getting Started Guide (page 47). The camera requires two types of calibration: intrinsic and extrinsic. Calibrating the drive system requires the use of a joystick. Winlab has purchased a Logitech Rumblepad which can be used for this purpose.
startservices.sh
A very simple shell script can be used to make sure all of the ERSP required services are started. It is already located in the home folder and bin folder of both robots. Its contents are:
!/bin/bash /etc/init.d/evolution-drivers-boot start /etc/init.d/evolution-firewire-boot start /etc/init.d/evolution-ovt-boot start /etc/init.d/evolution-peripherals-boot start /etc/init.d/evolution-pwc-boot start /etc/init.d/evolution-rcm-boot start
All of these services *should* launch on startup, regardless of whether or not the hardware is connected at startup. However, occasionally something may fail, and this script is a quick way of ensuring that everything is running.
Python
Python scripting is an easy way to control the robots. Most of the work we did in Winlab was in python. There is no explicit documentation of available python commands. An easy way to figure out which commands are available is to browse the directory /opt/evolution_robotics/python/ersp/. Descriptions from the c++ api apply to the python commands with the same name.
Most of our python scripts are located in ~/own.
neldermead.py
This script was the original attempt to locate the access point. It is an implementation of the Nelder-Mead simplex method. Although not very successful as an algorithm, the script contains many fundamental functions and imported in most of our other python scripts.
GoToXY(x,y)::
A function to simplify moving the robot. The parameters x,y are the coordinates to move to.
scanning_thread()::
This functions calls the utility iwconfig and reports back the absolute value of the signal strength. It is adapted from the open source project wifi-radar (wifi-radar is a python script and can be found in /usr/sbin).
getLQ()::
Similar to scanning_thread(), this function calls iwconfig and returns the Link Quality
BigReading()::
Calls scanning_thread() multiple times and returns an averaged result
Say(text_to_say)::
ERSP does not include text to speech for linux. We filled this void using the open source project flite. This Say function speaks any text aloud through the speaker. We use it often to have the robot report aloud the signal strength it has just measured. This allows us to estimate the progress of our algorithm without getting too close to the robot and interfering with the radio waves.
FindGrad(x,y,z)::
This function accepts three lists x,y,z corresponding to three points in space. It interpolates the three points to form a plane and returns the gradient of that plane.
gradfollower.py
This algorithm uses the gradient calculated from three points to attempt to hill climb towards the access point. Again it was not very successful because it has no mechanism to account for noisy data. The second generation of this algorithm, bigtri.py, attempted to account for noise by surveying nine points in groups of three, averaging each group, and using the averages to compute the gradient. This method was much more successful than the original. The final iteration of this algorithm is lsbigtri.py, which takes the averaging a step farther and computes a least-squared-regression plane using all nine points. To introduce the least squared process we began using the packages scipy and numpy. The functions which make use of the scipy libraries are located in datafit.py.
V3
This final and most successful of our algorithms is based on the method of trilateration. It is located (along with all the files it requires) in ~/own/bigarray/
We notice that beyond a certain range (~200cm) signal strength varies approximately linearly with distance. At each point the robot surveys, it guesses the distance, d1, between itself and the access point. This indicates that the access point is located along a circle centered at the robot of radius d1. The robot then moves to another point and measures the distance, d2, from itself to the access point. This indicates a second circle on which the access point must lie. The correct location of the access point is now limited to at most two points; it must lie on the intersection of the two circles. A third measurement resolves the unique location of the access point.
In practice, it never works quite that way. Signal strength is a very noisy measurement. However, after taking many measurements and using a least squares fit, the location of the access point can be guessed quite accurately. The main function of this algorithm is located in circles.py.
All of the config information this program uses is located in datafit.py.
Before this algorithm can be used, the relation between signal strength and distance must be known. A script in the home directory, coldata.py is an easy way to infer this. (This script was one of the earliest we wrote, its original intention was just to write something that moved and calculated the signal strength). Place the robot immediately beneath the access point and do the following:
$ python coldata.py [robot will move forward 8 meters] $ octave >> plotcoldata(100)
A graph of the data and its best fit line will appear, along with a histogram of the risiduals. You want the residuals to be approximately Gaussian. The parameter of plotcoldata.m is the starting point of the best fit line. Adjust it to achieve the best possible fit, then copy the corresponding values of acal and bcal into datafit.py.
Before v3 is run, all of the config values in datafit.py should be set since all of v3's runs are logged, and incorrect configuring will result in bad data.
v3 logs all of the tests it runs in /own/logs. A python script located in that directory, history.py, allows us to look through the logs and draws several relavent graphs for data analysis.
C++
Trilateration Classes (a cleaner, c++ version of V3)
Important source files:
circles.cpp: includes the main method which utilizes other classes/methods to find the access point using trilateration
alldata.cpp: a class that contains an array structure and other variables to hold the bulk of the data gathered before and after each trial run.
gnuplot_i.cpp: inlcudes the implemenation of the fine details of the plotting with GNUPLOT
plotting.cpp: provides methods that use gnuplot_i.cpp to simplify plotting.
iwhelper.cpp: includes methods that return signal strength and link quality
lstools.cpp: includes methods that use the least squares algorithm to approximate a guess of the location of the AP using data from alldata.cpp
movementtool.cpp: a class contains functions required to move the robot
config.txt: needs to be updated each time the variables are changed. (ex. num of sides, side length, points per side, etc)
All of the source files exist in the ~/own/cplus/circles directory.
To run the program:
- change the values in config.txt to set your variables and robot movement
- compile using existing Makefile and execute.
$ make [compilation] $ ./circles [The program will execute and will display a interactive graph]
Each trial run will be stored in ~/own/logs/[timestamp]/
In it will be: config.txt, v3.txt [data], aplog.txt [guessed location of ap], and a graph at each point.
Behaviors
Behaviors are xml files which control the robot. There are two types of xml files to consider: behavior networks and behavior schemes.
Behavior networks are completed behavior definitions. They are edited using the behavior composer, which is a java program that can be started using this command
$ composer.sh
The behavior composer is a drag-and-drop interface which allows for easy manipulation of behaviors networks.
To execute a behavior network, use the behave command:
$ behave some_network.xml
Behavior schemes are the building blocks of a behavior network. Behavior schemes must be located in one of the following directories:
/opt/evolution_robotics/config/behaviors /home/vamsi/samples/config/behaviors
(Note: Both of these are subdirectories of evolution's config directories. You can see which config directories are defined using $ echo $EVOLUTION_CONFIG)
In order to create a behavior scheme, it is necessary to both create an xml file for the scheme as well as create a class in a c++ library. A new scheme file can be adapted from an existing one.
The c++ library should be located in
/opt/evolution_robotics/lib
For instructions on creating a custom behavior scheme, refer to the ERSP tutorial 02-custom-behavior. The code for the library we've written (libiwBehavior.so and libbigarray.so) is located in ~/cpp/behaviors.
Each behavior scheme has a "category" parameter. This parameter determines the categorization of the scheme in the behavior composer. Both of the custom schemes we've created have the category "tutorial".
Using the Grid
- Making a reservation: Go to orbit-lab.org and click scheduler. Login using your orbit account and click on any desired empty timeblocks. Follow the instructions and the approval email will be sent if no conficts arise.
- At the reserved time, SSH in to the grid:
$ ssh username@console.grid.obit-lab.org [login]
- Imaging Nodes (as of 9/30/07)
Note: This step takes time (10-20 mins)
$ imageNodes4 [x,y] baseline-2.3.ndz [image node x,y; for more detailed instructions refere orbit lab FAQ]
- Turn them on
$ tellnode on [x,y] [on node x,y; for more detailed instructions refere orbit lab FAQ]
- Setting a node to be an Access Point
$ ssh root@nodex,y [ssh into node x,y] $ wlanconfig ath0 destroy $ wlanconfig ath0 create wlandev wifi0 wlanmode ap $ iwconfig ath0 essid 'desired essid' [desired essid, ex. TARGET] $ iwconfig ath0 up
