Web Client WuClass | WuKong Release 0.4 English Version

7.2 Web Client WuClass for Philip Hue

In this section, we show how to create and use the Philip Hue WuClass in FBP.

Controlling Philip Hue Light in WuKong
1. To allow users build their own apps, Philip Hue provides the HTTP API to get information and control Hue systems. Before using HTTP API, we must get the URL address of the Hue hub. Please follow http://www.developers.meethue.com/documentation/getting-started to find the URL address by API Debugger Tool. The URL address will be something like:
```
/api/1028d66426293e821ecfd9ef1a0731df/lights
```
  The long number above is the username of the Philip Hue Bridge, which is created if you follow the instructions of the above website.
2. Go to the directory of Philip Hue WuClass and change the URL address definition in a Philip Hue utility file according to your bridge.
```
cd <path_of_source_code>/wukong-darjeeling/wukong/gateway/udpwkpf/
vim udpdevice_philip_hue_*.py  
# change the user around line34 according to user name of your hue hub.
```
3. Add udpdevicephilip_hue*.py to WuKong according to Section 5.2.
4. Create the FBP and set the initial value
  
  An example Philip Hue FBP can be seen as below. Button is used to turn on/off Philip Hue Bulb, and slider is used to adjust the intensity of the red color. The rest of properties can be filled in the left menu, which will pop up once the Philip Hue component is clicked.
  
  Currently, WuKong has not supported string type, so we have to convert ip address to integer first. Since the integer length in the WuKong is only 2 bytes, we have to use two properties ip_high and ip_low to indicate the ip address of Philip Hue bridge. Here is an example:
  
  index is the id of each Philip Hue lamp, which shows on the Hue app as below.
  
  The range of rgb light intensity is from 0 to 254. The number filled in this blank will be set as the default value for the FBP component.
5. Deploy this FBP according to Section 5.3
Implementing Web Client WuClass

In the following, we're going to see how web client WuClass is implemented to control the color and on/off state of Philip Hue. Through web client wuclass, we can also connect to other IoT products which provide HTTP API as Philip Hue. Since Hue has a series of products and all of them can be controlled by the same HTTP API, we create an utility file with commonly used classes to avoid repetition codes. This utility file is philip_hue_utils.py as below.

Note: please refer to Twisted official website for more detailed information about how to use Twisted wevb client. (http://twistedmatrix.com/documents/current/web/howto/client.html)

http_get_path and http_put_path are defined according to HTTP API of Philip Hue.
put_command is a method used to send HTTP PUT request. The parameters include a request method, a request URI, the request headers, and an object which can produce the request body. The agent is responsible for resolving the hostname into an IP address and connecting to it.
get_gamma is used to send HTTP GET request to retrieve gamma value from Hue. Since the gamut of Hue products fall into three different areas and not all of the RGB values can be mapped to those gamuts, we need to calibrate each RGB value with gamma value.
The Response object of HTTP GET request has a deliverBody method which makes the response body available.
The BeginningPrinter protocol in this example is passed to Response.deliverBody and the response body is then delivered to its dataReceived method as it arrives.
After the content of HTTP body is parsed, the gamma value can be determined.
When the body has been completely delivered, the protocol's connectionLost method is called.

Next, the WuClass below uses the web client in the utility file to control Philip Hue.

Import web client from the utility file.
With the property value of Hue bridge ip, username, and index, an object of web client can be created.
Too frequent requests will cause Hue bridge to postpone reponse or drop message, so we have to set a minimum request period to ensure the functionality. In this case, the minimum period is set as 0.55 sec.
Use the method of web client to get gamma value.
Use gamma value to calibrate the RGB value.
These two commands will be sent to the Hue bridge as a HTTP body.
FileBodyProducer is responsible to produce a HTTP body object.
Use put_command to send HTTP request to the Hue bridge.

7.2 Web Client WuClass for Philip Hue

Controlling Philip Hue Light in WuKong

Implementing Web Client WuClass