lifxlan talks to LIFX bulbs over the local network

What the library covers and what it does not

lifxlan is a Python 3 module for locally controlling LIFX devices over a LAN, and it implements the LIFX LAN Protocol specification. The device coverage is broad: white, colour, multizone devices such as the LIFX Z and LIFX Beam, infrared with the LIFX+, and chain devices with the LIFX Tile, plus group-based control over arbitrary sets of lights. It also supports Unicode characters in names, groups and locations, which sounds like a minor point and is not, since a light called Café or a group called Küche is a normal thing to want. The README frames the library three ways: you can control devices with its high-level API, you can build your own high-level API on top of the low-level networking messages, and you can build virtual LIFX devices in software, for example adapters that make a set of Philips Hue bulbs look like LIFX devices to whatever is talking to them.

The class hierarchy is the design

The module list in the README is the whole API surface. lifxlan.py provides the LifxLAN class, which represents the local network, and a low-level API for sending broadcast packets. device.py provides the Device API and the low-level API for unicast packets to a device. light.py provides the Light API as a subclass of Device, multizonelight.py provides the MultiZoneLight API as a subclass of Light, tilechain.py provides the TileChain API, also a subclass of Light, and group.py provides the Group API, which lets you perform synchronized actions on groups of devices. The inheritance chain is doing real work: a multizone light is a light, a light is a device, and the low-level packet senders live at the layer that owns the transport. That structure is also why the README says to instantiate Light objects directly with a MAC and IP address when you already know them, since it bypasses discovery entirely.

Discovery is the slow path, and broadcast is the fast one

Creating a LifxLAN object is the simplest thing in the library:

lan = LifxLAN()
lan = LifxLAN(num_lights)   #this will make discovery go faster if all lights are responsive

Passing the number of lights you expect speeds up discovery when every device is responsive. The README is candid about the cost of the automatic path: the examples use automatic device discovery to find individual bulbs, which causes a short but noticeable delay, and the way to avoid it is either to instantiate Light objects directly using their MAC and IP address, which you can learn by running examples/hello_world.py, or to use the broadcast methods. The broadcast scripts, broadcast_on.py, broadcast_off.py and broadcast_color.py, let you send commands to all lights quickly from the command line without any discovery at all. For a room-wide scene change, that is the path to use.

The broadcast API and what the parameters mean

The LifxLAN methods cover discovery, filtering and whole-LAN control. There are getters that return the lights, the colour-capable lights, the infrared-capable lights, the multizone lights and the tile chain lights, plus name, group and location lookups that return a Device or a Group object. The bulk setters are set_power_all_lights, set_color_all_lights and set_waveform_all_lights, with matching getters that return dicts of Light and value pairs. The parameter conventions are spelled out in the comment block above the method list. Power can be on or off, True or False, 0 or 1, or 0 and 65535, and colour is a list of HSBK values with hue, saturation and brightness in the 0 to 65535 range and Kelvin between 2500 and 9000. Duration is the transition time in milliseconds. The rapid flag skips waiting for successful confirmation and sends multiple packets instead, and the README marks it as intended for super-fast light shows with lots of changes rather than normal use.

Device-level methods expose the hardware state

Because the LIFX protocol treats all lights as devices, the Device API is broad. There are setters for label and power, and getters for MAC address, IP address, service, which returns an integer where 1 means UDP, and port. There is a cluster of firmware getters: the host firmware tuple as a build timestamp in nanoseconds plus a version, the host firmware build timestamp and version separately, the Wi-Fi information tuple as signal in milliwatts with transmit and receive byte counts, the Wi-Fi signal and byte counters individually, the Wi-Fi firmware tuple and its parts, and a version tuple of vendor, product and version. Location and group are exposed too, with the location id as a sixteen byte bytearray, a location tuple pairing the id with the label and an updated-at timestamp in unsigned 64 bit epoch time, and the same shape for group. This is the layer to use for health checks on an installation.

Installing it and what it depends on

Installation is a single pip command, and the setup script shows the dependency surface is deliberately tiny:

      install_requires=[
        "bitstring",
        "ifaddr"
      ],

bitstring handles the binary protocol fields, and ifaddr identifies the local network interfaces so the library can pick the right one for broadcast. The rest of the setup metadata reads the version, description, url, author and licence out of lifxlan/__init__.py with a regular expression, so the package metadata lives in one place. The classifier list is short, with an MIT licence classifier and Python 3 support, and the package is marked not zip safe. Two dependencies for a protocol library is a good sign, because it means the code is doing the protocol work itself rather than delegating to a large framework. The README also mentions installing from source with setup.py install if you want the most recent fixes rather than the latest stable release.

Where lifxlan is the wrong choice

Three cases. The first is a user who wants cloud-managed LIFX features, since this library talks to devices on your LAN and knows nothing about accounts, remote access or vendor scenes. The second is a script that has to run on a machine with no route to the bulbs, whether that is a cloud function or a container on another subnet, because the discovery and broadcast model assumes local reachability. The third is a project that already depends on the official LIFX SDK and wants identical behaviour, since an independent implementation can differ in edge cases and you would be debugging protocol details rather than your own logic. Against a general home automation platform, the difference in approach is that lifxlan gives you direct, immediate, per-device control with no broker in the middle, which is why the examples include blink, breathe, rainbow, multizone chase, shimmering leaves and tile chain invader scripts. The cost is that you write the scene logic yourself, and that a LIFX Tile chain is addressed as a chain object rather than as a set of individually addressable zones, so the API shape depends on the hardware you bought.

Editorial conclusion

lifxlan is a good fit for a home automation script, a lighting installation, or a hardware project that needs to address LIFX bulbs directly on the LAN without going through a vendor cloud, since the library speaks the documented protocol and covers colour, multizone, infrared and tile chain devices through one hierarchy of classes. It is a poor fit for a LIFX account setup that expects cloud-managed scenes, and a poor fit for a deployment that needs the exact protocol behaviour of the official SDK. Check three things before you adopt it: that your bulbs are on the same network segment as the machine running the script, since discovery is broadcast based, that you understand the discovery delay, because the examples are written to use automatic discovery and the README notes this causes a short but noticeable delay you can avoid by instantiating Light objects with known MAC and IP addresses, and that you are happy with the two dependencies, bitstring and ifaddr, since the setup script lists nothing else.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mclarkk/lifxlan on GitHub
4. README
5. Releases