A HomeKit Dimmable Lightbulb 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 accessory 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.

Type	Device Type
30	Lightbulb

The following configuration is available for lightbulbs:

Section	Key	Description
Actions	"0", "1" etc.	The actions performed by the accessory
Digital Inputs	"b"	GPIOs that invoke specific actions
State & Status Inputs	"f[n]" & "g[n]"	Inputs that manage accessory state
Wildcard Actions	"y[n]"	Perform an action when an accessory reaches a target value
Accessory Notifications	"m"	Notifications to send to another accessory
Wildcard Actions	"y[n]"	Perform an action when an accessory reaches a target value
Initial State	"s"	State a lightbulb accessory enters on boot
RGBW GPIO Channels	"r", "g", "v", "w", "cw", "ww"	GPIO pins for colour controls
RGBW Factor	"fr", "fg", "fv", "fw", "fcw", "fww"	Factor to apply to colour value
Colour Transition Step	"st"	Colour step value
Automatic Dimmer Step Delay	"d"	Dimmer step delay
Automatic Dimmer Step	"e"	Dimmer step value

Example

{
  "c":{"q":850,"b":[{"g":0,"t":5}]},
  "a":[{
    "t":30,
    "r":15,
    "g":13,
    "v":12,
    "b":[{"g":0}]
  }]
}

This is an example of an RGB Lightbulb ("t":30). The PWM frequency has been set to 850Hz ("q":850) in the general configuration. The GPIO lines for the red, green & blue lights are 15, 13 & 12 respectively ("r":15, "g":13, "v":12) The on/off button is connected to GPIO 0 ("b":[{"g":0}])

Actions

Action	State	Description
"0"	Off	The default action after boot unless the Initial State has been set
"1"	On

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

RGBW GPIO Channels

Depending on the lightbulb type connected to the device you will need to define the GPIO channels to control it. Available channels are:

Key	Definition
"r"	Red channel
"g"	Green channel
"v"	Blue channel
"w"	Neutral white channel
"cw"	Cool white channel
"ww"	Warm white channel

The rules for setting these channels are as follows:

Colours	Rule
Single	Declare only the "w" option
Two Colour	Declare the "v" for cool white and "w" for warm white
RGB	Declare "r", "g" and "v" for Red, Green and Blue colours
RGBW	Declare "r", "g", "v" and "w" for Red, Green, Blue and White colors
RGB-CW-WW	Declare "r", "g", "v", "cw" and "ww" for Red, Green, Blue and Cool and Warm White colors
RGBW-CW-WW	Declare "r", "g", "v", "w", "cw" and "ww" for Red, Green, Blue and Neutral, Cool and Warm White colors

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

RGBW Factor

Define the factor to be applied to the color target value.

Available factors are:

Key	Factor
"fr"	Red
"fg"	Green
"fv"	Blue
"fw"	Neutral white
"fcw"	Cool white
"fww"	Warm white

The default factor applied is 1 but the factor can be any value from 0.01 to ∞.

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

Colour Transition Step

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

Key	Value	Description
"st"	1024	Step the colour transition value by 1024 (default)
	1 to 65535	Step value to apply to colour transitions

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.

Automatic Dimmer Step Delay

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

Key	Value	Description
"d"	1.00	Delay between dimmer steps is 1 second (default)
	0.01 to 65.50	Delay to apply between each step when dimming

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

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

Key	Value	Description
"e"	10	Automatically step the dimmer brightness by 10% (default)
	1 to 50	Brightness percentage step to apply when dimming

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

Accessory Notifications

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

Value	Notification
0	Switch is OFF (default)
1	Switch is ON

Accessory 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 accessory using the "m" option within the action object.

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

Digital Inputs

Digital Inputs "b" are supported by this accessory.

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

State and Status Inputs

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

Key	Required State
"f0"	Lightbulb off
"f1"	Lightbulb on
"f2"	Increase brightness by 10%
"f3"	Decrease brightness by 10%

Refer to State Inputs for more detail and examples.

ICMP Ping Inputs

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

Wildcard Actions

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

Key	Action
"y0"	Trigger action when lightbulb reaches a specific brightness

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.

Initial State

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