hue_rsapi

The module was created as a simple example of the new way to create a custom Type and Provider using the Resource API.

Table of Contents

1. Module Description - What the module does and why it is useful
2. Setup - The basics of getting started with hue_rsapi
   • Setup requirements
   • Getting started with hue_rsapi
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Module Description

The hue_rsapi module will connect to a Philips Hue hub and retrieve basic details of the lights that are connected to it.

The module enables the retrieval and modification of the data.

Setup

To install from source, download the tar file from GitHub and run puppet module install <file_name>.tar.gz --force.

Setup Requirements

The module has a dependency on the resource_api - it will be installed when the module is installed. Alternatively, it can be manually installed by running puppet module install puppetlabs-resource_api, or by following the setup instructions in the Resource API README.

Getting started with hue_rsapi

To get started, create or edit /etc/puppetlabs/puppet/device.conf, add a section for the device (this will become the device's certname), specify a type of philips_hue, and specify a url to a credentials file. For example:

[homehub]
type philips_hue
url file:////etc/puppetlabs/puppet/devices/homehub.conf

Next, create a credentials file containing a host and key as shown below, with the port value being optional and defaulting to 80 if not set. For more detailed information on the credentials file please see the files schema. See the HOCON documentation for information on quoted/unquoted strings and connecting the device.

host: 10.0.10.1
key:  onmdTvd198bMrC6QYyVE9iasfYSeyAbAj3XyQzfL
port: 80

To obtain an API key for the device follow the steps here: http://www.developers.meethue.com/documentation/getting-started

Test your setup and get the certificate signed:

puppet device --verbose --target homehub

This will sign the certificate and set up the device for Puppet.

See the puppet device documentation

Usage

Now you can manage your hue_light resources, See: REFERENCE.md.

Puppet Device

To get information from the device, use the puppet device --resource command. For example, to retrieve addresses on the device, run the following:

puppet device --resource --target homehub hue_light

To make changes to the light, write a manifest. Start by making a file named manifest.pp with the following content:

hue_light { '1':
  on => true,
  bri => 255,
  hue => 39139,
  sat => 255,
  effect => 'colorloop',
  alert => 'none',
}

Execute the following command:

puppet device --target homehub --apply manifest.pp

This will apply the manifest. Puppet will check if light is already configured with these settings (idempotency check) and if it finds that it needs to make changes will make the appropriate API calls.

Note that if you get errors, run the above commands with --verbose - this will give you error message output.

Development

If you do not have an active Philips Hue system handy when developing you may find the Hue-Emulator tool to be of use as it will allow you to test your changes without having an actual system in place. The tool is written in java and several differnt versions are provided as .jar files. In order to launch the emulator, you simply enter the following command into your terminal:

java -jar ./spec/fixtures/HueEmulator-v0.8.jar

Once it is running and before pressing start be sure to set the port. This can be set to whichever port that you wish, but it is advised to utilise port number 80 as it is the default port used by the module and the one that is advised by the emulator itself.

Testing

Unit Testing

Unit tests test the parsing and command generation logic, executed locally.

First execute bundle exec rake spec_prep to ensure that the local types are made available to the spec tests. Then execute with bundle exec rake spec.

Local testing can be carried out by running:

To retrieve:

bundle exec puppet device --verbose --debug --trace --modulepath spec/fixtures/modules --target=homehub --deviceconfig spec/fixtures/device.conf --resource hue_light

To set:

bundle exec puppet device --verbose --debug --trace --modulepath spec/fixtures/modules --target=homehub --deviceconfig spec/fixtures/device.conf --apply examples/hue_disco.pp