
Subsumption Architecture Environment (SAE) User Guide
-----------------------------------------------------

BEFORE STARTING THE FISRT TIME
------------------------------

1. Create a working directory of any name and move into it.

2. Make a file `hosts' that contains a list of machines which you whish
   to run AFSMs on. The format of each line should be 
   <machinename> <any-word>
   This is to allow `.rhosts' files to be copied directly that are in
   this style.

3. Type "sae -setup". This will install all the files needed. Files that
   end `.afsm.c' or `.nwk' are for the demonstration and are not
   essential to the program.

4. Try the demonstration (see `/export/src/master/sae/demo_guide').

HOW TO USE
----------

To start type "sae" in the working directory.

The top line of the display shows the current function of the mouse
buttons <1> to <3>, which varies depending on the position of the mouse
cursor. For example press button <3> whilst in the background and the
main menu will appear.

Create a control structure of AFSMs, registers and links as directed by
the top line information.

Each AFSM should have a coresponding file with the extension ".afsm.c"
or ".afsm.sc", depending on its type (C or SCHEME). This file should
contain one function whose name is that given to the AFSM (prefixed by
"afsm_" if a C function). When referring to registers prefix their name
with that of their host AFSM, and seperate the two with an underscore
(eg the AFSM "avoid" has a register "hit", refer to it as "avoid_hit").

In C no declarations or headers are necessary, and the registers
may be used as normal variables. To send an output register just prefix
its name with "send_" (eg "send_avoid_hit;"). In SCHEME input registers
can be accesses by prefixing with "get-" (eg "(get-avoid_hit)"). Output
registers can be set and sent: "(set-avoid_hit #t)" "(send-avoid_hit)".

An AFSM with the name "agent" is considered to be special, components
may be added to it and acessed via their registers which are
automatically added.


MAIN MENU
---------

start:  the first time it is selected the environment is created from
        the "setup.sc" file. This file is self explanitory, the objects
        created there may be referred to (when creating an agent) by a
        number which starts at 0 and increases in the order of
        creation. Subsequent selections of `start' will group all the
        chosen AFSMs (using button <2>) into a Unix process and start
        them. This may take a few moments whilst the files are
        compiled. Groups of AFSMs may be started whilst others are
        running, but new links between two already running AFSMs may
        not be made. 

new:    allows new agents to be started in the current environment with
        the same control structure.

clear:  clears the work area but does not affect any already running
        agents.

exit:   kills the user interface and leaves the environment running.
        The processes left must be killed with `cull'.

quit:   kills everything.

system: execute a shell command.


EXTRA COMMANDS
--------------

`getps' will list the processes assosciated with SAE that are running on
        a machine.

`cull'  will kill the processes assosciated with SAE that are running on
        a certain machine. Remember to execute this on all machines that
        have SAE processes. It uses a primitive method: kills any
        processes with words like "envt", "sae", etc (so save any files
        that you are editing before using cull). If you want to be extra
        careful you can examine the processes returned bu `getps' and
        kill one at a time.


OPTIONS
-------

-d      This option to sae will print out commands, for starting all
        the relevent processes, rather than actually executing them.
        These commands may then be copied into seperate windows. This
        allows seperation of the different processes output if for
        instance you are printing information for debugging purposes.
        Also the -v option may be inserted into these commands being
        copied which amongst other things will allow the monitoring of
        the sending of registers.

-v      Sets verbose mode. (see -d)

-setup  Used to initialise the users directory, ready for SAE use.


LOW LEVEL INTERFACE
-------------------

If automatic control of SAE is required then the various processes can
be started up seperately:

1. start `netwk'

2. start `envt' giving the address returned by `netwk' on the command
   line

3. start the AFSMs: make a file, `build_data.c', which specifies the
   AFSMs, registers and links; create a file `C_driver.h' or
`SC_driver.h' which notes which AFSMs are to be run in this process;
start `C_driver' or `SC_driver' giving the address returned by `netwk'
on the command line. For examples of the format required in these files
look at the ones automatically generated in the working directory when
the top level interface is used. All numbers used to refer to AFSMs and
registers start at 0 and increase in order of creation.

note: the -v option on any of these processes will produce a verbose
description of execution.


Adding Components and Properties
--------------------------------

The user should be familiar with C before attempting to add components.
In the following angle brackets <> denote variable syntax. Instance
variables are the data associated with a particular instance of a
component and includes its registers. Components may have parameters
(eg position on vehicle), these are requested from the user at the high
level inetrface. The steps shown here are for creating new components
and discuss all options. Just looking at the examples already in the
`components.c' file will give a good idea of how it is done.

1. Edit `components.c':

   a) Define a structure whose name if the component prefixed by
     `Carg_'. This should declare the instance variables used by
     the component.

   b) Make the function:
        C_fun<NAME> (r_num, args) int r_num; Carg_car *args;

      To access instance variables of the component use:
        args-><VARIABLE_NAME>

      For output registers (see `Cfun_proprioception' for an example),
      you must store the register_number as an instance variable, and
      to send it use:
        `send_reg(r_num, <REGISTER_NUMBER>)'

      Remember this function will be used by all instances of the
      component and all instances will share static variables if they
      are used.

   c) Make a function:
        Cinit_<COMP_NAME> (strargs, r_num) int r_num; char *strargs;

      Include the lines:
        comp *com = &robot[r_num]->component[ robot[r_num]->max_comp ];
        com->function = Cfun_<COMP_NAME>
        com->args = (Carg_<COMP_NAME>*)(malloc(sizeof(Carg_<NAME>)))'

      To set the parameters of the component, if it has any, use:
        sscanf(strargs, <FORMAT>, &com->args-><VARIABLE_NAME>, ...);

      Initialise the variables if desired:
        com->args-><VARIABLE_NAME> = <INITIAL_VALUE>;

      Make the registers. <TYPE> is CHARACTER, STRING or INTEGER:
        make_ireg(<REG_NAME>, <TYPE>, &com->args-><VARIABLE_NAME>
        make_oreg(<REG_NAME>, <TYPE>, &com->args-><VARIABLE_NAME>
   
   d) Add a line to the function `init_component_types'. The first
      <COMP_NAME> should be uppercase:
        make_component_type(<COMP_NAME>, Cinit_<COMP_NAME>);

2. Edit `components.sc'. This is used by the high level user interface.
   Add an item to the main list following the format shown:

     (<COMP_NAME>     (<`yes' only if components requires arguaments>)
                      (input  "<REG_NAME>" (<TYPE>) )
                       ...
                      (output "<REG_NAME>" (<TYPE>) )
                       ...
     )

3. Type `make envt'. There should be some invalid pointer warnings for
   `components.c'.

4. Here is some of the data available for making components. Look at
   `envt.h'.

  map[y][x]
    The cells of the environment (one byte each) hold the `solidness'
    property in the firts bit. If more space is needed for properties
    you could try converting this to a pointer to lists of properties.

  robot[ROBOT_NUMBER]
    Pointers to the structures which define the agents.
                    
  robot[ROBOT_NUMBER]->hit_point
    The distance of the contact point clockwise around the perimiter,
    -1 if none.

  robot[ROBOT_NUMBER]->motion
    ttue if the vehicle is moving


CHANGING THE ENVIRONMENT SIZE
-----------------------------

Edit `envt.h', change MAP_SIZE_X and MAP_SIZE_Y, then recompile by
typing `make envt'.


BUGS
----

The processes started on remote machines may crash after a while.
