From 76ac2c83531716eef9861adbd1aad9dc6502a4da Mon Sep 17 00:00:00 2001 From: Jojo-1000 <33495614+Jojo-1000@users.noreply.github.com> Date: Tue, 18 Aug 2020 23:08:10 +0200 Subject: [PATCH] Add documentation for ZLL sensors. --- include/hueplusplus/Sensor.h | 3 ++- include/hueplusplus/ZLLSensors.h | 158 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- src/ZLLSensors.cpp | 49 ++++++++++++++++++++++++++++++++++++++++--------- 3 files changed, 199 insertions(+), 11 deletions(-) diff --git a/include/hueplusplus/Sensor.h b/include/hueplusplus/Sensor.h index 2f67602..7eeb44f 100644 --- a/include/hueplusplus/Sensor.h +++ b/include/hueplusplus/Sensor.h @@ -97,6 +97,7 @@ public: //! \brief Get whether sensor has alerts bool hasAlert() const; //! \brief Get last sent alert + //! \note This is not cleared when the alert ends. //! \throws nlohmann::json::out_of_range when sensor has no alert. Alert getLastAlert() const; //! \brief Send alert @@ -285,7 +286,7 @@ public: bool hasBatteryState() const; //! \brief Get battery state //! \returns Battery state in percent - //! \throws nlohmann::json::out_of_range when sensor has no battery status. + //! \throws nlohmann::json::out_of_range when sensor has no battery state. int getBatteryState() const; //! \brief Set battery state //! \throws std::system_error when system or socket operations fail diff --git a/include/hueplusplus/ZLLSensors.h b/include/hueplusplus/ZLLSensors.h index c521608..2f8c061 100644 --- a/include/hueplusplus/ZLLSensors.h +++ b/include/hueplusplus/ZLLSensors.h @@ -28,133 +28,289 @@ namespace hueplusplus { namespace sensors { +//! \brief ZigBee Green Power sensor for button presses class ZGPSwitch : public BaseDevice { public: + //! \brief Construct from generic sensor explicit ZGPSwitch(Sensor sensor) : BaseDevice(std::move(sensor)) { } + //! \brief Check if sensor is on + //! + //! Sensors which are off do not change their status bool isOn() const; + //! \brief Enable or disable sensor + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void setOn(bool on); + //! \brief Get the code of the last switch event. + //! + //! Possible values are \ref c_button1 etc., or any other value. int getButtonEvent() const; + //! \brief Code for tap button 1 static constexpr int c_button1 = 34; + //! \brief Code for tap button 2 static constexpr int c_button2 = 16; + //! \brief Code for tap button 3 static constexpr int c_button3 = 17; + //! \brief Code for tap button 4 static constexpr int c_button4 = 18; + //! \brief ZGPSwitch sensor type name static constexpr const char* typeStr = "ZGPSwitch"; }; + +//! \brief ZigBee sensor reporting button presses class ZLLSwitch : public BaseDevice { public: + //! \brief Construct from generic sensor explicit ZLLSwitch(Sensor sensor) : BaseDevice(std::move(sensor)) { } + //! \brief Check if sensor is on + //! + //! Sensors which are off do not change their status bool isOn() const; + //! \brief Enable or disable sensor + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void setOn(bool on); + //! \brief Get whether sensor has a battery state bool hasBatteryState() const; + //! \brief Get battery state + //! \returns Battery state in percent int getBatteryState() const; + //! \brief Get last sent alert + //! \note This is not cleared when the alert ends. Alert getLastAlert() const; + //! \brief Send alert + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void sendAlert(Alert type); + //! \brief Get whether sensor is reachable bool isReachable() const; + //! \brief Get the code of the last switch event. + //! + //! Possible values are \ref c_ON_INITIAL_PRESS etc., or any other value. int getButtonEvent() const; + //! \brief Get time of last status update + //! \returns The last update time, or a time with a zero duration from epoch + //! if the last update time is not set. time::AbsoluteTime getLastUpdated() const; + //! \brief Button 1 (ON) pressed static constexpr int c_ON_INITIAL_PRESS = 1000; + //! \brief Button 1 (ON) held static constexpr int c_ON_HOLD = 1001; + //! \brief Button 1 (ON) released short press static constexpr int c_ON_SHORT_RELEASED = 1002; + //! \brief Button 1 (ON) released long press static constexpr int c_ON_LONG_RELEASED = 1003; + //! \brief Button 2 (DIM UP) pressed static constexpr int c_UP_INITIAL_PRESS = 2000; + //! \brief Button 2 (DIM UP) held static constexpr int c_UP_HOLD = 2001; + //! \brief Button 2 (DIM UP) released short press static constexpr int c_UP_SHORT_RELEASED = 2002; + //! \brief Button 2 (DIM UP) released long press static constexpr int c_UP_LONG_RELEASED = 2003; + //! \brief Button 3 (DIM DOWN) pressed static constexpr int c_DOWN_INITIAL_PRESS = 3000; + //! \brief Button 3 (DIM DOWN) held static constexpr int c_DOWN_HOLD = 3001; + //! \brief Button 3 (DIM DOWN) released short press static constexpr int c_DOWN_SHORT_RELEASED = 3002; + //! \brief Button 3 (DIM DOWN) released long press static constexpr int c_DOWN_LONG_RELEASED = 3003; + //! \brief Button 4 (OFF) pressed static constexpr int c_OFF_INITIAL_PRESS = 4000; + //! \brief Button 4 (OFF) held static constexpr int c_OFF_HOLD = 4001; + //! \brief Button 4 (OFF) released short press static constexpr int c_OFF_SHORT_RELEASED = 4002; + //! \brief Button 4 (OFF) released long press static constexpr int c_OFF_LONG_RELEASED = 4003; + //! \brief ZLLSwitch sensor type name static constexpr const char* typeStr = "ZLLSwitch"; }; + +//! \brief Sensor detecting presence in the vicinity class ZLLPresence : public BaseDevice { public: + //! \brief Construct from generic sensor explicit ZLLPresence(Sensor sensor) : BaseDevice(std::move(sensor)) { } + + //! \brief Check if sensor is on + //! + //! Sensors which are off do not change their status bool isOn() const; + //! \brief Enable or disable sensor + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void setOn(bool on); + //! \brief Get whether sensor has a battery state bool hasBatteryState() const; + //! \brief Get battery state + //! \returns Battery state in percent int getBatteryState() const; + //! \brief Get last sent alert + //! \note This is not cleared when the alert ends. Alert getLastAlert() const; + //! \brief Send alert + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void sendAlert(Alert type); + //! \brief Get whether sensor is reachable bool isReachable() const; + //! \brief Get sensor sensitivity int getSensitivity() const; + //! \brief Get maximum sensitivity int getMaxSensitivity() const; + //! \brief Set sensor sensitivity + //! \param sensitivity Sensitivity from 0 to max sensitivity (inclusive) void setSensitivity(int sensitivity); + //! \brief Get presence status bool getPresence() const; + //! \brief Get time of last status update + //! \returns The last update time, or a time with a zero duration from epoch + //! if the last update time is not set. time::AbsoluteTime getLastUpdated() const; + //! \brief ZLLPresence sensor type name static constexpr const char* typeStr = "ZLLPresence"; }; +//! \brief ZigBee temperature sensor class ZLLTemperature : public BaseDevice { public: + //! \brief Construct from generic sensor explicit ZLLTemperature(Sensor sensor) : BaseDevice(std::move(sensor)) { } + //! \brief Check if sensor is on + //! + //! Sensors which are off do not change their status bool isOn() const; + //! \brief Enable or disable sensor + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void setOn(bool on); + //! \brief Get whether sensor has a battery state bool hasBatteryState() const; + //! \brief Get battery state + //! \returns Battery state in percent int getBatteryState() const; + //! \brief Get last sent alert + //! \note This is not cleared when the alert ends. Alert getLastAlert() const; + //! \brief Send alert + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void sendAlert(Alert type); + //! \brief Get whether sensor is reachable bool isReachable() const; + //! \brief Get recorded temperature int getTemperature() const; + //! \brief ZLLTemperature sensor type name static constexpr const char* typeStr = "ZLLTemperature"; }; + +//! \brief ZigBee sensor detecting ambient light level class ZLLLightLevel : public BaseDevice { public: + //! \brief Construct from generic sensor explicit ZLLLightLevel(Sensor sensor) : BaseDevice(std::move(sensor)) { } + //! \brief Check if sensor is on + //! + //! Sensors which are off do not change their status bool isOn() const; + //! \brief Enable or disable sensor + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void setOn(bool on); + //! \brief Get whether sensor has a battery state bool hasBatteryState() const; + //! \brief Get battery state + //! \returns Battery state in percent int getBatteryState() const; + //! \brief Get whether sensor is reachable bool isReachable() const; + //! \brief Get threshold to detect darkness int getDarkThreshold() const; + //! \brief Set threshold to detect darkness + //! \param threshold Light level as reported by \ref getLightLevel + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void setDarkThreshold(int threshold); - + //! \brief Get offset over dark threshold to detect daylight int getThresholdOffset() const; + //! \brief Set offset to detect daylight + //! \param offset Offset to dark threshold to detect daylight. Must be greater than 1. + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed void setThresholdOffset(int offset); + //! \brief Get measured light level + //! \returns Light level in 10000*log10(lux)+1 (logarithmic scale) int getLightLevel() const; + //! \brief Check whether light level is below dark threshold bool isDark() const; + //! \brief Check whether light level is above light threshold + //! + //! Light threshold is dark threshold + offset bool isDaylight() const; + //! \brief Get time of last status update + //! \returns The last update time, or a time with a zero duration from epoch + //! if the last update time is not set. time::AbsoluteTime getLastUpdated() const; + //! \brief ZLLLightLevel sensor type name static constexpr const char* typeStr = "ZLLLightLevel"; }; } // namespace sensors diff --git a/src/ZLLSensors.cpp b/src/ZLLSensors.cpp index d2d625e..bdff4e6 100644 --- a/src/ZLLSensors.cpp +++ b/src/ZLLSensors.cpp @@ -27,6 +27,13 @@ namespace hueplusplus { namespace sensors { + +constexpr int ZGPSwitch::c_button1; +constexpr int ZGPSwitch::c_button2; +constexpr int ZGPSwitch::c_button3; +constexpr int ZGPSwitch::c_button4; +constexpr const char* ZGPSwitch::typeStr; + bool ZGPSwitch::isOn() const { return state.getValue().at("config").at("on").get(); @@ -34,7 +41,7 @@ bool ZGPSwitch::isOn() const void ZGPSwitch::setOn(bool on) { - sendPutRequest("/config", nlohmann::json{ {"on", on} }, CURRENT_FILE_INFO); + sendPutRequest("/config", nlohmann::json {{"on", on}}, CURRENT_FILE_INFO); } int ZGPSwitch::getButtonEvent() const @@ -42,6 +49,24 @@ int ZGPSwitch::getButtonEvent() const return state.getValue().at("state").at("buttonevent").get(); } +constexpr int ZLLSwitch::c_ON_INITIAL_PRESS; +constexpr int ZLLSwitch::c_ON_HOLD; +constexpr int ZLLSwitch::c_ON_SHORT_RELEASED; +constexpr int ZLLSwitch::c_ON_LONG_RELEASED; +constexpr int ZLLSwitch::c_UP_INITIAL_PRESS; +constexpr int ZLLSwitch::c_UP_HOLD; +constexpr int ZLLSwitch::c_UP_SHORT_RELEASED; +constexpr int ZLLSwitch::c_UP_LONG_RELEASED; +constexpr int ZLLSwitch::c_DOWN_INITIAL_PRESS; +constexpr int ZLLSwitch::c_DOWN_HOLD; +constexpr int ZLLSwitch::c_DOWN_SHORT_RELEASED; +constexpr int ZLLSwitch::c_DOWN_LONG_RELEASED; +constexpr int ZLLSwitch::c_OFF_INITIAL_PRESS; +constexpr int ZLLSwitch::c_OFF_HOLD; +constexpr int ZLLSwitch::c_OFF_SHORT_RELEASED; +constexpr int ZLLSwitch::c_OFF_LONG_RELEASED; +constexpr const char* ZLLSwitch::typeStr; + bool ZLLSwitch::isOn() const { return state.getValue().at("config").at("on").get(); @@ -49,7 +74,7 @@ bool ZLLSwitch::isOn() const void ZLLSwitch::setOn(bool on) { - sendPutRequest("/config", nlohmann::json{ {"on", on} }, CURRENT_FILE_INFO); + sendPutRequest("/config", nlohmann::json {{"on", on}}, CURRENT_FILE_INFO); } bool ZLLSwitch::hasBatteryState() const { @@ -89,6 +114,8 @@ time::AbsoluteTime ZLLSwitch::getLastUpdated() const return time::AbsoluteTime::parseUTC(it->get()); } +constexpr const char* ZLLPresence::typeStr; + bool ZLLPresence::isOn() const { return state.getValue().at("config").at("on").get(); @@ -96,7 +123,7 @@ bool ZLLPresence::isOn() const void ZLLPresence::setOn(bool on) { - sendPutRequest("/config", nlohmann::json{ {"on", on} }, CURRENT_FILE_INFO); + sendPutRequest("/config", nlohmann::json {{"on", on}}, CURRENT_FILE_INFO); } bool ZLLPresence::hasBatteryState() const { @@ -149,6 +176,8 @@ time::AbsoluteTime ZLLPresence::getLastUpdated() const return time::AbsoluteTime::parseUTC(it->get()); } +constexpr const char* ZLLTemperature::typeStr; + bool ZLLTemperature::isOn() const { return state.getValue().at("config").at("on").get(); @@ -156,7 +185,7 @@ bool ZLLTemperature::isOn() const void ZLLTemperature::setOn(bool on) { - sendPutRequest("/config", { "on", on }, CURRENT_FILE_INFO); + sendPutRequest("/config", {"on", on}, CURRENT_FILE_INFO); } bool ZLLTemperature::hasBatteryState() const { @@ -174,7 +203,7 @@ Alert ZLLTemperature::getLastAlert() const } void ZLLTemperature::sendAlert(Alert type) { - sendPutRequest("/state", nlohmann::json{ {"alert", alertToString(type)} }, CURRENT_FILE_INFO); + sendPutRequest("/state", nlohmann::json {{"alert", alertToString(type)}}, CURRENT_FILE_INFO); } bool ZLLTemperature::isReachable() const { @@ -186,6 +215,8 @@ int ZLLTemperature::getTemperature() const return state.getValue().at("state").at("temperature").get(); } +constexpr const char* ZLLLightLevel::typeStr; + bool ZLLLightLevel::isOn() const { return state.getValue().at("config").at("on").get(); @@ -193,7 +224,7 @@ bool ZLLLightLevel::isOn() const void ZLLLightLevel::setOn(bool on) { - sendPutRequest("/config", { "on", on }, CURRENT_FILE_INFO); + sendPutRequest("/config", {"on", on}, CURRENT_FILE_INFO); } bool ZLLLightLevel::hasBatteryState() const { @@ -214,7 +245,7 @@ int ZLLLightLevel::getDarkThreshold() const void ZLLLightLevel::setDarkThreshold(int threshold) { - sendPutRequest("/config", nlohmann::json{ { "tholddark", threshold} }, CURRENT_FILE_INFO); + sendPutRequest("/config", nlohmann::json {{"tholddark", threshold}}, CURRENT_FILE_INFO); } int ZLLLightLevel::getThresholdOffset() const { @@ -223,7 +254,7 @@ int ZLLLightLevel::getThresholdOffset() const void ZLLLightLevel::setThresholdOffset(int offset) { - sendPutRequest("/config", nlohmann::json{ { "tholdoffset", offset} }, CURRENT_FILE_INFO); + sendPutRequest("/config", nlohmann::json {{"tholdoffset", offset}}, CURRENT_FILE_INFO); } int ZLLLightLevel::getLightLevel() const @@ -247,7 +278,7 @@ time::AbsoluteTime ZLLLightLevel::getLastUpdated() const auto it = stateJson.find("lastupdated"); if (it == stateJson.end() || !it->is_string() || *it == "none") { - return time::AbsoluteTime(std::chrono::system_clock::time_point(std::chrono::seconds{ 0 })); + return time::AbsoluteTime(std::chrono::system_clock::time_point(std::chrono::seconds {0})); } return time::AbsoluteTime::parseUTC(it->get()); } -- libgit2 0.21.4