This document discusses developing a Puppet module to control Philips Hue lights. It covers starting with discovery of the Hue API, writing Puppet types and providers to model lights as resources, adding functionality through the Hue API, testing and releasing the module, and the potential for controlling other IP-connected devices through similar modules. The document provides code examples and discusses best practices for ease of use, documentation, and testing.

1. device based
modules
making them as simple as a light switch
TP Honey
@tphoney_puppet - tp@puppet.com

2. Agenda
where it started
writing puppet code
adding new functionality
the final mile - release
making life easy
where does this lead
Q&A
2simple_hue

3. where it started
3

4. Why it started
4simple_hue
the team

5. Why it started
5simple_hue
the office

6. Why it started
kitchen
6simple_hue

7. the Hue experience
Hue hub + bulbs lamp shade
7simple_hue
+ = AWESOME

8. Baby steps - discovery
8simple_hue
to control the hue:
● IP address (upnp scanner helps)
● developer key
Useful starting points:
● http://IP_OF_HUE/debug/clip.html
● http://www.developers.meethue.com/docu
mentation/getting-started
● http://www.developers.meethue.com/docu
mentation/lights-api

9. the initial probe
● curl is your friend, a bad bad friend
● the api debugger for the hue is way more
helpful
9simple_hue

10. The big bang moment
● using api’s to change the world
around you.
● still only a light switch :)
10simple_hue
exec {'change-lights': command => "curl -X PUT
http://9.9.9.9/api/asodasd/lights/1 {"name":"Bedroom Light"}",
require => [ Package['curl']],
}

11. writing puppet code
11

12. Writing code is hard - let's borrow it
12simple_hue

13. how much code do you need
13simple_hue

14. puppet resource (get the state)
As a user I want to be able to retrieve the state of the philips light bulb
- self-instances > create http connection > get http uri
puppet apply (set the state)
As a user I want to be able to set the state of the philips light bulb
- self-instances > create http connection > get http uri > flush > put http uri
where to start - mvp / use cases
14

15. Provider
- self-instances
- flush
where to start - class diagram
15
Type
- attributes
Parent class
- create http connection
- get http uri
- put http uri
- boiler plate code

16. what is a type
Puppet::Type.newtype(:hue_light) do
newparam(:name) do
desc 'The light name'
isnamevar
end
newproperty(:on) do
desc 'is the light on'
end
newproperty(:hue) do
desc 'hue of the hue_light'
end
end
16simple_hue

17. provider code
17simple_hue
def self.instances
instances = []
lights = Puppet::Provider::Hue.hue_get('lights')
return [] if lights.nil?
lights.each do |light|
instances << new(:name => light.first,
:on => light.last['state']['on'].to_s,
:hue => light.last['state']['hue'].to_s)
end
instances
end
def flush
name = @original_values[:name]
@property_hash = @property_hash.reject { |k, _v|
!resource[k] }
@property_hash.delete(:name)
@property_hash[:hue] = @property_hash[:hue].to_i
result =
Puppet::Provider::Hue.hue_put("lights/#{name}/state",
@property_hash)
end

18. the ugly side - parent class
18simple_hue
def self.connection
@connection = Faraday.new(:url =>
"http://#{hue_ip}/api/#{hue_key}", :ssl => { :verify =>
false })
end
def self.hue_get(url, args = nil)
url = URI.escape(url) if url
result = connection.get(url, args)
output = JSON.parse(result.body)
rescue JSON::ParserError
return nil
end
def self.hue_put(url, message)
message = message.to_json
message.gsub!(/"false"/, 'false')
message.gsub!(/"true"/, 'true')
connection.put(url, message)
end

19. types and providers
some great blog posts
http://garylarizza.com/blog/2013/11/25/fun-with-
providers/
http://garylarizza.com/blog/2013/11/26/fun-with-
providers-part-2/
http://garylarizza.com/blog/2013/12/15/seriously
-what-is-this-provider-doing/
AWS and azure
19simple_hue

20. setting up the environment
20

21. setting up the environment
21
ITS MESSY TO START

22. iterate iterate iterate
22simple_hue

23. switching the light off and on
● writing a manifest
● using puppet resource
● using puppet apply
23simple_hue

24. adding new functionality
24

25. living life to the max
25simple_hue

26. adding funk-tionality
26

27. let’s look at the philips API
27simple_hue
FLASHY LIGHTS

28. Live coding - hopefully
28simple_hue

29. the final mile - release
29

30. ease of use - users
have a readme
simple examples
naming is hard
dependency hell
semver
30simple_hue

31. ease of use - developers
docs / urls for apis
code snippets
debugging
copy pasta for contributors (readme,
test, code)
how to set up an environment
dependency hell
31simple_hue

32. going for approval
avoiding common mistakes:
● start early
● follow the docs guides
● write tests / any tests
why it’s good:
● attracts users
● attracts developers
● you’ll get noticed
32simple_hue

33. acceptance testing
painful but worth it / hard work already done with
the environment setup
peace of mind
ensuring your code will be maintained over time.
33simple_hue

34. Puppet device
https://github.com/tphoney/simple_hue_device
34simple_hue

35. where does this lead
35

36. technology impact
if you can control a $10 light bulb. you can
control a $100,000 switch
we can control anything with an ip
agentless FTW
someone could fork your branch into something
really weird and awesome
36simple_hue

37. last minute win - auto-generation of code
Netconf - yang
built on simple_hue
same architecture (if you can call it that)
80% of the code is generated
37simple_hue

38. Q&A
38
https://forge.puppet.com/tphoney/simple_hue