FadeLed
A simple Arduino library to fade leds on hardware PWM
FadeLed Class Reference

Main class of the FadeLed-library. More...

#include <FadeLed.h>

Public Member Functions

 FadeLed (byte pin)
 Simple constructor of a FadeLed object with gamma correction. More...
 
 FadeLed (byte pin, const flvar_t *gammaLookup, flvar_t biggestStep)
 Constructor of a FadeLed object. More...
 
 FadeLed (byte pin, bool hasGammaTable)
 Simple constructor of a FadeLed object. More...
 
 ~FadeLed ()
 Simple destructor of a FadeLed object. More...
 
void begin (flvar_t val)
 Set a direct begin value to start at without fade. More...
 
void set (flvar_t val)
 Set the brightness to fade to. More...
 
flvar_t get ()
 Returns the last set brightness. More...
 
flvar_t getCurrent ()
 Returns the current brightness. More...
 
bool done ()
 Returns if the LED is done fading. More...
 
void on ()
 Fade to max brightness. More...
 
void off ()
 Fade to off. More...
 
void beginOn ()
 Sets the start brightness directly to full. More...
 
void setTime (unsigned long time, bool constTime=false)
 Set the time a (full) fade will take. More...
 
bool rising ()
 Returns if the LED is still fading up. More...
 
bool falling ()
 Returns if the LED is still fading down. More...
 
void stop ()
 Stops the current fading. More...
 
void setGammaTable (const flvar_t *table, flvar_t biggestStep=100)
 Sets a gamma table to use. More...
 
void noGammaTable ()
 Use no gamma correction for full range. More...
 
flvar_t getGammaValue (flvar_t step)
 Get gamma corrected value. More...
 
flvar_t getBiggestStep ()
 Get the biggest brightness step. More...
 

Static Public Member Functions

static void update ()
 Updates all FadeLed objects. More...
 
static void setInterval (unsigned int interval)
 Sets the interval at which to update the fading. More...
 

Protected Member Functions

void updateThis ()
 Updates fading of this object only. More...
 
flvar_t getGamma (flvar_t step)
 

Protected Attributes

const byte _pin
 PWM pin to control.
 
flvar_t _setVal
 The brightness to which last set to fade to.
 
flvar_t _startVal
 The brightness at which the new fade needs to start.
 
flvar_t _curVal
 Current brightness.
 
bool _constTime
 Constant time fade or just constant speed fade.
 
unsigned long _countMax
 The number of _interval's a fade should take.
 
unsigned long _count
 The number of _interval's passed.
 
const flvar_t_gammaLookup
 Pointer to the Gamma table in PROGMEM.
 
flvar_t _biggestStep
 The biggest input step possible.
 

Static Protected Attributes

static FadeLed_ledList [FADE_LED_MAX_LED]
 array of pointers to all FadeLed objects
 
static byte _ledCount = 0
 Next number of FadeLed object.
 
static unsigned int _interval = 50
 Interval (in ms) between updates.
 
static unsigned int _millisLast = 0
 Last time all FadeLed objects where updated.
 

Detailed Description

Main class of the FadeLed-library.

The FadeLed class includes all the functions to easily fade a LED including a static function to update all constructed FadeLed objects.

See also
set(), update()

Constructor & Destructor Documentation

◆ FadeLed() [1/3]

FadeLed::FadeLed ( byte  pin)

Simple constructor of a FadeLed object with gamma correction.

Makes a object to fade a specific pin. You can make a object for each PWM pin you want to fade. Updating all objects is done by simply calling update()

When created the default brightness is 0. You can start at a different brightness by calling begin().

Note
Make all objects global (or static if you really must) because a destruct will lead to errors!
Warning
Don't make two objects for the same pin, they will conflict!
Parameters
[in]pinThe PWM pin to fade with this object
See also
FadeLed(byte, const flvar_t*, flvar_t), update(), set(), on(), off()

◆ FadeLed() [2/3]

FadeLed::FadeLed ( byte  pin,
const flvar_t gammaLookup,
flvar_t  biggestStep 
)

Constructor of a FadeLed object.

Makes a object to fade a specific pin. You can make a object for each PWM pin you want to fade. Updating all objects is done by simply calling update()

When created the default brightness is 0. You can start at a different brightness by calling begin().

With this constructor you can supply your own gamma table as gammaLookup. This must be an array of type flvar_t and should be placed in PROGMEM. Specify the largest steps in that table as biggestStep. For an example see the 'SineFade.ino' example in the examples folder.

{C++}
//put gamma table in PROGMEM
const flvar_t myGammaTable[20] PROGMEM = {....};
FadeLed ledCustom = {Pin, myGammaTable, 19};
Note
Make all objects global (or static if you really must) because a destruct will lead to errors!
Warning
Don't make two objects for the same pin, they will conflict!
Parameters
[in]pinThe PWM pin to fade with this object
[in]gammaLookupGamma table of type flvar_t in PROGMEM
[in]biggestStepThe largest possible value of the gamma table (gammaLookup).
See also
setGammaTable(), FadeLed(byte), FadeLed(byte, bool), update(), set(), on(), off()

◆ FadeLed() [3/3]

FadeLed::FadeLed ( byte  pin,
bool  hasGammaTable 
)

Simple constructor of a FadeLed object.

Simalair to FadeLed(byte) but with the possibility to disable the use of a gamma table by specifying false as hasGammaTable.

Parameters
[in]pinThe PWM pin to fade with this object
[in]hasGammaTablefalse to disable the use of a gamma table, true to use the default gamma table.
See also
FadeLed(byte)

◆ ~FadeLed()

FadeLed::~FadeLed ( )

Simple destructor of a FadeLed object.

Destroy your FadeLed object and removes it from the FadeLed::update() cycle.

Member Function Documentation

◆ begin()

void FadeLed::begin ( flvar_t  val)

Set a direct begin value to start at without fade.

If you want to directly start the LED at a certain brightness you can set it with this. This will directly set the brightness without fading.

Note
You can also use this to set a brightness without fading
See also
beginOn()
Parameters
[in]valThe brightness to start at.

◆ beginOn()

void FadeLed::beginOn ( )

Sets the start brightness directly to full.

Short for calling begin(255)

See also
begin()

◆ done()

bool FadeLed::done ( )

Returns if the LED is done fading.

true if the LED is done fading and reached the set() value.

false if it's still fading

Returns
If the LED is fading or not

◆ falling()

bool FadeLed::falling ( )

Returns if the LED is still fading down.

true if fading down.

false otherwise

Returns
if the LED is fading down

◆ get()

flvar_t FadeLed::get ( )

Returns the last set brightness.

Returns the last set brightness via set() (or begin())

See also
set(), begin()
Returns
The last set brightness

◆ getBiggestStep()

flvar_t FadeLed::getBiggestStep ( )

Get the biggest brightness step.

Gives the biggest brightness step for the gamma table in use. If no table is in use, it returns the biggest output level.

Returns
Biggest brightness step

◆ getCurrent()

flvar_t FadeLed::getCurrent ( )

Returns the current brightness.

Returns the current brightness of the output

Note
It does not return the last set value. For that, use get()
See also
get()
Returns
Current brightness of the LED.

◆ getGamma()

flvar_t FadeLed::getGamma ( flvar_t  step)
inlineprotected

Gives the output level for a given gamma step

Looks it up in the PROGMEM gamma table for this object if table is assigned. Deals with the variable size used.

Can't be called directly (it's protected) but it's inline for speed. If you want to get a gamma value for a given step, use getGammaValue() instead.

Returns
Corresponding level for the given step. Returns in if no table is in use.
Note
Does not check for out of range! That's up to the caller. For that, use getGammaValue().
See also
getGammaValue()
Parameters
[in]stepThe step to get the gamma corrected output level for.
Returns
The gamma corrected output level if a gamma table is used, otherwise it returns in.

◆ getGammaValue()

flvar_t FadeLed::getGammaValue ( flvar_t  step)

Get gamma corrected value.

Gives the gamma corrected output level. Checks for the biggest possible step.

See also
getGamma()
Parameters
[in]stepThe step to get the gamma corrected output level for. Limited to the biggest possible value
Returns
The gamma corrected output level if a gamma table is used, otherwise it returns in.

◆ noGammaTable()

void FadeLed::noGammaTable ( )

Use no gamma correction for full range.

Let this object use no gamma correction and just use the full PWM range.

It's short for setGammaTable(nullptr, FADE_LED_RESOLUTION)

See also
setGammaTable(), FADE_LED_RESOLUTION

◆ off()

void FadeLed::off ( )

Fade to off.

Sets the LED to fade to off. Same as calling set(0)

See also
set()

◆ on()

void FadeLed::on ( )

Fade to max brightness.

Sets the LED to fade to max brightness. Same as calling set(255)

See also
set()

◆ rising()

bool FadeLed::rising ( )

Returns if the LED is still fading up.

true if fading up.

false otherwise

Returns
if the LED is fading up

◆ set()

void FadeLed::set ( flvar_t  val)

Set the brightness to fade to.

Set the brightness to which the LED should fade to.

In constant fade speed if the new value is in the same fading direction as were started and the value is not yet passed the fade just continues to the new value

In constant fade time a new value is ignored if the LED is still fading

Otherwise the fade is just reset and the LED will start fading to the new brightness.

Note
To make all the fading work you need to call FadeLed::update() often in the loop()!
See also
done(), setTime()
Parameters
[in]valThe brightness to fade to.

edit 2016-11-17 Fix so you can set it to a new value while fading in constant speed. And impossible to set a new value in constant time.

edit 2016-11-30 Fixed out of range possibility

◆ setGammaTable()

void FadeLed::setGammaTable ( const flvar_t table,
flvar_t  biggestStep = 100 
)

Sets a gamma table to use.

Let this FadeLed object use a specific gamma table. This table must be put in PROGMEM to work. flvar_t can be used as variable type to get a variable type that matches the (set) bit resolution of the PWM.

{C++}
//put gamma table in PROGMEM
const flvar_t myGammaTable[20] PROGMEM = {....};
//link it to an object
//biggestStep is size - 1!
led.setGammaTable(myGammaTable, 19)

Pointing to a nullptr will result in no gamma correction. biggestStep will then limit the brightness. But easier to use noGammaTable().

{C++}
//No gamma table, 8-bit PWM
led.setGammaTable(nullptr, 255);

It will stop the current fading. It also resets it to start from 0 for the next fade.

If you want to fade from the current brightness with the new gamma table you have to find the starting value yourself and set it via begin().

By default a 101 steps (0-100 aka percentage) table is used with a gamma of 2,3. To generate a table with a different gamma you can use the provided Python script ('FadeLed\extras\GammaTable.py'). (You need to install Python for it to work!) Call it like: python GammaTable.py Gamma Steps PWMbits [VariableName]. VariableName is optional. For example python gamma.py 2.5 50 10 will result in a table with 50 steps (0 - 49) with gamma = 2,5 for a 10-bit PWM. This will be stored in gamma.h and can be copy pasted into your code.

Note
It stops and resets but does not change the PWM output. This only gets changed after a new call to set(), on(), off(), begin() or beginOn(). If no action is taken an abrupt jump will happen if not at zero brightness.
Parameters
[in]tableThe gamma table in PROGMEM
[in]biggestStepThe biggest step of that gamma table (aka size -1) If no parameter is used 100 is assumed to be the top value possible.

◆ setInterval()

void FadeLed::setInterval ( unsigned int  interval)
static

Sets the interval at which to update the fading.

Only every interval when calling update() it's checked to see if the brightness of the LEDs needs to change (fade) to leave time for other stuff.

default: 50ms

Warning
Call this before setting a fading time (via setTime()). Changing the interval will change the fading time or each FadeLed object.
See also
setTime()
Parameters
[in]intervalInterval in ms

◆ setTime()

void FadeLed::setTime ( unsigned long  time,
bool  constTime = false 
)

Set the time a (full) fade will take.

This will set how much time a fade will take.

The real fade time will be a whole multiple of the set interval (rounded down). For example, if interval is set to 50ms and you specify a fade time of 1025ms the fading time is actually set to 1000ms.

Constant fade speed (default)
In constant fade speed this is the time a fade from off to full brightness (or vice versa) will take. A fade of less will go with the same speed but will take less time

Constant fade time
In constant fade time this is the time each fade will take. No matter how much change in brightness. Each call to set() will reset the fading time and it will fade from it's current brightness to the new brightness in this time. Useful for example if you want to fade a RGB LED from one color to another in a set time. No matter the level of the individual RGB colors.

Note
If you want to change the update interval (setInterval()) do that before calling setTime(). The fade time is calculated using the interval.
See also
setInterval()
Parameters
[in]timeThe time (ms) a fade will take
[in]constTime[optional] true to use constant fade time. Default constant fading speed

◆ stop()

void FadeLed::stop ( )

Stops the current fading.

Makes the current brightness the set brightness

Useful if you fade to find the desired brightness

◆ update()

void FadeLed::update ( )
static

Updates all FadeLed objects.

This is the core function of FadeLed. Calling this function will check each object of FadeLed to see if the brightness needs changing (fade).

It's a static function, you only need to call it once for all objects of FadeLed. You can call it using the class name like:

{C++}
loop(){
}
Note
Call this function often in order not to skip steps. Make the code non-blocking aka don't use delay() anywhere! See Blink Without Delay()

Fix issue #13 Weird fade when not calling update() while not fading

◆ updateThis()

void FadeLed::updateThis ( )
protected

Updates fading of this object only.

Can't be called directly (it's protected). Instead call update() to update all FadeLed objects.

See also
update()

The documentation for this class was generated from the following files: