Download and Install
Requirements
Machinetta is written in Java and requires Java JRE 1.4 be
installed. Because it is Java, it should run on most platforms and has
been tested (to various degrees and at various stages in development)
on Linux, Windows and Solaris. At worst simple changes will be
required to get it to work in any environment where Java 1.4 is
available.
You should be able to run at least 50 proxies on a reasonable desktop
machine, unless the domain is particularly dynamic or requires
excessive failure recovery, role allocation or fault detection.
Typically, memory (due to the JVM footprint) is the bottleneck, rather
than CPU speed.
Agents
Notice that Machinetta provides a coordination proxy and does not
provide "domain level intelligence". Thus, the proxy must have some
sort of agent (or person or robot) to communicate with in order to
actually get anything done. On the download page, we have posted all
the code for a simple fire fighting domain, including the necessary
agents.
Installing
To run Machinetta, you will need the proxy code and some
communications mechanism. A simple communications mechanism is
provided on the download page. Simply download the zip files and
unzip them. You should then set your CLASSPATH to point to the
directory in which you unzipped the files. That's it - pretty easy,
huh?
Configuring
There are two parts to configuring a Machinetta proxy. First, the
proxy itself needs to be configured, including which algorithms to use
and which settings of those algorithms to use. Second, the initial
beliefs of the proxy need to be defined, including who its team mates
are, what plan templates are available and what the capabilities of
its "RAP" are. We describe each of these configuration files below.
Proxy configuration files
The proxy configuration file sets public, static values as defined in
Machinetta/Configuration.java which
is used by all parts of the software to get configuration
parameters. The configuration file consists of lines of "name value",
where name matches the variable name in Configuration.java. Here is an example for a fire truck in a
simple disaster response simulation.
The meaning of most of the parameters is documented in Configuration.java.
The most critical parameters are the algorithms to use for the key
parts of a proxies behavior: communication, coordination, adjustable
autonomy and RAP interface. The value for these parameters is the
class name that implements the algorithm.
For COORD_IMPLEMENTATION_TYPE the recommended implementation is
Machinetta.Coordination.MACoordination, which has been shown to
coordinate up to 200 team members and can probably effectively
coordinate many more (This implementation is described in some detail
in this
paper.)
If you are using the simple communication server provided on the
download page, then you should set COMMS_IMPLEMENTATION_TYPE to
Machinetta.Communication.LocalComms (or
Machinetta.Communication.SSLocalComms if you are using the
simple disaster simulation which uses the communications server as the
communications infrastructure for the simulation.)
AA_IMPLEMENTATION_TYPE and
RAP_INTERFACE_IMPLEMENTATION_TYPE are both domain dependant
and specify the adjustable autonomy algorithms and methods for
communicating with the RAP respectively.
Another key configuration parameter is DEBUG_LEVEL. Throughout
the proxy code, instead of using "System.out.println" to display
messages we write to a special debugger and include the importance of
the message. The debug level parameter indicates how many of these
messages you want the proxy to display. If DEBUG_LEVEL=0 then
you will get extremely detailed output about everything the proxy
does. If DEBUG_LEVEL=5 then you will only get fatal (or
probably fatal) errors printed out. Unless you are debugging
DEBUG_LEVEL=3 provides enough information to see what the proxy
did, without having to wade through megabytes of output.
Proxy initial beliefs
The proxy's initial beliefs are specified in an XML file (referred to
in the configuration file). Here is an
example for a fire truck in the simple disaster simulation
environment. While the XML is potentially human readable (and
writable), it is easier to create it automatically using a simple
program that creates beliefs and then writes them to file. Machinetta
includes code that translates Beliefs to XML for purposes of
communication, we simply leverage this mechanism to create the initial
beliefs. Here is an example program
for creating configuration and initial belief files for the fire
trucks (code for this is included on the download page).
Maybe one day someone will build a tool that provides a simpler way of
specifying the initial beliefs.....
Running
Running a proxy, once the configuration files are in place, is pretty
simple. Here is how I start a proxy for the disaster response domain:
java -classpath /usr0/pscerri/Code Machinetta/Proxy
/usr0/pscerri/Code/Configs/FireBrigade7.cfg >
/usr0/pscerri/Code/output/proxy7 & .
Actually, it is a little more complex than that. In the case above,
the proxy will immediately try to connect to the simulator (because
that is what the configure RAP interface implementation gets it to
do.) Also, it needs the communications server up and running,
although for the disaster response domain the communications server is
built into the simulator, so nothing needs to be done.
Checking Output
Depending on the debug level (see above), the proxy will spew out
messages describing its progress. These messages will let you know
what is going on. Each message looks something like this: 2 :
"WASM4 can start on DestroyTarget0primary" from PlanAgent . The
2 : indicates the importance of the message, the higher the
more important. The string in quotes is the message itself. Finally
the from PlanAgent tells you the class
(Machinetta.Coordination.MAC.PlanAgent) that generated the message, if
you need to investigate further.
Look out for messages beginning with 5 :, since typically these
indicate fatal errors and might explain why nothing is working. If
things sort of work, but don't really, then 3 : messages might
provide the answer, since typically these indicate warnings that are
not fatal but things are not going as the developer anticipated.
Messages of lower importance than this simply describe the reasoning
of the agent and can be used (in theory) to work out what the agent is
doing (in practice, this is probably pretty tough if you are not the
code developer!).
Here is a complete output file
(DEBUG_LEVEL=1) for a successful proxy run in a UAV simulation.
(Notice the 5 : messages at the end of this file were printed
when the simulation was shut off, killing the socket connection.)
Sample start up scripts
Here is my script for running the simple disaster simulator and 8 proxies (on Linux):
#!/bin/csh
java -Xmx512m DisasterSim/Sim DisasterSim/config.cfg &
sleep 1
setenv i 0
while ($i < 8)
@ i = $i + 1
java -classpath /usr0/pscerri/Code Machinetta/Proxy /usr0/pscerri/Code/Configs/FireBrigade$i.cfg > /usr0/pscerri/Code/output/proxy$i &
sleep 1
end
sleep 600
kill `ps -Alf | grep java | grep -v NetBeans | grep -v java_vm | awk '{print $4}'`