                                   HueSet

-----------------------------------------------------------------------------
  Introduction:
-----------------------------------------------------------------------------

  This package contains a cross-platform (Linux and Windows) demonstration
implementation in C++ for the control of Philips Hue bulbs via their http API.
It is intended for developers as an example and is not currently refined into
an end user program.  (Philips Hue is a trademark of Philips.  This software is
unaffiliated with Philips.)

  The primary contents are a library for controlling the bulbs, and an
example console application which uses this library.  The PhilipsHue class in
PhilipsHue.h which provides functions for setting the RGB, HSV, or brightness
of individual bulbs, as well as registering/linking a new username for
access.

  The hueset program in hueset.cpp takes command line parameters for setting
the brightness or RGB values, or for running two example light show modes.
The spectrum mode cycles through the rainbow, while the christmas mode
randomly alters bulb colors between red, green, and blue to emulate Christmas
lights.

-----------------------------------------------------------------------------
  Quick start guide:
-----------------------------------------------------------------------------

  1) Edit the line of hueset.cpp which reads:
       PhilipsHue hue("192.168.0.50", "huesetuser");
     Set the correct ip address there for your Philips Hue bridge controller.

  2) If necessary, edit the line of hueset.cpp which reads:
       Data1D<u32> bulb_set{1, 2, 3};
     Set the set of bulbs you want to control with the hueset program.  If
     you are beginning with the starter kit which comes with three bulbs,
     they will start as 1, 2, and 3.

  3) Execute "make" to compile under Linux, or on Windows with ming,
     try "make hueset.exe".  Otherwise, edit the short Makefile if you need
     to adjust the compile flags for your system.  Note that C++11 is
     required for hueset.cpp.

  4) Run "./hueset link" to register the new username with your controller.

  5) Run "./hueset" to see the help, and try some of the modes.  Good luck!


-----------------------------------------------------------------------------
  Brief documentation:
-----------------------------------------------------------------------------

  The fairly self-explanatory help for hueset is:

    Manually set the color (all values range from 0 to 1.0)
      hueset <brightness>
      hueset <red> <green> <blue>

    Light show modes:
      hueset spectrum
      hueset christmas

    To register with a new bridge controller:
      hueset link

  To make use of PhilipsHue.h in your own applications, you need to copy
PhilipsHue.h, http.h, and the RC directory containing RC Lib.  These are all
released under the permissive Boost license, so there should be no
restrictions in programs you can use these in other than the "as is"
disclaimers (see LICENSE.txt for the details).

  To use the API, first use the constructor like:
    PhilipsHue hue("192.168.0.50", "huesetuser");

  Then call hue.Link() on the first execution to register a new username with
the controller.  After that, the function Bulb can be used to set the
brightness or RGB values, and BulbBSH for brightness, saturation, and hue.
Following are the function descriptions:

  // Set the address (ip address, most likely), and the username given
  // permission.
  PhilipsHue(RC::RStr address, RC::RStr username);

  // Sets a bulb's brightness (0-255), saturation (0-255) and hue (0-65535).
  // If brightness is 0, the bulb is turned off.
  void BulbBSH(u32 bulb, u32 bri_int, u32 sat_int, u32 hue_int) const;

  // Sets a bulb by RGB values (0-1.0 each).  If all three are 0, the bulb
  // is turned off.
  void Bulb(u32 bulb, f32 r, f32 g, f32 b) const;

  // Sets a bulb's brightness to val (0-1.0), using white light.
  // If val is 0, it is turned off.
  void Bulb(u32 bulb, f32 val) const;

  // Registers the username.  Returns error message or "" if succeeded.
  RC::RStr Link() const;


-----------------------------------------------------------------------------

  Ryan A. Colyer
  http://rcolyer.net

-----------------------------------------------------------------------------

