A HomeKit Dimmable Lightbulb service with auto-dimmer managed by external switches/buttons. It can be Single Color, 2-channels selectable temperature color, RGB, RGBW, RGB-CW-WW and RGBW-CW-WW.

The lightbulb service has an automatic dimmer function that will continuously apply the next brightness step, with a delay between each step.

To activate it, ensure that light is on. Then, toggle twice switch or double press button. To stop, press it again once.

To use PWM, hardware must be PWM controlled. Max total PWM channels are 8.

The following configuration is available for lightbulbs:

Software PWM.

{
  "c":{"q":500,"io":[[[15,13,12],7],[[0],6]],"b":[[0,5]]},
  "a":[{
    "t":30,
    "g":[15,13,12],
    "b":[[0]]
  }]
}

This is an example of a RGB Lightbulb ("t":30).

The PWM frequency has been set to 500Hz ("q":500) in the general configuration.

The GPIO lines for the red, green & blue lights are 15, 13 & 12 respectively ("g":[15,13,12]).

The on/off button is connected to GPIO 0 ("b":[{"g":0}]).

Rotary Encoder to control brightness.

{
  "c":{
    "io":[[[12],6],[[4,5],6,0,0,1]],
    "z":0,"b":[[12,5]]
  },
  "a":[
    {"t":30,"b":[[12]]},
    {"h":0,"i":0.2,"1":{"m":[[7001,-10000],[7003,1],[7003,-1],[1,305]]},"f1":[[4,0]]},
    {"h":0,"i":0.2,"1":{"m":[[-1,-10000],[7001,1],[7001,-1],[1,605]]},"f1":[[5,0]]},
    {"h":0,"i":0.4,"0":{"m":[[-2,-10001]]}},
    {"h":0,"i":0.4,"0":{"m":[[-2,-10001]]}}
  ]
}

This is an example of a rotary encoder managing a Virtual Lightbulb ("t":30).

The on/off button is connected to GPIO 12.

Rotary encoder pins are connected to GPIOs 4 and 5.

It defines type of lightbulb based on hardware to use.

A lightbulb has two actions. The Binary Outputs "r": [ ] for each should be configured to attain the desired state.

Depending on the lightbulb type connected to the device you will need to define the GPIO channels to control it. Available channels must be in a array.

Remember to declare used GPIOs as PWM Output into "io":[...] array. See GPIOs Configuration

The rules for setting these channels with a PWM Lightbulb type are as follows:

NOTE: A two colour light is a light with 2 channels to enable a colour temperature

Mixing up this order will result in anomalous colors, so first verify these are correct.

NRZ Protocol type uses declaration as follow:

Different NRZ Lightbulbs can be declared using same GPIO but different LED ranges.

Note: NRZ is NOT supported by ESP32-C2 chips.

When NRZ Lightbulb type is selected, a NRZ Protocol must be defined. This protocol uses different times of pulses to manage an array of LEDs. By default, NRZ Protocol uses WS2812b at 800MHz times, but any other protocol times can be used.

Used GPIOs must not be into "io":[...] array.

Times are available in datasheet of each LED type. Needed vales are T0H, T1H and T0L, and must be in us (microseconds).

If several lightbulbs with NRZ Protocol and same GPIO are declared, "nrz" array must be declare only once, in one of them.

Format and some of them are:

A WS2812B 800MHz RGB LED strip with a total of 20 LEDs attached to GPIO 5:

{
  "a":[{
    "t":30,
    "ty":8,
    "g":[5,1,20]
  }]
}

A SK6812 RGBW LED strip configured in 3 segments (5, 10 and 5 LEDs) attached to GPIO 5:

{
  "a":[{
    "t":30,
    "ty":8,
    "n":4,
    "nrz":[0.3,0.6,0.9],
    "g":[5,1,5],
    "es":[{
      "t":30,
      "ty":8,
      "n":4,
      "g":[5,6,15]
    },{
      "t":30,
      "ty":8,
      "n":4,
      "g":[5,16,20]
    }]
  }]
}

Used by NRZ Protocol Lightbulb to swap channels.

Definitions are:

• 0: Red
• 1: Green
• 2: Blue
• 3: Cool white
• 4: Warm white

By default, "cm" : [ 1, 0, 2, 3, 4 ] is used, meaning that LED order is GRB (default for WS2812B 800MHz).

Declare each color in right order.

It is possible to set number of channels manually.

The new color mixing function created by Kevin Cutler (@kevinjohncutler) at https://github.com/kevinjohncutler/colormixing supports RGB, RGBW, and RGB-CW-WW, and by default it maximizes brightness and stretches the sRGB color gamut to fill the gamut of your LEDs, meaning that that colors are as saturated as possible. The defaults in HAA work well for typical LED strips, but there are a number of ways to get your bulbs looking just right. Logs are suggested. Throughout this guide we will refer to ‘chromaticity coordinates’, meaning the tuple [x,y] in the CIE xyY color space corresponding to a unique color.

Attempt to get the ‘spectrum test report’ for your bulbs. This will give the xy chromaticity coordinates for each LED, and you can put this into your MEPLHAA script as the coordinate array "ca":

The reports collected so far show that typical bulbs and strips have very similar reds and blues, with he most variation being in green and warm white. If you cannot get the test report, then you can continue to the next steps and still get good results.

Internal color calculations assume the brightness of each channel is the same, but this is never true, especially for lightbulbs, which will have many more white LEDs than RGB LEDs. Each channel will be rescaled by the entry in the flux array. The MEPLHAA script syntax is

For example, an RGB-CW-WW bulb with 4 RGB modules, 12 CW modules, and 14 WW modules should be "fa": [ 4, 4, 4, 12, 14 ]. This is equivalent to "fa": [ 2, 2, 2, 6, 7 ]. These numbers can be changed further to reflect differences in intrinsic LED flux as well (white LEDS are usually brighter than RGB, and the green LED may be brighter than the red etc.). Since channel outputs are divided by the flux array, this will lead to more accurate but less bright colors.

The current software enables users to set the act chromaticity coordinates to which the following Siri colors correspond: red, green, blue, cyan, magenta, and yellow. By default, red, green, and blue are mapped to the LED coordinates so that you will see the purest red, green, and blue that your hardware can make (that is, only one color LED is turned on). Cyan (the same as Siri teal), magenta (the same as Siri purple), and yellow are much more likely to look off, so there are two separate arrays:

• "rgb": [ rx, ry, gx, gy, bx, by ]
• "cmy": [ cx, cy, mx, my, yx, yy ]

To calibrate your lights, enable logs and tell Siri to set the light cyan. Adjust this in the Home app until you get a color that you think looks the most ‘cyan’ to you. The logs will show a "new chromaticity" every time you change a color, and once you found one you like, write it down to use as [ cx, cy ]. Do the same for magenta and yellow. Once the CMY array is in your MEPLHAA script, the bulb will now perfectly reproduce the cyan, magenta, and yellow that you chose, which should also improve the look of interpolated colors (such as orange).

The D50 standard illuminant is the default, but you can change this to make your colors warmer or cooler. For example, standard illuminant A Is a lot warmer and will shift all your whites towards the warm end of the Planckian locus. Refer to the table here for a list of standard illuminates to try. The MEPLHAA script syntax is "wp": [ wx, wy ].

Table: TO-DO

This variable is between 0 and 1 and can be used to limit the maximum LED usage to prevent overheating (though it seems like lower PWM has fixed that).

If you wish to keep your whites as bright as possible but also subdue the white LEDs for better pastels, this may be for you. This curve factor is the parameter "a" in the ‘power curve’ function 1-(exp(ax)-1)/(exp(a)-1), where x is the saturation in the range (0,1). The syntax is "cf":#, and typical ranges would be between -5 and 5. Negative values suppress the white LEDs and positive values keep them turned on (relative to how they are to begin with), so start with something like "cf":-1 if you want to play with it. While 0 technically corresponds to a linear power curve, I use this case to turn off the power curve altogether. If you want something close to linear, use "cf":0.1.

By default, lightbulb service will load last brightness, hue and saturation used values. To set initial BRI, HUE and SAT at boot, "it:" key is used.

• 1 channel: "it": [ BRI ]
• 2 channels: "it": [ BRI, TEMP ]
• 3+ channels: "it": [ BRI, HUE, SAT ]

Colour transition step is defined by the "st" key contained within the service object.

The "st" option defines the colour step value. This is the increment that will be applied to a colour value each time a step is requested, each 20ms.

Automatic dimmer step delay is defined by the "d" key contained within the service object.

This option specifies the delay in seconds to apply between each automatic dimmer step.

The option uses is a floating point value, accurate to 2 decimal places e.g. 1.14

Automatic dimmer step is defined by the "e" key contained within the service object.

This option defines the brightness step percentage that will be applied to each automatic dimmer step.

A value of 0 will disable Automatic dimmer feature.

The list of notifications "m" supported by a lightbulb are as follows:

Service notifications can be included as part of an action definition. When an action occurs any one of the above notifications can be sent to another service using the "m" option within the action object.

See the general Service Notifications section for details of how to configure these notifications.

Binary Inputs "b" are supported by this service.

See Binary Inputs for details on how to define this mandatory option.

State inputs "f[n]" & Status Inputs "g[n]" are supported by this service. The supported list is:

Refer to State Inputs for more detail and examples.

ICMP Ping inputs "p[n]" and "q[n]" are supported by this service. Refer to ICMP Ping Inputs for more detail.

Wildcard Actions "y[n]" are supported by this service. The supported list is:

The brightness is expressed as a percentage e.g. if you want to trigger a wildcard action when a lightbulb reaches 20% brightness then use {"y0": [{"v":20, "0":{...}}]}

Refer to Wildcard Actions for more detail.

The Initial Lock State about Service and Physical controls.

The Initial State key is supported by this service. Refer to Initial State for details of the available values.