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](PWM.md). 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](#dimmer) | `LIGHT_PROVIDER_DIMMER` (default) | 
| [my92xx](#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](https://github.com/xoseperez/my92xx), 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 |

---