Monitoring API

The monitoring API provides an eventlet-based polling layer allowing you to respond to changes in state of Philips Hue devices.

Note

Use of the monitoring API requires you install eventlet. You can do so using pip:

pip install eventlet

There are two stages to setting up this monitoring:

  1. Setup your the changes you wish to monitor.
  2. Call hue_api.start_monitor_loop(). Doing so will pause execution and begin monitoring for events.

For example:

def handle(resource, field, previous, current):
    print "Change from {} to {}".format(previous, current)

switch = TapSwitch.objects.get(id=3)
# Monitor the entire state of the switch
switch.monitor(field=lambda sw: sw.state.as_dict(), callback=handle, poll_interval=0.2)

light = Light.objects.get(id=1)
# Monitor only the on state of the light
light.monitor(field=lambda l: l.state.on, callback=handle, poll_interval=1)

# Start the monitoring loop
hue_api.start_monitor_loop()
print "This will never be printed!"

The value given by field will be checked every poll_interval seconds. If the values changes, callback will be called.

See MonitorMixin.monitor() for more information, and details of callback parameters.

class hueclient.monitor.MonitorMixin

Mixin to provide monitoring functionality to Resources.

monitor_class

Monitor

The Monitor class to instantiate. Provided to facilitate extending monitoring functionality.

monitor(field, callback, poll_interval=None)

Monitor field for change

Will monitor field for change and execute callback when change is detected.

Example usage:

def handle(resource, field, previous, current):
    print "Change from {} to {}".format(previous, current)

switch = TapSwitch.objects.get(id=3)
# Note that we monitor the entire state of the Hue Tap
# switch rather than a specific field
switch.monitor(lambda sw: sw.state.as_dict(), handle, poll_interval=0.2)

# Execution will stop here and the API client will begin polling for changes
hue_api.start_monitor_loop()
Parameters:
  • field (string) – The name of the field to be monitored. This may also be a callable which will be called with the resource instance as its single argument and must return a value which can be compared to previous values.
  • callback (callable) –

    The callable to be called when a change is detected. It will be called with parameters as follows:

    • resource instance
    • field name,
    • previous value
    • current value.
  • poll_interval (float) – Interval between polling in seconds. Defaults to the API’s poll_interval value (which defaults to 0.1 second.
Returns:
Return type:

Monitor
class hueclient.monitor.Monitor(resource, field, callback, poll_interval, event_queue, poll_pool)

Manages the process of monitoring a resource

field

string|callable

The field to monitor. See MonitorMixin.monitor().

resource

Resource

The Resource instance to monitor. See MonitorMixin.monitor().

callback

callable

The callback to call when complete

poll_interval

float

The interval between polls in milliseconds

event_queue

Queue

The eventlet.queue.Queue onto which to push the change events

poll_pool

GreenPool

The eventlet.greenpool.GreenPool for the eventlets tasked with polling the API

__init__(resource, field, callback, poll_interval, event_queue, poll_pool)

Initialise a Monitor instance

See above for definitions of arguments