homebridge-kasa-lightstrip

homebridge-kasa-lightstrip is a Homebridge plugin that exposes tp-link kasa light strip devices to Apple's HomeKit smart home platform.

This plugin was developed as a stop-gap to provide integration of Kasa's light strips, while the [far superior] plugin (homebridge-tplink-smarthome) lacks support!

This plugin creates Lightbulb accessories for you to integrate with your lightstrips. It can also, optionally, create stateless Switch accessories to enable Light Effects.

Prerequisites

The python-kasa library is required for this plugin. Credit to that team and the maintainers! 🏆👏

Specifically, version 0.4.0.dev3 is required, as newer iterations (0.4.1+) do not work quickly/effectively.

Installation instructions for Homebridge Raspberry Pi Image:

sudo apt install python3-pip
sudo pip3 install python-kasa==0.4.0.dev3

If you have the incorrect version you can uninstall the library with:

sudo pip3 uninstall python-kasa

Installation instructions for the onzu/homebridge Docker Container:

sudo docker exec -it homebridge sudo pip3 install python-kasa==0.4.0.dev3

...where homebridge is your container name. You can get your container name by typing sudo docker ps.

Validation

You can validate that the correct version of python-kasa library is installed by executing kasa --version at the command line of your environment:

You should see something similar the above output. If you do not, and you see something like -bash: kasa: command not found, you will need to install it (instructions above), or find a way to get it into your environment. Review the python-kasa repository for any additional instructions.

Installation Instructions

Option 1: Install via Homebridge Config UI X

Search for "kasa" in homebridge-config-ui-x and install homebridge-kasa-lightstrip.

Option 2: Manually Install

sudo npm install -g homebridge-kasa-lightstrip

Supported Devices

Kasa Light Strips

• KL400L5 - Brightness, Hue, Saturation, Effects (via stateless switch)
• KL430 - ""

Configuration

Device names and IP Addresses must be configured manually in current state:

Example

platforms: [
    {
        "platform": "HomebridgeKasaLightstrip",
        "accessories": [
            {
                "name": "Couch Strip",
                "ip": "10.10.10.10",
                "effects": {
                    "Aurora": true,
                    "Hanukkah": true,
                    "CustomEffects": [
                        {
                            "name": "MyCustomEffect1",
                            "json": "{'custom':1,'id':'xqUxDhbAhNLqulcuRMyPBmVGyTOyEMEu','brightness':100,'name':'MyCustomEffect1','segments':[0],'expansion_strategy':1,'enable':1,'type':'sequence','duration':0,'transition':1500,'direction':4,'spread':7,'repeat_times':0,'sequence':[[120,100,100],[240,100,100],[260,100,100],[280,100,100]]}"
                        }
                    ]
                }
            }
        ],
        "name": "KasaLightstrip",
        "debug": false
    }
]

• platform (mandatory): the name of the plugin
• accessories (mandatory): array containing the devices and their info:
  • name (mandatory): the name of the accessory to create
  • ip (mandatory): the IP address of the device
  • effects (optional): object containing any effects to create:
    • <effectName> (optional): boolean to enable a specific built-in effect
    • CustomEffects (optional): array containing any custom effects to create:
      • name (optional): the name of the custom effect
      • json (optional): the json for the custom effect*
• name (optional): platform name to display in logs
• debug (optional): boolean to enable more verbose logging

Lighting Effects

Stateless Switches (they turn off after 1 second) are created if you include any of the effects object in your config.json. All 14 pre-defined Lighting Effects are available to be created and toggled for any Lightstrip you configure. Additionally, custom Lighting Effects can be created.

*see CustomLightingEffects.md for more information

Characteristic Errors

Erorrs may common due to the nature of the implementation: Flooding your devices with rapid python-kasa calls may result in several dropped connections.

It is most often seen with the Brightness slider -> as you slide, the Home app can send numerous Brightness values, resulting in numerous kasa executions. You'll see the following displayed in the log:

[KasaLightstrip] StripName - Error setting characteristic 'Brightness'

Attempt to slow your inputs! 🤔 Or speed your swipe?! 🤷‍♂️

---