Peter M. Groen / hueplusplus

Commit c24d3db5d7a75a885f5213f3027d8d38b2b9eb8d

Authored by Jojo-1000
Committed by Moritz Wirger
1 parent 76ac2c83

Add documentation for CLIP sensors.

Inline Side-by-side
Showing 2 changed files with 139 additions and 0 deletions
include/hueplusplus/CLIPSensors.h
  View file @c24d3db
... ... @@ -28,116 +28,254 @@ namespace hueplusplus
28 28 {
29 29 namespace sensors
30 30 {
  31 +//! \brief Common methods for CLIP sensors
31 32 class BaseCLIP : public BaseDevice
32 33 {
33 34 public:
  35 + //! \brief Check if sensor is on
  36 + //!
  37 + //! Sensors which are off do not change their status
34 38 bool isOn() const;
  39 + //! \brief Enable or disable sensor
  40 + //! \throws std::system_error when system or socket operations fail
  41 + //! \throws HueException when response contained no body
  42 + //! \throws HueAPIResponseException when response contains an error
  43 + //! \throws nlohmann::json::parse_error when response could not be parsed
35 44 void setOn(bool on);
36 45  
  46 + //! \brief Get whether sensor has a battery state
37 47 bool hasBatteryState() const;
  48 + //! \brief Get battery state
  49 + //! \returns Battery state in percent
  50 + //! \throws nlohmann::json::out_of_range when sensor has no battery state.
38 51 int getBatteryState() const;
  52 + //! \brief Set battery state
  53 + //! \throws std::system_error when system or socket operations fail
  54 + //! \throws HueException when response contained no body
  55 + //! \throws HueAPIResponseException when response contains an error
  56 + //! \throws nlohmann::json::parse_error when response could not be parsed
39 57 void setBatteryState(int percent);
40 58  
  59 + //! \brief Get whether sensor is reachable
  60 + //! \note Reachable verification is not implemented for CLIP sensors yet
41 61 bool isReachable() const;
42 62  
  63 + //! \brief Get whether sensor has a URL
43 64 bool hasURL() const;
  65 + //! \brief Get sensor URL
44 66 std::string getURL() const;
  67 + //! \brief Set sensor URL
  68 + //! \throws std::system_error when system or socket operations fail
  69 + //! \throws HueException when response contained no body
  70 + //! \throws HueAPIResponseException when response contains an error
  71 + //! \throws nlohmann::json::parse_error when response could not be parsed
45 72 void setURL(const std::string& url);
46 73  
  74 + //! \brief Get time of last status update
  75 + //! \returns The last update time, or a time with a zero duration from epoch
  76 + //! if the last update time is not set.
47 77 time::AbsoluteTime getLastUpdated() const;
48 78  
49 79 protected:
  80 + //! \brief Protected constructor to be used by subclasses
50 81 explicit BaseCLIP(Sensor sensor) : BaseDevice(std::move(sensor)) { }
51 82 };
52 83  
  84 +//! \brief CLIP sensor for button presses
53 85 class CLIPSwitch : public BaseCLIP
54 86 {
55 87 public:
  88 + //! \brief Construct from generic sensor
56 89 explicit CLIPSwitch(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
57 90  
  91 + //! \brief Get the code of the last switch event.
58 92 int getButtonEvent() const;
  93 + //! \brief Set the button event code
  94 + //! \throws std::system_error when system or socket operations fail
  95 + //! \throws HueException when response contained no body
  96 + //! \throws HueAPIResponseException when response contains an error
  97 + //! \throws nlohmann::json::parse_error when response could not be parsed
59 98 void setButtonEvent(int code);
60 99  
  100 + //! \brief CLIPSwitch sensor type name
61 101 static constexpr const char* typeStr = "CLIPSwitch";
62 102 };
  103 +
  104 +//! \brief CLIP sensor detecting whether a contact is open or closed
63 105 class CLIPOpenClose : public BaseCLIP
64 106 {
65 107 public:
  108 + //! \brief Construct from generic sensor
66 109 explicit CLIPOpenClose(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
67 110  
  111 + //! \brief Get whether switch is open
68 112 bool isOpen() const;
  113 + //! \brief Set switch state
  114 + //!
  115 + //! The sensor needs to stay in a state for at least 1s.
  116 + //! \throws std::system_error when system or socket operations fail
  117 + //! \throws HueException when response contained no body
  118 + //! \throws HueAPIResponseException when response contains an error
  119 + //! \throws nlohmann::json::parse_error when response could not be parsed
69 120 void setOpen(bool open);
70 121  
  122 + //! \brief CLIPOpenClose sensor type name
71 123 static constexpr const char* typeStr = "CLIPOpenClose";
72 124 };
73 125  
  126 +//! \brief CLIP sensor to detect presence
74 127 class CLIPPresence : public BaseCLIP
75 128 {
76 129 public:
  130 + //! \brief Construct from generic sensor
77 131 explicit CLIPPresence(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
78 132  
  133 + //! \brief Get whether presence was dtected
79 134 bool getPresence() const;
  135 + //! \brief Set presence state
  136 + //! \throws std::system_error when system or socket operations fail
  137 + //! \throws HueException when response contained no body
  138 + //! \throws HueAPIResponseException when response contains an error
  139 + //! \throws nlohmann::json::parse_error when response could not be parsed
80 140 void setPresence(bool presence);
81 141  
  142 + //! \brief CLIPPresence sensor type name
82 143 static constexpr const char* typeStr = "CLIPPresence";
83 144 };
84 145  
  146 +//! \brief CLIP sensor for temperature
85 147 class CLIPTemperature : public BaseCLIP
86 148 {
87 149 public:
  150 + //! \brief Construct from generic sensor
88 151 explicit CLIPTemperature(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
89 152  
  153 + //! \brief Get measured temperature
  154 + //! \returns Temperature in 0.01 degrees Celsius.
90 155 int getTemperature() const;
  156 + //! \brief Set temperature
  157 + //! \param temperature Temperature in 0.01 degreese Celsius.
  158 + //! \throws std::system_error when system or socket operations fail
  159 + //! \throws HueException when response contained no body
  160 + //! \throws HueAPIResponseException when response contains an error
  161 + //! \throws nlohmann::json::parse_error when response could not be parsed
91 162 void setTemperature(int temperature);
92 163  
  164 + //! \brief CLIPTemperature sensor type name
93 165 static constexpr const char* typeStr = "CLIPTemperature";
94 166 };
  167 +
  168 +//! \brief CLIP sensor for humidity
95 169 class CLIPHumidity : public BaseCLIP
96 170 {
97 171 public:
  172 + //! \brief Construct from generic sensor
98 173 explicit CLIPHumidity(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
99 174  
  175 + //! \brief Get measured humidity
  176 + //! \returns Humidity in 0.01% steps
100 177 int getHumidity() const;
  178 + //! \brief Set humidity
  179 + //! \param humidity Humidity in 0.01%
  180 + //! \throws std::system_error when system or socket operations fail
  181 + //! \throws HueException when response contained no body
  182 + //! \throws HueAPIResponseException when response contains an error
  183 + //! \throws nlohmann::json::parse_error when response could not be parsed
101 184 void setHumidity(int humidity);
102 185  
  186 + //! \brief CLIPHumidity sensor type name
103 187 static constexpr const char* typeStr = "CLIPHumidity";
104 188 };
  189 +
  190 +//! \brief CLIP sensor for light level
105 191 class CLIPLightLevel : public BaseCLIP
106 192 {
107 193 public:
  194 + //! \brief Construct from generic sensor
108 195 explicit CLIPLightLevel(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
109 196  
  197 + //! \brief Get threshold to detect darkness
110 198 int getDarkThreshold() const;
  199 + //! \brief Set threshold to detect darkness
  200 + //! \param threshold Light level as reported by \ref getLightLevel
  201 + //! \throws std::system_error when system or socket operations fail
  202 + //! \throws HueException when response contained no body
  203 + //! \throws HueAPIResponseException when response contains an error
  204 + //! \throws nlohmann::json::parse_error when response could not be parsed
111 205 void setDarkThreshold(int threshold);
112 206  
  207 + //! \brief Get offset over dark threshold to detect daylight
113 208 int getThresholdOffset() const;
  209 + //! \brief Set offset to detect daylight
  210 + //! \param offset Offset to dark threshold to detect daylight. Must be greater than 1.
  211 + //! \throws std::system_error when system or socket operations fail
  212 + //! \throws HueException when response contained no body
  213 + //! \throws HueAPIResponseException when response contains an error
  214 + //! \throws nlohmann::json::parse_error when response could not be parsed
114 215 void setThresholdOffset(int offset);
115 216  
  217 + //! \brief Get measured light level
  218 + //! \returns Light level in <code>10000*log10(lux)+1</code> (logarithmic scale)
116 219 int getLightLevel() const;
  220 + //! \brief Set measured light level
  221 + //! \param level Light level in <code>10000*log10(lux)+1</code>
  222 + //! \throws std::system_error when system or socket operations fail
  223 + //! \throws HueException when response contained no body
  224 + //! \throws HueAPIResponseException when response contains an error
  225 + //! \throws nlohmann::json::parse_error when response could not be parsed
117 226 void setLightLevel(int level);
  227 + //! \brief Check whether light level is below dark threshold
118 228 bool isDark() const;
  229 + //! \brief Check whether light level is above light threshold
  230 + //!
  231 + //! Light threshold is dark threshold + offset
119 232 bool isDaylight() const;
120 233  
  234 + //! \brief CLIPLightLevel sensor type name
121 235 static constexpr const char* typeStr = "CLIPLightLevel";
122 236 };
  237 +
  238 +//! \brief CLIP sensor for a generic 3rd party sensor.
  239 +//!
  240 +//! Can be created by POST.
123 241 class CLIPGenericFlag : public BaseCLIP
124 242 {
125 243 public:
  244 + //! \brief Construct from generic sensor
126 245 explicit CLIPGenericFlag(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
127 246  
  247 + //! \brief Get boolean flag
128 248 bool getFlag() const;
  249 + //! \brief Set flag
  250 + //! \throws std::system_error when system or socket operations fail
  251 + //! \throws HueException when response contained no body
  252 + //! \throws HueAPIResponseException when response contains an error
  253 + //! \throws nlohmann::json::parse_error when response could not be parsed
129 254 void setFlag(bool flag);
130 255  
  256 + //! \brief CLIPGenericFlag sensor type name
131 257 static constexpr const char* typeStr = "CLIPGenericFlag";
132 258 };
  259 +
  260 +//! \brief CLIP sensor for a generic 3rd party status
  261 +//!
  262 +//! Can be created by POST.
133 263 class CLIPGenericStatus : public BaseCLIP
134 264 {
135 265 public:
  266 + //! \brief Construct from generic sensor
136 267 explicit CLIPGenericStatus(Sensor sensor) : BaseCLIP(std::move(sensor)) { }
137 268  
  269 + //! \brief Get sensor status
138 270 int getStatus() const;
  271 + //! \brief Set sensor status
  272 + //! \throws std::system_error when system or socket operations fail
  273 + //! \throws HueException when response contained no body
  274 + //! \throws HueAPIResponseException when response contains an error
  275 + //! \throws nlohmann::json::parse_error when response could not be parsed
139 276 void setStatus(int status);
140 277  
  278 + //! \brief CLIPGenericStatus sensor type name
141 279 static constexpr const char* typeStr = "CLIPGenericStatus";
142 280 };
143 281 } // namespace sensors
... ...
include/hueplusplus/ZLLSensors.h
  View file @c24d3db
... ... @@ -243,6 +243,7 @@ public:
243 243 bool isReachable() const;
244 244  
245 245 //! \brief Get recorded temperature
  246 + //! \returns Temperature in 0.01 degrees Celsius.
246 247 int getTemperature() const;
247 248  
248 249 //! \brief ZLLTemperature sensor type name
... ...