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()
 {