<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>

JLed - Advanced LED Library

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

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

<table> <tr> <th>JLed in action</th> <th>Interactive JLed playground</th> </tr> <tr> <td><a href="examples/multiled"><img alt="JLed in action" src="doc/jled.gif" width=256></a></td> <td><a href="https://jandelgado.github.io/jled-wasm"><img alt="jled running in the browser" src="doc/jled-wasm.png" width=256></a> </td> </tr> </table>

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();
}

Features
Cheat Sheet
Installation
- Arduino IDE
- PlatformIO
Usage
Framework notes
Platform notes
Example sketches
- Building examples with PlatformIO
- Building examples with the Arduino IDE
Extending
- Support new hardware
Unit tests
Contributing
FAQ
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 platforms compatible, runs even in the browser
supports Arduino, mbed, Raspberry Pi Pico and ESP32 ESP-IDF SDK's
well tested

Cheat Sheet

JLed 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 updated with subsequent calls to the Update() method, typically from the loop() function. While the effect is active, Update returns true, otherwise false.

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

Output pipeline

First the configured effect (e.g. Fade) is evaluated for the current time t. JLed internally uses unsigned bytes to represent brightness values, ranging from 0 to 255. Next, the value is scaled to the limits set by MinBrightness and MaxBrightness (optionally). When the effect is configured for a low-active LED using LowActive, the brightness value will be inverted, i.e., the value will be subtracted from 255. Finally the value is passed to the hardware abstraction, which might scale it to the resolution used by the actual device (e.g. 10 bits for an ESP8266). Finally the brightness value is written out to the configure GPIO.

┌───────────┐    ┌────────────┐    ┌─────────┐    ┌────────┐    ┌─────────┐    ┌────────┐
│ Evaluate  │    │  Scale to  │    │  Low    │YES │ Invert │    │Scale for│    │Write to│
│ effect(t) ├───►│ [min, max] ├───►│ active? ├───►│ signal ├───►│Hardware ├───►│  GPIO  │
└───────────┘    └────────────┘    └────┬────┘    └────────┘    └───▲─────┘    └────────┘
                                        │ NO                        │
                                        └───────────────────────────┘

Effects

Static on and off

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, 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 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 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

#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 takes the 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. The Breathe() 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();
}

It is also possible to specify fade-on, on- and fade-off durations for the breathing mode to customize the effect.

// LED will fade-on in 500ms, stay on for 1000ms, and fade-off in 500ms.
// It will delay for 1000ms afterwards and continue the pattern.
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. 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 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*/).

Candle example

#include <jled.h>

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

void setup() { }

v

Jled

Install / Use

README