Update README.md

This updates the README to explain the API a bit better.

1 files changed, 47 insertions, 21 deletions

diff --git a/README.md b/README.md
index 9bd7d38..cbe1015 100644
--- a/README.md
+++ b/README.md
@@ -3,17 +3,20 @@
 Rumba is part of ARCFIRE 2020, Work Package 3. It is a framework in
 Python which allows user to write a Python script to define a RINA
 network. The physical graph needed for this RINA network is then
-calculated and realised on one of the supported testbeds. Next, one of
-the supported RINA prototypes is installed. After installation, the
-network is bootstrapped. For an example of such a Python script, have
-a look at the examples/ folder.
+calculated and realised on one of the supported testbeds. Next, if the
+user requests this, one of the supported RINA prototypes is
+installed. The network is then bootstrapped on the available
+nodes. Finally, the experiment can be swapped out of the testbed. For
+an example of such a Python script, have a look at the examples/
+folder.
 
 ## Workflow, both external and internal:
 
   1. User defines the network graph, creating instances of model.Node
-    and model.DIF classes
+     and model.DIF classes
 
-  2. User creates an instance of a Testbed class
+  2. User creates an instance of a Testbed class. See below for
+     testbed specific configuration
 
   3. User creates an instance of prototype.Experiment class, passing
      the testbed instance and a list of Node instances
@@ -23,17 +26,19 @@ a look at the examples/ folder.
        per-node IPCPs, registrations and enrollment, ready to be
        used by the plugins
 
-  4. User calls run() on the prototype.Experiment instance:
+  4. User calls methods on the prototype.Experiment instance:
 
-    1. run() calls Testbed.swap_in(), passing the Experiment, and
-       filling in the missing information
+    1. swap_in() swaps the experiment in on the testbed, and fills in
+       the missing information in the model.
 
-    2. run() calls a prototype-specific setup function, to create the
-       required IPCPs, perform registrations, enrollments, etc.
+    2. install_prototype() installs the chosen prototype on the
+       testbed. Currently an Ubuntu image is assumed.
 
-    3. Perform tests (TODO)
+    3. bootstrap_prototype() calls a prototype-specific setup function,
+       to create the required IPCPs, perform registrations,
+       enrollments, etc.
 
-    4. run() calls Testbed.swap_out()
+    4. swap_out() swaps the experiment out of the testbed.
 
 ## Installation
 
@@ -69,10 +74,30 @@ a look at the examples/ folder.
  * [QEMU](http://wiki.qemu-project.org/Main_Page) is a generic and
    open source machine emulator and virtualizer.
 
+   A minimal QEMU testbed is defined as follows:
+
+       tb = qemu.Testbed(exp_name = "twolayers",
+                         username = "root",
+                         password = "root")
+
+   A user can optionally also specify the path to a bzImage and to an
+   initramfs. If they are not specified, the latest buildroot image
+   for the specific prototype will be downloaded. (Around 40 MB in
+   size) The login to those images is root/root.
+
  * [Emulab](https://www.emulab.net/) is a network testbed, giving
    researchers a wide range of environments in which to develop,
    debug, and evaluate their systems.
 
+   An emulab testbed instance is defined as follows:
+
+       tb = emulab.Testbed(exp_name = "rochefort10",
+                           username = "ricksanchez")
+
+   A password can also be provided but is not necessary when an SSH
+   key has been added. Optionally, a project name, a different testbed
+   URL and a custom image can be specified.
+
  * [jFed](http://jfed.iminds.be/) is a Java-based framework for
    testbed federation.
 
@@ -89,7 +114,8 @@ a look at the examples/ folder.
 
    Here the experiment name is rochefort10, the user's name is
    ricksanchez, and the certificate can be found in
-   /home/morty/cert.pem. An absolute path must be used for cert_file.
+   /home/morty/cert.pem. An absolute path must be used for
+   cert_file. Optionally a custom image can be selected.
 
    Before running the rumba you must run an SSH agent in same terminal.
    This will also avoid you having to enter the passphrase for every
@@ -102,15 +128,15 @@ a look at the examples/ folder.
        $ eval `ssh-agent`
        $ ssh-add /home/morty/cert.pem
 
-    To access a node once the experiment swapped in, use the following
-    command (in the same terminal where ssh-agent was run):
+   To access a node once the experiment swapped in, use the following
+   command (in the same terminal where ssh-agent was run):
 
-        $ ssh -A -oProxyCommand="ssh -i $CERTPATH
+       $ ssh -A -oProxyCommand="ssh -i $CERTPATH
             -o StrictHostKeyChecking=no $USER@bastion.test.iminds.be
             nc $NODENAME.$EXP.wall2-ilabt-iminds-be.wall2.ilabt.iminds.be 22"
             $USER@$NODENAME.$EXP.wall2-ilabt-iminds-be.wall2.ilabt.iminds.be
 
-    where $CERTPATH is the absolute path of the certificate (e.g.
-    /home/morty/cert.pem), $USER is the jFed username (e.g. "ricksanchez"),
-    $NODENAME is the name of the node you want to access (e.g. "a"),
-    and $EXP is the name of the experiment (e.g. "rochefort10").
+   where $CERTPATH is the absolute path of the certificate (e.g.
+   /home/morty/cert.pem), $USER is the jFed username (e.g. "ricksanchez"),
+   $NODENAME is the name of the node you want to access (e.g. "a"),
+   and $EXP is the name of the experiment (e.g. "rochefort10").