Peter M. Groen / hueplusplus

Commit 544f68c5d079f9d68a1e888b97f93331d92f3c3c

Authored by Nodeduino
1 parent 9a60a144

Add documentation to previously undocumented files and clean up documentation

Inline Side-by-side
Showing 12 changed files with 382 additions and 127 deletions
hueplusplus/include/BrightnessStrategy.h
  View file @544f68c
... ... @@ -24,11 +24,18 @@
24 24  
25 25 class HueLight;
26 26  
  27 +//! Virtual base class for all BrightnessStrategys
27 28 class BrightnessStrategy
28 29 {
29 30 public:
  31 + //! \brief Virtual function for changing a lights brightness with a specified transition.
  32 + //!
  33 + //! \param bri The brightness raning from 0 = off to 255 = fully lit
  34 + //! \param transition The time it takes to fade to the new brightness in multiples of 100ms, 4 = 400ms and should be seen as the default
  35 + //! \param light A reference of the light
30 36 virtual bool setBrightness(unsigned int bri, uint8_t transition, HueLight& light) const = 0;
  37 + //! \brief Virtual dtor
31 38 virtual ~BrightnessStrategy() = default;
32 39 };
33 40  
34   -#endif
35 41 \ No newline at end of file
  42 +#endif
... ...
hueplusplus/include/ColorHueStrategy.h
  View file @544f68c
... ... @@ -24,19 +24,84 @@
24 24  
25 25 class HueLight;
26 26  
  27 +//! Virtual base class for all ColorHueStrategys
27 28 class ColorHueStrategy
28 29 {
29 30 public:
  31 + //! \brief Function for changing a lights color in hue with a specified transition.
  32 + //!
  33 + //! The hue ranges from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
  34 + //! \param hue The hue of the color
  35 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  36 + //! \param light A reference of the light
30 37 virtual bool setColorHue(uint16_t hue, uint8_t transition, HueLight& light) const = 0;
31   - virtual bool setColorSaturation(uint8_t sat, uint8_t transition, HueLight& light) const = 0;
  38 + //! \brief Function for changing a lights color in saturation with a specified transition.
  39 + //!
  40 + //! The saturation ranges from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated (vibrant).
  41 + //! \param sat The saturation of the color
  42 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  43 + //! \param light A reference of the light
  44 + virtual bool setColorSaturation(uint8_t sat, uint8_t transition, HueLight& light) const = 0;
  45 + //! \brief Function for changing a lights color in hue and saturation format with a specified transition.
  46 + //!
  47 + //! The hue ranges from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
  48 + //! The saturation ranges from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated (vibrant).
  49 + //! \param hue The hue of the color
  50 + //! \param sat The saturation of the color
  51 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  52 + //! \param light A reference of the light
32 53 virtual bool setColorHueSaturation(uint16_t hue, uint8_t sat, uint8_t transition, HueLight& light) const = 0;
  54 + //! \brief Function for changing a lights color in CIE format with a specified transition.
  55 + //!
  56 + //! \param x The x coordinate in CIE, ranging from 0 to 1
  57 + //! \param y The y coordinate in CIE, ranging from 0 to 1
  58 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  59 + //! \param light A reference of the light
33 60 virtual bool setColorXY(float x, float y, uint8_t transition, HueLight& light) const = 0;
  61 + //! \brief Function for changing a lights color in rgb format with a specified transition.
  62 + //!
  63 + //! Red, green and blue are ranging from 0 to 255.
  64 + //! \param r The red portion of the color
  65 + //! \param g The green portion of the color
  66 + //! \param b The blue portion of the color
  67 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  68 + //! \param light A reference of the light
34 69 virtual bool setColorRGB(uint8_t r, uint8_t g, uint8_t b, uint8_t transition, HueLight& light) const = 0;
  70 + //! \brief Function for turning on/off the color loop feature of a light.
  71 + //!
  72 + //! Can be theoretically set for any light, but it only works for lights that support this feature.
  73 + //! When this feature is activated the light will fade through every color on the current hue and saturation settings.
  74 + //! Notice that none of the setter functions check whether this feature is enabled and
  75 + //! the colorloop can only be disabled with this function or by simply calling Off()/OffNoRefresh()
  76 + //! and then On()/OnNoRefresh(), so you could alternatively call Off() and
  77 + //! then use any of the setter functions.
  78 + //! \param on Boolean to turn this feature on or off, true/1 for on and false/0 for off
  79 + //! \param light A reference of the light
35 80 virtual bool setColorLoop(bool on, HueLight& light) const = 0;
  81 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  82 + //!
  83 + //! The hue ranges from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
  84 + //! The saturation ranges from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated (vibrant).
  85 + //! \param hue The hue of the color
  86 + //! \param sat The saturation of the color
  87 + //! \param light A reference of the light
36 88 virtual bool alertHueSaturation(uint16_t hue, uint8_t sat, HueLight& light) const = 0;
  89 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  90 + //!
  91 + //! \param x The x coordinate in CIE, ranging from 0 to 1
  92 + //! \param y The y coordinate in CIE, ranging from 0 to 1
  93 + //! \param light A reference of the light
37 94 virtual bool alertXY(float x, float y, HueLight& light) const = 0;
  95 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  96 + //!
  97 + //! Red, green and blue are ranging from 0 to 255.
  98 + //! \param r The red portion of the color
  99 + //! \param g The green portion of the color
  100 + //! \param b The blue portion of the color
  101 + //! \param light A reference of the light
38 102 virtual bool alertRGB(uint8_t r, uint8_t g, uint8_t b, HueLight& light) const = 0;
  103 + //! \brief Virtual dtor
39 104 virtual ~ColorHueStrategy() = default;
40 105 };
41 106  
42   -#endif
43 107 \ No newline at end of file
  108 +#endif
... ...
hueplusplus/include/ColorTemperatureStrategy.h
  View file @544f68c
... ... @@ -24,12 +24,25 @@
24 24  
25 25 class HueLight;
26 26  
  27 +//! Virtual base class for all ColorTemperatureStrategys
27 28 class ColorTemperatureStrategy
28 29 {
29 30 public:
  31 + //! \brief Virtual function for changing a lights color temperature in mired with a specified transition.
  32 + //!
  33 + //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold and 500 is warm.
  34 + //! \param mired The color temperature in mired
  35 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  36 + //! \param light A reference of the light
30 37 virtual bool setColorTemperature(unsigned int mired, uint8_t transition, HueLight& light) const = 0;
31   - virtual bool alertTemperature(unsigned int mired, HueLight& light) const = 0;
  38 + //! \brief Virtual function that lets the light perform one breath cycle in the specified color.
  39 + //!
  40 + //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold and 500 is warm.
  41 + //! \param mired The color temperature in mired
  42 + //! \param light A reference of the light
  43 + virtual bool alertTemperature(unsigned int mired, HueLight& light) const = 0;
  44 + //! \brief Virtual dtor
32 45 virtual ~ColorTemperatureStrategy() = default;
33 46 };
34 47  
35   -#endif
36 48 \ No newline at end of file
  49 +#endif
... ...
hueplusplus/include/ExtendedColorHueStrategy.h
  View file @544f68c
... ... @@ -22,12 +22,35 @@
22 22  
23 23 #include "SimpleColorHueStrategy.h"
24 24  
  25 +//! Class extending the implementation of SimpleColorHueStrategy
25 26 class ExtendedColorHueStrategy : public SimpleColorHueStrategy
26 27 {
27 28 public:
  29 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  30 + //!
  31 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  32 + //! The hue ranges from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
  33 + //! The saturation ranges from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated (vibrant).
  34 + //! \param hue The hue of the color
  35 + //! \param sat The saturation of the color
  36 + //! \param light A reference of the light
28 37 bool alertHueSaturation(uint16_t hue, uint8_t sat, HueLight& light) const;
  38 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  39 + //!
  40 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  41 + //! \param x The x coordinate in CIE, ranging from 0 to 1
  42 + //! \param y The y coordinate in CIE, ranging from 0 to 1
  43 + //! \param light A reference of the light
29 44 bool alertXY(float x, float y, HueLight& light) const;
  45 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  46 + //!
  47 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  48 + //! Red, green and blue are ranging from 0 to 255.
  49 + //! \param r The red portion of the color
  50 + //! \param g The green portion of the color
  51 + //! \param b The blue portion of the color
  52 + //! \param light A reference of the light
30 53 bool alertRGB(uint8_t r, uint8_t g, uint8_t b, HueLight& light) const;
31 54 };
32 55  
33   -#endif
34 56 \ No newline at end of file
  57 +#endif
... ...
hueplusplus/include/ExtendedColorTemperatureStrategy.h
  View file @544f68c
... ... @@ -18,16 +18,29 @@
18 18 **/
19 19  
20 20 #ifndef _EXTENDED_COLOR_TEMPERATURE_STRATEGY_H
21   -#define _EXTENDED_COLOR_TEMPERATURE_STRATEGY_H
  21 +#define _EXTENDED_COLOR_TEMPERATURE_STRATEGY_H
22 22  
23 23 #include "ColorTemperatureStrategy.h"
24 24 #include "HueLight.h"
25 25  
  26 +//! Class implementing the functions of ColorTemperatureStrategy
26 27 class ExtendedColorTemperatureStrategy : public ColorTemperatureStrategy
27 28 {
28 29 public:
  30 + //! \brief Function for changing a lights color temperature in mired with a specified transition.
  31 + //!
  32 + //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold and 500 is warm.
  33 + //! \param mired The color temperature in mired
  34 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  35 + //! \param light A reference of the light
29 36 bool setColorTemperature(unsigned int mired, uint8_t transition, HueLight& light) const;
  37 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  38 + //!
  39 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  40 + //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold and 500 is warm.
  41 + //! \param mired The color temperature in mired
  42 + //! \param light A reference of the light
30 43 bool alertTemperature(unsigned int mired, HueLight& light) const;
31 44 };
32 45  
33   -#endif
34 46 \ No newline at end of file
  47 +#endif
... ...
hueplusplus/include/HttpHandler.h
  View file @544f68c
... ... @@ -27,30 +27,33 @@
27 27 class HttpHandler
28 28 {
29 29 public:
30   - //! Function that sends a request to a specific address \ref adr on a specific \ref port.
31   - //! It returns a string containing the answer of the host
32   - //! \param msg String that contains the request that is sent to \ref adr
33   - //! \param adr String that contains an ip or hostname
34   - //! \param port Optional Integer that specifies the port to which the request is sent. Standard value is 80
35   - //! \return String containing the answer of the host
36   - std::string sendRequest(const std::string &msg, const std::string &adr, int port=80);
  30 + //! \brief Function that sends a http request with the specified message and returns the response.
  31 + //!
  32 + //! It returns a string containing the response of the host.
  33 + //! \param msg String that contains the request that is sent to the specified address
  34 + //! \param adr String that contains an ip or hostname in dotted decimal notation like "192.168.2.1"
  35 + //! \param port Optional integer that specifies the port to which the request is sent to. Default is 80
  36 + //! \return String containing the response of the host
  37 + std::string sendRequest(const std::string &msg, const std::string &adr, int port=80);
37 38  
38   - //! Function that sends a request to a specific address \ref adr on a specific \ref port.
39   - //! It returns a string containing only the body of the answer of the host
40   - //! \param msg String that contains the request that is sent to \ref adr
41   - //! \param adr String that contains an ip or hostname
42   - //! \param port Optional Integer that specifies the port to which the request is sent. Standard value is 80
43   - //! \return String containing the body of the answer of the host
44   - std::string sendRequestGetBody(const std::string &msg, const std::string &adr, int port = 80);
  39 + //! \brief Function that sends a http request with the specified message and returns the body of the response.
  40 + //!
  41 + //! It returns a string containing only the body of the response of the host.
  42 + //! \param msg String that contains the request that is sent to the specified address
  43 + //! \param adr String that contains an ip or hostname in dotted decimal notation like "192.168.2.1"
  44 + //! \param port Optional integer that specifies the port to which the request is sent. Default is 80
  45 + //! \return String containing the body of the response of the host
  46 + std::string sendRequestGetBody(const std::string &msg, const std::string &adr, int port = 80);
45 47  
46   - //! Function that sends a multicast request to a specific address \ref adr on a specific \ref port with a \ref timeout.
47   - //! It returns a vector containing all answers the multicast request got
48   - //! \param msg String that contains the request that is sent to \ref adr
49   - //! \param adr Optional String that contains an ip or hostname. Standard value is "239.255.255.250"
50   - //! \param port Optional Integer that specifies the port to which the request is sent. Standard value is 1900
51   - //! \param timeout Optional Integer that specifies the timeout of the request in seconds. Standard value is 5
52   - //! \return Vector containing strings of each answer received
53   - std::vector<std::string> sendMulticast(const std::string &msg, const std::string &adr = "239.255.255.250", int port = 1900, int timeout = 5);
  48 + //! \brief Function that sends a multicast request with the specified message.
  49 + //!
  50 + //! It returns a vector containing all responses the multicast request got back
  51 + //! \param msg String that contains the request that is sent to the specified address
  52 + //! \param adr Optional String that contains an ip or hostname in dotted decimal notation, default is "239.255.255.250"
  53 + //! \param port Optional integer that specifies the port to which the request is sent. Default is 1900
  54 + //! \param timeout Optional Integer that specifies the timeout of the request in seconds. Default is 5
  55 + //! \return Vector containing strings of each answer received
  56 + std::vector<std::string> sendMulticast(const std::string &msg, const std::string &adr = "239.255.255.250", int port = 1900, int timeout = 5);
54 57 };
55 58  
56   -#endif
57 59 \ No newline at end of file
  60 +#endif
... ...
hueplusplus/include/Hue.h
  View file @544f68c
... ... @@ -48,92 +48,107 @@ public:
48 48 std::string mac;
49 49 };
50 50 public:
51   - //! Function that finds all bridges in the network and returns them.\n
  51 + //! \brief Function that finds all bridges in the network and returns them.
  52 + //!
52 53 //! The user should be given the opportunity to select the correct one based on the mac address.
53 54 //! \return vector containing ip and mac of all found bridges
54 55 std::vector<HueIdentification> FindBridges() const;
55 56  
56   - //! Function that gets a \ref Hue bridge based on its identification
  57 + //! \brief Function that gets a \ref Hue bridge based on its identification
  58 + //!
57 59 //! \param identification \ref HueIdentification that specifies a bridge
58 60 //! \return \ref Hue class object
59 61 Hue GetBridge(const HueIdentification& identification);
60 62  
61   - //! Function that adds a username to the \ref usernames map
  63 + //! \brief Function that adds a username to the \ref usernames map
  64 + //!
62 65 //! \param mac MAC address of Hue bridge
63 66 //! \param username Username that is used to control the Hue bridge
64 67 void AddUsername(const std::string& mac, const std::string& username);
65 68  
66   - //! Function that returns a map of mac addresses and usernames.
  69 + //! \brief Function that returns a map of mac addresses and usernames.
  70 + //!
67 71 //! These should be saved at the end and re-loaded next time, so only one username is generated per bridge.
68 72 //! \returns A map mapping mac address to username for every bridge
69 73 const std::map<std::string, std::string>& GetAllUsernames() const;
70 74 private:
71   - //! Function that sends a username request to the Hue bridge for about 30 seconds, but you have 5 seconds to prepare.\n
  75 + //! \brief Function that sends a username request to the Hue bridge.
  76 + //!
  77 + //! It does that for about 30 seconds and you have 5 seconds to prepare.
72 78 //! It returns the username received
73 79 //! \param ip String that specifies the ip the request is send to
74 80 //! \return String containing username
75 81 std::string RequestUsername(const std::string& ip) const;
76 82  
77 83 private:
78   - std::map<std::string, std::string> usernames;
  84 + std::map<std::string, std::string> usernames; //!< Maps all macs to usernames added by \ref HueFinder::AddUsername
79 85 };
80 86  
81 87 //! Hue class
82 88 class Hue
83 89 {
84 90 public:
85   - //! Constructor of Hue class
86   - //! \param ip String that specifies the ip address of the Hue bridge
  91 + //! \brief Constructor of Hue class
  92 + //!
  93 + //! \param ip String that specifies the ip address of the Hue bridge in dotted decimal notation like "192.168.2.1"
87 94 //! \param username String that specifies the username that is used to control the bridge. This needs to be acquired in \ref requestUsername
88 95 Hue(const std::string& ip, const std::string& username);
89 96  
90   - //! Function to get the ip address of the hue bridge
  97 + //! \brief Function to get the ip address of the hue bridge
  98 + //!
91 99 //! \return string containing ip
92 100 std::string getBridgeIP();
93 101  
94   - //! Function that sends a username request to the Hue bridge for about 30 seconds, but you have 5 seconds to prepare
  102 + //! \brief Function that sends a username request to the Hue bridge.
  103 + //!
  104 + //! It does that for about 30 seconds and you have 5 seconds to prepare
95 105 //! It automatically sets the \ref username variable according to the username received
96 106 //! This function should only be called once to acquire a username to control the bridge and the username should be saved for future use
97   - //! \param ip String that specifies the ip the request is send to
  107 + //! \param ip String that specifies the ip (in dotted decimal notation like "192.168.2.1") the request is send to
98 108 void requestUsername(const std::string& ip);
99 109  
100   - //! Function that returns the \ref username
  110 + //! \brief Function that returns the \ref username
  111 + //!
101 112 //! \return String containing \ref username
102 113 std::string getUsername();
103 114  
104   - //! Function to set the ip address of the Hue bridge in this class
105   - //! \param ip String that specifies the ip
  115 + //! \brief Function to set the ip address of this class representing a bridge
  116 + //!
  117 + //! \param ip String that specifies the ip in dotted decimal notation like "192.168.2.1"
106 118 void setIP(const std::string ip);
107 119  
108   - // todo: some intelligence of finding light
109   - //! Function that returns a \HueLight of specified \ref id
  120 + //! \todo add some intelligence of finding light
  121 + //! \brief Function that returns a \ref Hue::HueLight of specified id
  122 + //!
110 123 //! \param id Integer that specifies the ID of a Hue light
111 124 //! \return \ref HueLight that can be controlled
112 125 HueLight& getLight(int id);
113 126  
114   - //! Function that returns all light types that are associated with this bridge
  127 + //! \brief Function that returns all light types that are associated with this bridge
  128 + //!
115 129 //! \return A map mapping light id's to light types for every light
116 130 //const std::map<uint8_t, ColorType>& getAllLightTypes();
117 131  
118   - //! Function that returns all lights that are associated with this bridge
  132 + //! \brief Function that returns all lights that are associated with this bridge
  133 + //!
119 134 //! \return A vector containing references to every HueLight
120 135 std::vector<std::reference_wrapper<HueLight>> getAllLights();
121 136  
122 137 private:
123   - //! Function that refreshes the local \ref state of the Hue bridge
  138 + //! \brief Function that refreshes the local \ref state of the Hue bridge
124 139 void refreshState();
125 140  
126 141 private:
127   - std::string ip;
128   - std::string username;
129   - Json::Value state;
130   - std::map< uint8_t, HueLight > lights;
131   -
132   - std::shared_ptr<BrightnessStrategy> simpleBrightnessStrategy;
133   - std::shared_ptr<ColorHueStrategy> simpleColorHueStrategy;
134   - std::shared_ptr<ColorHueStrategy> extendedColorHueStrategy;
135   - std::shared_ptr<ColorTemperatureStrategy> simpleColorTemperatureStrategy;
136   - std::shared_ptr<ColorTemperatureStrategy> extendedColorTemperatureStrategy;
  142 + std::string ip; //!< IP-Address of the hue bridge in dotted decimal notation like "192.168.2.1"
  143 + std::string username; //!< Username that is ussed to access the hue bridge
  144 + Json::Value state; //!< The state of the hue bridge as it is returned from it
  145 + std::map< uint8_t, HueLight > lights; //!< Maps ids to HueLights that are controlled by this bridge
  146 +
  147 + std::shared_ptr<BrightnessStrategy> simpleBrightnessStrategy; //!< Strategy that is used for controlling the brightness of lights
  148 + std::shared_ptr<ColorHueStrategy> simpleColorHueStrategy; //!< Strategy that is used for controlling the color of lights
  149 + std::shared_ptr<ColorHueStrategy> extendedColorHueStrategy; //!< Strategy that is used for controlling the color of lights
  150 + std::shared_ptr<ColorTemperatureStrategy> simpleColorTemperatureStrategy; //!< Strategy that is used for controlling the color temperature of lights
  151 + std::shared_ptr<ColorTemperatureStrategy> extendedColorTemperatureStrategy; //!< Strategy that is used for controlling the color temperature of lights
137 152 };
138 153  
139   -#endif
140 154 \ No newline at end of file
  155 +#endif
... ...
hueplusplus/include/HueLight.h
  View file @544f68c
... ... @@ -69,7 +69,7 @@ LTW014, // Hue Spot BR30, Color Gamut 2200K-6500K, CTL
69 69 LLC020 // Hue Go, Color Gamut C, ECL
70 70 };*/
71 71  
72   -//! enum that specifies the color type of all Hue lights
  72 +//! enum that specifies the color type of all HueLights
73 73 enum ColorType
74 74 {
75 75 UNDEFINED, //!< ColorType for this light is unknown or undefined
... ... @@ -96,69 +96,78 @@ class HueLight
96 96 friend class ExtendedColorTemperatureStrategy;
97 97  
98 98 public:
99   - //! std dtor
  99 + //! \brief std dtor
100 100 ~HueLight() = default;
101 101  
102   - //! Function that turns the light on.
  102 + //! \brief Function that turns the light on.
  103 + //!
103 104 //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
104 105 //! \return Bool that is true on success
105 106 bool On(uint8_t transition = 4);
106 107  
107   - //! Function that turns the light off.
  108 + //! \brief Function that turns the light off.
  109 + //!
108 110 //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
109 111 //! \return Bool that is true on success
110 112 bool Off(uint8_t transition = 4);
111 113  
112   - //! Function that returns the name of the light.
  114 + //! \brief Function that returns the name of the light.
  115 + //!
113 116 //! \return String containig the name of the light
114 117 std::string getName();
115 118  
116   - //! Function that returns the color type of the light.
  119 + //! \brief Function that returns the color type of the light.
  120 + //!
117 121 //! \return ColorType containig the color type of the light
118 122 ColorType getColorType();
119 123  
120   - //! Function that converts Kelvin to Mired.
  124 + //! \brief Function that converts Kelvin to Mired.
  125 + //!
121 126 //! \param kelvin Unsigned integer value in Kelvin
122 127 //! \return Unsigned integer value in Mired
123 128 unsigned int KelvinToMired(unsigned int kelvin);
124 129  
125   - //! Function that converts Mired to Kelvin.
  130 + //! \brief Function that converts Mired to Kelvin.
  131 + //!
126 132 //! \param mired Unsigned integer value in Mired
127 133 //! \return Unsigned integer value in Kelvin
128 134 unsigned int MiredToKelvin(unsigned int mired);
129 135  
130   - //! Function that sets the brightness of this light if the
131   - //! light has a reference to a specific \ref BrightnessStrategy.
132   - //! The brightness can range from 0=off to 255=fully on.
  136 + //! \brief Function that sets the brightness of this light.
  137 + //!
  138 + //! Notice the brightness will only be set if the light has a reference to a specific \ref BrightnessStrategy.
  139 + //! The brightness can range from 0 = off to 255 = fully lit.
133 140 //! \param bri Unsigned int that specifies the brightness
134 141 //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
135 142 //! \return Bool that is true on success
136   - bool setBrightness(unsigned int bri, uint8_t transition = 4)
137   - {
138   - if (brightnessStrategy)
  143 + bool setBrightness(unsigned int bri, uint8_t transition = 4)
  144 + {
  145 + if (brightnessStrategy)
139 146 {
140 147 return brightnessStrategy->setBrightness(bri, transition, *this);
141 148 }
142 149 return false;
143 150 };
144 151  
145   - //! Fucntion that sets the color temperature of this light in mired if the
146   - //! light has a reference to a specific \ref ColorTemperatureStrategy.
  152 + //! \brief Fucntion that sets the color temperature of this light in mired.
  153 + //!
  154 + //! Notice the color temperature will only be set if the light has a reference to a specific \ref ColorTemperatureStrategy.
147 155 //! The color temperature can range from 153 to 500.
148 156 //! \param mired Unsigned int that specifies the color temperature in Mired
149 157 //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
150 158 //! \return Bool that is true on success
151 159 bool setColorTemperature(unsigned int mired, uint8_t transition = 4)
152   - {
  160 + {
153 161 if (colorTemperatureStrategy)
154   - {
155   - return colorTemperatureStrategy->setColorTemperature(mired, transition, *this);
  162 + {
  163 + return colorTemperatureStrategy->setColorTemperature(mired, transition, *this);
156 164 }
157 165 return false;
158 166 };
159 167  
160   - //! Function to set the color of this light with specified hue if the
161   - //! light has a reference to a specific \ref ColorHueStrategy.
  168 + //! \brief Function to set the color of this light with specified hue.
  169 + //!
  170 + //! Notice the color will only be set if the light has a reference to a specific \ref ColorHueStrategy.
162 171 //! The hue can range from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
163 172 //! \param hue uint16_t that specifies the hue
164 173 //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
... ... @@ -172,8 +181,9 @@ public:
172 181 return false;
173 182 };
174 183  
175   - //! Function to set the saturation of color of this light with specified saturation if the
176   - //! light has a reference to a specific \ref ColorHueStrategy.
  184 + //! \brief Function to set the color of this light with specified saturation.
  185 + //!
  186 + //! Notice the color will only be set if the light has a reference to a specific \ref ColorHueStrategy.
177 187 //! The saturation can range from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated.
178 188 //! \param sat uint8_t that specifies the saturation
179 189 //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
... ... @@ -187,8 +197,9 @@ public:
187 197 return false;
188 198 };
189 199  
190   - //! Function to set the color of this light with specified hue and saturation if the
191   - //! light has a reference to a specific \ref ColorHueStrategy.
  200 + //! \brief Function to set the color of this light with specified hue and saturation.
  201 + //!
  202 + //! Notice the color will only be set if the light has a reference to a specific \ref ColorHueStrategy.
192 203 //! \param hue uint16_t that specifies the hue
193 204 //! \param sat uint8_t that specifies the saturation
194 205 //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms.
... ... @@ -202,8 +213,9 @@ public:
202 213 return false;
203 214 };
204 215  
205   - //! Function to set the color of this light in CIE with specified x y if the
206   - //! light has a reference to a specific \ref ColorHueStrategy.
  216 + //! \brief Function to set the color of this light in CIE with specified x y.
  217 + //!
  218 + //! Notice the color will only be set if the light has a reference to a specific \ref ColorHueStrategy.
207 219 //! The values of x and y are ranging from 0 to 1.
208 220 //! \param x float that specifies the x coordinate in CIE
209 221 //! \param y float that specifies the y coordinate in CIE
... ... @@ -218,8 +230,9 @@ public:
218 230 return false;
219 231 };
220 232  
221   - //! Function to set the color of this light with red green and blue values if the
222   - //! light has a reference to a specific \ref ColorHueStrategy.
  233 + //! \brief Function to set the color of this light with red green and blue values.
  234 + //!
  235 + //! Notice the color will only be set if the light has a reference to a specific \ref ColorHueStrategy.
223 236 //! The values of red, green and blue are ranging from 0 to 255.
224 237 //! \param r uint8_t that specifies the red color value
225 238 //! \param g uint8_t that specifies the green color value
... ... @@ -235,13 +248,15 @@ public:
235 248 return false;
236 249 };
237 250  
238   - //! Function that lets the light perform one breath cycle.
  251 + //! \brief Function that lets the light perform one breath cycle.
  252 + //!
  253 + //! Can be used for locating a light.
239 254 //! \return bool that is true on success
240 255 virtual bool alert();
241 256  
242   - //! Function that lets the light perform one breath cycle in specified color temperature
243   - //! if the light has a reference to a specific \ref ColorTemperatureStrategy.
244   - //! It uses this_thread::sleep_for to accomodate for the time an \ref alert() needs.
  257 + //! \brief Function that lets the light perform one breath cycle in specified color temperature.
  258 + //!
  259 + //! Notice the breath cylce will only be performed if the light has a reference to a specific \ref ColorTemperatureStrategy.
245 260 //! \param mired Color temperature in mired
246 261 //! \return Bool that is true on success
247 262 bool alertTemperature(unsigned int mired)
... ... @@ -253,9 +268,9 @@ public:
253 268 return false;
254 269 };
255 270  
256   - //! Function that lets the light perform one breath cycle in specified color if the
257   - //! light has a reference to a specific \ref ColorHueStrategy.
258   - //! It uses this_thread::sleep_for to accomodate for the time an \ref alert() needs
  271 + //! \brief Function that lets the light perform one breath cycle in specified color.
  272 + //!
  273 + //! Notice the breath cylce will only be performed if the light has a reference to a specific \ref ColorHueStrategy.
259 274 //! \param hue uint16_t that specifies the hue
260 275 //! \param sat uint8_t that specifies the saturation
261 276 //! \return Bool that is true on success
... ... @@ -268,10 +283,10 @@ public:
268 283 return false;
269 284 };
270 285  
271   - //! Function that lets the light perform one breath cycle in specified color if the
272   - //! light has a reference to a specific \ref ColorHueStrategy.
  286 + //! \brief Function that lets the light perform one breath cycle in specified color.
  287 + //!
  288 + //! Notice the breath cylce will only be performed if the light has a reference to a specific \ref ColorHueStrategy.
273 289 //! The values of x and y are ranging from 0 to 1.
274   - //! It uses this_thread::sleep_for to accomodate for the time an \ref alert() needs
275 290 //! \param x float that specifies the x coordinate in CIE
276 291 //! \param y float that specifies the y coordinate in CIE
277 292 //! \return Bool that is true on success
... ... @@ -284,10 +299,10 @@ public:
284 299 return false;
285 300 };
286 301  
287   - //! Function that lets the light perform one breath cycle in specified color if the
288   - //! light has a reference to a specific \ref ColorHueStrategy.
  302 + //! \brief Function that lets the light perform one breath cycle in specified color.
  303 + //!
  304 + //! Notice the breath cylce will only be performed if the light has a reference to a specific \ref ColorHueStrategy.
289 305 //! The values of red, green and blue are ranging from 0 to 255.
290   - //! It uses this_thread::sleep_for to accomodate for the time an \ref alert() needs
291 306 //! \param r uint8_t that specifies the red color value
292 307 //! \param g uint8_t that specifies the green color value
293 308 //! \param b uint8_t that specifies the blue color value
... ... @@ -301,12 +316,13 @@ public:
301 316 return false;
302 317 };
303 318  
304   - //! Function to enable colorloop effect if the
305   - //! light has a reference to a specific \ref ColorHueStrategy.
  319 + //! \brief Function to turn colorloop effect on/off.
  320 + //!
  321 + //! Notice this function will only be performed light has a reference to a specific \ref ColorHueStrategy.
306 322 //! The colorloop effect will loop through all colors on current hue and saturation levels.
307   - //! Notice that none of the setter functions check whether this feature is enabled and
308   - //! the colorloop can only be disabled with this function or by simply calling Off()/OffNoRefresh()
309   - //! and then On()/OnNoRefresh(), so you could alternatively call Off() and
  323 + //! Notice that none of the setter functions check whether this feature is enabled and
  324 + //! the colorloop can only be disabled with this function or by simply calling Off()/OffNoRefresh()
  325 + //! and then On()/OnNoRefresh(), so you could alternatively call Off() and
310 326 //! then use any of the setter functions.
311 327 //! \param on bool that enables this feature when true and disables it when false
312 328 //! \return Bool that is true on success
... ... @@ -320,15 +336,17 @@ public:
320 336 };
321 337  
322 338 protected:
323   - //! protected ctor that is used by \ref Hue class.
  339 + //! \brief Protected ctor that is used by \ref Hue class.
  340 + //!
324 341 //! \param ip String that specifies the ip of the Hue bridge
325 342 //! \param username String that specifies the username used to control the bridge
326 343 //! \param id Integer that specifies the id of this light
327 344 //!
328 345 //! leaves strategies unset
329 346 HueLight(const std::string& ip, const std::string& username, int id);
330   -
331   - //! protected ctor that is used by \ref Hue class, also sets strategies.
  347 +
  348 + //! \brief Protected ctor that is used by \ref Hue class, also sets strategies.
  349 + //!
332 350 //! \param ip String that specifies the ip of the Hue bridge
333 351 //! \param username String that specifies the username used to control the bridge
334 352 //! \param id Integer that specifies the id of this light
... ... @@ -337,37 +355,43 @@ protected:
337 355 //! \param colorHueStrategy Strategy for color hue/saturation. May be nullptr.
338 356 HueLight(const std::string& ip, const std::string& username, int id, std::shared_ptr<const BrightnessStrategy> brightnessStrategy, std::shared_ptr<const ColorTemperatureStrategy> colorTempStrategy, std::shared_ptr<const ColorHueStrategy> colorHueStrategy);
339 357  
340   - //! protected function that sets the brightness strategy which defines how
341   - //! specific commands that deal with brightness control are executed
  358 + //! \brief Protected function that sets the brightness strategy.
  359 + //!
  360 + //! The strategy defines how specific commands that deal with brightness control are executed
342 361 //! \param strat a strategy of type \ref BrightnessStrategy
343 362 void setBrightnessStrategy(std::shared_ptr<const BrightnessStrategy> strat) { brightnessStrategy = std::move(strat); };
344 363  
345   - //! protected function that sets the colorTemperature strategy which defines how
346   - //! specific commands that deal with colortemperature control are executed
  364 + //! \brief Protected function that sets the colorTemperature strategy.
  365 + //!
  366 + //! The strategy defines how specific commands that deal with colortemperature control are executed
347 367 //! \param strat a strategy of type \ref ColorTemperatureStrategy
348 368 void setColorTemperatureStrategy(std::shared_ptr<const ColorTemperatureStrategy> strat) { colorTemperatureStrategy = std::move(strat); };
349 369  
350   - //! protected function that sets the colorHue strategy which defines how
351   - //! specific commands that deal with color control are executed
  370 + //! \brief Protected function that sets the colorHue strategy.
  371 + //!
  372 + //! The strategy defines how specific commands that deal with color control are executed
352 373 //! \param strat a strategy of type \ref ColorHueStrategy
353 374 void setColorHueStrategy(std::shared_ptr<const ColorHueStrategy> strat) { colorHueStrategy = std::move(strat); };
354 375  
355   - //! Function that turns the light on without refreshing its state.
  376 + //! \brief Function that turns the light on without refreshing its state.
  377 + //!
356 378 //! \param transition Optional parameter to set the transition from current state to new standard is 4 = 400ms
357 379 //! \return Bool that is true on success
358 380 bool OnNoRefresh(uint8_t transition = 4);
359 381  
360   - //! Function that turns the light off without refreshing its state.
  382 + //! \brief Function that turns the light off without refreshing its state.
  383 + //!
361 384 //! \param transition Optional parameter to set the transition from current state to new standard is 4 = 400ms
362 385 //! \return Bool that is true on success
363 386 bool OffNoRefresh(uint8_t transition = 4);
364 387  
365   - //! utility function to send a put request to the light.
  388 + //! \brief Utility function to send a put request to the light.
  389 + //!
366 390 //! \throws std::runtime_error if the reply could not be parsed
367 391 //! \return The parsed reply
368 392 Json::Value SendPutRequest(const Json::Value& request);
369 393  
370   - //! virtual function that refreshes the \ref state of the light.
  394 + //! \brief Virtual function that refreshes the \ref state of the light.
371 395 virtual void refreshState();
372 396  
373 397 protected:
... ...
hueplusplus/include/SimpleBrightnessStrategy.h
  View file @544f68c
... ... @@ -23,10 +23,16 @@
23 23 #include "BrightnessStrategy.h"
24 24 #include "HueLight.h"
25 25  
  26 +//! Class implementing the functions of BrightnessStrategy
26 27 class SimpleBrightnessStrategy : public BrightnessStrategy
27 28 {
28 29 public:
  30 + //! \brief Function for changing a lights brightness with a specified transition.
  31 + //!
  32 + //! \param bri The brightness raning from 0 = off to 255 = fully lit
  33 + //! \param transition The time it takes to fade to the new brightness in multiples of 100ms, 4 = 400ms and should be seen as the default
  34 + //! \param light A reference of the light
29 35 bool setBrightness(unsigned int bri, uint8_t transition, HueLight& light) const;
30 36 };
31 37  
32   -#endif
33 38 \ No newline at end of file
  39 +#endif
... ...
hueplusplus/include/SimpleColorHueStrategy.h
  View file @544f68c
... ... @@ -22,18 +22,85 @@
22 22  
23 23 #include "HueLight.h"
24 24  
  25 +//! Class implementing the functions of ColorHueStrategy
25 26 class SimpleColorHueStrategy : public ColorHueStrategy
26 27 {
27 28 public:
  29 + //! \brief Function for changing a lights color in hue with a specified transition.
  30 + //!
  31 + //! The hue ranges from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
  32 + //! \param hue The hue of the color
  33 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  34 + //! \param light A reference of the light
28 35 bool setColorHue(uint16_t hue, uint8_t transition, HueLight& light) const;
29   - bool setColorSaturation(uint8_t sat, uint8_t transition, HueLight& light) const;
  36 + //! \brief Virtual function for changing a lights color in saturation with a specified transition.
  37 + //!
  38 + //! The saturation ranges from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated (vibrant).
  39 + //! \param sat The saturation of the color
  40 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  41 + //! \param light A reference of the light
  42 + bool setColorSaturation(uint8_t sat, uint8_t transition, HueLight& light) const;
  43 + //! \brief Virtual function for changing a lights color in hue and saturation format with a specified transition.
  44 + //!
  45 + //! The hue ranges from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
  46 + //! The saturation ranges from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated (vibrant).
  47 + //! \param hue The hue of the color
  48 + //! \param sat The saturation of the color
  49 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  50 + //! \param light A reference of the light
30 51 bool setColorHueSaturation(uint16_t hue, uint8_t sat, uint8_t transition, HueLight& light) const;
  52 + //! \brief Virtual function for changing a lights color in CIE format with a specified transition.
  53 + //!
  54 + //! \param x The x coordinate in CIE, ranging from 0 to 1
  55 + //! \param y The y coordinate in CIE, ranging from 0 to 1
  56 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  57 + //! \param light A reference of the light
31 58 bool setColorXY(float x, float y, uint8_t transition, HueLight& light) const;
  59 + //! \brief Virtual function for changing a lights color in rgb format with a specified transition.
  60 + //!
  61 + //! Red, green and blue are ranging from 0 to 255.
  62 + //! \param r The red portion of the color
  63 + //! \param g The green portion of the color
  64 + //! \param b The blue portion of the color
  65 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  66 + //! \param light A reference of the light
32 67 bool setColorRGB(uint8_t r, uint8_t g, uint8_t b, uint8_t transition, HueLight& light) const;
  68 + //! \brief Virtual function for turning on/off the color loop feature of a light.
  69 + //!
  70 + //! Can be theoretically set for any light, but it only works for lights that support this feature.
  71 + //! When this feature is activated the light will fade through every color on the current hue and saturation settings.
  72 + //! Notice that none of the setter functions check whether this feature is enabled and
  73 + //! the colorloop can only be disabled with this function or by simply calling Off()/OffNoRefresh()
  74 + //! and then On()/OnNoRefresh(), so you could alternatively call Off() and
  75 + //! then use any of the setter functions.
  76 + //! \param on Boolean to turn this feature on or off, true/1 for on and false/0 for off
  77 + //! \param light A reference of the light
33 78 bool setColorLoop(bool on, HueLight& light) const;
  79 + //! \brief Virtual function that lets the light perform one breath cycle in the specified color.
  80 + //!
  81 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  82 + //! The hue ranges from 0 to 65535, whereas 65535 and 0 are red, 25500 is green and 46920 is blue.
  83 + //! The saturation ranges from 0 to 254, whereas 0 is least saturated (white) and 254 is most saturated (vibrant).
  84 + //! \param hue The hue of the color
  85 + //! \param sat The saturation of the color
  86 + //! \param light A reference of the light
34 87 bool alertHueSaturation(uint16_t hue, uint8_t sat, HueLight& light) const;
  88 + //! \brief Virtual function that lets the light perform one breath cycle in the specified color.
  89 + //!
  90 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  91 + //! \param x The x coordinate in CIE, ranging from 0 to 1
  92 + //! \param y The y coordinate in CIE, ranging from 0 to 1
  93 + //! \param light A reference of the light
35 94 bool alertXY(float x, float y, HueLight& light) const;
  95 + //! \brief Virtual function that lets the light perform one breath cycle in the specified color.
  96 + //!
  97 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  98 + //! Red, green and blue are ranging from 0 to 255.
  99 + //! \param r The red portion of the color
  100 + //! \param g The green portion of the color
  101 + //! \param b The blue portion of the color
  102 + //! \param light A reference of the light
36 103 bool alertRGB(uint8_t r, uint8_t g, uint8_t b, HueLight& light) const;
37 104 };
38 105  
39   -#endif
40 106 \ No newline at end of file
  107 +#endif
... ...
hueplusplus/include/SimpleColorTemperatureStrategy.h
  View file @544f68c
... ... @@ -23,11 +23,24 @@
23 23 #include "ColorTemperatureStrategy.h"
24 24 #include "HueLight.h"
25 25  
  26 +//! Class implementing the functions of ColorTemperatureStrategy
26 27 class SimpleColorTemperatureStrategy : public ColorTemperatureStrategy
27 28 {
28 29 public:
  30 + //! \brief Function for changing a lights color temperature in mired with a specified transition.
  31 + //!
  32 + //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold and 500 is warm.
  33 + //! \param mired The color temperature in mired
  34 + //! \param transition The time it takes to fade to the new color in multiples of 100ms, 4 = 400ms and should be seen as the default
  35 + //! \param light A reference of the light
29 36 bool setColorTemperature(unsigned int mired, uint8_t transition, HueLight& light) const;
  37 + //! \brief Function that lets the light perform one breath cycle in the specified color.
  38 + //!
  39 + //! It uses this_thread::sleep_for to accomodate for the time an \ref HueLight::alert() needs
  40 + //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold and 500 is warm.
  41 + //! \param mired The color temperature in mired
  42 + //! \param light A reference of the light
30 43 bool alertTemperature(unsigned int mired, HueLight& light) const;
31 44 };
32 45  
33   -#endif
34 46 \ No newline at end of file
  47 +#endif
... ...
hueplusplus/include/UPnP.h
  View file @544f68c
... ... @@ -20,13 +20,19 @@
20 20 #ifndef _UPNP_H
21 21 #define _UPNP_H
22 22  
23   -#include <string>
  23 +#include <string>
24 24 #include <vector>
25 25  
  26 +//! Class that looks for UPnP devices using an m-search package
26 27 class UPnP
27 28 {
28 29 public:
  30 + //! \brief Function that searches for UPnP devices and returns all found ones.
  31 + //!
  32 + //! It does it by sending an m-search packet and waits for all responses.
  33 + //! Since responses can be received multiple times this function conveniently removes all duplicates.
  34 + //! \return A vector containing pairs of address and name of all found devices
29 35 std::vector<std::pair<std::string, std::string>> getDevices();
30 36 };
31 37  
32   -#endif
33 38 \ No newline at end of file
  39 +#endif
... ...