optionally return last brightness value from Update() (#131)

add new example examples/last_brightness

Author: jandelgado

.github/workflows/test.yml

@@ -7,11 +7,6 @@ on:
       - master
 
 name: run tests
-
-concurrency:
-  group: ${{ github.head_ref }}
-  cancel-in-progress: true
-
 jobs:
   lint:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -1,8 +1,13 @@
 # JLed changelog (github.com/jandelgado/jled)
 
+## [2024-12-01] 4.15.0
+
+* new: `Update()` methods now optionally return the last brightness value
+       calculated and written out to the LED. See `examples/last_brightness`
+
 ## [2024-09-21] 4.14
 
-* new: make `Jled::Update(unit32_t t)` public, allowing  optimizations and
+* new: make `JLed::Update(unit32_t t)` public, allowing  optimizations and
        simplified tests
 
 ## [2023-09-10] 4.13.1

README.md

@@ -1,5 +1,5 @@
-<table><tr><td> 
-<b>Preferring Python?</b> I just released <a href="https://github.com/jandelgado/jled-circuitpython">jled-circuitpython</a>, 
+<table><tr><td>
+<b>Preferring Python?</b> I just released <a href="https://github.com/jandelgado/jled-circuitpython">jled-circuitpython</a>,
 a JLed implementation for CircuitPython and MicroPython.
 </td></tr></table>
 
@@ -91,8 +91,8 @@ void loop() {
         * [Arduino framework](#arduino-framework)
     * [Raspberry Pi Pico](#raspberry-pi-pico)
 * [Example sketches](#example-sketches)
-    * [PlatformIO](#platformio-1)
-    * [Arduino IDE](#arduino-ide-1)
+    * [Building examples with PlatformIO](#building-examples-with-platformio)
+    * [Building examples with the Arduino IDE](#building-examples-with-the-arduino-ide)
 * [Extending](#extending)
     * [Support new hardware](#support-new-hardware)
 * [Unit tests](#unit-tests)
@@ -194,9 +194,9 @@ 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 default period of 1ms, that 
+Technically, `Set`, `On` and `Off` are effects with a default period of 1ms, that
 set the brightness to a constant value. Specifying a different period has an
-effect on when the `Update()` method will be done updating the effect and 
+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.
 
@@ -268,25 +268,25 @@ auto led = JLed(13).Breathe(500, 1000, 500).DelayAfter(1000).Forever();
 
 #### Candle
 
-In candle mode, the random flickering of a candle or fire is simulated. 
+In candle mode, the random flickering of a candle or fire is simulated.
 The builder method has the following signature:
   `Candle(uint8_t speed, uint8_t jitter, uin16_t period)`
 
-* `speed` - controls the speed of the effect. 0 for fastest, increasing speed 
+* `speed` - controls the speed of the effect. 0 for fastest, increasing speed
   divides into halve per increment. The default value is 7.
 * `jitter` - the amount of jittering. 0 none (constant on), 255 maximum. Default
   value is 15.
 * `period` - Period of effect in ms.  The default value is 65535 ms.
 
 The default settings simulate a candle. For a fire effect for example use
-call the method with `Candle(5 /*speed*/, 100 /* jitter*/)`. 
+call the method with `Candle(5 /*speed*/, 100 /* jitter*/)`.
 
 ##### Candle example
 
 ```c++
 #include <jled.h>
 
-// Candle on LED pin 13 (PWM capable). 
+// Candle on LED pin 13 (PWM capable).
 auto led = JLed(13).Candle();
 
 void setup() { }
@@ -363,7 +363,7 @@ two methods:
   as an unsigned byte, where 0 means LED off and 255 means full brightness.
 * `uint16_t Period() const` - period of the effect.
 
-All time values are specified in milliseconds. 
+All time values are specified in milliseconds.
 
 The [user_func](examples/user_func) example demonstrates a simple user provided
 brightness function, while the [morse](examples/morse) example shows how a more
@@ -410,10 +410,29 @@ specified by `DelayAfter()` method.
 
 ##### Update
 
-Call `Update()` or `Update(uint32_t t)` periodically to update the state of the
-LED. `Update` returns `true` if the effect is active, and `false` when it
-finished. `Update()` is a shortcut to call `Update(uint32_t t)` with the
-current time.
+Call `Update(int16_t *pLast=nullptr)` or `Update(uint32_t t, int16_t *pLast=nullptr)`
+to periodically update the state of the LED.
+
+`Update` returns `true`, if the effect is active, or `false` when it finished.
+`Update()` is a shortcut to call `Update(uint32_t t)` with the current time in
+milliseconds.
+
+To obtain the value of the last written brightness value (after applying min-
+and max-brightness transformations), pass an additional optional pointer
+`*pLast` , where this value will be stored, when it was written. Example:
+
+```c++
+int16_t lastVal = -1;
+led.Update(&lastVal);
+if (lastVal != -1) {
+    // the LED was updated with the brightness value now stored in lastVal
+    ...
+}
+```
+
+Most of the time just calling `Update()` without any parameters is what you want.
+
+See [last_brightness](examples/last_brightness) example for a working example.
 
 ##### IsRunning
 
@@ -453,16 +472,16 @@ will be inverted by JLed (i.e., instead of x, the value of 255-x will be set).
 
 ##### Minimum- and Maximum brightness level
 
-The `MaxBrightness(uint8_t level)` method is used to set the maximum brightness 
-level of the LED. A level of 255 (the default) is full brightness, while 0 
+The `MaxBrightness(uint8_t level)` method is used to set the maximum brightness
+level of the LED. A level of 255 (the default) is full brightness, while 0
 effectively turns the LED off. In the same way, the `MinBrightness(uint8_t level)`
 method sets the minimum brightness level. The default minimum level is 0. If
 minimum or maximum brightness levels are set, the output value is scaled to be
 within the interval defined by `[minimum brightness, maximum brightness]`: a
 value of 0 will be mapped to the minimum brightness level, a value of 255 will
 be mapped to the maximum brightness level.
 
-The `uint_8 MaxBrightness() const` method returns the current maximum 
+The `uint_8 MaxBrightness() const` method returns the current maximum
 brightness level. `uint8_t MinBrightness() const` returns the current minimum
 brightness level.
 
@@ -500,10 +519,10 @@ The `JLedSequence` provides the following methods:
   else `false`.
 * Use the `Repeat(n)` method to specify the number of repetitions. The default
   value is 1 repetition. The `Forever()` methods sets to repeat the sequence
-  forever. 
-* `Stop()` - turns off all `JLed` objects controlled by the sequence and 
+  forever.
+* `Stop()` - turns off all `JLed` objects controlled by the sequence and
    stops the sequence. Further calls to `Update()` will have no effect.
-* `Reset()` - Resets all `JLed` objects controlled by the sequence and 
+* `Reset()` - Resets all `JLed` objects controlled by the sequence and
    the sequence, resulting in a start-over.
 
 ## Framework notes
@@ -518,7 +537,7 @@ framework:
 platform=ststm32
 board = nucleo_f401re
 framework = mbed
-build_flags = -Isrc 
+build_flags = -Isrc
 src_filter = +<../../src/>  +<./>
 upload_protocol=stlink
 ```
@@ -570,8 +589,8 @@ so it should be avoided and is normally not necessary.
 For completeness, the full signature of the Esp32Hal constructor is
 
 ```
-Esp32Hal(PinType pin, 
-         int chan = kAutoSelectChan, 
+Esp32Hal(PinType pin,
+         int chan = kAutoSelectChan,
          uint16_t freq = 5000,
          ledc_timer_t timer = LEDC_TIMER_0)
 ```
@@ -600,9 +619,14 @@ necessary to upload sketches to the microcontroller.
 
 ### Raspberry Pi Pico
 
-When using JLed on a Raspberry Pi Pico, the Pico-SDK and tools must be
-installed.  The Pico supports up to 16 PWM channels in parallel. See
-the [pico-demo](examples/raspi_pico) for an example and build instructions.
+When using JLed on a Raspberry Pi Pico, the Pico-SDK and tools can be
+used.  The Pico supports up to 16 PWM channels in parallel. See
+the [pico-demo](examples/raspi_pico) for an example and build instructions when
+the Pico-SDK is used.
+
+A probably easier approach is to use the Arduino platform. See
+[platformio.ini](platformio.ini) for details (look for
+`env:raspberrypi_pico_w`, which targets the Raspberry Pi Pico W.
 
 ## Example sketches
 
@@ -621,6 +645,7 @@ Example sketches are provided in the [examples](examples/) directory.
 * [Controlling multiple LEDs sequentially](examples/sequence)
 * [Simple User provided effect](examples/user_func)
 * [Morsecode example](examples/morse)
+* [Last brightness value example](examples/last_brightness)
 * [Custom HAL example](examples/custom_hal)
 * [Custom PCA9685 HAL](https://github.com/jandelgado/jled-pca9685-hal)
 * [Dynamically switch sequences](https://github.com/jandelgado/jled-example-switch-sequence)
@@ -629,9 +654,9 @@ Example sketches are provided in the [examples](examples/) directory.
 * [ESP32 ESP-IDF example](https://github.com/jandelgado/jled-esp-idf-example)
 * [ESP32 ESP-IDF PlatformIO example](https://github.com/jandelgado/jled-esp-idf-platformio-example)
 
-### PlatformIO
+### Building examples with PlatformIO
 
-To build an example using [the PlatformIO ide](http://platformio.org/), 
+To build an example using [the PlatformIO ide](http://platformio.org/),
 uncomment the example to be built in the [platformio.ini](platformio.ini)
 project file, e.g.:
 
@@ -642,7 +667,7 @@ src_dir = examples/hello
 ;src_dir = examples/breathe
 ```
 
-### Arduino IDE
+### Building examples with the Arduino IDE
 
 To build an example sketch in the Arduino IDE, select an example from
 the `File` > `Examples` > `JLed` menu.
@@ -670,8 +695,8 @@ the host-based provided unit tests [is provided here](test/README.md).
 * add code
 * add [unit test(s)](test/)
 * add [documentation](README.md)
-* make sure the cpp [linter](https://github.com/cpplint/cpplint) does not 
-  report any problems (run `make lint`). Hint: use `clang-format` with the 
+* make sure the cpp [linter](https://github.com/cpplint/cpplint) does not
+  report any problems (run `make lint`). Hint: use `clang-format` with the
   provided [settings](.clang-format)
 * commit changes
 * submit a PR

devbox.json

@@ -1,13 +1,13 @@
 {
   "packages": [
-    "python@3.11",
+    "python@3.13",
     "lcov@1.16",
     "pipx",
     "cpplint@2.0.0"
   ],
   "shell": {
-    "init_hook": [
-      "echo 'Welcome to devbox!' > /dev/null"
+    "init_hook": [  
+      ". $VENV_DIR/bin/activate"
     ],
     "scripts": {
       "test": [

devbox.lock

@@ -89,24 +89,60 @@
       "resolved": "github:NixOS/nixpkgs/75a52265bda7fd25e06e3a67dee3f0354e73243c#pipx",
       "source": "nixpkg"
     },
-    "python@3.11": {
-      "last_modified": "2024-03-22T11:26:23Z",
-      "plugin_version": "0.0.3",
-      "resolved": "github:NixOS/nixpkgs/a3ed7406349a9335cb4c2a71369b697cecd9d351#python3",
+    "python@3.13": {
+      "last_modified": "2024-11-28T07:51:56Z",
+      "plugin_version": "0.0.4",
+      "resolved": "github:NixOS/nixpkgs/226216574ada4c3ecefcbbec41f39ce4655f78ef#python313",
       "source": "devbox-search",
-      "version": "3.11.8",
+      "version": "3.13.0",
       "systems": {
         "aarch64-darwin": {
-          "store_path": "/nix/store/c05vbvkjxarxkws9zkwrcwrzlsx9nd68-python3-3.11.8"
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/fbyrkq5n04a9hn5zs26vrmqjzdx73d4g-python3-3.13.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/fbyrkq5n04a9hn5zs26vrmqjzdx73d4g-python3-3.13.0"
         },
         "aarch64-linux": {
-          "store_path": "/nix/store/pxzzyri1wbq7kc7pain665g94afkl4ww-python3-3.11.8"
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/jbz9fj3sp5c8bf0s6d0bkjjj9mslxsrc-python3-3.13.0",
+              "default": true
+            },
+            {
+              "name": "debug",
+              "path": "/nix/store/60jgy93wj50wwimmhm2p53pzaiap8ypm-python3-3.13.0-debug"
+            }
+          ],
+          "store_path": "/nix/store/jbz9fj3sp5c8bf0s6d0bkjjj9mslxsrc-python3-3.13.0"
         },
         "x86_64-darwin": {
-          "store_path": "/nix/store/1zaap1xxxvw2ypsgh1mfxb3wzdd49873-python3-3.11.8"
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/c7j1vxcdcqswsddm5m1n2n4z5zfhmbq2-python3-3.13.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/c7j1vxcdcqswsddm5m1n2n4z5zfhmbq2-python3-3.13.0"
         },
         "x86_64-linux": {
-          "store_path": "/nix/store/7wz6hm9i8wljz0hgwz1wqmn2zlbgavrq-python3-3.11.8"
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/0b83hlniyfbpha92k2j0w93mxdalv8kb-python3-3.13.0",
+              "default": true
+            },
+            {
+              "name": "debug",
+              "path": "/nix/store/xzhxhqs8my0yvfi09aj1s9i1s9nrmpvg-python3-3.13.0-debug"
+            }
+          ],
+          "store_path": "/nix/store/0b83hlniyfbpha92k2j0w93mxdalv8kb-python3-3.13.0"
         }
       }
     }

examples/last_brightness/last_brightness.ino

@@ -0,0 +1,38 @@
+// Stops an effect when a button is pressed (and hold). When the button is
+// released, the LED will fade to off with starting the brightness value it had
+// when the effect was stopped.
+//
+// dependency: arduinogetstarted/ezButton@1.0.6 to control the button
+//
+// Copyright 2024 by Jan Delgado. All rights reserved.
+// https://github.com/jandelgado/jled
+//
+#include <ezButton.h>  // arduinogetstarted/ezButton@1.0.6
+#include <jled.h>
+
+constexpr auto LED_PIN = 16;
+constexpr auto BUTTON_PIN = 18;
+
+auto button = ezButton(BUTTON_PIN);
+
+// start with a pulse effect
+auto led =
+    JLed(LED_PIN).DelayBefore(1000).Breathe(2000).Forever().MinBrightness(25);
+
+void setup() {}
+
+void loop() {
+    static int16_t lastBrightness = 0;
+
+    button.loop();
+    led.Update(&lastBrightness);
+
+    if (button.isPressed()) {
+        // when the button is pressed, stop the effect on led, but keep the LED
+        // on with it's current brightness ...
+        led.Stop(JLed::KEEP_CURRENT);
+    } else if (button.isReleased()) {
+        // when the button is released, fade from the last brightness to 0
+        led = JLed(LED_PIN).Fade(lastBrightness, 0, 1000);
+    }
+}

library.json

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

library.properties

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