================================================================== UserDevel_HOWTO.txt Created by : Uluc Saranli Sat Feb 22 13:47:11 EST 2003 ================================================================== This text file describes how to create and use a custom Supervisor directory for RHexLib local to each user. ------------------------------------------------------------------ Table of Contents: 1 - Unpacking the sample archive 2 - Custom configuration a - Adding new modules b - Adding new modes c - Dealing with configuration files 3 - Compiling and Execution 4 - Host-based development utility scripts a - Path configuration b - upload_sup.sh, upload_config.sh, upload_all.sh c - make_sup.sh ------------------------------------------------------------------ 1 - Unpacking the sample archive -------------------------------- In the standard RHex CVS, the sample user development directory resides in $(RHEX_HOME)/SWRI/UserDevel.tar.gz. It should appear in that location following a cvs update. In the rest of this HOWTO, we will assume that user 'john' is working on a flying controller. We also assume that the users/john directory is properly setup and checking into the CVS repository. First, we need to go into the user directory, unpack the archive and rename the extracted directory appropriately. # cd ~/users/john # tar -xvzf ~/RHex/SWRI/UserDevel.tar.gz # mv SampleDevel Flying The final step is to import the new directory structure into the users CVS directory. You *must* make sure that you do not compile the source before this step. Otherwise, all the binary object files and executable will also be checked in and we do not want that. # cd Flying # cvs import users/john/Flying john initial 2 - Custom configuration -------------------------------- 2.a - Adding new modules ------------------------ The example distribution comes with a sample module, called SampleMachine. It is functional, but does not do anything useful. We need to remove this module from the hierarchy and add our own module All the module sources reside in the 'modes' directory, while the associated header files are in the 'include' directory. I assume that you are familiar with how to write modules. Let's say you have already created a module called FlyingMachine. Put FlyingMachine.cc in 'modes', and FlyingMachine.hh in 'include'. There are two additional steps before the module can be compiled. Edit modes/Makefile and change the following line SOURCES = SampleMachine.cc to SOURCES = FlyingMachine.cc Finally, edit Supervisor/supervisor.cc and replace the following line addModule( new SampleMachine, SAMPLEMACHINE_PERIOD, SAMPLEMACHINE_OFFSET, SAMPLEMACHINE_ORDER ); with addModule( new FlyingMachine, FLYMACHINE_PERIOD, FLYMACHINE_OFFSET, FLYMACHINE_ORDER ); Note that you also have to put #include "FlyingMachine.hh" somewhere in supervisor.cc and define FLYMACHINE_PERIOD, FLYMACHINE_OFFSET, FLYMACHINE_ORDER in the header file. Next time you do a top level make, the FlyingMachine should be compiled into the supervisor. 2.b - Adding new modes ---------------------- Adding modes is very similar to adding modules. Let's say you want to create aFlyingMode. Put FlyingMode.cc and FlyingMode.mod in 'modes' and FlyingMode.hh in 'include'. Then, edit modes/Makefile and supervisor.cc appropriately. Finally, edit Supervisor/Makefile and replace the line CUSTOM_MODES = SampleMode with CUSTOM_MODES = FlyingMode Next time you compile, the mode will be compiled in the supervisor and the apropriate structure and accessor files will be created. 2.c - Dealing with configuration files -------------------------------------- Naturally, adding new modules and modes means that new configuration files also will be needed. By default, the custom executables will look into $RHEX_HOME/SWRI/Config/ directory to load "list.rc" and the associated files. However, under the Supervisor directory of this custom user development package (~/users/john/Flying/Supervisor in this case), there is a "locallist.rc" configuration file, which is directly loaded from supervisor.cc. You can include additional files that are required by the new modules in this local configuration list. Note that all new config files must reside in the same directory as the supervisor executable. It is also possible to override some of the config files in SWRI/Config by copying them under ~/users/john/Flying/Supervisor and making additional edits. The search path is setup to override config files in this directory to the SWRI configuration files. 2 - Compiling and execution -------------------------------- 2.a - Compilation ----------------- Compiling the custom supervisor is trivial. A top level make creates the supervisor executable and links the proper GUI executables to the proper locations: # cd ~/users/john/Flying # make 2.a - Execution ----------------- The supervisor executable resides in the directory 'Supervisor'. To execute, use the following commands: # cd ~/users/john/Flying/Supervisor # ./start.sh -d Note that -d disables aborting through keyboard input (except Ctrl-C, which always exits the supervisor). This flag should *always* be used on the robot when manually executing the supervisor because it eliminates the timing glitches resulting from keyboard reads. Execution of the GUI is similar. The GUI executables reside in the directory 'Operator' and the following commands can be used for their invocation # cd ~/users/john/Flying/Operator # ./start.sh 3000 [hostname] where hostname should be replaced with the name of the robot on the network. 4 - Host-based development utility scripts ------------------------------------------ With this distribution, we also include scripts to facilitate host based development. following a top level make, these scripts are linked to the top level directory and can be invoked either on the QNX host, or the OCU laptop. 4.a - Path configuration ------------------------ In order for these scripts to work, you must make sure that the paths indicated in the file path_config.sh are correct. By default, the supervisor executable is places in ~/bin and the config files are placed in ~/config on the robot. Our new task manager configuration will recognize these locations and execute the supervisor with the appropriate settings. (not yet implemented) 4.b - upload_sup.sh, upload_config.sh, upload_all.sh ---------------------------------------------------------- These scripts are used to transfer the supervisor executable, the configuration files, or both to the robot. All of these scripts accept 0, 1 or 2 arguments. When invoked with 0 arguments, the transfer is done from localhost to the machine whose name is in $RHEX_ROBOTNAME environment variable. When invoked with 1 argument, the transfer us done from localhost to the machine indicated by the only argument to the script. Note that for the above two schemes to work, the QNX host (or localhost) *must* have direct access to the robot, either through the wired network, or an access point. Finally, if the script is invoked with 2 argument, the transfer is done from the machine in the first argument to the machine in the second argument. This invocation must be used when there is no direct connection between the robot and the QNX host machine (e.g. robot is on local peer-to-peer network, OCU laptop is both P2P and connected to the wired network, and the QNX host is on the wired network.) Examples: # ./upload_sup.sh : Uploads the supervisor from localhost to $RHEX_ROBOTNAME # ./upload_sup.sh rhex@chacha : Uploads the supervisor from localhost to the rhex user on the robot chacha # ./upload_config.sh merced rhex@bugs : Transfers the config files form merced (QNX host machine) to the rhex user in bugs robot. 4.c - make_sup.sh ---------------------------------------------------------- This script is used to do a top level make and transfer the resulting executable (stripped from debugging symbols) to the robot. The argument format is the same as in 4.b. One important note is that, when the source for the transfer is different than localhost, a remote make command is invoked. Namely, the following command: # make_sup.sh merced rhex@bugs will connect to merced, invoke a make in the appropriate directory and upload the resulting supervisor to the rhex user on the bugs robot.