add effects for HALight

Author: martaisty

src/device-types/HALight.cpp

@@ -58,14 +58,31 @@ HALight::HALight(const char* uniqueId, const uint8_t features) :
     _maxMireds(),
     _currentColorTemperature(0),
     _currentRGBColor(),
+    _effects(nullptr),
+    _currentEffect(0),
     _stateCallback(nullptr),
     _brightnessCallback(nullptr),
     _colorTemperatureCallback(nullptr),
-    _rgbColorCallback(nullptr)
+    _rgbColorCallback(nullptr),
+    _effectCallback(nullptr)
 {
 
 }
 
+HALight::~HALight()
+{
+    if (_effects) {
+        const uint8_t effectsNb = _effects->getItemsNb();
+        const HASerializerArray::ItemType* effects = _effects->getItems();
+
+        for (uint8_t i = 0; i < effectsNb; i++) {
+            delete[] effects[i];
+        }
+
+        delete _effects;
+    }
+}
+
 bool HALight::setState(const bool state, const bool force)
 {
     if (!force && state == _currentState) {
@@ -122,13 +139,49 @@ bool HALight::setRGBColor(const RGBColor& color, const bool force)
     return false;
 }
 
+void HALight::setEffects(const char* const effects[], const uint8_t size)
+{
+    if (!(_features & EffectsFeature) || !effects || size == 0 || _effects) { // effects can be set only once
+        return;
+    }
+
+    _effects = new HASerializerArray(size, false);
+
+    uint8_t effectLen = 0;
+    for (uint8_t i = 0; i < size; i++) {
+        effectLen = strlen(effects[i]);
+
+        char* const effect = new char[effectLen + 1]; // include null terminator
+        effect[effectLen] = '\0';
+        memcpy(effect, effects[i], effectLen);
+
+        _effects->add(effect);
+    }
+}
+
+bool HALight::setEffect(const uint8_t effect, const bool force)
+{
+    if (!force && effect == _currentEffect) {
+        return true;
+    }
+
+    if (publishEffect(effect)) {
+        _currentEffect = effect;
+        return true;
+    }
+
+    return false;
+}
+
 void HALight::buildSerializer()
 {
-    if (_serializer || !uniqueId()) {
+    // EffectsFeature enabled and no _effects set => unlogical
+    const bool effectsEnabledButNotSet = (_features & EffectsFeature) && !_effects;
+    if (_serializer || !uniqueId() || effectsEnabledButNotSet) {
         return;
     }
 
-    _serializer = new HASerializer(this, 19); // 19 - max properties nb
+    _serializer = new HASerializer(this, 22); // 22 - max properties nb
     _serializer->set(AHATOFSTR(HANameProperty), _name);
     _serializer->set(AHATOFSTR(HAObjectIdProperty), _objectId);
     _serializer->set(HASerializer::WithUniqueId);
@@ -189,6 +242,17 @@ void HALight::buildSerializer()
         _serializer->topic(AHATOFSTR(HARGBStateTopic));
     }
 
+    if (_features & EffectsFeature) {
+        _serializer->topic(AHATOFSTR(HAEffectStateTopic));
+        _serializer->topic(AHATOFSTR(HAEffectCommandTopic));
+
+        _serializer->set(
+            AHATOFSTR(HAEffectsProperty),
+            _effects,
+            HASerializer::ArrayPropertyType
+        );
+    }
+
     _serializer->set(HASerializer::WithDevice);
     _serializer->set(HASerializer::WithAvailability);
     _serializer->topic(AHATOFSTR(HAStateTopic));
@@ -209,6 +273,7 @@ void HALight::onMqttConnected()
         publishBrightness(_currentBrightness);
         publishColorTemperature(_currentColorTemperature);
         publishRGBColor(_currentRGBColor);
+        publishEffect(_currentEffect);
     }
 
     subscribeTopic(uniqueId(), AHATOFSTR(HACommandTopic));
@@ -224,6 +289,10 @@ void HALight::onMqttConnected()
     if (_features & RGBFeature) {
         subscribeTopic(uniqueId(), AHATOFSTR(HARGBCommandTopic));
     }
+
+    if (_features & EffectsFeature) {
+        subscribeTopic(uniqueId(), AHATOFSTR(HAEffectCommandTopic));
+    }
 }
 
 void HALight::onMqttMessage(
@@ -258,6 +327,14 @@ void HALight::onMqttMessage(
         )
     ) {
         handleRGBCommand(payload, length);
+    } else if (
+        HASerializer::compareDataTopics(
+            topic,
+            uniqueId(),
+            AHATOFSTR(HAEffectCommandTopic)
+        )
+    ) {
+        handleEffectCommand(payload, length);
     }
 }
 
@@ -317,6 +394,20 @@ bool HALight::publishRGBColor(const RGBColor& color)
     return publishOnDataTopic(AHATOFSTR(HARGBStateTopic), str, true);
 }
 
+bool HALight::publishEffect(const uint8_t effect)
+{
+    if (!(_features & EffectsFeature) || !_effects || effect >= _effects->getItemsNb()) {
+        return false;
+    }
+
+    const char* effectName = _effects->getItems()[effect];
+    if (!effectName) {
+        return false;
+    }
+
+    return publishOnDataTopic(AHATOFSTR(HAEffectStateTopic), effectName, true);
+}
+
 void HALight::handleStateCommand(const uint8_t* cmd, const uint16_t length)
 {
     (void)cmd;
@@ -370,4 +461,21 @@ void HALight::handleRGBCommand(const uint8_t* cmd, const uint16_t length)
     }
 }
 
+void HALight::handleEffectCommand(const uint8_t* cmd, const uint16_t length)
+{
+    if (!_effectCallback) {
+        return;
+    }
+
+    const uint8_t effectsNb = _effects->getItemsNb();
+    const HASerializerArray::ItemType* effects = _effects->getItems();
+
+    for (uint8_t i = 0; i < effectsNb; i++) {
+        if (strlen(effects[i]) == length && memcmp(cmd, effects[i], length) == 0) {
+            _effectCallback(i, this);
+            return;
+        }
+    }
+}
+
 #endif

src/device-types/HALight.h

@@ -6,14 +6,17 @@
 
 #ifndef EX_ARDUINOHA_LIGHT
 
+class HASerializerArray;
+
 #define HALIGHT_STATE_CALLBACK(name) void (*name)(bool state, HALight* sender)
 #define HALIGHT_BRIGHTNESS_CALLBACK(name) void (*name)(uint8_t brightness, HALight* sender)
 #define HALIGHT_COLOR_TEMP_CALLBACK(name) void (*name)(uint16_t temperature, HALight* sender)
 #define HALIGHT_RGB_COLOR_CALLBACK(name) void (*name)(HALight::RGBColor color, HALight* sender)
+#define HALIGHT_EFFECT_CALLBACK(name) void (*name)(uint8_t index, HALight* sender)
 
 /**
  * HALight allows adding a controllable light in the Home Assistant panel.
- * The library supports only the state, brightness, color temperature and RGB color.
+ * The library supports only the state, brightness, color temperature, RGB color and effects.
  * If you need more features please open a new GitHub issue.
  *
  * @note
@@ -29,7 +32,8 @@ class HALight : public HABaseDeviceType
         DefaultFeatures = 0,
         BrightnessFeature = 1,
         ColorTemperatureFeature = 2,
-        RGBFeature = 4
+        RGBFeature = 4,
+        EffectsFeature = 8
     };
 
     struct RGBColor {
@@ -77,6 +81,7 @@ class HALight : public HABaseDeviceType
      *                 `HALight::BrightnessFeature | HALight::ColorTemperatureFeature`
      */
     HALight(const char* uniqueId, const uint8_t features = DefaultFeatures);
+    ~HALight();
 
     /**
      * Changes state of the light and publishes MQTT message.
@@ -122,6 +127,33 @@ class HALight : public HABaseDeviceType
      */
     bool setRGBColor(const RGBColor& color, const bool force = false);
 
+    /**
+     * Sets the list of available effects that will be listed.
+     * For example:
+     * `
+     * const char* const lightEffects[] = {"Fire","Rainbow","Snowflales","Rain","Smoke"};
+     * light.setEffects(lightEffects, 5);
+     * `
+     *
+     *
+     * @param effects The list of effects i.e. array of strings.
+     * @param size The size of the effects list i.e. total number of effects.
+     * @note The effects list can be set only once.
+     */
+    void setEffects(const char* const effects[], const uint8_t size);
+
+    /**
+     * Changes the effect of the light and publishes MQTT message.
+     * Effect represents the index of the effect that was set using setEffects method.
+     * Please note that if a new value is the same as previous one,
+     * the MQTT message won't be published.
+     *
+     * @param effect The new effect index of the light.
+     * @param force Forces to update the value without comparing it to a previous known value.
+     * @return Returns `true` if the effect is set successfully.
+     */
+    bool setEffect(const uint8_t effect, const bool force = false);
+
     /**
      * Alias for `setState(true)`.
      */
@@ -202,6 +234,24 @@ class HALight : public HABaseDeviceType
     inline const RGBColor& getCurrentRGBColor() const
         { return _currentRGBColor; }
 
+    /**
+     * Sets the current effect of the light without pushing the value to Home Assistant.
+     * This method may be useful if you want to change the effect before the connection
+     * with the MQTT broker is acquired.
+     *
+     * @param effect The new effect.
+     */
+    inline void setCurrentEffect(const uint8_t effect)
+        { _currentEffect = effect; }
+
+    /**
+     * Returns the last known effect of the light.
+     * Effect represents the index of the effect that was set using setEffects method.
+     * By default the effect is set to `0`.
+     */
+    inline uint8_t getCurrentEffect() const
+        { return _currentEffect; }
+
     /**
      * Sets icon of the light.
      * Any icon from MaterialDesignIcons.com (for example: `mdi:home`).
@@ -297,6 +347,21 @@ class HALight : public HABaseDeviceType
     inline void onRGBColorCommand(HALIGHT_RGB_COLOR_CALLBACK(callback))
         { _rgbColorCallback = callback; }
 
+    /**
+    * Registers callback that will be called each time the effect command from HA is received.
+    * Please note that it's not possible to register multiple callbacks for the same light.
+    *
+    * @param callback
+    * @note In non-optimistic mode, the effect must be reported back to HA using the HALight::setEffect method.
+    */
+    inline void onEffectCommand(HALIGHT_EFFECT_CALLBACK(callback))
+        { _effectCallback = callback; }
+
+#ifdef ARDUINOHA_TEST
+    inline HASerializerArray* getEffects() const
+        { return _effects; }
+#endif
+
 protected:
     virtual void buildSerializer() override;
     virtual void onMqttConnected() override;
@@ -339,6 +404,14 @@ class HALight : public HABaseDeviceType
      */
     bool publishRGBColor(const RGBColor& color);
 
+    /**
+     * Publishes the MQTT message with the given effect.
+     *
+     * @param effect The effect to publish.
+     * @returns Returns `true` if the MQTT message has been published successfully.
+     */
+    bool publishEffect(const uint8_t effect);
+
     /**
      * Parses the given state command and executes the callback with proper value.
      *
@@ -371,6 +444,14 @@ class HALight : public HABaseDeviceType
      */
     void handleRGBCommand(const uint8_t* cmd, const uint16_t length);
 
+    /**
+    * Parses the given effect command and executes the callback with proper value.
+    *
+    * @param cmd The data of the command.
+    * @param length Length of the command.
+    */
+    void handleEffectCommand(const uint8_t* cmd, const uint16_t length);
+
     /// Features enabled for the light.
     const uint8_t _features;
 
@@ -404,6 +485,12 @@ class HALight : public HABaseDeviceType
     /// The current RBB color. By default the value is not set.
     RGBColor _currentRGBColor;
 
+    /// Array of effects for the serializer.
+    HASerializerArray* _effects;
+
+    /// The current effect (the current effect's index). By default it's `0`.
+    uint8_t _currentEffect;
+
     /// The callback that will be called when the state command is received from the HA.
     HALIGHT_STATE_CALLBACK(_stateCallback);
 
@@ -415,6 +502,9 @@ class HALight : public HABaseDeviceType
 
     /// The callback that will be called when the RGB command is received from the HA.
     HALIGHT_RGB_COLOR_CALLBACK(_rgbColorCallback);
+
+    /// The callback that will be called when the effect is received from the HA.
+    HALIGHT_EFFECT_CALLBACK(_effectCallback);
 };
 
 #endif

src/utils/HADictionary.cpp

@@ -65,6 +65,7 @@ const char HASpeedRangeMinProperty[] PROGMEM = {"spd_rng_min"};
 const char HABrightnessScaleProperty[] PROGMEM = {"bri_scl"};
 const char HAMinMiredsProperty[] PROGMEM = {"min_mirs"};
 const char HAMaxMiredsProperty[] PROGMEM = {"max_mirs"};
+const char HAEffectsProperty[] PROGMEM = {"fx_list"};
 const char HATemperatureUnitProperty[] PROGMEM = {"temp_unit"};
 const char HAMinTempProperty[] PROGMEM = {"min_temp"};
 const char HAMaxTempProperty[] PROGMEM = {"max_temp"};
@@ -105,6 +106,8 @@ const char HATemperatureStateTopic[] PROGMEM = {"temp_stat_t"};
 const char HARGBCommandTopic[] PROGMEM = {"rgb_cmd_t"};
 const char HARGBStateTopic[] PROGMEM = {"rgb_stat_t"};
 const char HAJsonAttributesTopic[] PROGMEM = {"json_attr_t"};
+const char HAEffectCommandTopic[] PROGMEM = {"fx_cmd_t"};
+const char HAEffectStateTopic[] PROGMEM = {"fx_stat_t"};
 
 // misc
 const char HAOnline[] PROGMEM = {"online"};

src/utils/HADictionary.h

@@ -65,6 +65,7 @@ extern const char HASpeedRangeMinProperty[];
 extern const char HABrightnessScaleProperty[];
 extern const char HAMinMiredsProperty[];
 extern const char HAMaxMiredsProperty[];
+extern const char HAEffectsProperty[];
 extern const char HATemperatureUnitProperty[];
 extern const char HAMinTempProperty[];
 extern const char HAMaxTempProperty[];
@@ -105,6 +106,8 @@ extern const char HATemperatureStateTopic[];
 extern const char HARGBCommandTopic[];
 extern const char HARGBStateTopic[];
 extern const char HAJsonAttributesTopic[];
+extern const char HAEffectCommandTopic[];
+extern const char HAEffectStateTopic[];
 
 // misc
 extern const char HAOnline[];