Merge branch 'dev'

fabianoriccardi · Nov 3, 2023 · a240991 · a240991
2 parents 2ac4735 + 2f50c55
commit a240991
Show file tree

Hide file tree

Showing 22 changed files with 495 additions and 478 deletions.
diff --git a/.clang-format b/.clang-format
@@ -152,3 +152,4 @@ UseTab: Never
 WhitespaceSensitiveMacros: []
 AlignConsecutiveMacros: AcrossEmptyLines
 AlignArrayOfStructures: Left
+CommentPragmas: '^#define'
diff --git a/.github/workflows/LibraryBuild.yml b/.github/workflows/LibraryBuild.yml
@@ -41,7 +41,7 @@ jobs:
 
           - config-name: esp8266-v3
             platform-url: https://arduino.esp8266.com/stable/package_esp8266com_index.json
-            arduino-platform: esp8266:esp8266@3.0.2
+            arduino-platform: esp8266:esp8266@3.1.2
             arduino-boards-fqbn: esp8266:esp8266:d1_mini
 
           - config-name: esp32-v1
@@ -51,7 +51,7 @@ jobs:
 
           - config-name: esp32-v2
             platform-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
-            arduino-platform: esp32:[email protected].4
+            arduino-platform: esp32:[email protected].14
             arduino-boards-fqbn: esp32:esp32:esp32
 
           - config-name: arduino-uno

diff --git a/examples/6_8_lights_effects/effect.cpp b/examples/6_8_lights_effects/effect.cpp
@@ -15,7 +15,11 @@ extern DimmableLightLinearized
 #endif
 
 #if defined(ESP8266)
-  lights[N_LIGHTS] = { { 5 }, { 4 }, { 14 }, { 12 }, { 15 }, { 16 }, { 0 }, { 2 } };
+  // Remember that GPIO0 (D3) and GPIO2 (D4) are "critical" since they control the boot phase.
+  // I have to disconnect them to make it boot when using Krida's dimmers. If you want to
+  // use those pins without disconnecting and connecting the wires, you need additional circuitry to
+  // "protect" them.
+    lights[N_LIGHTS] = { { 5 }, { 4 }, { 14 }, { 12 }, { 15 }, { 16 }, { 0 }, { 2 } };
 #elif defined(ESP32)
   lights[N_LIGHTS] = { { 4 }, { 16 }, { 17 }, { 5 }, { 18 }, { 19 }, { 21 }, { 22 } };
 #elif defined(AVR)  // Arduino

diff --git a/library.json b/library.json
@@ -1,6 +1,6 @@
 {
   "name": "Dimmable Light for Arduino",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "authors": {
     "name": "Fabiano Riccardi",
     "email": "[email protected]"

diff --git a/library.properties b/library.properties
@@ -1,5 +1,5 @@
 name=Dimmable Light for Arduino
-version=1.5.0
+version=1.5.1
 author=Fabiano Riccardi <[email protected]>
 maintainer=Fabiano Riccardi <[email protected]>
 sentence=This library allows to easily control dimmers (also known as thyristors).

diff --git a/platformio.ini b/platformio.ini
@@ -18,32 +18,34 @@ src_dir = examples/1_dimmable_light
 lib_dir = .
 
 [env:esp8266]
-platform = espressif8266
+platform = espressif8266@4.2.1
 board = d1_mini
 framework = arduino
 
 [env:esp32]
-platform = espressif32
+platform = espressif32@6.4.0
 board = lolin32
 framework = arduino
 
 [env:uno]
-platform = atmelavr
+platform = atmelavr@4.2.0
 board = uno
 framework = arduino
 lib_deps = 
     ${env.lib_deps}
     mike-matera/ArduinoSTL@^1.3.3
+upload_speed = 115200
 
 [env:mega2560]
-platform = atmelavr
+platform = atmelavr@4.2.0
 board = megaatmega2560
 framework = arduino
 lib_deps = 
     ${env.lib_deps}
     mike-matera/ArduinoSTL@^1.3.3
+upload_speed = 115200
 
 [env:nano_33_iot]
-platform = atmelsam
+platform = atmelsam@8.2.0
 board = nano_33_iot
 framework = arduino
diff --git a/readme.md b/readme.md
@@ -7,22 +7,23 @@ A library to manage thyristors (aka dimmer or triac) and phase-fired control (ak
 ## Motivations
 
 At the very beginning, this library was born from the curiosity to experiment the performance and capabilities of hardware timer on ESP8266 and to control old-fashioned incandescence lights.
-In the second instance, I needed to move thyristor controller to other microcontrollers, and the library had to adapt to the underlying hardware timers, which often vary for specifications and expose a very different interface from architecture to architecture. Moreover, at the time there weren't multi-platform libraries to control thyristor, so I decided to extend and maintain this library.
+In the second instance, I wanted to port the original piece of software to ESP32, and so I started to conceive a flexible software architecture that better adapts to different hardware platforms. Moreover, at the time there weren't multi-platform libraries to control thyristors, so I decided to publish, extend, and maintain this library over time.
 
 ### About the timers
 
-Actually, it was interesting (and sometime frustrating) to discover that a *simple* peripheral such as timer can really vary from architecture to architecture. ESP8266 is equipped with 2 timers, but one is dedicated to Wi-Fi management. This can complicate the development of applications that require multiple and simultaneous use of timer. Moreover, it hasn't "advanced" capabilities such as input compare, multiple output compare channels, and bidirectional counter. At least, these 2 timers are 32-bit. ESP32 is way better than its predecessor: it has 4 64-bit counters with up and down counters, but again no input capture and just 1 output compare channel per timer. Finally, I tried the ATmega328 of AVR family. The main difference and drawback is that they have only 8-bit or 16-bit timers, but this is reasonable if you consider that they were launched in the late 1996, when 8-bit microcontrollers were the standard. However, they provide more functionalities such as input compare and output compare with multiple channels and uniformed control registers over the different family's models. Moreover, they are well-supported by C header files containing complete registers' specifications.
-For sure, among these MCUs, the most complete implementation is provided by the old but gold AVR family.
-This brief overview gives a glimpse of the variety of timers embedded in microcontrollers, and it highlights the importance of building an abstraction layer that hides these differences and expose the essential functionalities needed to control thyristors: one-shot trigger and stop the timer.
+Actually, it was interesting (and sometime frustrating) to discover that a *simple* peripheral such as timer can heavily vary among different platforms.
+For example, the ESP8266 is equipped with 2 timers, but only one is usable by the user since the other is reserved for Wi-Fi management. This can lead immediately to a complicate development if the user application needs the timer for multi purposes. For this reason, [ESP8266TimerInterrupt](https://github.com/khoih-prog/ESP8266TimerInterrupt) was born. Moreover, that timer hasn't "advanced" capabilities such as input compare, multiple output compare channels, a bidirectional counter, and it is only 23-bit. Another example is the ESP32, that is way better than its predecessor: it has 4 64-bit timers with up and down counters, but still no input capture and just 1 output compare channel per timer. Finally, I cannot avoid mentioning the AVR ATmega's timers: they have multiple full-featured 8-bit or 16-bit timers running at lower clock frequency than modern MCUs, which may reduce the overall resolution of dimmer control or lead to more complicated ISRs to handle multiple rollovers. At least, AVR MCUs, compared to ESP8266 and ESP32, are well-supported by C header files containing complete registers' specifications.
+This brief overview gives a glimpse of the variety of properties to consider while working with timers embedded in microcontrollers, and it highlights the importance of building an abstraction layer that hides all these differences and exposes the 2 primitives needed to control thyristors: one-shot timer activation and stop counting.
 
 ## Features
 
-1. Control multiple thyristors at the same time
+1. Control multiple thyristors using a single hardware timer
 2. Compatible with multiple platforms (ESP8266/ESP32/AVR/SAMD)
 3. Interrupt optimization (trigger interrupts only if necessary, no periodic interrupt)
-4. Control the load via gate activation time or relative power
+4. Control the load by 2 measurement unit: gate activation time or linearized relative power
+5. Documented parameters to finely tune the library on your hardware and requirements
 
-Here a comparison against 2 similar and popular libraries:
+Here the comparison against 2 similar and popular libraries:
 
 |                                          | Dimmable Light for Arduino                  | [RobotDynOfficial/RDBDimmer](https://github.com/RobotDynOfficial/RBDDimmer) | [circuitar/Dimmer](https://github.com/circuitar/Dimmer) |
 |------------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------|

diff --git a/src/circular_queue.h b/src/circular_queue.h
@@ -1,22 +1,22 @@
-/***************************************************************************
- *   This file is part of Dimmable Light for Arduino, a library to         *
- *   control dimmers.                                                      *
- *                                                                         *
- *   Copyright (C) 2018-2022  Fabiano Riccardi                             *
- *                                                                         *
- *   Dimmable Light for Arduino is free software; you can redistribute     *
- *   it and/or modify it under the terms of the GNU Lesser General Public  *
- *   License as published by the Free Software Foundation; either          *
- *   version 2.1 of the License, or (at your option) any later version.    *
- *                                                                         *
- *   This library is distributed in the hope that it will be useful,       *
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
- *   Lesser General Public License for more details.                       *
- *                                                                         *
- *   You should have received a copy of the GNU General Public License     *
- *   along with this program; if not, see <http://www.gnu.org/licenses/>   *
- ***************************************************************************/
+/******************************************************************************
+ *  This file is part of Dimmable Light for Arduino, a library to control     *
+ *  dimmers.                                                                  *
+ *                                                                            *
+ *  Copyright (C) 2018-2023  Fabiano Riccardi                                 *
+ *                                                                            *
+ *  Dimmable Light for Arduino is free software; you can redistribute         *
+ *  it and/or modify it under the terms of the GNU Lesser General Public      *
+ *  License as published by the Free Software Foundation; either              *
+ *  version 2.1 of the License, or (at your option) any later version.        *
+ *                                                                            *
+ *  This library is distributed in the hope that it will be useful,           *
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU          *
+ *  Lesser General Public License for more details.                           *
+ *                                                                            *
+ *  You should have received a copy of the GNU Lesser General Public License  *
+ *  along with this library; if not, see <http://www.gnu.org/licenses/>.      *
+ ******************************************************************************/
 #ifndef CIRCULAR_QUEUE_H
 #define CIRCULAR_QUEUE_H
 

diff --git a/src/dimmable_light.cpp b/src/dimmable_light.cpp
@@ -1,22 +1,22 @@
-/***************************************************************************
- *   This file is part of Dimmable Light for Arduino, a library to         *
- *   control dimmers.                                                      *
- *                                                                         *
- *   Copyright (C) 2018-2022  Fabiano Riccardi                             *
- *                                                                         *
- *   Dimmable Light for Arduino is free software; you can redistribute     *
- *   it and/or modify it under the terms of the GNU Lesser General Public  *
- *   License as published by the Free Software Foundation; either          *
- *   version 2.1 of the License, or (at your option) any later version.    *
- *                                                                         *
- *   This library is distributed in the hope that it will be useful,       *
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
- *   Lesser General Public License for more details.                       *
- *                                                                         *
- *   You should have received a copy of the GNU General Public License     *
- *   along with this program; if not, see <http://www.gnu.org/licenses/>   *
- ***************************************************************************/
+/******************************************************************************
+ *  This file is part of Dimmable Light for Arduino, a library to control     *
+ *  dimmers.                                                                  *
+ *                                                                            *
+ *  Copyright (C) 2018-2023  Fabiano Riccardi                                 *
+ *                                                                            *
+ *  Dimmable Light for Arduino is free software; you can redistribute         *
+ *  it and/or modify it under the terms of the GNU Lesser General Public      *
+ *  License as published by the Free Software Foundation; either              *
+ *  version 2.1 of the License, or (at your option) any later version.        *
+ *                                                                            *
+ *  This library is distributed in the hope that it will be useful,           *
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU          *
+ *  Lesser General Public License for more details.                           *
+ *                                                                            *
+ *  You should have received a copy of the GNU Lesser General Public License  *
+ *  along with this library; if not, see <http://www.gnu.org/licenses/>.      *
+ ******************************************************************************/
 #include "dimmable_light.h"
 
 uint8_t DimmableLight::nLights = 0;
diff --git a/src/dimmable_light.h b/src/dimmable_light.h
@@ -1,22 +1,22 @@
-/***************************************************************************
- *   This file is part of Dimmable Light for Arduino, a library to         *
- *   control dimmers.                                                      *
- *                                                                         *
- *   Copyright (C) 2018-2022  Fabiano Riccardi                             *
- *                                                                         *
- *   Dimmable Light for Arduino is free software; you can redistribute     *
- *   it and/or modify it under the terms of the GNU Lesser General Public  *
- *   License as published by the Free Software Foundation; either          *
- *   version 2.1 of the License, or (at your option) any later version.    *
- *                                                                         *
- *   This library is distributed in the hope that it will be useful,       *
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
- *   Lesser General Public License for more details.                       *
- *                                                                         *
- *   You should have received a copy of the GNU General Public License     *
- *   along with this program; if not, see <http://www.gnu.org/licenses/>   *
- ***************************************************************************/
+/******************************************************************************
+ *  This file is part of Dimmable Light for Arduino, a library to control     *
+ *  dimmers.                                                                  *
+ *                                                                            *
+ *  Copyright (C) 2018-2023  Fabiano Riccardi                                 *
+ *                                                                            *
+ *  Dimmable Light for Arduino is free software; you can redistribute         *
+ *  it and/or modify it under the terms of the GNU Lesser General Public      *
+ *  License as published by the Free Software Foundation; either              *
+ *  version 2.1 of the License, or (at your option) any later version.        *
+ *                                                                            *
+ *  This library is distributed in the hope that it will be useful,           *
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU          *
+ *  Lesser General Public License for more details.                           *
+ *                                                                            *
+ *  You should have received a copy of the GNU Lesser General Public License  *
+ *  along with this library; if not, see <http://www.gnu.org/licenses/>.      *
+ ******************************************************************************/
 #ifndef DIMMABLE_LIGHT_H
 #define DIMMABLE_LIGHT_H