Yeelight support for Homebridge with particular support of ceiling lights

Usage no npm install needed!

<script type="module">
  import homebridgeYeelighter from 'https://cdn.skypack.dev/homebridge-yeelighter';


Welcome to homebridge-yeelighter 👋

Version License: MIT Twitter: cellcortex

Yeelight support for Homebridge: https://github.com/nfarina/homebridge with particular focus on supporting the special features of ceiling lights.

There are many plugins for Yeelight already. This one is unique (so far) in supporting the background light that some yeelights have and also has a diffent approach to the moonlight mode (exposed as just another range for brightness).

If a light supports a background light, it will show up as a secondary service in the light accessory. If a light supports moonlight mode, the brightness will be adjusted so that the lower 50% are reserved for moonlight brightness and the upper 50% are using the "normal" mode. While this makes it simple to control the moonlight mode, it has the small drawback that setting the color-temperature will only work when in the normal light mode. I could not find an API to set the color temperature of the moonlight.

🏠 Homepage


  • node >=16.6.0
  • homebridge >=1.0.0


You might want to update npm through: $ sudo npm -g i npm@latest

Install homebridge through: $ sudo npm -g i homebridge

Follow the instructions on GitHub to create a config.json in ~/.homebridge, as described;

Install the homebridge-hue plugin through: $ sudo npm -g i homebridge-yeelighter

Edit ~/.homebridge/config.json and add the yeelighter platform provided by homebridge-yeelighter, see Configuration;


In homebridge's config.json you need to specify homebridge-yeelighter as a platform plugin. Furthermore, you need to specify what you want to expose to HomeKit. The simplest form is show below. This will enable the plugin and add all lights with their detected configuration to homekit.

"platforms": [
    "platform": "Yeelighter",
    "name": "Yeelighter",
    "timeout": 5000,
    "interval": 60000

The plugin supports setting the configuration through homebridge-config-ui-x.

You can use the override array to override the automatic configuration of the lights. An example for disabling the light with id 0x00000000deadbeef and enabling moonlight and disabling background for 0x0000000012345678:

"platforms": [
    "platform": "Yeelighter",
    "name": "Yeelighter",
    "override": [
        "id": "0x00000000deadbeef",
        "ignored": true
        "id": "0x0000000012345678",
        "background": false,
        "nightLight": true

Optional per light configuration:

  • id: string (mandatory) - the id of the light (as reported in the device config of homebridge)
  • name?: string (optional) - the name to be used in log messages
  • color?: boolean (optional) - this light is full RGB color
  • backgroundLight?: boolean (optional) - this light has a secondary color mood light
  • nightLight?: boolean (optional) - this light supports moonlight mode
  • log?: boolean (optional) - enalbe detailed logging for this light
  • offOnDisconnect?: boolean (optional) - switch the light off in homekit when it disconnects (this is for people with old-school wall switches)
  • colorTemperature?: { min: number, max: number } (optional) - colorTemperature limits in kelvin

Forcing a light to be shown (for network configs that don't support multicast)

Since the yeelights respond with their configuration to the discovery request, this information needs to be manually entered into the config. Use at your own risk - this may be screwing with your config since there's no way for Yeelighter to tell if the light is really there.

  • id: string - the id of the light (you have to find this from the app)
  • address: string - the IP address of the light
  • model: string - model (name of the light)
  • supports: string - whitespace separated list of commands that the light supports.

Setting up the lights

Make sure to enable "LAN control" for the lights you want to control. This is done in the Yeelight app either when setting up the light or in the lights settings which hide behind the ⏏ - button.

There are existing configurations for a number of lights. If your light is not supported, it will hopefully fall back to a decent fallback configuration. You can use the settings to fine-tune it. In those cases, it would be great if you could open a ticket in the issues page including the homebridge logs for the light being setup so the configuration can be added for future users.


👤 Thomas Kroeber

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!