Rewrote parts of the README

README.md

@@ -1,31 +1,28 @@
-## ModuleInterface v2.0
-ModuleInterface is an Arduino compatible library for automatic transfer of settings and values between devices, with very little programming needed for each device. Version 2.0 has been tested with PJON v10.0, please use v1.3 for PJON v9.1 or v8.2.
+## ModuleInterface v2.1
 
-This is ideal for quickly creating a master-slave based collection of devices (modules) doing things like measuring temperatures and other sensors, turning things on and off, regulating heating and so on. With synchronization between the modules, and between the modules and a database if using the HTTP client that is available for the master module.
+This library enables fast and efficient setup of automation systems based on a collection of devices ("modules") controlled through a dynamic and responsive web interface. All under your control running locally with no subscriptions or cloud access required. The web interface can be easily extended and adapted to your use, or replaced with your own design.
 
-A typical setup can consist of multiple Arduino Nano devices connected to a master on an Arduino Mega with an Ethernet shield. Or a collection of devices like ESP8266.
+ModuleInterface takes care of automatic transfer of settings (module configuration) and values between devices, with very little programming needed for each device. It is built on top of the PJON communication library, allowing a wide range of devices to be connected with a single wire (no extra hardware!), Ethernet or WiFi, ASK/FSK/OOK/LoRa radio transceivers, serial, RS485 or light using LEDs and lasers.
 
-![UseCase1](images/UseCase1.png)
+A simple setup can consist of multiple Arduino Nano devices connected with a single wire to a master on an Arduino Mega with an Ethernet shield for communicating with the web server. No extra shields are needed for communication between the Arduinos, keeping this a low-cost but stable solution.
+
+Other platforms than Arduino are supported, and they can be connected with different media. A collection of ESP8266 devices can communicate using built-in WiFi both between themselves and the web server. The master can also run on a Windows or Linux computer (including Raspberry PI), communicating with modules over Ethernet or WiFi.
 
-#### Why?
-There is a lot of interest in IoT nowadays, and there are several alternatives that let small devices exchange data with the cloud. And some like MQTT let the user have the broker on a private computer and exchange values between modules in that way without exposing data in the cloud.
+Automatic persistence of module settings in EEPROM is supported, so that a module can continue working autonomously after a power failure even if it is isolated, if it has enough local input to meaningfully do so.
 
-This library has the following focus:
-- Full user control and privacy. No data into the cloud (unless you want it).
-- The broker / master is also implemented on a small device, making it possible to run setups not involving computers.
-- It can run a whole setup or parts of it without Ethernet. This removes vulnerabilities, which is a hot topic with Ethernet-enabled devices like ESP8266.
-- It can communicate using the PJON library with a bus on a a single wire with no hardware add-ons/shields. Cheap and uncomplicated. Or wirelessly using cheap 433 MHz ASK modules, or using WiFi or through LAN or Internet. Or a combination.
-- If web page control / visualization is needed, this is easy to do with a local LAMP/WAMP setup. Usable examples are included.
+The terms _device_ and _module_ are used somewhat interchangeably in this text, with a device being an standalone Arduino, ESP8266 or similar, and a module usually being a programmed device with some attached equipment, capable of doing some actual work.
+
+![UseCase1](images/UseCase1.png)
 
-#### Features
+### Features
 - Transport of values (measured and calculated) between modules according to their contracts
 - Transport of settings between master and modules in both directions.
 - HTTP client lets the master transfer settings between a database and the modules, for configuration in web pages and/or in the modules themselves.
 - HTTP client lets the master save output values from the modules into a database, for time series trending and inspection in web pages
 - Optional persistence lets each module remember its last received settings at startup, for autonomous operation even if it has been disconnected from the master
 - Coarse clock synchronization of all modules (within a few seconds)
 
-#### How it works
+### How it works
 It is a master-slave based system where a master can relate to multiple devices (modules) using the ModuleInterface library.
 
 Each module does not know about any other device. The master contacts each module and retrieves its service contracts for settings, input values and output values. The master will then read and write the values in the contracts regularly at a configurable time interval.
@@ -36,21 +33,21 @@ Depending on the type of master used, the settings for all modules can be config
 
 When polling for settings from the database, the time from the database server is also retrieved, and distributed to modules as a coarse clock synchronization. This allows for modules to perform schedule based actions, working autonomously and therefore not depending on the master to be continuously available.
 
-The optional persistence functionality lets new settings be kept and automatically updated in EEPROOM for each module. Each module can the start in its previous state immediately, before gaining contact with the master. So each module can continue working after a restart even if the master or network is down.
+The optional persistence functionality lets new settings be kept and automatically updated in EEPROOM for each module. Each module can then start in its previous state immediately, before gaining contact with the master. So each module can continue working after a restart even if the master or network is down.
 
 The ModuleInterface library consists of a collection of classes, and some files with functions for functionality like EEPROM based persistence and master HTTP transfer. The basic classes are ModuleVariable (keeping one setting or input or output value), ModuleVariableSet (keeping a set of settings or input or output values), ModuleInterface (keeping settings, input values, output values and functionality for a module), ModuleInterfaceSet (in the master -- a collection of ModuleInterface objects that are kept synchronized with the modules).
 
 The ModuleInterface code in a master typically uses more storage space and RAM than within a module. It is still fine to run on an Arduino Uno or Nano, but when adding the HTTP client (and implicitly the large required Ethernet and ArduinoJson libraries), it is necessary to step up to an Arduino Mega or similar for the master. An ESP8266 based setup is also an alternative.
 
 Also read the [design principles](documentation/README.md) document.
 
-#### PJON
+### PJON
 The ModuleInterface class that is used by a module, and the ModuleInterfaceSet class that is used by a master, implement transport logic and serialization/deserialization and other functionality, but do not implement any communication. The communication between modules is designed to be handled by deriving a class from each of these two, and letting these classes do the talking by some protocol.
 
 This library is not worth much without a proper communication bus for letting a master and multiple modules talk together. Luckily, we have the brilliant [PJON](https://github.com/gioblu/PJON) communication bus library created by *Giovanni Blu Mitolo* available, and this has been used as the primary choice for this library. The PJON library can be used for single-wire multi-master bus communication directly between Arduinos with no extra hardware, a brilliant feat. It can also be used for wireless communication, so ModuleInterface modules need not be wired to the master.
 The PJON library also supports a lot of different devices, making it a great choice.
 
-#### Module implementation
+### Module implementation
 Each module must declare a global object of a ModuleInterface derived class like the PJONModuleInterface that is part of the library. In the declaration of this object, the contracts (names and data types) for settings, input values and output values are specified as text parameters for simplicity.
 
 The object's loop function must be called regularly. Contracts are exchanged automatically with the master, and settings will arrive shortly. Settings are retrieved from the object with getter functions using the same order as the contract specifies.
@@ -88,7 +85,7 @@ void read_sensors() {
 
 ```
 
-Adding reading of more sensors is done by adding more output parameters to the input string as a space separated list, like "Motion:b1 Temp:f4" for having a variable named Temp as a 4 byte floating point value. Simple values are supported: boolean (b1), signed and unsigned byte, short and int (i1, u1, i2, u2, i4, u4), and float (f4). The digit in the data type specifies the number of bytes the data type uses.
+Adding reading of more sensors is done by adding more output parameters to the contract string as a space separated list, like "Motion:b1 Temp:f4" for having a variable named Temp as a 4 byte floating point value. Simple values are supported: boolean (b1), signed and unsigned byte, short and int (i1, u1, i2, u2, i4, u4), and float (f4). The digit in the data type specifies the number of bytes the data type uses.
 
 After adding the variable, the value must be set in a similar way as the motion in the example.