Code documentation and readme

Signed-off-by: Fabiano Riccardi <[email protected]>

examples/1_dimmable_light/1_dimmable_light.ino

@@ -1,13 +1,19 @@
+/** 
+ * The main parameters to configure this sketch accordingly to your hardware setup are:
+ *  - syncPin, that is the pin listening to AC zero cross signal
+ *  - light, the pin which is connected to the thyristor
+ */ 
+
 #include "dimmable_light.h"
 
-// Pin listening to AC zero cross signal
 const int syncPin = D7;
+const int thyristorPin = D5;
+
+DimmableLight light(thyristorPin);
 
 // Delay between a brightness changement in millisecond
 int period = 50;
 
-DimmableLight light(D5);
-
 void setup() {
   Serial.begin(115200);
   while(!Serial);

examples/2_dimmable_lights/2_dimmable_lights.ino

@@ -1,14 +1,18 @@
+/** 
+ * An extension of the first example to demonstrate 
+ * how easy it is to control multiple lights.
+ */ 
 #include "dimmable_light.h"
 
 // Pin listening to AC zero cross signal
 const int syncPin = D7;
 
-// Delay between a brightness changement in millisecond
-int period = 1000;
-
 DimmableLight light1(D5);
 DimmableLight light2(D6);
 
+// Delay between a brightness changement in millisecond
+int period = 1000;
+
 void setup() {
   Serial.begin(115200);
   while(!Serial);

examples/3_dimmable_light_5_light/3_dimmable_light_5_light.ino

@@ -3,8 +3,10 @@
  * dimmable lights. To switch between effect, (un)comment the proper line
  * in the setup function.
  * 
- * NOTE: do not connect sync or gate with D3 - GPIO0,  D4 - GPIO2
- * they are needed to switch between the boot mode.
+ * NOTE1: do not connect sync or gate with D3 - GPIO0,  D4 - GPIO2
+ * they are needed to switch between different boot modes.
+ *
+ * NOTE2: only for ESP8266 and ESP32 due to Ticker.h dependency
  */
 
 #include <Ticker.h>

examples/4_lights_manager/4_lights_manager.ino

@@ -1,3 +1,6 @@
+/**
+ * A simple example to show DimmableLightManager api's.
+ */
 #include "dimmable_light_manager.h"
 
 const int N = 3;

examples/5_dimmable_manager_n_lights/5_dimmable_manager_n_lights.ino

@@ -1,18 +1,13 @@
 /**
- * This advanced example aims to show how to use the Dimmable Light Manager.
- * Basically it gives you the ability to add a friendly/logic name to a Dimmable Light.
- * 
- * The main parameters to configure accordingly to your hardware settings are:
- *  - syncPin, that is the pin listening to AC zero cross signal
- *  - N, that is the number of lights
- *  - pins, that is the array containing the pins which are connected to the thyristor
+ * This advanced example aims to show how to use the Dimmable Light Manager,
+ * combined with Ticker.h library.
  *  
- * In this case the friendly name are "light1", "light2" and so on...
- * Once the entire setting is ready (light, thyristor, wemos, and sketch), 
+ * In this case the friendly names are "light1", "light2" and so on...
+ * Once your setup is ready (light, thyristor, wemos flashed with this sketch), 
  * you should see a very simple effect: all the light will fade from 
  * dark to maximum brightness simultaneously.
  * 
- * NOTE: only for ESP8266 and ESP32
+ * NOTE: only for ESP8266 and ESP32 due to Ticker.h dependency
  */
 
 #include <Ticker.h>

examples/6_8_lights_effects/6_8_lights_effects.ino

@@ -1,7 +1,8 @@
 /**
  * Some effects to test and demonstrate the potentiality of DimmableLight.
- * Upload the code and select one effect through the serial port. 
- * Available effect list can be read in setup() function.
+ * Upload the code and select one effect writing code effect through the serial port.
+ * The available code range between e0 and e12. Remember to select CRLF 
+ * line ending in serial console.
  * 
  * NOTE: install https://github.com/kroimon/Arduino-SerialCommand
  */

readme.md

@@ -1,19 +1,21 @@
 # Dimmable Light for Arduino
-A simple library to manage thyristors (also knows as dimmer) easily in Arduino environment. 
+A simple library to manage thyristors (aka dimmer) easily in Arduino environment. 
 
 ## Features
 1. Multiple and indipendent control over thyristors
 2. Support to multiple platforms (ESP8266/ESP32/AVR/...)
 3. Raise interrupts only if strictly necessary (i.e. when the applicance has to turn on, no useless periodic interrupts)
 
 ## Motivations
-This library was born from the curiosity to learn how hardware timer works on esp8266 (precision and flexibility) and to control the old fashioned incandescence lights. I can confirm the timer is pretty poor if compared with other SoC, and a single timer (there is also Timer 0, but it is mandatory for WiFi operations) is not enough for some applications (i.e. play a tone with buzzer and simultaneously control dimmers).
+This library was born from the curiosity to learn how hardware timer works on ESP8266 (precision and flexibility) and to control old-fashioned incandescence lights.
+
+Actually it was interesting (and sometime frustrating) to discover that a *simple* peripheral such as timer can really vary from architecture to architecture. In my opinion, the ESP8266 is the worst implementation among these 3 architectures. It could be barely considered a timer/counter: no Input Compare, 1 Output Compare channel, only-down counter and single interrupt on 0 matching. It should carry only 2 of them, and, usually, the first is dedicated to WiFi management. This can stuck application requiring multiple and simultaneous PWM. The unique pro is that they are 32 bits. ESP32 is way better then its predecessor: 4 64bits counters with plenty functionalities, but again no input capture and just 1 output compare channel. The most surpring implementation was provided by old but gold AVR family. The main drawback is that they are only 8 or 16 bits, but you should consider that they are very old (they were launched more that 20 years ago) and 8-bit born. However, they provide many functionalities such as Input Compare/Output Compare with multiple channel and pretty clear and uniform control register over the different family's models. Moreover, they are well supported by well-written C header files containing complete registers' specifications.
 
 ## Installation
 You can install Dimmable Light for Arduino through Arduino Library Manager or cloning this repository.
 
 ### Requirements
-You need Arduino IDE and the appropriate board packages. If you want to use the libary on AVR boards such as Arduino/Genuino Uno, you also need [ArduinoSTL](https://github.com/mike-matera/ArduinoSTL) (available on Arduino Library Manager). If you want to compile the 6th example (the most complete), you also need [ArduinoSerialCommand](https://github.com/kroimon/Arduino-SerialCommand) library.
+You need Arduino IDE and the appropriate board packages. If you want to use the library on AVR boards such as Arduino/Genuino Uno, you also need [ArduinoSTL](https://github.com/mike-matera/ArduinoSTL) (available on Arduino Library Manager). If you want to compile the 6th example (the most complete), you also need [ArduinoSerialCommand](https://github.com/kroimon/Arduino-SerialCommand) library.
 
 ## Usage
 The main APIs are accessible through DimmableLight class. First, you must instantiate one or more DimmableLight, specifying the corresponding pin. Second, you must set Zero Cross pin, calling the static method *setSyncPin(..)*. Finally you must call static method *begin()*: this activated interrupt on Zero Cross pin, hence activating thryristor whenever required. To set the delivered power level, call method *setBrightness(..)*: it accepts value from 0 to 255, fitting into 8 bit. 

src/dimmable_light.h

@@ -23,10 +23,8 @@
 #include "thyristor.h"
 
 /**
- * This is the user-accessible DimmableLight class.
- * 
- * NOTE for programmers: the class should keep a static array with a brightness value
- * 					per object (that is a light).
+ * This is the user-oriented DimmableLight class, 
+ * a wrapper on Thyristor class.
  */
 class DimmableLight{
   public:

src/dimmable_light_manager.h

@@ -28,6 +28,10 @@
 
 #include <dimmable_light.h>
 
+/**
+ * Class to store the mapping between a DimmableLight object and 
+ * a (friendly) name. This could be useful when developing APIs.
+ */
 class DimmableLightManager{
 public:
 

src/thyristor.h

@@ -22,10 +22,20 @@
 #include "Arduino.h"
 
 /**
- * This is the developer-accessible Thryristor class.
+ * This is the developer-oriented Thyristor class. 
  * 
- * NOTE for programmers: the class should keep a static array with a delay value
- *          per object (that is a thyristor).
+ * NOTE Class Design Principle: The concept of Thyristor is agnostic 
+ * with respect to appliance controlled, hence measurement unit 
+ * to regulate the power should be also appliance-agnostic. Moreover,
+ * I decided to separate the code in 2 level of classes: 
+ * a low level one (appliance-agnostic), and a higher level one for final 
+ * user (a nice appliance-dependent Wrapper, e.g. Dimmable Light). Hence, 
+ * about this class:
+ * 1) the control method is called setDelay(..) and not, for example, setPower(..), 
+ *      setBrightness(..),... giving a precise idea of what's happening in 
+ *      electrical world.
+ * 2) time in microsecond (allowing a fine control, often exceeding the real need),
+ *      to match the notion of time given by setDelay()
  */
 class Thyristor{
   public: