Update README

README.md

@@ -4,20 +4,155 @@ JGrafchart utilities
 This repository contains commands and ROS nodes for executing a SFC statemachine defined in KIF using the KIF_utils package by means of the JGrafchart tool (http://www.control.lth.se/Research/tools/grafchart.html).
 
 
+
+Requirements
+------------
+
+This package relies on a number of tools for installation.
+
+```
+java
+maven
+```
+
+For execution
+
+```
+jgrafchart
+java
+python
+bash
+dot (graphviz)
+```
+
+
 Installation
 ------------
 
+The instructions below assume the installation takes place in the home folder on a linux system. The `dev` folder below can be exchanged for a name of choice.
+
+
+The first step is to clone the repository. The latest version is located in master HEAD.
+
+`mkdir ~/dev`
+
+`cd ~/dev`
+
+`git clone https://git.cs.lth.se/mathias/grafchart_utils.git`
+
+
+The software is partially packaged as a Java maven project. It therefore needs compilation of the software into a jar package.
+
+`cd ~/dev/grafchart_utils/utils`
+
+`mvn package shade:shade`
+
+
+There should now be an automatically generated `~/dev/grafchart_utils/utils/target` folder containing a jar file `grafchart_utils-0.0.1-SNAPSHOT.jar`.
+
+
 
 Configuration
 -------------
 
+Before using the software some environment variables need to be set. In the `~/dev/grafchart_utils/utils/scripts/scripts` folder there is a file `setup.bash` that should be edited. It contains:
+
+
+```
+#
+# Source this file to setup environment
+#
+# Environment for grafchart tools
+#
+# Edit below:
+#
+
+export JGRAFCHART_HOME=/home/mathias/dev/grafchart/JGrafchart-2.6.1
+export JGRAFCHART_UTILS_HOME=/home/mathias/dev/grafchart_utils/utils
+
+export PATH=$PATH:$JGRAFCHART_UTILS_HOME/scripts
+```
+
+The `JGRAFCHART_UTILS_HOME` environment variable should point to the utils folder of the repository. All commands are available in the scripts folder which is added to the `PATH` environment variable.
+
+The `JGRAFCHART_HOME` environment variable should point to the root of a JGrafChart installation.
+
+
+After updating the `setup.bash` file it can be sourced in the local shell to make KIF commands available.
+
+`source setup.bash`
+
+
 
 Commands
 --------
 
+### sfc2dot
+
+sfc2dot creates an input file to the graphviz dot program to perform graphical layout of the statemachine.
+
+```
+usage: sfc2dot statemachine-file
+```
+
+#### Sample usage
+
+`sfc2dot statemachine.txt >statemachine.txt.gv` where *statemachine.txt* is the output from the the *sfclist* command in the kif_utils package.
+
+This should be followed by the layout step
+
+`dot -Tplain statemachine.txt.gv >statemachine.txt.gv.plain` where *statemachine.txt.gv.plain* contains the layout output from dot.
+
+
+
+### dot2jgrafchart
+
+dot2jgrafchart creates a xml file suitable as input to jgrafchart.
+
+```
+usage: dot2jgrafchart statemachine-file plain-file
+```
+
+#### Sample usage
+
+`dot2jgrafchart statemachine.txt statemachine.txt.gv.plain >statemachine.xml`
+
+
+
+### jgrafchart
+
+jgrafchart loads, compiles and/or starts executing a statemachine.
+
+
+```
+usage: jgrafchart [-lcs] [file]
+```
+
+
+#### Sample usage
+
+`jgrafchart -s statemachine.xml`. Load, compile and start the statemachine contained in the *statemachine.xml* file.
+
+The statemachine, when started, will connect to localhost port 4242 for communication with external entities.
+
+If needed, for instance for debugging of the statemachine, the following command can be issued before jgrafchart is started
+
+`nc -l 4242` 
+
+This command allows direct interaction with the statemachine through the keyboard:
+
+```
+Output|node=http://node/e1aacfb7-c17b-4924-8e7f-155248a91fef,xml_file=/home/mathias/certh/samples/xml_parser/keyframes_sequence_001/kf0.xml,result_reset=no,call=folding_initial,result_values=yes;no,result_name=initial_result_1
+initial_result_1|yes
+Output|node=http://node/987e0c16-925a-4a90-b127-694a388418ec,xml_file=/home/mathias/certh/samples/xml_parser/keyframes_sequence_001/kf46.xml,result_reset=no,call=folding_grasp,result_values=yes;no,result_name=grasp_result_2
+```
+
+where Output lines are written by the statemachine and *initial_result_1|yes* is written by the operator.
+
+
 
-ROS nodes
----------
+ROS node and bridge
+-------------------
 
 
 This repository contains utilities related to using the JGrafchart SFC editing