Lights

This page describes various light settings supported by ESPurna.

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

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	W
2	WW
3	RGB
4	RGBW
5	RGBWW

MQTT

By default, topics are configured as:

• {root topic}/{state topic}
• {root topic}/{command topic}/set (ref. MQTT_SETTER build flag)

We support the following state & command topics:

• brightness
• channel/{number} (refer to the channels assigment above)
• rgb
• hsv
• mired
• kelvin (note: only command topic)

Common

State topic	Example payload
{root topic}/brightness	35 1
{root topic}/channel/{number}	128

Command topic	Example payload
{root topic}/brightness/set	200 1
{root topic}/channel/{number}/set	0

⁽¹⁾ Value ranges from 0 to 255 (ref. LIGHT_{MIN,MAX}_BRIGHTNESS build flag).

Color

State topic	Example payload
{root topic}/rgb	#FF0000 or 255,0,0 2
{root topic}/hsv	300,100,100 3
{root topic}/mired	320 5

Command topic	Example payload
{root topic}/rgb/set	#FFFFFF or 255,255,255 2 3 4
{root topic}/hsv/set	200,50,25 3
{root topic}/mired/set	400 5
{root topic}/kelvin/set	6000

⁽²⁾ HEX color prefixed with # if "Use CSS style" / useCSS setting is enabled, comma-separated values otherwise.

⁽³⁾ #RRGGBBAA values are interpreted like RGB + brightness.

⁽⁴⁾ If more than 3 channels are configured: ch0,ch1,ch2,ch3,.... ch0->R, ch1->G, ch2->B, ch3->(white or WW, or ...)

⁽⁵⁾ Value ranges from 153 to 500 (ref. LIGHT_{COLD,WARM}WHITE_MIRED build flag and / or light{Cold,Warm}Mired setting).

openHAB

Dimmer should be configured as:

Type dimmer : dimmer "Dimmer" [stateTopic = "{root topic}/brightness", commandTopic = "{root topic}/brightness/set", min=0, max=255 ]

The min/max will cause the binding to scale the value of 0-100 to match that of the ESPurna's min-max.

(ref. #1460, thanks to @CrispinP for clarification)

Terminal

Command	description
LIGHT
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)
useCSS	Use CSS (#FF0000) or comma separated values (255,0,0) for color reporting	0 (CSV) or 1 (CSS)	1 (CSS)
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 basic 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_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

---