# HG changeset patch
# User Andrey Skvortsov <andrej.skvortzov@gmail.com>
# Date 1532728870 0
# Node ID b0418bb135278a0f267bf9c5be886d9672359fcd
# Parent  de3f7c183e62ede05b419d0c740ddf62f633d148
Rework README.md, add examples section, add instructions for Modbus extension, more information about runtime.

diff -r de3f7c183e62 -r b0418bb13527 README.md
--- a/README.md	Fri Jul 27 15:44:20 2018 +0300
+++ b/README.md	Fri Jul 27 22:01:10 2018 +0000
@@ -8,89 +8,94 @@
 
 With Beremiz, you conform to standards, avoid vendor lock, and contribute to the better future of Automation. 
 
+Beremiz consists of two components:
+
+* Integrated Development Environment (IDE), [Beremiz.py](https://bitbucket.org/automforge/beremiz/src/tip/Beremiz.py?at=default). It's running on user's computer and is used to write/compile/debug PLC programs and control PLC runtime.
+* Reference runtime implementation in python, [Beremiz_service.py](https://bitbucket.org/automforge/beremiz/src/tip/Beremiz_service.py?at=default). It's running on target platform, communicates with I/O and executes PLC program.
+
 See official [Beremiz website](http://www.beremiz.org/) for more information.
 
-### Build on Linux ###
+## Build on Linux ##
 
 * Prerequisites
-```
-#!sh
 
-* # Ubuntu/Debian :
-sudo apt-get install build-essential bison flex autoconf
-sudo apt-get install python-wxgtk3.0 pyro mercurial
-sudo apt-get install python-nevow python-matplotlib python-lxml python-zeroconf python-cycler
-```
+		# Ubuntu/Debian :
+		sudo apt-get install build-essential bison flex autoconf
+		sudo apt-get install python-wxgtk3.0 pyro mercurial
+		sudo apt-get install python-nevow python-matplotlib python-lxml python-zeroconf python-cycler
+
 * Prepare
-```
-#!sh
-mkdir ~/Beremiz
-cd ~/Beremiz
-```
+
+		mkdir ~/Beremiz
+		cd ~/Beremiz
 
 * Get Source Code
-```
-#!sh
-cd ~/Beremiz
 
-hg clone https://bitbucket.org/skvorl/beremiz
-hg clone https://bitbucket.org/mjsousa/matiec
-```
+		cd ~/Beremiz
+		hg clone https://bitbucket.org/skvorl/beremiz
+		hg clone https://bitbucket.org/mjsousa/matiec
 
 * Build MatIEC compiler
-```
-#!sh
-cd ~/Beremiz/matiec
-autoreconf -i
-./configure
-make
-```
 
-* Build CanFestival (optional)
-Only needed for CANopen support. Please read CanFestival manual to choose CAN interface other than 'virtual'.
+		cd ~/Beremiz/matiec
+		autoreconf -i
+		./configure
+		make
 
-```
-#!sh
-cd ~/Beremiz
-hg clone http://dev.automforge.net/CanFestival-3
+* Build CanFestival (optional)  
+  Only needed for CANopen support. Please read CanFestival manual to choose CAN interface other than 'virtual'.
 
-cd ~/Beremiz/CanFestival-3
-./configure --can=virtual
-make
-```
+        cd ~/Beremiz
+        hg clone http://dev.automforge.net/CanFestival-3
+        cd ~/Beremiz/CanFestival-3
+        ./configure --can=virtual
+        make
+
+* Build Modbus library (optional)
+  Only needed for Modbus support.
+
+		cd ~/Beremiz
+		hg clone https://bitbucket.org/mjsousa/modbus Modbus
+		cd ~/Beremiz/Modbus
+		make
 
 * Launch Beremiz IDE
 
-```
-#!sh
-cd ~/Beremiz/beremiz
-python Beremiz.py
-```
+		cd ~/Beremiz/beremiz
+		python Beremiz.py
 
-### Run standalone Beremiz service ###
+## Run standalone Beremiz runtime ##
+
+Runtime implementation can be different on different platforms.
+For example, PLC used Cortex-M most likely would have C-based runtime. Beremiz project contains reference implementation in python, that can be easily run on GNU/Linux, Windows and Mac OS X.
+This section will describe how to run it.
+
+If project's URL is 'LOCAL://', then IDE launches temprorary instance of Beremiz python runtime (Beremiz_service.py) localy as user tries to connect to PLC. This allows to debug programs localy without PLC.
+
+If you want to run Beremiz_service.py as standalone service, then follow these instructions:
 
 * Start standalone Beremiz service
-```
-#!sh
-cd ~/Beremiz
-mkdir beremiz_workdir
 
-cd ~/beremiz
-python Beremiz_service.py -p 61194 -i localhost -x 0 -a 1 ~/Beremiz/beremiz_workdir
-```
+		cd ~/Beremiz
+		mkdir beremiz_workdir
+		cd ~/beremiz
+		python Beremiz_service.py -p 61194 -i localhost -x 0 -a 1 ~/Beremiz/beremiz_workdir
 
 * Launch Beremiz IDE
-```
-#!sh
-cd ~/Beremiz/beremiz
-python Beremiz.py
-```
-* Open/Create PLC project in Beremiz IDE.
-* 
-Enter target location URI in project's settings (project->Config->BeremizRoot/URI_location) pointed to your running Beremiz service (For example, PYRO://127.0.0.1:61194).
-Save project and connect to running Beremiz service.
 
-### Documentation ###
+		cd ~/Beremiz/beremiz
+		python Beremiz.py
+
+* Open/Create PLC project in Beremiz IDE.  
+  Enter target location URI in project's settings (project->Config->BeremizRoot/URI_location) pointed to your running Beremiz service (For example, PYRO://127.0.0.1:61194).
+  Save project and connect to running Beremiz service.
+
+## Examples ##
+
+Almost for all functionality exists example in ['tests'](https://bitbucket.org/automforge/beremiz/src/tip/tests/?at=default) directory.
+Most of examples are shown on [Beremiz youtube channel](https://www.youtube.com/channel/UCcE4KYI0p1f6CmSwtzyg-ZA).
+
+## Documentation ##
 
  * See [Beremiz youtube channel](https://www.youtube.com/channel/UCcE4KYI0p1f6CmSwtzyg-ZA) to get quick information how to use Beremiz IDE.
  
@@ -108,7 +113,7 @@
 
  * See official [Beremiz website](http://www.beremiz.org/) for more information.
 
-### Support and development ###
+## Support and development ##
 
 Main community support channel is [mailing list](https://sourceforge.net/p/beremiz/mailman/beremiz-devel/) (beremiz-devel@lists.sourceforge.net).