Update light entity docs according to arch #123

docs/core/entity/light.md

@@ -10,28 +10,58 @@ A light entity controls the brightness, hue and saturation color value, white va
 
 | Name | Type | Default | Description
 | ---- | ---- | ---- | ----
-| brightness | int | None | Return the brightness of this light between 0..255
+| brightness | int | None | Integer between 0 and 255 representing the light's brightness, where 0 means the light is off, 1 is the minimum brightness and 255 is the maximum brightness supported by the light. This controls the brightness of all channels (R,G,B,WW,CW). 50% brightness means all channels are at most 50% on.
-| color_temp | int | None | Return the CT color value in mireds.
+| color_temp | int | None | The color temperature in mireds. At the coldest possible color_temp, only the cold white channel is on and the warm white cahnnel is off. At the warmest possible color_temp, only the warm white channel is on and the cold white cahnnel is off. 
-| effect | String | None | Return the current effect.
+| effect | String | None | The current effect.
 | effect_list | list | None | Return the list of supported effects.
-| hs_color | list | None | Return the hue and saturation color value [float, float].
+| hs_color | list | None | The ligh'ts color represented as hue and saturation [float, float].
-| is_on    | bool | bool  | Returns if the light entity is on or not.  
+| is_on    | bool | bool  | If the switch is currently on or off. If is_on is false, all channels (R,G,B,WW,CW) are OFF.
-| max_mireds | int | int | Return the warmest color_temp that this light supports.
+| max_mireds | int | int | The warmest color_temp that this light supports.
-| min_mireds | int | int | Return the coldest color_temp that this light supports.
+| min_mireds | int | int | The coldest color_temp that this light supports.
+| rgb_color | list | None | The color represented as RGB [int, int, int]. Each channel is between 0..255. The color is normalized, meaning the RGB representation is not scaled for brightness.
 | supported_features | int | int | Flag supported features.
-| white_value | int | None | Return the white value of this light between 0..255.
+| white_value | int | None | Integer between 0 and 255 representing the light's white value. The white value represents the brightness of the white channel(s) (cold white and warm white) for RGBW and RGBWW lights. If white_value == 0, the light is in color mode and the white channel(s) are turned off. If white_value > 0, the light is in white mode and the color channels are turned off.
+| xy_color | list | None | The color represented as an XY-value.
+
+## Approximate channel brightness formulas for dimmable lights
+Note: The formulas are naive - actual mixing between R/G/B and cw/ww channels is not usually linear.
+
+### Simple dimmer
+brightness = int(state == 'ON') * (state.brightness/255)
+
+### White light with adjustable color temperature
+CW = int(state == 'ON') * (state.brightness/255) * (state.color_temp-state.min_mireds)/(state.max_mireds-state.min_mireds)
+WW = int(state == 'ON') * (state.brightness/255) * (state.max_mireds-state.color_temp)/(state.max_mireds-state.min_mireds)
+
+### RGB light - Full color light without separate white channel(s)
+R = int(state == 'ON') * (state.brightness/255) * (state.rgb_color[0]/255)
+G = int(state == 'ON') * (state.brightness/255) * (state.rgb_color[1]/255)
+B = int(state == 'ON') * (state.brightness/255) * (state.rgb_color[2]/255)
+
+### RGBW light - Full color light with white channel
+R = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.rgb_color[0]/255)
+G = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.rgb_color[1]/255)
+B = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.rgb_color[2]/255)
+W = int(state == 'ON') * int(state.white_value > 0) * (state.brightness/255)
+
+### RGBWW light - Full color light with white channels with adjustable color temperature
+R = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.rgb_color[0]/255)
+G = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.rgb_color[1]/255)
+B = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.rgb_color[2]/255)
+CW = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.color_temp-state.min_mireds)/(state.max_mireds-state.min_mireds)
+WW = int(state == 'ON') * int(state.white_value == 0) * (state.brightness/255) * (state.max_mireds-state.color_temp)/(state.max_mireds-state.min_mireds)
 
 ## Support Feature
 
 | Constant | Description 
 |----------|-----------------------
-| `SUPPORT_BRIGHTNESS` | Controls the brightness of a light source
+| `SUPPORT_BRIGHTNESS` | The light's brightness can be controlled
-| `SUPPORT_COLOR` | Controls the color a light source shows
+| `SUPPORT_COLOR` | The light's color can be controlled
-| `SUPPORT_COLOR_TEMP` | Controls the representation a light source shows based on temperature
+| `SUPPORT_COLOR_TEMP` | The color temperature of the light can be controlled when the light is in white mode 
-| `SUPPORT_EFFECT` | Controls the effect a light source shows
+| `SUPPORT_EFFECT` | The light supports effects such as color cycling etc.
-| `SUPPORT_FLASH` | Controls the duration of a flash a light source shows
+| `SUPPORT_FLASH` | The light can be set to flashing with controllable duration
-| `SUPPORT_TRANSITION` | Controls the duration of transitions between color and effects
+| `SUPPORT_TRANSITION` | The duration transitions between colors and effects can be controlled
-| `SUPPORT_WHITE_VALUE` | Controls the white light a light source shows.
+| `SUPPORT_WHITE_VALUE` | The light can be set in white mode
 
 ## Methods