/lifx-lan-python

Python wrapper for LIFX LAN API.

Primary LanguagePythonMIT LicenseMIT

LIFX LAN python wrapper

A low-level python wrapper around the LIFX LAN v2 API. Exposes a small synchonous interface with nothing 'going on behind the scenes'.

Note: Please consult the LAN specification for any unexpected behaviour (such as receiving unknown responses etc.).

Installation

Clone this repository, then install using pip as follows:

pip install /path/to/lifx-lan-python

Now, you can import the pylifx module from anywhere.

import pylifx as lifx

lifx module

The lifx module consists of a network interface using a bound UDP socket, an internal data class for device messages derived from struct.Struct and implementations for the currently available message types, which directly maps to the message types in the LAN specification. The module is simple, two functions for posting and receiving messages to the devices is to be used together with the preconfigured message types of the LAN protocol.

lifx.post

A function that posts a message but does not wait for results. Either broadcasted to the network or targeting a single device. The device MAC-address is part of the header in all respons messages sent from the device (see lifx.get).

lifx.post(Message, v1, v2, ..., device=0, port=56700)

Argument Comment
Message The message to post, such as lifx.GetService.
v1, v2, ... Payload data for the message that maps directly to the payload in the LAN specifications (the types are according to pythons struct-module).
device Optional device address (as left-shifted 64-bit unsigned int). The default (0) will broadcast to the network.
port Port defaults to 56700. lifx.StateService returns a requested port that can be used instead.

lifx.get

A function that posts a message and yields the result (as a generator). The iteration stops after a certain amount of time or when the specified amount of results has been collected.

lifx.get(Message, Response, v1, v2, ..., device=0, ack=0, res=0, timeout=0.5, limit=None, port=56700)

Argument Comment
Message The message to post such as lifx.GetService.
Response The message to receive such as lifx.StateService.
v1, v2, ... Payload for the message.
device Optional device address.
ack Acknowledgement message required (see API spec).
res Response message required (see API spec).
timeout Defaults to 0.5 seconds. Can be set to None to block indefinitely.
limit Number of results to obtain.
port Port defaults to 56700.

The response is formatted with the data of the message header as as the first part (same for all Response types) and the payload data according to the LAN specification. These argument are the values that is not reserved for further protocol expansion, even so, they may not be of any use anyway.

(size, source, target, sequence, type), (p1, p2, ...)

Value Comment
size The byte size of the message (internal usage).
source A unique source number generated by the module (internal usage).
target The device MAC address. This value is used as device argument for targeting this device in both functions.
sequence A unique sequence number generated by the function (internal usage).
type Message type (Response.type, internal usage) .
p1, p2, ... Payload data for the response, message specific.

Messages

See LAN specification for details on payload.

Device messages

  • GetService
  • StateService
  • GetHostInfo
  • StateHostInfo
  • GetHostFirmware
  • StateHostFirmware
  • GetWifiInfo
  • StateWifiInfo
  • GetWifiFirmware
  • StateWifiFirmware
  • GetPower
  • SetPower
  • StatePower
  • GetLabel
  • SetLabel
  • StateLabel
  • GetVersion
  • StateVersion
  • GetInfo
  • StateInfo
  • Acknowledgement
  • GetLocation
  • StateLocation
  • GetGroup
  • StateGroup
  • EchoRequest

Light messages

  • LightGet
  • LightSetColor
  • LightState
  • LightGetPower
  • LightSetPower
  • LightStatePower

Example

Turn on all lights: lifx.post(lifx.LightSetPower, 65535, 0)