Lights - xoseperez/espurna GitHub Wiki

This page describes various light settings supported by ESPurna.

🔴 WARNING When setting channels, be careful not to override any of the GPIO used for flash - this would normally render your board unresponsive and you would need to re-flash it using USB programmer, which is not always convenient.

Lights

PWM aka DIMMER

See PWM page for more info. When using LIGHT_PROVIDER_DIMMER, use PWM configuration to fine-tune the hardware output.

Channels

ESPurna supports up to 5 individual "channels" by defining LIGHT_CHANNELS={0..5}. With 1 or 2 channels, first one is considered Warm White. Second one is Cold White. If 3 or more channels are configured, first 3 will be configured as RGB and the last 2 will be Warm White and Cold White respectively.

Usual configurations are:

Number of channels Color configuration
1 WARM WHITE
2 WARM WHITE + COLD WHITE
3 RGB
4 RGB + WARM WHITE (aka RGBW)
5 RGB + WARM WHITE + COLD WHITE (aka RGBWW)

Terminal

Command description
brightness <value> Sets RGB brightness (only for lights)
channel <id> <value> Sets value for channel #id (only for lights)
color <value> Sets RGB color (only for lights)
kelvin Sets the temperature color in Kelvin (only for lights)
mired Sets the temperature color in Mired (only for lights)

Settings

Key Description Possible values Default value
brightness Brightness value 0 to 255 255
ch# Value for the n-th channel 0 to 255 0
useColor Use first 3 channels for RGB 0 (no) or 1 (yes) 1 (yes)
useGamma Use gamma correction for color channels 0 (no) or 1 (yes) 0 (no)
useWhite Use white channel if all 3 RGB have the same value 0 (no) or 1 (yes) 0 (no)
useRGB Use first three channels as color channels (only if light has at least 3 ch) 0 (no) or 1 (yes) 1 (yes)
useTransitions Use color transitions 0 (no) or 1 (yes) 1 (yes)
lightColdMired 153..500 LIGHT_COLDWHITE_MIRED=153
lightWarmMired 153..500 LIGHT_WARMWHITE_MIRED=500

Build-time configuration

Option Note
LIGHT_MIN_VALUE={0..255}
LIGHT_MAX_VALUE={0..255}
LIGHT_MIN_BRIGHTNESS={0..255}
LIGHT_MAX_BRIGHTNESS={0..255}
LIGHT_COLDWHITE_MIRED=153 Default value should be changed if the light has different limits!
LIGHT_WARMWHITE_MIRED=500 Default value should be changed if the light has different limits!
LIGHT_USE_WHITE={0,1} Use 4th channel independently (0) or include it in brightness calculation (1)
LIGHT_USE_CCT={0,1} Use both white channels. Depends on USE_WHITE
LIGHT_USE_GAMMA={0,1} Use gamma table instead of using RGB channel values directly
LIGHT_USE_TRANSITIONS={0,1} Gradually scale channel value instead of changing it right away
LIGHT_TRANSITION_STEP=10 (ms)
LIGHT_TRANSITION_TIME=500 (ms)
LIGHT_STEP=... How much to scale channel value with each "step" of the transition

Providers

To change the current provider, set the LIGHT_PROVIDER flag.

Light provider Build flag
Basic dimmer LIGHT_PROVIDER_DIMMER (default)
my92xx LIGHT_PROVIDER_MY92XX

Dimmer

This will enable support for generic dimmer, where each channel is controlled via PWM on specified GPIO pins. Current channel value (ranging from 0 to 255) will be scaled to the appropriate PWM frequency (MIN_PWM and MAX_PWM).

Option Note
LIGHT_CH#_PIN
LIGHT_MIN_PWM={0..10000}
LIGHT_MAX_PWM={0..10000}
LIGHT_LIMIT_PWM=LIGHT_MAX_PWM
Key Description Possible values Default value
ltDimmerGPIO# GPIO pin for channel # 0-5,12-15 LIGHT_CH1_PIN for channel 0, LIGHT_CH2_PIN for channel 1 etc.
ltDimmerInv# Invert values when setting PWM 0 (no) or 1 (yes) 0 (no)

my92xx

Enable support of MY9291 and MY9231. Options are taken from the my92xx library, please reference it's documentation.

Option Note
MY92XX_MODEL MY92XX_MODEL_MY9231 or MY92XX_MODEL_MY9291
MY92XX_CHIPS=
MY92XX_DI_PIN=
MY92XX_DCKI_PIN=
MY92XX_COMMAND=MY92XX_COMMAND_DEFAULT
MY92XX_MAPPING= Map hardware channels to software ones