Add period to on and off effects (#93)

Author: jandelgado

CHANGELOG.md

@@ -1,5 +1,11 @@
 # JLed changelog (github.com/jandelgado/jled)
 
+## [2022-02-24] 4.10.0
+
+* new: `On`, `Off` and `Set` now take an optional `duration` value, making
+       these effects behave like any other in this regard. This allows to add 
+       an `On` effect to a `JLedSequence` for a specific amount of time.
+
 ## [2022-02-24] 4.9.1
 
 * fix: make sure JLedSequence methods like `Repeat` and `Forever` are chainable

README.md

@@ -155,18 +155,22 @@ See the examples section below for further details.
 
 #### Static on and off
 
-Calling `On()` turns the LED on.  To immediately turn a LED on, make a call
-like `JLed(LED_BUILTIN).On().Update()`.
+Calling `On(uint16_t period=1)` turns the LED on. To immediately turn a LED on,
+make a call like `JLed(LED_BUILTIN).On().Update()`. The `period` is optional
+and defaults to 1ms.
 
 `Off()` works like `On()`, except that it turns the LED off, i.e. it sets the
 brightness to 0.
 
-Use the `Set(uint8_t brightness)` method to set the brightness to the given
-value, i.e. `Set(255)` is equivalent to calling `On()` and `Set(0)` is
-equivalent to calling `Off()`.
+Use the `Set(uint8_t brightness, uint16_t period=1)` method to set the
+brightness to the given value, i.e. `Set(255)` is equivalent to calling `On()`
+and `Set(0)` is equivalent to calling `Off()`.
 
-Technically `Set`,  `On` and `Off` are effects with a period of 1ms that 
-set the brightness to a constant value.
+Technically, `Set`, `On` and `Off` are effects with a default period of 1ms, that 
+set the brightness to a constant value. Specifiying a different period has an
+effect on when the `Update()` method will be done updating the effect and 
+return false (like for any other effects). This is important when for example
+in a `JLedSequence` the LED should stay on for a given amount of time.
 
 ##### Static on example
 

library.json

@@ -1,6 +1,6 @@
 {
     "name": "JLed",
-    "version": "4.9.1",
+    "version": "4.10.0",
     "description": "An embedded library to control LEDs",
     "license": "MIT",
     "frameworks": ["espidf", "arduino", "mbed"],

library.properties

@@ -1,5 +1,5 @@
 name=JLed
-version=4.9.1
+version=4.10.0
 author=Jan Delgado <jdelgado[at]gmx.net>
 maintainer=Jan Delgado <jdelgado[at]gmx.net>
 sentence=An Arduino library to control LEDs

src/jled_base.h

@@ -66,14 +66,16 @@ class CloneableBrightnessEvaluator : public BrightnessEvaluator {
 
 class ConstantBrightnessEvaluator : public CloneableBrightnessEvaluator {
     uint8_t val_;
+    uint16_t duration_;
 
  public:
     ConstantBrightnessEvaluator() = delete;
-    explicit ConstantBrightnessEvaluator(uint8_t val) : val_(val) {}
+    explicit ConstantBrightnessEvaluator(uint8_t val, uint16_t duration = 1)
+        : val_(val), duration_(duration) {}
     BrightnessEvaluator* clone(void* ptr) const override {
         return new (ptr) ConstantBrightnessEvaluator(*this);
     }
-    uint16_t Period() const override { return 1; }
+    uint16_t Period() const override { return duration_; }
     uint8_t Eval(uint32_t) const override { return val_; }
 };
 
@@ -261,17 +263,19 @@ class TJLed {
     bool IsLowActive() const { return bLowActive_; }
 
     // turn LED on
-    B& On() { return Set(kFullBrightness); }
+    B& On(uint16_t duration = 1) { return Set(kFullBrightness, duration); }
 
     // turn LED off
-    B& Off() { return Set(kZeroBrightness); }
+    B& Off(uint16_t duration = 1) { return Set(kZeroBrightness, duration); }
 
-    // Sets LED to given brightness
-    B& Set(uint8_t brightness) {
+    // Sets LED to given brightness. As for every effect, a duration can be
+    // specified. Update() will return false after the duration elapsed.
+    B& Set(uint8_t brightness, uint16_t duration = 1) {
         // note: we use placement new and therefore not need to keep track of
         // mem allocated
-        return SetBrightnessEval(new (brightness_eval_buf_)
-                                     ConstantBrightnessEvaluator(brightness));
+        return SetBrightnessEval(
+            new (brightness_eval_buf_)
+                ConstantBrightnessEvaluator(brightness, duration));
     }
 
     // Fade LED on
@@ -467,8 +471,14 @@ class TJLed {
     uint16_t delay_after_ = 0;   // delay after each repetition
 };
 
-template<typename T> T* ptr(T &obj) {return &obj;}  // NOLINT
-template<typename T> T* ptr(T *obj) {return obj;}
+template <typename T>
+T* ptr(T& obj) {    // NOLINT
+    return &obj;
+}
+template <typename T>
+T* ptr(T* obj) {
+    return obj;
+}
 
 // a group of JLed objects which can be controlled simultanously, in parallel
 // or sequentially.
@@ -494,7 +504,7 @@ class TJLedSequence {
         if (!ptr(leds_[cur_])->Update()) {
             return ++cur_ < n_;
         }
-        return true;;
+        return true;
     }
 
     void ResetLeds() {
@@ -503,7 +513,6 @@ class TJLedSequence {
         }
     }
 
-
  public:
     enum eMode { SEQUENCE, PARALLEL };
     TJLedSequence() = delete;
@@ -519,8 +528,9 @@ class TJLedSequence {
             return false;
         }
 
-        const auto led_running = (mode_ == eMode::PARALLEL) ? UpdateParallel()
-                                                  : UpdateSequentially();
+        const auto led_running = (mode_ == eMode::PARALLEL)
+                                     ? UpdateParallel()
+                                     : UpdateSequentially();
         if (led_running) {
             return true;
         }
@@ -529,7 +539,7 @@ class TJLedSequence {
         cur_ = 0;
         ResetLeds();
 
-        is_running_ = ++iteration_ < num_repetitions_  ||
+        is_running_ = ++iteration_ < num_repetitions_ ||
                       num_repetitions_ == kRepeatForever;
 
         return is_running_;