JLed - Advanced LED Library

An embedded C++ library to control LEDs. It uses a non-blocking approach and cancontrol LEDs in simple (on/off) and complex (blinking,breathing and more) ways in a time-driven manner.

JLed got some coverage on Hackadayand someone did a video tutorial for JLed - Thanks!

Example

// breathe LED (on gpio 9) 6 times for 1500ms, waiting for 500ms after each run
#include <jled.h>

auto led_breathe = JLed(9).Breathe(1500).Repeat(6).DelayAfter(500);

void setup() { }

void loop() {
  led_breathe.Update();
}

Contents

• Features
• Cheat Sheet
• Installation
  • Arduino IDE
  • PlatformIO
• Usage
  • Effects
    • Static on and off
      • Static on example
    • Blinking
      • Blinking example
    • Breathing
      • Breathing example
    • Candle
      • Candle example
    • FadeOn
      • FadeOn example
    • FadeOff
    • User provided brightness function
      • User provided brightness function example
    • Delays and repetitions
      • Initial delay before effect starts
      • Delay after effect finished
      • Repetitions
    • State functions
      • Update
      • IsRunning
      • Reset
      • Immediate Stop
    • Misc functions
      • Low active for inverted output
      • Maximum brightness level
  • Controlling a group of LEDs
• Framework notes
• Platform notes
  • ESP8266
  • ESP32
  • STM32
    • Arduino framework
  • Raspberry Pi Pico
• Example sketches
  • PlatformIO
  • Arduino IDE
• Extending
  • Support new hardware
• Unit tests
• Contributing
• FAQ
  • How do I check if a JLed object is still being updated?
  • How do I restart an effect?
  • How do I change a running effect?
• Author and Copyright
• License

Features

• non-blocking
• effects: simple on/off, breathe, blink, candle, fade-on, fade-off, user-defined (e.g. morse)
• supports inverted polarity of LED
• easy configuration using fluent interface
• can control groups of LEDs sequentially or in parallel
• Portable: Arduino, ESP8266, ESP32, Mbed, Raspberry Pi Pico and more platformscompatible, runs even in the browser
• supports Arduino, mbed and Raspberry Pi Pico SDKs
• well tested

Cheat Sheet

Installation

Arduino IDE

In the main menu of the Arduino IDE, select Sketch > Include Library >Manage Libraries... and search for jled, then press install.

PlatformIO

Add jled to your library dependencies in your platformio.ini project file,e.g.

...
[env:nanoatmega328]
platform = atmelavr
board = nanoatmega328
framework = arduino
lib_deps=jled
...

Usage

First, the LED object is constructed and configured, then the state is updatedwith subsequent calls to the Update() method, typically from the loop()function. While the effect is active, Update returns true, otherwisefalse.

The constructor takes the pin, to which the LED is connected to asthe only argument. Further configuration of the LED object is done using a fluentinterface, e.g. JLed led = JLed(13).Breathe(2000).DelayAfter(1000).Repeat(5).See the examples section below for further details.

Effects

Static on and off

Calling On() turns the LED on. To immediately turn a LED on, make a calllike JLed(LED_BUILTIN).On().Update().

Off() works like On(), except that it turns the LED off, i.e. it sets thebrightness to 0.

Use the Set(uint8_t brightness) method to set the brightness to the givenvalue, i.e. Set(255) is equivalent to calling On() and Set(0) isequivalent to calling Off().

Technically Set, On and Off are effects with a period of 1ms thatset the brightness to a constant value.

Static on example

#include <jled.h>

// turn builtin LED on after 1 second.
auto led = JLed(LED_BUILTIN).On().DelayBefore(1000);

void setup() { }

void loop() {
  led.Update();
}

Blinking

In blinking mode, the LED cycles through a given number of on-off cycles, on-and off-cycle durations are specified independently. The Blink() method takesthe duration for the on- and off cycle as arguments.

Blinking example

#include <jled.h>

// blink internal LED every second; 1 second on, 0.5 second off.
auto led = JLed(LED_BUILTIN).Blink(1000, 500).Forever();

void setup() { }

void loop() {
  led.Update();
}

Breathing

In breathing mode, the LED smoothly changes the brightness using PWM. TheBreathe() method takes the period of the effect as an argument.

Breathing example

#include <jled.h>

// connect LED to pin 13 (PWM capable). LED will breathe with period of
// 2000ms and a delay of 1000ms after each period.
auto led = JLed(13).Breathe(2000).DelayAfter(1000).Forever();

void setup() { }

void loop() {
  led.Update();
}

Candle

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 speeddivides into halve per increment. The default value is 7.
• jitter - the amount of jittering. 0 none (constant on), 255 maximum. Defaultvalue 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 usecall the method with Candle(5 /*speed*/, 100 /* jitter*/).

Candle example

#include <jled.h>

// Candle on LED pin 13 (PWM capable). 
auto led = JLed(13).Candle();

void setup() { }

void loop() {
  led.Update();
}

FadeOn

In FadeOn mode, the LED is smoothly faded on to 100% brightness using PWM. TheFadeOn() method takes the period of the effect as an argument.

The brightness function uses an approximation of this function (example withperiod 1000):

FadeOn example

#include <jled.h>

// LED is connected to pin 9 (PWM capable) gpio
auto led = JLed(9).FadeOn(1000).DelayBefore(2000);

void setup() { }

void loop() {
  led.Update();
}

FadeOff

In FadeOff mode, the LED is smoothly faded off using PWM. The fade starts at100% brightness. Internally it is implemented as a mirrored version of theFadeOn function, i.e. FadeOn(t) = FadeOff(period-t). The FadeOff() methodtakes the period of the effect as argument.

User provided brightness function

It is also possible to provide a user defined brightness evaluator. The classmust be derived from the jled::BrightnessEvaluator class and implementtwo methods:

• uint8_t Eval(uint32_t t) const - the brightness evaluation function thatcalculates a brightness for the given time t. The brightness must be returnedas 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.

The user_func example demonstrates a simple user providedbrightness function, while the morse example shows how a morecomplex application, allowing you to send morse codes (not necessarily with anLED), can be realized.

User provided brightness function example

The example uses a user provided function to calculate the brightness.

class UserEffect : public jled::BrightnessEvaluator {
  public:
    uint8_t Eval(uint32_t t) const override {
        // this function changes between 0 and 255 and
        // vice versa every 250 ms.
        return 255*((t/250)%2);
    }
    // duration of effect: 5 seconds.
    uint16_t Period() const override { return 5000; }
};

Delays and repetitions

Initial delay before effect starts

Use the DelayBefore() method to specify a delay before the first effect starts.The default value is 0 ms.

Delay after effect finished

Use the DelayAfter() method to specify a delay after each repetition ofan effect. The default value is 0 ms.

Repetitions

Use the Repeat() method to specify the number of repetitions. The defaultvalue is 1 repetition. The Forever() methods sets to repeat the effectforever. Each repetition includes a full period of the effect and the timespecified by DelayAfter() method.

State functions

Update

Call Update() periodically to update the state of the LED. Update returnstrue if the effect is active, and false when it finished.

IsRunning

IsRunning() returns true if the current effect is running, else false.

Reset

A call to Reset() brings the JLed object to its initial state. Use it whenyou want to start-over an effect.

Immediate Stop

Call Stop() to immediately turn the LED off and stop any running effects.Further calls to Update() will have no effect unless the Led is reset (usingReset()) or a new effect activated.

Misc functions

Low active for inverted output

Use the LowActive() method when the connected LED is low active. All outputwill be inverted by JLed (i.e. instead of x, the value of 255-x will be set).

Maximum brightness level

The MaxBrightness(uint8_t level) method is used to set the maximum brightnesslevel of the LED. A level of 255 (the default) is full brightness, while 0effectively turns the LED off.

The uint_8 MaxBrightness() const method returns the current maximumbrightness level. Since currently only the upper 5 bits of the providedbrighness value are used, the lower 3 bits returned are always 0.

If you want to programmatically increment or decrement the maximum brightnesslevel, use the JLed::kBrightnessStep constant (which is defined as 1 << (8-JLed::kBitsBrightness) as the increment (instead of the hard wired value8) to be independent of the current JLed implementation using 5 bits.

Controlling a group of LEDs

The JLedSequence class allows controlling a group of JLed objectssimultaneously, either in parallel or sequentially, starting the next JLedeffect when the previous finished. The constructor takes the mode (PARALLEL,SEQUENCE), an array of JLed objects and the size of the array, e.g.

JLed leds[] = {
    JLed(4).Blink(750, 250).Repeat(10),
    JLed(3).Breathe(2000).Repeat(5);
};

auto sequence = JLedSequence(JLedSequence::eMode::PARALLEL, leds).Repeat(2);

void setup() {
}

void loop() {
    sequence.Update();
}

Because the size of the array is known at compile time in this example, it isnot necessary to pass the array size to the constructor. A second constructoris available in case the JLed array is created dynamically at runtime:JLed(eMode mode, JLed* leds, size_t n).

The JLedSequence provides the following methods:

• Update() - updates the active JLed objects controlled by the sequence.Like the JLed::Update() method, it returns true if an effect is running,else false.
• Use the Repeat(n) method to specify the number of repetitions. The defaultvalue is 1 repetition. The Forever() methods sets to repeat the sequenceforever.
• Stop() - turns off all JLed objects controlled by the sequence andstops the sequence. Further calls to Update() will have no effect.
• Reset() - Resets all JLed objects controlled by the sequence andthe sequence, resulting in a start-over.

Framework notes

JLed supports the Arduino and mbed frameworks. Whenusing platformio, the framework to be used is configured in the platform.inifile, as shown in the following example, which for example selects the mbedframework:

[env:nucleo_f401re_mbed]
platform=ststm32
board = nucleo_f401re
framework = mbed
build_flags = -Isrc 
src_filter = +<../../src/>  +<./>
upload_protocol=stlink

An mbed example is provided here.To compile it for the F401RE, make your plaform.ini look like:

...
[platformio]
default_envs = nucleo_f401re_mbed
src_dir = examples/multiled_mbed
...

Platform notes

ESP8266

The DAC of the ESP8266 operates with 10 bits, every value JLed writes out getsautomatically scaled to 10 bits, since JLed internally only uses 8 bits. Thescaling methods make sure that min/max relationships are preserved, i.e. 0 ismapped to 0 and 255 is mapped to 1023. When using a user-defined brightnessfunction on the ESP8266, 8-bit values must be returned, all scaling is done byJLed transparently for the application, yielding platform-independent code.

ESP32

The ESP32 Arduino SDK does not provide an analogWrite() function. Tobe able to use PWM, we use the ledc functions of the ESP32 SDK.(See esspressif documentation for details).

The ledc API connects so-called channels to GPIO pins, enabling them to usePWM. There are 16 channels available. Unless otherwise specified, JLedautomatically picks the next free channel, starting with channel 0 and wrappingover after channel 15. To manually specify a channel, the JLed object must beconstructed this way:

auto esp32Led = JLed(jled::Esp32Hal(2, 7)).Blink(1000, 1000).Forever();

The jled::Esp32Hal(pin, chan) constructor takes the pin number as the firstargument and the ESP32 ledc channel number on the second position. Note thatusing the above-mentioned constructor yields non-platform independent code, soit should be avoided and is normally not necessary.

STM32

Arduino framework

I had success running JLed on a STM32 Nucleo64 F401REboard using thisSTM32 Arduinocoreand compiling examples from the Arduino IDE. Note that the stlink isnecessary to upload sketches to the microcontroller.

Raspberry Pi Pico

When using JLed on a Raspberry Pi Pico, the Pico-SDK and tools must beinstalled. The Pico supports up to 16 PWM channels in parallel. Seethe pico-demo for an example and build instructions.

Example sketches

Example sketches are provided in the examples directory.

• Hello, world
• Turn LED on after a delay
• Breathe effect
• Candle effect
• Fade LED on
• Fade LED off
• Controlling multiple LEDs in parallel
• Controlling multiple LEDs in parallel (mbed)
• Controlling multiple LEDs sequentially
• Simple User provided effect
• Morsecode example
• Custom HAL example
• JLed compiled for WASM and running in the browser
• Raspberry Pi Pico Demo

PlatformIO

To build an example using the PlatformIO ide,uncomment the example to be built in the platformio.iniproject file, e.g.:

[platformio]
; uncomment example to build
src_dir = examples/hello
;src_dir = examples/breathe

Arduino IDE

To build an example sketch in the Arduino IDE, select an example fromthe File > Examples > JLed menu.

Extending

Support new hardware

JLed uses a very thin hardware abstraction layer (hal) to abstract access tothe actual MCU/framework used (e.g. ESP32, ESP8266). The hal object encapsulateaccess to the GPIO and time functionality of the MCU under the framework beingused. During the unit test, mocked hal instances are used, enabling tests tocheck the generated output. The Custom HAL projectprovides an example for a user define HAL.

Unit tests

JLed comes with an exhaustive host-based unit test suite. Info on how to runthe host-based provided unit tests is provided here.

Contributing

• fork this repository
• create your feature branch
• add code
• add unit test(s)
• add documentation
• make sure the cpp linter does notreport any problems (run make lint). Hint: use clang-format with theprovided settings
• commit changes
• submit a PR

FAQ

How do I check if a JLed object is still being updated?

• Check the return value of the JLed::Update method: the method returns true ifthe effect is still running, otherwise false.
• The JLed::IsRunning method returns true if an effect is running, else false.

How do I restart an effect?

Call Reset() on a JLed object to start over.

How do I change a running effect?

Just 'reconfigure' the JLed with any of the effect methods (e.g. FadeOn,Breathe, Blink etc). Time-wise, the effect will start over.

Author and Copyright

Copyright 2017, 2018 by Jan Delgado, jdelgado[at]gmx.net.

License

MIT