Detailed Description

lbuild module: modm:ui:led

Header: #include <modm/ui/led.hpp>

This module provides abstractions for animating LEDs by wrapping the modm:ui:animation* module and providing look-up tables for performing gamma correction of LED brightness.

The main functionality is part of the modm::ui::Led class, which provides a basic interface to fade an LED with an 8-bit value. Note that this class does not do any gamma correction on it's own, it just wraps an 8-bit modm::ui::Animation and a 8-bit value.

You must provide a function handler which gets called whenever the LED value needs updating, at most every 1ms, but only when the value has actually changed. The implementation of this function is up to you.

Animating LEDs

To animate the LED you need to call the modm::ui::Led::update() member function regularly. The function updates the LED value at most every 1ms, however you may call it more often than that. If the function is called less regularly, it will automatically catch up the skipped milliseconds, and execute the brightness handler at most once if the value has changed. Depending on how smooth you require your animation to be, you may call the update function with intervals of up to 250ms.

You can also pass the modm::ui::Led class directly into the modm::ui::KeyFrameAnimation class and it's derivatives, to animate it's brightness by interpolating between key frames. Note that you only need to call the update() member of the animator!

If you want to animate a lot of LEDs it is more efficient to execute all update methods inside a 1ms modm::PeriodicTimer:

Using Gamma Correction

In order to map the linearly animated brightness value to a gamma-corrected value, this module by default generates look-up tables for a gamma value of 2.2 mapping from a 256 input range to 7, 8, 10, 12 and 16 bit resolution output ranges. The generated tables have this naming schema: modm::ui::table{gamma}_{output_bits}_{input_range}.

For example, you can set up a timer to output 16-bit PWM to drive your LED, and use the modm::ui::table22_16_256 table to map the linear LED animation values to a gamma corrected 16-bit value:

You may also generate other tables using the module options, for example, if you want to map a percentage (0-100%) to LED brightness, without scaling this to the full 256 value range, you can also generate a 100 value look-up table:

This module generated the product of these options, in this case 4 look-up tables. The linker will throw out those you don't use.

You can then animate your LED in the 0-99 value range:

Note that you can also use the handler to animate LEDs which are connected externally, for example, via a WS2812 LED chain. Here you can use a helper function to map the values into an array which then transferred into the WS2812 LED chain.

Module Options

modm:ui:led:gamma: Gamma correction of values

Generated with: {2.2} in [1.0 ... 3.0]

modm:ui:led:bit: Resolution of target values

Generated with: {12, 16, 7, 8} in [2 ... 16]

modm:ui:led:range: Range of input values

Generated with: {256} in [2 ... 1024]

Variable Documentation