- reworked first part

Author: ubidefeo

README.md

@@ -1,62 +1,71 @@
 # ArduinoIoTCloud
 
-This library allows to connect to the Arduino IoT Cloud service. It provides a ConnectionManager to handle connection/disconnection, property-change updates and events callbacks.
-The supported boards are MKRGSM, MKR1000 (WiFi101) and MKR 1010 (WiFiNINA).
+This library facilitates interactions between boards featuring a cryptography co-processor and the Arduino IoT Cloud service. It includes a ConnectionManager to handle connection/disconnection/reconnection flows and provides means to interface local sketch variables with cloud based Thing properties, enabling synchronization and on-change callbacks.
+Currently supported boards: MKR1000 (WiFi101) and MKR 1010 (WiFiNINA). Support for MKRGSM is nearing completion and more cryptography enabled boards are following.
 
 ## Arduino IoT Cloud
 
-[Arduino IoT Cloud](https://create.arduino.cc/iot/things) is a service which allows connecting the cloud to the world around you. [Here](https://www.arduino.cc/en/IoT/HomePage) is an introduction.
-Now the platform is in public beta, feedback is welcome.
+[Arduino IoT Cloud](https://create.arduino.cc/iot) is a service which facilitates connections between cloud-based applications and the world around you. More information [is available here](https://www.arduino.cc/en/IoT/HomePage) and a detailed tutorial can be found on [Arduino Project Hub](https://create.arduino.cc/projecthub/133030/iot-cloud-getting-started-c93255).
+The platform is currently in public beta, we appreciate any feedback provided.
 
 
 ### Arduino IoT Cloud Components
 
-- **Devices**: Physical objects like a hardware board (e.g. MKR WiFi 1010). This is the hardware which runs the software, reads sensors, controls actuators and communicates with the Arduino IoT Cloud.
+- **Devices**: Physical objects built around a board (e.g. MKR WiFi 1010). This is the hardware which runs the sketch, reads sensors, controls actuators and communicates with the Arduino IoT Cloud.
 
-- **Things**: Logical representation of a connected object. They represent the inherent properties of the object, with as little reference to the actual hardware used to implement them. Each thing is represented by a collection of properties (e.g., temperature, light).
+- **Things**: Logical representation of a connected object. They embody inherent properties of the object, with as little reference to the actual hardware or code used to implement them. Each Thing is represented by a collection of _Properties_ (e.g., temperature, light, pressure...).
 
-- **Properties**: Qualities defining the characteristics of a system. A property can be something like a read-only (RO) setting to indicate the Arduino IoT Cloud can read the data, but cannot change the value of the property. A property might be designed as read and write (RW) if the Arduino IoT Cloud can also remotely change the property’s value and send an event notification to the device.
+- **Properties**: Qualities defining the characteristics of a system. A _Property_ can be defined as *read-only* (RO) to indicate that Arduino IoT Cloud can read the data, but cannot change the value of such _Property_. On the other end it may be designated to be *read-and-write* (RW), allowing Arduino IoT Cloud to remotely change the property’s value and trigger an event notification on the device to be handled via code.
 
-- **Events**: When something happens the Arduino IoT Cloud is aware of it thanks to application messages. For example, it might be informed by a face-recognition application that someone is at a door, or it has received a request from another app that a light be turned on.
+- **Events**: When a physical event is triggered on the _Device_, Arduino IoT Cloud is made aware of it thanks to application messages. It might, for example, be notified that a proximity sensor detected someone or something outside a door.
 
-- **Software**: It's quickly autogenerated automatically by the Arduino IoT Cloud when setting up a new thing: in this way, almost everything that you need is done and ready. The connection to the cloud is handled by this library. You have only to implement the callbacks linked to the properties.
+- **Software**: An Arduino Create sketch is automatically generated by Arduino IoT Cloud when setting up a new thing: this simplifies starting efforts. Because he connection to the cloud is handled by the library, The user can focus on  implementing the last bits of code required to handle the change of variables linked to properties.
+The introductory tutorial linked above explains this in an easy and comprehensive way.
 
 ## ArduinoIoTCloud library
 
-The library is divided into various classes:
-- `ConnectionManager` which is responsable for the connection to the Internet through `WiFiConnectionManager` or `GSMConnectionManager`. The selection is done using the type of board used.
+The library is made of multiple classes:
+- `ArduinoIoTCloud` is the main class. It's responsible for the connection to the MQTT Broker and to Arduino IoT Cloud.
+This library has multiple `begin(...)` methods allowing you to take more control of its behavior when it comes to network *Client* or to use a `ConnectionManager`
 
-- `ArduinoIoTCloud` it's the leading class. It's responsible for the connection to the MQTT Broker and to the Arduino IoT Cloud.
+- `ConnectionManager` is an abstract Class defining methods to be implemented in derived classes, such as `WiFiConnectionManager`, `GSMConnectionManager` and so on. The right `ConnectionManager` is chosen on a board basis during compilation.
+
+- `WiFiConnectionManager` handles connection, network time retrieval, disconnection, and reconnection to Internet for WiFi equipped boards (*MKR1000*, *MKR WIFI 1010* and upcoming implementations.
+
+- `GSMConnectionManager`. handles connection, network time retrieval, disconnection, and reconnection to Internet for GSM equipped boards (*MKR GSM 1400*)
+
+
+- `CloudSerial` is similar to [Serial](https://www.arduino.cc/reference/en/language/functions/communication/serial/), but used in combination with the cloud, allowing the user to send and receive custom messages using Arduino IoT Cloud as a channel.
 
-- `CloudSerial` it's similar to [Serial](https://www.arduino.cc/reference/en/language/functions/communication/serial/), but used in combination with the cloud.
 
 ### ConnectionManager
 
-*Connection Manager* is capable of knowing which board is being used through some `ifdef`.
+*Connection Manager* is configured via a series of compiler directives, including the correct implementation of the class based on which board is selected.
 
-- Instantiate the class with `ConnectionManager *ArduinoIoTPreferredConnection = new WiFiConnectionManager(SECRET_SSID, SECRET_PASS);` if you are using a WiFi board
+### How to use it
+- Instantiate the class with `ConnectionManager *ArduinoIoTPreferredConnection = new WiFiConnectionManager(SECRET_SSID, SECRET_PASS);` if you are using a WiFi board, otherwise replace *WiFi* with *GSM* or any future implementation.
 
-- `check()` function does all the job. It uses a finite state machine and it's responsible for the connection and reconnection to the Internet. The function is non blocking thanks to *millis*
+- the `check()` method does all the work. It uses a finite state machine and is responsible for connection and reconnection to a network. The method is designed to be non-blocking by using time (milliseconds) to perform its tasks.
 
-- `getTime()` function actually return the time from a NTP server. It's used for the connection to the cloud
+- `getTime()` returns different implementations of the `getTIme()` method based on the board used. Time is retrieved from an NTP server and is required for the SSL connection to the cloud.
 
-- `&getClient()` returns the client
+- `&getClient()` returns a reference an instance of the `Client` class used to connect to the network.
 
-- `	getStatus()` returns the network connection status
+- `getStatus()` returns the network connection status. The different states are defined in an `enum`
 
-- `debugMessage(char *_msg, uint8_t _debugLevel)` function used to print debug messages on the serial
+- `debugMessage(char *_msg, uint8_t _debugLevel, bool _timestamp = true, bool _newline = true)` is the method used to print debug messages on the physical serial. This helps providing troubleshooting information should anything go wrong.
 
-- The `setDebugMessageLevel(uint8_t _debugLevel)` function is used to set a debug level. Every debug message comes with a level which goes from 0 to 4. Higher level means higher verbosity. Debug messages with level higher than `_debugLevel` will not been showed.
+- The `setDebugMessageLevel(uint8_t _debugLevel)` method is used to set a level of granularity in information output. Every debug message comes with a level which goes from 0 to 4. A higher level means more verbosity. Debug messages with level higher than `_debugLevel` will not been showed. The lowest level has a higher importance and is usually used for errors, which are always printed.
 
 ### ArduinoIoTCloud
 
-- The `begin(ConnectionManager *connection = ArduinoIoTPreferredConnection, String brokerAddress = "mqtts-sa.iot.arduino.cc")` function is used to initialize the connection to the Arduino IoT Cloud through MQTT
+- The `begin(ConnectionManager *connection = ArduinoIoTPreferredConnection, String brokerAddress = "mqtts-sa.iot.arduino.cc")` method is used to initialize the connection to the Arduino IoT Cloud through MQTT
 
-- The `connect()` function is used to connect to the MQTT broker
+- The `connect()` method is used to connect to the MQTT broker
 
 - `disconnect()` stops the MQTT Client
 
-- The `update()` function is called periodically in the loop of `.ino` file. It checks the connnection with the MQTT broker, retrieve data from the Cloud and pushes back data using function `writeProperties(const byte data[], int length)`.
+- The `update()` method is called periodically in the loop of `.ino` file. It checks the connnection with the MQTT broker, retrieve data from the Cloud and pushes back data using method `writeProperties(const byte data[], int length)`.
 
 - `connected()` simply returns the current status of the MQTT connection.
 
@@ -66,4 +75,4 @@ The library is divided into various classes:
 
 - `getThingId()` returns the *THING_ID*
 
-- `connectionCheck()` function is like `check()` from *ConnectionManager*. Uses a finite state machine and it's responsible for the connection to Arduino IoT Cloud. It also uses *debugMessage* from *ConnectionManager* to print debug messages.
+- `connectionCheck()` method is like `check()` from *ConnectionManager*. Uses a finite state machine and it's responsible for the connection to Arduino IoT Cloud. It also uses *debugMessage* from *ConnectionManager* to print debug messages.