diff --git a/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.cpp b/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.cpp index 2deb82c..cc7f003 100644 --- a/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.cpp +++ b/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.cpp @@ -1,13 +1,38 @@ #include +/** + * @brief Construct a new Remote Variable object + * This constructor does not take any arguments. + * Please use the begin method to initialize the object. +*/ RemoteVariable::RemoteVariable() { this->topic = nullptr; this->value = nullptr; } + +/** + * @brief Destroy the Remote Variable object + * This destructor does not take any arguments. + * It will free the memory allocated for the topic and value. +*/ RemoteVariable::~RemoteVariable() { - delete this->topic; - delete this->value; + free(this->value); } + +/** + * @brief Initialize the RemoteVariable object with value request + * + * This method is used to initialize the RemoteVariable object. + * + * @param size The maximum size of the variable in bytes + * @param topic The topic that the variable is published to + * @param iot The ESPMegaIoT object + * @param useValueRequest Whether to use value request + * @param valueRequestTopic The topic to request value + * + * @note Because the value is null terminated, the size should be the desired text length + 1 + * @warning This use dynamic memory allocation, so it is important to call the destructor when the object is no longer needed +*/ void RemoteVariable::begin(size_t size, const char* topic, ESPMegaIoT* iot, bool useValueRequest, const char* valueRequestTopic) { this->iot = iot; this->size = size; @@ -22,10 +47,26 @@ void RemoteVariable::begin(size_t size, const char* topic, ESPMegaIoT* iot, bool this->subscribe(); } +/** + * @brief Initialize the RemoteVariable object + * + * This method is used to initialize the RemoteVariable object. + * + * @param size The maximum size of the variable in bytes + * @param topic The topic that the variable is published to + * @param iot The ESPMegaIoT object + * + * @note Because the value is null terminated, the size should be the desired text length + 1 + * @warning This use dynamic memory allocation, so it is important to call the destructor when the object is no longer needed +*/ void RemoteVariable::begin(size_t size, const char* topic, ESPMegaIoT* iot) { this->begin(size, topic, iot, false, nullptr); } +/** + * @brief Subscribe to the topic + * This method is used internally to subscribe to the topic from iot core +*/ void RemoteVariable::subscribe() { ESP_LOGD("RemoteVariable", "Subscribing to %s", this->topic); this->iot->subscribe(this->topic); @@ -34,10 +75,22 @@ void RemoteVariable::subscribe() { this->requestValue(); } } + +/** + * @brief Get the value of the variable + * + * This method is used to get the value of the variable. + * + * @return char* The null terminated string of the value +*/ char* RemoteVariable::getValue() { return this->value; } +/** + * @brief The MQTT callback + * This method is binded to the MQTT callback in iot core +*/ void RemoteVariable::mqtt_callback(char* topic, char* payload) { if (strcmp(topic, this->topic) == 0) { ESP_LOGD("RemoteVariable", "Received MQTT message from %s", topic); @@ -45,6 +98,11 @@ void RemoteVariable::mqtt_callback(char* topic, char* payload) { } } +/** + * @brief Request the value of the variable + * This method request a value update from the device that has the variable + * @note This method is only functional if the useValueRequest is set to true +*/ void RemoteVariable::requestValue() { if(!this->useValueRequest) return; @@ -52,11 +110,22 @@ void RemoteVariable::requestValue() { this->iot->publish(this->valueRequestTopic, "request"); } +/** + * @brief Enable the set value feature + * This method is used to enable the set value feature + * @param setValueTopic The topic to send the value to +*/ void RemoteVariable::enableSetValue(const char* setValueTopic) { this->useSetValue = true; this->setValueTopic = setValueTopic; } +/** + * @brief Set the value of the variable + * This method is used to set the value of the variable + * @param value The value to set + * @note This method is only functional if the enableSetValue is already called +*/ void RemoteVariable::setValue(const char* value) { if(!this->useSetValue) return; diff --git a/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.hpp b/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.hpp index fcf7a78..3292c3f 100644 --- a/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.hpp +++ b/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/RemoteVariable.hpp @@ -1,5 +1,12 @@ #pragma once #include +/** + * @brief A class that create a variable that exists on other devices and can be accessed remotely + * + * This class is used to create a variable that exists on other devices and can be accessed remotely. + * Supports setting and getting values from the variable. + * Also support value request. +*/ class RemoteVariable { public: