The module was created as a simple example of the new way to create a custom Type and Provider using the Resource API.
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with hue_rsapi
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
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.
To install from source, download the tar file from GitHub and run puppet module install <file_name>.tar.gz --force
.
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.
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
Now you can manage your hue_light resources, See: REFERENCE.md.
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.
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.
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