Peter M. Groen / hueplusplus

Commit 76ac2c83531716eef9861adbd1aad9dc6502a4da

Authored by Jojo-1000
Committed by Moritz Wirger
1 parent a90a9779

Add documentation for ZLL sensors.

Inline Side-by-side
Showing 3 changed files with 199 additions and 11 deletions
include/hueplusplus/Sensor.h
  View file @76ac2c8
... ... @@ -97,6 +97,7 @@ public:
97 97 //! \brief Get whether sensor has alerts
98 98 bool hasAlert() const;
99 99 //! \brief Get last sent alert
  100 + //! \note This is not cleared when the alert ends.
100 101 //! \throws nlohmann::json::out_of_range when sensor has no alert.
101 102 Alert getLastAlert() const;
102 103 //! \brief Send alert
... ... @@ -285,7 +286,7 @@ public:
285 286 bool hasBatteryState() const;
286 287 //! \brief Get battery state
287 288 //! \returns Battery state in percent
288   - //! \throws nlohmann::json::out_of_range when sensor has no battery status.
  289 + //! \throws nlohmann::json::out_of_range when sensor has no battery state.
289 290 int getBatteryState() const;
290 291 //! \brief Set battery state
291 292 //! \throws std::system_error when system or socket operations fail
... ...
include/hueplusplus/ZLLSensors.h
  View file @76ac2c8
... ... @@ -28,133 +28,289 @@ namespace hueplusplus
28 28 {
29 29 namespace sensors
30 30 {
  31 +//! \brief ZigBee Green Power sensor for button presses
31 32 class ZGPSwitch : public BaseDevice
32 33 {
33 34 public:
  35 + //! \brief Construct from generic sensor
34 36 explicit ZGPSwitch(Sensor sensor) : BaseDevice(std::move(sensor)) { }
35 37  
  38 + //! \brief Check if sensor is on
  39 + //!
  40 + //! Sensors which are off do not change their status
36 41 bool isOn() const;
  42 + //! \brief Enable or disable sensor
  43 + //! \throws std::system_error when system or socket operations fail
  44 + //! \throws HueException when response contained no body
  45 + //! \throws HueAPIResponseException when response contains an error
  46 + //! \throws nlohmann::json::parse_error when response could not be parsed
37 47 void setOn(bool on);
38 48  
  49 + //! \brief Get the code of the last switch event.
  50 + //!
  51 + //! Possible values are \ref c_button1 etc., or any other value.
39 52 int getButtonEvent() const;
40 53  
  54 + //! \brief Code for tap button 1
41 55 static constexpr int c_button1 = 34;
  56 + //! \brief Code for tap button 2
42 57 static constexpr int c_button2 = 16;
  58 + //! \brief Code for tap button 3
43 59 static constexpr int c_button3 = 17;
  60 + //! \brief Code for tap button 4
44 61 static constexpr int c_button4 = 18;
45 62  
  63 + //! \brief ZGPSwitch sensor type name
46 64 static constexpr const char* typeStr = "ZGPSwitch";
47 65 };
  66 +
  67 +//! \brief ZigBee sensor reporting button presses
48 68 class ZLLSwitch : public BaseDevice
49 69 {
50 70 public:
  71 + //! \brief Construct from generic sensor
51 72 explicit ZLLSwitch(Sensor sensor) : BaseDevice(std::move(sensor)) { }
52 73  
  74 + //! \brief Check if sensor is on
  75 + //!
  76 + //! Sensors which are off do not change their status
53 77 bool isOn() const;
  78 + //! \brief Enable or disable sensor
  79 + //! \throws std::system_error when system or socket operations fail
  80 + //! \throws HueException when response contained no body
  81 + //! \throws HueAPIResponseException when response contains an error
  82 + //! \throws nlohmann::json::parse_error when response could not be parsed
54 83 void setOn(bool on);
55 84  
  85 + //! \brief Get whether sensor has a battery state
56 86 bool hasBatteryState() const;
  87 + //! \brief Get battery state
  88 + //! \returns Battery state in percent
57 89 int getBatteryState() const;
58 90  
  91 + //! \brief Get last sent alert
  92 + //! \note This is not cleared when the alert ends.
59 93 Alert getLastAlert() const;
  94 + //! \brief Send alert
  95 + //! \throws std::system_error when system or socket operations fail
  96 + //! \throws HueException when response contained no body
  97 + //! \throws HueAPIResponseException when response contains an error
  98 + //! \throws nlohmann::json::parse_error when response could not be parsed
60 99 void sendAlert(Alert type);
61 100  
  101 + //! \brief Get whether sensor is reachable
62 102 bool isReachable() const;
63 103  
  104 + //! \brief Get the code of the last switch event.
  105 + //!
  106 + //! Possible values are \ref c_ON_INITIAL_PRESS etc., or any other value.
64 107 int getButtonEvent() const;
65 108  
  109 + //! \brief Get time of last status update
  110 + //! \returns The last update time, or a time with a zero duration from epoch
  111 + //! if the last update time is not set.
66 112 time::AbsoluteTime getLastUpdated() const;
67 113  
  114 + //! \brief Button 1 (ON) pressed
68 115 static constexpr int c_ON_INITIAL_PRESS = 1000;
  116 + //! \brief Button 1 (ON) held
69 117 static constexpr int c_ON_HOLD = 1001;
  118 + //! \brief Button 1 (ON) released short press
70 119 static constexpr int c_ON_SHORT_RELEASED = 1002;
  120 + //! \brief Button 1 (ON) released long press
71 121 static constexpr int c_ON_LONG_RELEASED = 1003;
  122 + //! \brief Button 2 (DIM UP) pressed
72 123 static constexpr int c_UP_INITIAL_PRESS = 2000;
  124 + //! \brief Button 2 (DIM UP) held
73 125 static constexpr int c_UP_HOLD = 2001;
  126 + //! \brief Button 2 (DIM UP) released short press
74 127 static constexpr int c_UP_SHORT_RELEASED = 2002;
  128 + //! \brief Button 2 (DIM UP) released long press
75 129 static constexpr int c_UP_LONG_RELEASED = 2003;
  130 + //! \brief Button 3 (DIM DOWN) pressed
76 131 static constexpr int c_DOWN_INITIAL_PRESS = 3000;
  132 + //! \brief Button 3 (DIM DOWN) held
77 133 static constexpr int c_DOWN_HOLD = 3001;
  134 + //! \brief Button 3 (DIM DOWN) released short press
78 135 static constexpr int c_DOWN_SHORT_RELEASED = 3002;
  136 + //! \brief Button 3 (DIM DOWN) released long press
79 137 static constexpr int c_DOWN_LONG_RELEASED = 3003;
  138 + //! \brief Button 4 (OFF) pressed
80 139 static constexpr int c_OFF_INITIAL_PRESS = 4000;
  140 + //! \brief Button 4 (OFF) held
81 141 static constexpr int c_OFF_HOLD = 4001;
  142 + //! \brief Button 4 (OFF) released short press
82 143 static constexpr int c_OFF_SHORT_RELEASED = 4002;
  144 + //! \brief Button 4 (OFF) released long press
83 145 static constexpr int c_OFF_LONG_RELEASED = 4003;
84 146  
  147 + //! \brief ZLLSwitch sensor type name
85 148 static constexpr const char* typeStr = "ZLLSwitch";
86 149 };
  150 +
  151 +//! \brief Sensor detecting presence in the vicinity
87 152 class ZLLPresence : public BaseDevice
88 153 {
89 154 public:
  155 + //! \brief Construct from generic sensor
90 156 explicit ZLLPresence(Sensor sensor) : BaseDevice(std::move(sensor)) { }
  157 +
  158 + //! \brief Check if sensor is on
  159 + //!
  160 + //! Sensors which are off do not change their status
91 161 bool isOn() const;
  162 + //! \brief Enable or disable sensor
  163 + //! \throws std::system_error when system or socket operations fail
  164 + //! \throws HueException when response contained no body
  165 + //! \throws HueAPIResponseException when response contains an error
  166 + //! \throws nlohmann::json::parse_error when response could not be parsed
92 167 void setOn(bool on);
93 168  
  169 + //! \brief Get whether sensor has a battery state
94 170 bool hasBatteryState() const;
  171 + //! \brief Get battery state
  172 + //! \returns Battery state in percent
95 173 int getBatteryState() const;
96 174  
  175 + //! \brief Get last sent alert
  176 + //! \note This is not cleared when the alert ends.
97 177 Alert getLastAlert() const;
  178 + //! \brief Send alert
  179 + //! \throws std::system_error when system or socket operations fail
  180 + //! \throws HueException when response contained no body
  181 + //! \throws HueAPIResponseException when response contains an error
  182 + //! \throws nlohmann::json::parse_error when response could not be parsed
98 183 void sendAlert(Alert type);
99 184  
  185 + //! \brief Get whether sensor is reachable
100 186 bool isReachable() const;
101 187  
  188 + //! \brief Get sensor sensitivity
102 189 int getSensitivity() const;
  190 + //! \brief Get maximum sensitivity
103 191 int getMaxSensitivity() const;
  192 + //! \brief Set sensor sensitivity
  193 + //! \param sensitivity Sensitivity from 0 to max sensitivity (inclusive)
104 194 void setSensitivity(int sensitivity);
105 195  
  196 + //! \brief Get presence status
106 197 bool getPresence() const;
107 198  
  199 + //! \brief Get time of last status update
  200 + //! \returns The last update time, or a time with a zero duration from epoch
  201 + //! if the last update time is not set.
108 202 time::AbsoluteTime getLastUpdated() const;
109 203  
  204 + //! \brief ZLLPresence sensor type name
110 205 static constexpr const char* typeStr = "ZLLPresence";
111 206 };
112 207  
  208 +//! \brief ZigBee temperature sensor
113 209 class ZLLTemperature : public BaseDevice
114 210 {
115 211 public:
  212 + //! \brief Construct from generic sensor
116 213 explicit ZLLTemperature(Sensor sensor) : BaseDevice(std::move(sensor)) { }
117 214  
  215 + //! \brief Check if sensor is on
  216 + //!
  217 + //! Sensors which are off do not change their status
118 218 bool isOn() const;
  219 + //! \brief Enable or disable sensor
  220 + //! \throws std::system_error when system or socket operations fail
  221 + //! \throws HueException when response contained no body
  222 + //! \throws HueAPIResponseException when response contains an error
  223 + //! \throws nlohmann::json::parse_error when response could not be parsed
119 224 void setOn(bool on);
120 225  
  226 + //! \brief Get whether sensor has a battery state
121 227 bool hasBatteryState() const;
  228 + //! \brief Get battery state
  229 + //! \returns Battery state in percent
122 230 int getBatteryState() const;
123 231  
  232 + //! \brief Get last sent alert
  233 + //! \note This is not cleared when the alert ends.
124 234 Alert getLastAlert() const;
  235 + //! \brief Send alert
  236 + //! \throws std::system_error when system or socket operations fail
  237 + //! \throws HueException when response contained no body
  238 + //! \throws HueAPIResponseException when response contains an error
  239 + //! \throws nlohmann::json::parse_error when response could not be parsed
125 240 void sendAlert(Alert type);
126 241  
  242 + //! \brief Get whether sensor is reachable
127 243 bool isReachable() const;
128 244  
  245 + //! \brief Get recorded temperature
129 246 int getTemperature() const;
130 247  
  248 + //! \brief ZLLTemperature sensor type name
131 249 static constexpr const char* typeStr = "ZLLTemperature";
132 250 };
  251 +
  252 +//! \brief ZigBee sensor detecting ambient light level
133 253 class ZLLLightLevel : public BaseDevice
134 254 {
135 255 public:
  256 + //! \brief Construct from generic sensor
136 257 explicit ZLLLightLevel(Sensor sensor) : BaseDevice(std::move(sensor)) { }
137 258  
  259 + //! \brief Check if sensor is on
  260 + //!
  261 + //! Sensors which are off do not change their status
138 262 bool isOn() const;
  263 + //! \brief Enable or disable sensor
  264 + //! \throws std::system_error when system or socket operations fail
  265 + //! \throws HueException when response contained no body
  266 + //! \throws HueAPIResponseException when response contains an error
  267 + //! \throws nlohmann::json::parse_error when response could not be parsed
139 268 void setOn(bool on);
140 269  
  270 + //! \brief Get whether sensor has a battery state
141 271 bool hasBatteryState() const;
  272 + //! \brief Get battery state
  273 + //! \returns Battery state in percent
142 274 int getBatteryState() const;
143 275  
  276 + //! \brief Get whether sensor is reachable
144 277 bool isReachable() const;
145 278  
  279 + //! \brief Get threshold to detect darkness
146 280 int getDarkThreshold() const;
  281 + //! \brief Set threshold to detect darkness
  282 + //! \param threshold Light level as reported by \ref getLightLevel
  283 + //! \throws std::system_error when system or socket operations fail
  284 + //! \throws HueException when response contained no body
  285 + //! \throws HueAPIResponseException when response contains an error
  286 + //! \throws nlohmann::json::parse_error when response could not be parsed
147 287 void setDarkThreshold(int threshold);
148   -
  288 + //! \brief Get offset over dark threshold to detect daylight
149 289 int getThresholdOffset() const;
  290 + //! \brief Set offset to detect daylight
  291 + //! \param offset Offset to dark threshold to detect daylight. Must be greater than 1.
  292 + //! \throws std::system_error when system or socket operations fail
  293 + //! \throws HueException when response contained no body
  294 + //! \throws HueAPIResponseException when response contains an error
  295 + //! \throws nlohmann::json::parse_error when response could not be parsed
150 296 void setThresholdOffset(int offset);
151 297  
  298 + //! \brief Get measured light level
  299 + //! \returns Light level in <code>10000*log10(lux)+1</code> (logarithmic scale)
152 300 int getLightLevel() const;
  301 + //! \brief Check whether light level is below dark threshold
153 302 bool isDark() const;
  303 + //! \brief Check whether light level is above light threshold
  304 + //!
  305 + //! Light threshold is dark threshold + offset
154 306 bool isDaylight() const;
155 307  
  308 + //! \brief Get time of last status update
  309 + //! \returns The last update time, or a time with a zero duration from epoch
  310 + //! if the last update time is not set.
156 311 time::AbsoluteTime getLastUpdated() const;
157 312  
  313 + //! \brief ZLLLightLevel sensor type name
158 314 static constexpr const char* typeStr = "ZLLLightLevel";
159 315 };
160 316 } // namespace sensors
... ...
src/ZLLSensors.cpp
  View file @76ac2c8
... ... @@ -27,6 +27,13 @@ namespace hueplusplus
27 27 {
28 28 namespace sensors
29 29 {
  30 +
  31 +constexpr int ZGPSwitch::c_button1;
  32 +constexpr int ZGPSwitch::c_button2;
  33 +constexpr int ZGPSwitch::c_button3;
  34 +constexpr int ZGPSwitch::c_button4;
  35 +constexpr const char* ZGPSwitch::typeStr;
  36 +
30 37 bool ZGPSwitch::isOn() const
31 38 {
32 39 return state.getValue().at("config").at("on").get<bool>();
... ... @@ -34,7 +41,7 @@ bool ZGPSwitch::isOn() const
34 41  
35 42 void ZGPSwitch::setOn(bool on)
36 43 {
37   - sendPutRequest("/config", nlohmann::json{ {"on", on} }, CURRENT_FILE_INFO);
  44 + sendPutRequest("/config", nlohmann::json {{"on", on}}, CURRENT_FILE_INFO);
38 45 }
39 46  
40 47 int ZGPSwitch::getButtonEvent() const
... ... @@ -42,6 +49,24 @@ int ZGPSwitch::getButtonEvent() const
42 49 return state.getValue().at("state").at("buttonevent").get<int>();
43 50 }
44 51  
  52 +constexpr int ZLLSwitch::c_ON_INITIAL_PRESS;
  53 +constexpr int ZLLSwitch::c_ON_HOLD;
  54 +constexpr int ZLLSwitch::c_ON_SHORT_RELEASED;
  55 +constexpr int ZLLSwitch::c_ON_LONG_RELEASED;
  56 +constexpr int ZLLSwitch::c_UP_INITIAL_PRESS;
  57 +constexpr int ZLLSwitch::c_UP_HOLD;
  58 +constexpr int ZLLSwitch::c_UP_SHORT_RELEASED;
  59 +constexpr int ZLLSwitch::c_UP_LONG_RELEASED;
  60 +constexpr int ZLLSwitch::c_DOWN_INITIAL_PRESS;
  61 +constexpr int ZLLSwitch::c_DOWN_HOLD;
  62 +constexpr int ZLLSwitch::c_DOWN_SHORT_RELEASED;
  63 +constexpr int ZLLSwitch::c_DOWN_LONG_RELEASED;
  64 +constexpr int ZLLSwitch::c_OFF_INITIAL_PRESS;
  65 +constexpr int ZLLSwitch::c_OFF_HOLD;
  66 +constexpr int ZLLSwitch::c_OFF_SHORT_RELEASED;
  67 +constexpr int ZLLSwitch::c_OFF_LONG_RELEASED;
  68 +constexpr const char* ZLLSwitch::typeStr;
  69 +
45 70 bool ZLLSwitch::isOn() const
46 71 {
47 72 return state.getValue().at("config").at("on").get<bool>();
... ... @@ -49,7 +74,7 @@ bool ZLLSwitch::isOn() const
49 74  
50 75 void ZLLSwitch::setOn(bool on)
51 76 {
52   - sendPutRequest("/config", nlohmann::json{ {"on", on} }, CURRENT_FILE_INFO);
  77 + sendPutRequest("/config", nlohmann::json {{"on", on}}, CURRENT_FILE_INFO);
53 78 }
54 79 bool ZLLSwitch::hasBatteryState() const
55 80 {
... ... @@ -89,6 +114,8 @@ time::AbsoluteTime ZLLSwitch::getLastUpdated() const
89 114 return time::AbsoluteTime::parseUTC(it->get<std::string>());
90 115 }
91 116  
  117 +constexpr const char* ZLLPresence::typeStr;
  118 +
92 119 bool ZLLPresence::isOn() const
93 120 {
94 121 return state.getValue().at("config").at("on").get<bool>();
... ... @@ -96,7 +123,7 @@ bool ZLLPresence::isOn() const
96 123  
97 124 void ZLLPresence::setOn(bool on)
98 125 {
99   - sendPutRequest("/config", nlohmann::json{ {"on", on} }, CURRENT_FILE_INFO);
  126 + sendPutRequest("/config", nlohmann::json {{"on", on}}, CURRENT_FILE_INFO);
100 127 }
101 128 bool ZLLPresence::hasBatteryState() const
102 129 {
... ... @@ -149,6 +176,8 @@ time::AbsoluteTime ZLLPresence::getLastUpdated() const
149 176 return time::AbsoluteTime::parseUTC(it->get<std::string>());
150 177 }
151 178  
  179 +constexpr const char* ZLLTemperature::typeStr;
  180 +
152 181 bool ZLLTemperature::isOn() const
153 182 {
154 183 return state.getValue().at("config").at("on").get<bool>();
... ... @@ -156,7 +185,7 @@ bool ZLLTemperature::isOn() const
156 185  
157 186 void ZLLTemperature::setOn(bool on)
158 187 {
159   - sendPutRequest("/config", { "on", on }, CURRENT_FILE_INFO);
  188 + sendPutRequest("/config", {"on", on}, CURRENT_FILE_INFO);
160 189 }
161 190 bool ZLLTemperature::hasBatteryState() const
162 191 {
... ... @@ -174,7 +203,7 @@ Alert ZLLTemperature::getLastAlert() const
174 203 }
175 204 void ZLLTemperature::sendAlert(Alert type)
176 205 {
177   - sendPutRequest("/state", nlohmann::json{ {"alert", alertToString(type)} }, CURRENT_FILE_INFO);
  206 + sendPutRequest("/state", nlohmann::json {{"alert", alertToString(type)}}, CURRENT_FILE_INFO);
178 207 }
179 208 bool ZLLTemperature::isReachable() const
180 209 {
... ... @@ -186,6 +215,8 @@ int ZLLTemperature::getTemperature() const
186 215 return state.getValue().at("state").at("temperature").get<int>();
187 216 }
188 217  
  218 +constexpr const char* ZLLLightLevel::typeStr;
  219 +
189 220 bool ZLLLightLevel::isOn() const
190 221 {
191 222 return state.getValue().at("config").at("on").get<bool>();
... ... @@ -193,7 +224,7 @@ bool ZLLLightLevel::isOn() const
193 224  
194 225 void ZLLLightLevel::setOn(bool on)
195 226 {
196   - sendPutRequest("/config", { "on", on }, CURRENT_FILE_INFO);
  227 + sendPutRequest("/config", {"on", on}, CURRENT_FILE_INFO);
197 228 }
198 229 bool ZLLLightLevel::hasBatteryState() const
199 230 {
... ... @@ -214,7 +245,7 @@ int ZLLLightLevel::getDarkThreshold() const
214 245  
215 246 void ZLLLightLevel::setDarkThreshold(int threshold)
216 247 {
217   - sendPutRequest("/config", nlohmann::json{ { "tholddark", threshold} }, CURRENT_FILE_INFO);
  248 + sendPutRequest("/config", nlohmann::json {{"tholddark", threshold}}, CURRENT_FILE_INFO);
218 249 }
219 250 int ZLLLightLevel::getThresholdOffset() const
220 251 {
... ... @@ -223,7 +254,7 @@ int ZLLLightLevel::getThresholdOffset() const
223 254  
224 255 void ZLLLightLevel::setThresholdOffset(int offset)
225 256 {
226   - sendPutRequest("/config", nlohmann::json{ { "tholdoffset", offset} }, CURRENT_FILE_INFO);
  257 + sendPutRequest("/config", nlohmann::json {{"tholdoffset", offset}}, CURRENT_FILE_INFO);
227 258 }
228 259  
229 260 int ZLLLightLevel::getLightLevel() const
... ... @@ -247,7 +278,7 @@ time::AbsoluteTime ZLLLightLevel::getLastUpdated() const
247 278 auto it = stateJson.find("lastupdated");
248 279 if (it == stateJson.end() || !it->is_string() || *it == "none")
249 280 {
250   - return time::AbsoluteTime(std::chrono::system_clock::time_point(std::chrono::seconds{ 0 }));
  281 + return time::AbsoluteTime(std::chrono::system_clock::time_point(std::chrono::seconds {0}));
251 282 }
252 283 return time::AbsoluteTime::parseUTC(it->get<std::string>());
253 284 }
... ...