Merge commit '2b749fc5b576abfe0a24f1d4f0253942c4d75128'

Author: tfeldmann

.github/workflows/tests.yml

@@ -29,6 +29,8 @@ jobs:
             "examples/Pattern",
             "examples/Pattern2",
             "examples/FadingBlink",
+            "examples/CustomSpeed",
+            "examples/SpeedAdjustment",
           ]
 
     # Steps represent a sequence of tasks that will be executed as part of the job

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## v2.0.0 (2021-12-16)
+
+- **Revamped API!**
+- New: writes the state only on changes, not on every update
+- Renamed the classes and header files:
+  - `IndicatorPin` -> `Indicator`
+  - `FadingIndicatorPin` -> `FadeIndicator`
+  - `Indicator` -> `BaseIndicator`
+  - `FadingIndicator` -> `BaseFadeIndicator`
+- Code cleanups
+- Uses GitHub Actions for tests
+
+## v1.2.0 (2021-11-15)
+
+- Renamed `configure`-method
+
+## v1.1.0 (2021-11-12)
+
+- renamed `count()` method to `pattern()`
+
+## v1.0.1 (2021-11-12)
+
+- Initial release

README.md

@@ -12,25 +12,28 @@
 - Basics: On / off / toggle
 - Supports blink patterns in the style of "Blink x times, pause, blink y times, repeat"
 - Supports infinite blinking
-- Supports single flashes
+- Supports single flashes and pauses, resuming the previous mode
+- Completely non-blocking (no `delay()`)
 - Parameters for pause- / off- / on-time duration can be adjusted on the fly
-- Super-nice fading effects (optional) with logarithmic brightness compensation
+- Super-nice fading effects (optional) with logarithmic brightness compensation for LEDs
 - Lightweight
-- Good-looking defaults (at least I tried)
-- Easily extendable
-- Non-blocking (no `delay()`), no dynamic allocations
+- Easily extendable to control components via SPI / CAN / I2C / UART ...
+- Comes with good-looking defaults (at least I tried)
 
 ## Example
 
-This example blinks the built-in LED on pin 13 with a smooth fade effect and logarithmic
-brightness compensation in the following pattern:
+This example blinks the built-in LED on pin 13 in the following pattern:
 
-`Blink 2x → Short pause → Blink 3x → Long pause → Repeat`
+- Blink 2x
+- Short pause
+- Blink 3x
+- Long pause
+- Repeat
 
 ```C
-#include <FadingIndicatorPin.h>
+#include <FadeIndicator.h>
 
-FadingIndicatorPin led(13);
+FadeIndicator led(13);
 
 void setup()
 {
@@ -43,16 +46,22 @@ void loop()
 }
 ```
 
+Easy, uh? It's not only blinking, it does so with smooth fading effects and
+logarithmic LED brightness compensation. Your boards never looked more professional! /s
+
+> Note: If you don't love the fading effects, just use the `Indicator`-class instead of
+> `FadeIndicator`.
+
 ## Full API
 
 ```C
 // Without fading effect:
-#include <IndicatorPin.h>
-IndicatorPin myPin(13);
+#include <Indicator.h>
+Indicator myPin(13);
 
 // With fading effect:
-#include <FadingIndicatorPin.h>
-FadingIndicatorPin myPin(13);
+#include <FadeIndicator.h>
+FadeIndicator myPin(13);
 
 // now in your code you can do:
 myPin.permanent(LOW);
@@ -61,45 +70,63 @@ myPin.blink();
 ```
 
 ```C
+// set permanently ON
+void on();
+
+// set permanently OFF
+void off();
+
 // toggle between on / off
 void toggle();
 
 // set ON / OFF permanently
 void permanent(bool enable);
 
-// blink infinitely. `speed` can be 0 (slow) or 1 (fast).
-void blink(Speed speed = Speed::FAST);
+// blink infinitely. Speed is fast by default.
+void blink(SpeedSetting speed = SPEED_FAST);
 
 // blink `num` times, then long pause
 // repeats, if `repeat` is set, OFF otherwise.
-void pattern(int num, bool repeat = true, Speed speed = Speed::FAST);
+void pattern(int num, bool repeat = true, SpeedSetting speed = SPEED_FAST);
 
 // blink `num1` times, short pause, blink `num2` times, long pause
 // repeats, if `repeat` is set, OFF otherwise.
-void pattern(int num1, int num2, bool repeat = true, Speed speed = Speed::FAST);
+void pattern(int num1, int num2, bool repeat = true, SpeedSetting speed = SPEED_FAST);
 
 // turn ON for the given duration in ms. Continues in the previous mode afterwards.
 void flash(uint16_t duration_ms);
 
+// turn OFF for the given duration in ms. Continues in the previous mode afterwards.
+void pause(uint16_t duration_ms);
+
 // setup the timing parameters
-void setTiming(
-    uint16_t fast_on_ms,
-    uint16_t fast_off_ms,
-    uint16_t fast_pause_ms,
-    uint16_t fast_ending_ms,
-    uint16_t slow_on_ms,
-    uint16_t slow_off_ms,
-    uint16_t slow_pause_ms,
-    uint16_t slow_ending_ms);
-
-// Hint: You can also modify the values directly, e.g.:
-myLed.fast_on_ms = 250;
-
-// shorthand for setting up the timing parameters by defining the fast ON duration in ms.
-// all other durations are derived from that with some internal factors.
-void setTiming(uint16_t on_ms);
-
-// `true` if the indicator is currently blinking, showing a pattern or flashing
+void setSpeed(SpeedSetting setting);
+// Available by default: SPEED_RAPID, SPEED_FAST, SPEED_SLOW
+
+// Or use your own settings. SpeedSetting is a struct:
+typedef struct
+{
+    uint16_t on_ms;
+    uint16_t off_ms;
+    uint16_t pause_ms;
+    uint16_t ending_ms;
+} SpeedSetting;
+
+// ... alternatively you can setup the speed settings directly
+void setSpeed(
+    uint16_t on_ms,
+    uint16_t off_ms,
+    uint16_t pause_ms,
+    uint16_t ending_ms);
+
+// ... or by providing a single value, the other values are inferred from that
+void setSpeed(uint16_t on_ms);
+
+// Hint: You can also modify the values directly - even on the fly - e.g.:
+myLed.settings.on_ms = 250;
+myLed.settings.pause_ms = 2000;
+
+// `true` if the indicator is currently blinking, showing a pattern, flashing or pausing
 bool isOn();
 
 // You must call this in your loop!
@@ -112,10 +139,11 @@ int update();
 
 No problem! You have two options.
 
-- Use the generic `Indicator` class from `<Indicator.h>`. The `.update()`-method returns
-  a boolean whether the status is currently `HIGH` or `LOW`. You can then send this
-  value to your status indicator (see `examples/GenericBlink`). Use the `FadingIndictor`
-  class if you want fading effects. Here the `update` method returns an integer `0..255`.
+- Use the generic `BaseIndicator` class from `<BaseIndicator.h>`. The `.update()`-method
+  returns a boolean whether the status is currently `HIGH` or `LOW`. You can then send
+  this value to your status indicator (see `examples/GenericBlink`).
+  Use the `BaseFadeIndictor` class if you want fading effects. Here the `update` method
+  returns an integer `0..255`.
 
-- Subclass the `Indicator` class with custom logic. This is what `IndicatorPin` does
-  internally (see `src/IndicatorPin.h`).
+- Subclass the `BaseIndicator` class with custom logic. This is what `Indicator` does
+  internally (see `src/Indicator.h`). Have a look at the `SerialBlink` example!

example_build.sh

@@ -0,0 +1 @@
+pio ci examples/$1 --board=micro --lib=src

test_example.sh renamed to example_upload.sh

@@ -2,11 +2,10 @@
 Start a blinking pattern on the built-in LED with a smooth fading effect.
 */
 
-#include <FadingIndicatorPin.h>
+#include <FadeIndicator.h>
 
-// Use `FadingIndicatorPin` for a smooth fade.
-// If you want hard blinking, use `IndicatorPin`.
-FadingIndicatorPin led(13);
+// We use `FadeIndicator` for a smooth fade.
+FadeIndicator led(13);
 
 void setup()
 {

examples/Blink/Blink.ino

@@ -0,0 +1,20 @@
+#include <Indicator.h>
+
+Indicator led(13);
+SpeedSetting mySettings = {
+    .on_ms = 100,
+    .off_ms = 100,
+    .pause_ms = 2000,
+    .ending_ms = 2000,
+};
+
+void setup()
+{
+    // blink 2x on repeat with custom settings
+    led.pattern(2, true, mySettings);
+}
+
+void loop()
+{
+    led.update();
+}

examples/CustomSpeed/CustomSpeed.ino

@@ -1,9 +1,9 @@
 /*
 Start a blinking pattern on the built-in LED with a smooth fading effect.
 */
-#include <FadingIndicatorPin.h>
+#include <FadeIndicator.h>
 
-FadingIndicatorPin led(13);
+FadeIndicator led(13);
 
 void setup()
 {

examples/FadingBlink/FadingBlink.ino

@@ -2,12 +2,12 @@
 This example shows how to use a generic indicator.
 The `update()` method returns HIGH or LOW that you can use however you want.
 
-Of course this example would be easer with a `IndicatorPin` which handles the
+Of course this example would be easer with a `Indicator` which handles the
 digital output automatically.
 */
-#include <Indicator.h>
+#include <BaseIndicator.h>
 
-Indicator myIndicator;
+BaseIndicator myIndicator;
 
 void setup()
 {
@@ -17,5 +17,6 @@ void setup()
 
 void loop()
 {
-    digitalWrite(13, myIndicator.update());
+    bool isOn = myIndicator.update();
+    digitalWrite(13, isOn);
 }

examples/GenericBlink/GenericBlink.ino

@@ -1,6 +1,6 @@
-#include <IndicatorPin.h>
+#include <Indicator.h>
 
-IndicatorPin led(13);
+Indicator led(13);
 
 void setup()
 {

examples/Pattern/Pattern.ino

@@ -1,18 +1,18 @@
-#include <IndicatorPin.h>
+#include <Indicator.h>
 
-IndicatorPin led(13);
+Indicator led(13);
 
 void setup()
 {
     // This will set the LED to pattern mode:
     //
-    // 1. blink three times
+    // 1. blink two times
     // 2. pause
-    // 3. blink five times
+    // 3. blink three times
     // 4. longer pause
     //
     // (repeat)
-    led.pattern(3, 5);
+    led.pattern(2, 3);
 }
 
 void loop()

examples/Pattern2/Pattern2.ino

@@ -0,0 +1,28 @@
+/**
+ * This example does not blink a light, but outputs its state directly to the Serial
+ * port.
+ */
+
+#include <BaseIndicator.h>
+
+class SerialBlinker : public BaseIndicator
+{
+public:
+    void write(int state) override
+    {
+        Serial.print("LED: ");
+        Serial.println(state);
+    }
+};
+
+SerialBlinker myBlinker;
+
+void setup()
+{
+    myBlinker.pattern(2, 4);
+}
+
+void loop()
+{
+    myBlinker.update();
+}

examples/SerialBlink/SerialBlink.ino

@@ -0,0 +1,27 @@
+#include <FadeIndicator.h>
+
+FadeIndicator led(13);
+
+uint32_t lastSwitch;
+bool isFast;
+
+void setup()
+{
+    isFast = false;
+    lastSwitch = millis();
+
+    led.blink(SPEED_SLOW);
+}
+
+void loop()
+{
+    led.update();
+
+    // toggle speed every 3 seconds
+    if (millis() - lastSwitch > 3000)
+    {
+        lastSwitch = millis();
+        isFast = !isFast;
+        led.blink(isFast ? SPEED_FAST : SPEED_SLOW);
+    }
+}

examples/SpeedAdjustment/SpeedAdjustment.ino

@@ -1,6 +1,6 @@
 {
     "name": "Indicator",
-    "version": "1.2.0",
+    "version": "2.0.0",
     "description": "This library gives you non-blocking blinking patterns and smooth fade effects for your LEDs, buzzers or any other status indicators",
     "keywords": "led, signal, fading, blink",
     "repository": {
@@ -22,7 +22,10 @@
     "platforms": "*",
     "export": {
         "exclude": [
-            "*.sh"
+            "*.sh",
+            ".github",
+            "platformio.ini",
+            "test"
         ]
     }
 }

library.json

@@ -1,5 +1,5 @@
 name=Indicator
-version=1.2.0
+version=2.0.0
 author=Thomas Feldmann <mail@tfeldmann.de>
 maintainer=Thomas Feldmann <mail@tfeldmann.de>
 sentence=Supercharge your status LEDs / beepers