----------------------------------------------------------------------
Migration guidelines from the old RHex tree to the new robot
              development directory hierarchy.

Prepared by: Uluc Saranli
----------------------------------------------------------------------

======================================================================
** Environment variable definitions
======================================================================

The following environment variables are *required* by the new
hierarchy for a successful top level make:

RHEX_HARDWARE  : _SIMSECT_, _MCRHIO_ or _RUGGED_. Determines which
                 hardware library is to be linked against the
                 executable.

RHEX_ROBOTNAME : Determines the robot specific configuration 
                 directory in start.sh scripts

In order to be able to make individual components in subdirectories
under RoboDevel, the following variables must also be defined. If you
only type make at the top level RoboDevel directory, these are not
required.

setenv LIBS_TOPDIR ~/RoboDevel/Libraries
setenv RHEX_TOPDIR ~/RoboDevel/RHex
setenv RISE_TOPDIR ~/RoboDevel/RiSE

setenv RHEX_DIR    ~/RoboDevel/Libraries/RHexLib
setenv SIMSECT_DIR ~/RoboDevel/RHex/Simulation/SimSect++

======================================================================
** How to change modules and modes to use the new hardware access
   classes:
======================================================================

 RHexLib now has a slightly different method of handling hardware
components. There is no central "rHioHW", "SimSectHW" etc. instances
that need to be fetched with MMGetHardware(). Instead, each hardware
component is implemented in its own class (see EncoderHW.hh,
DriveHW.cc etc. in RHexLib/include/hardware) and maintains a pointer
to the associated instances of its implementations. More detailed
documentation is work in progress, but the following recipe will help
you migrate to the new scheme.

Here are the things you need to do in your supervisors, modules and
modes:

- Get rid of all "ChooseHardware.hh" includes
- Get rid of all MMGetHardware() calls in modules and modes.
- Locate all references to the hardware class pointer used in fetching
  pointers to individual components (e.g. hw->dcmotors, hw->encoders
  etc.). From now on, you can get pointers to these components
  directly from their interface classes: DCMotorHW::instance(),
  EncoderHW::instance() etc. use the following table to help the
  conversion. Also, in the associated source files, include the
  necessary header.

  Old form          New form                Include file
  ------------      --------------          ---------------
  hw->encoders      EncoderHW::instance()   hardware/EncoderHW.hh
  hw->analogIO      AnalogHW::instance()    hardware/AnalogHW.hh
  hw->digitalIO     DigitalHW::instance()   hardware/DigitalHW.hh
  hw->timers        TimerHW::instance()     hardware/TimerHW.hh
  hw->accels        AccelHW::instance()     hardware/AccelHW.hh
  hw->gyros         GyroHW::instance()      hardware/GyroHW.hh
  hw->power         PowerHW::instance()     hardware/PowerHW.hh
  hw->switches      SwitchHW::instance()    hardware/SwitchHW.hh
  hw->dials         DialHW::instance()      hardware/DialHW.hh
  hw->dcmotors      DCMotorHW::instance()   hardware/DCMotorHW.hh

 This conversion has been done for all modes and modules in the
standard RHex executable. The only ones that you have to worry about
are your use directories. Further migration guidelines for user
Supervisor directories can be found below.

======================================================================
** How to update the local user Supervisor development tree for
   individual developers:
======================================================================

 The new tree includes a sample user directory hierarchy under
RoboDevel/RHex/examples/UserDevel/UserDevel.tar.gz. The contents of
this file are very similar to the custom user directory structure that
we had adopted in the past. However, in order to migrate your existing
development tree, you will need to make a few changes:

- Update all the Makefiles based on the new samples (i.e. top level,
  modes, Supervisor and Operator directories).

- Correct all hardware component references in sources based on Jay's
  changes (see below for details on how to migrate to the new hardware
  abstraction layer).

- Update start.sh in both Supervisor and Operator directories.