==========================================================================
  CMPack'04 Source Code Release for OPEN-R SDK 1.1.5-r2 for ERS7
  Copyright (C) 2004 Multirobot Lab [Project Head: Manuela Veloso]
  School of Computer Science, Carnegie Mellon University
-------------------------------------------------------------------------
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1; with
  no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  copy of the license is included in the file "free_document_license.txt".
=========================================================================

This release is setup for the OPEN-R SDK.

We have a bunch of papers on this stuff as well.  You can find a list
of our papers at:

  http://www.cs.cmu.edu/~mmv/pubs04.html

The home page for our legged team is at:

  http://www.cs.cmu.edu/~robosoccer/legged/

The website for an undergraduate robotics course taught using this code (some lecture slides have code examples) is at:

http://www.andrew.cmu.edu/course/15-491/    (2004)
http://www-2.cs.cmu.edu/~robosoccer/cmrobobits/  (2003)

This code was developed to run under Linux.  The code itself can be compiled and used under Windows by using Cygwin, or under OS-X, but most of the tools will not work because of the visual libraries required.  Under Linux the following libraries must be installed on your system to successfully compile the code and tools:

gcc
ruby (needed to compile)
perl (needed for most scripts)
FLTK (used by vision tools)
GTK and Glade (optional, used by old tools)
ImageMagick++ (needed by vision tools)
Fluid (needed by vision tools)


The first step is to get the code to compile.    You will need to set up your environment variables to include the OPENR directories and dogs/util/bin in your $PATH variable.  For example:

export DOGROOT=<yourpath>/dogs
export PATH=/usr/local/OPEN_R_SDK/bin:/usr/local/OPEN_R_SDK/RP_OPEN_R/bin:${DOGROOT}/util/bin:${PATH}

You should now be able to build using the Makefile in dogs/agent just by typing 'make' from the agent directory. Once you get the code built, put it on the memory stick in the usual place and it should run.  To quickly set up a blank stick, go to dogs/util/stick_images/ers7/ and run ./make_stick.sh from this directory.  This will copy all the open-r binaries to the stick (this stick will actually work, although it will contain a default configuration).  You can then place the built executables on the stick by running the 'stickit -a' command. 

You will need to calibrate vision to have the robot behave normally.

Setup for running:
------------------
- Calibrate vision
  - Gather pictures from robot using the behavior "Camera"
	(You set behaviors in /MS/config/run.cfg where /MS
	is the directory your memory stick is mounted to)
    - Pressing head button takes a picture
      - Hold down button
      - All LEDs light when picture taken
    - Chin head button writes pictures to memory stick
      - Robot will wave head and light some LEDs when starts writing
      - Robot will collapse when done writing log
    - Head is aimed by moving tail
    - Back buttons pause/unpause the robot
    - camera.cfg controls camera gain/lighting/shutter parameters used
    - Copy log file from memory stick to a directory.
    - Run util/log_processing/log_extractor/logextract <log file> util/log_processing/log_extractor/extract_configs/vis_raw.cfg
    - You should now have a bunch of files like i0000.ppm which contain the images you took
  - Run 'util/tile/tile 4 *ppm'
  - Load resulting imagergb.ppm in an image editor
  - Hand color the image using the colors from agent/config/config/colors.txt
    - Label both the green of the field and the green of the markers using the same green
    - Use black (0,0,0) for pixels that aren't any of the interesting colors
    - Use grey (64,64,64)-(192,192,192) for pixels that you don't care about the labelling of
  - Save the resulting image as label.ppm
  - Modify the file util/thresh/colors.txt to point to the files you just created
  - Run 'util/thresh/thresh colors.txt' (this should generate a out.tmap file amongst others)
  - Look at the out<blah>.ppm file you mentioned in the test section to make sure things
    went ok.
- Setup memory stick
  - Make /MS/motion and /MS/config directory on memstick
    (MS is the memory stick drive)
  - Copy agent/config/config/*           to /MS/config/
  - Copy agent/config/motion/*           to /MS/motion/
       (agent/Motion/test.cc can generate these motion files)
  - Copy util/thresh/out.tmap            to /MS/config/thresh.tm

- Setup wavelan on the memory stick
  - change IP addresses as needed

- Setup wavelan on a linux host

You need to have the OPEN-R Linux software installed as well as the
Game manager stuff from the web page. Follow the instructions for
using the Game Manager for inter-robot communication as well as
starting and stopping the robots for games. The correct
CONNECT.CFG, HOSTGW.CFG, and OBJECT.CFG files may be found in:

dogs/util/InterRobotComm/RP/host/MS/OPEN-R/MW/CONF

You'll need to setup your own IP addresses in all of the files and on the
robots. An example robotgw.cfg may be found in:

dogs/agent/config/open-r/mw/conf

(you will also find connect.cfg and object.cfg in this directory - these are
needed on the memory stick in order to run the code)

- You should be able to run now. Boot the robots and then start both inter-robot
communication and the game manager.

If you are using chokechain (util/chokechain) start that before inter-robot
communication.

Configuration options:
----------------------
- Use /MS/config/run.cfg to control the role of the robot
  -You can specify a hierarchy of behaviors.  For example:
       Attacker
       LEDs
       Getup

  -The above setup will run the Attacker and LEDs, but if the robot falls over the Getup behavior will take over the control of the robot because it has a higher priority.
- Use /MS/config/behave.cfg to control goal color and jersey color
	The team color may be set to "red" or "blue"
	The goal color must be "yellow" or "cyan". Do not use "blue" as the goal
	color.
- Use util/setitup to set up most of the common parameters (will need to be modified
    for your environment)
- Use /MS/config/spout.cfg to control the rate of dumping various debug info over the
    serial line or wavelan (0=don't send, #=send every # occurence)

Utilities:
----------
util/chokechain -
  Main debugging aid.  GUI display of information being sent over the serial line
	or wavelan. (You need Glade to build this)
util/thresh -
  Code to learn color thresholds from example images.
  Makes a cache.dat file when run that allows changing the color weights/confidences
    without going through the full learning process (delete this file whenever changing
    the examples given to the learning program).
  Takes about 110MB and 90 seconds on a PII-366MHz
util/tile -
  Tile seperate ppm files into a single large ppm file
util/vision_test -
  Program to test vision system from example images

Some of the directories in agent also contain utility programs for testing.

All code was created and tested on Linux IA-32 machines.  The code should probably
work on most varieties of Unix which support memory mapped files.  The code should
probably work on most 32-bit little endian processors.

Questions:
----------
For questions or help, email soniac@cs.cmu.edu

