HALight class¶

class HALight : public HABaseDeviceType ¶

HALight allows adding a controllable light in the Home Assistant panel. The library supports only the state, brightness, color temperature and RGB color. If you need more features please open a new GitHub issue.

Note

You can find more information about this entity in the Home Assistant documentation: https://www.home-assistant.io/integrations/light.mqtt/

Public Types

enum Features¶

Values:

enumerator DefaultFeatures¶

enumerator BrightnessFeature¶

enumerator ColorTemperatureFeature¶

enumerator RGBFeature¶

Public Functions

HALight(const char *uniqueId, const uint8_t features = DefaultFeatures)¶

Parameters

uniqueId – The unique ID of the light. It needs to be unique in a scope of your device.
features – Features that should be enabled for the light. You can enable multiple features by using OR bitwise operator, for example: HALight::BrightnessFeature | HALight::ColorTemperatureFeature

bool setState(const bool state, const bool force = false)¶

Changes state of the light and publishes MQTT message. Please note that if a new value is the same as previous one, the MQTT message won’t be published.

Parameters

state – New state of the light.
force – Forces to update state without comparing it to previous known state.

Returns

Returns true if MQTT message has been published successfully.

bool setBrightness(const uint8_t brightness, const bool force = false)¶

Changes the brightness of the light and publishes MQTT message. Please note that if a new value is the same as previous one, the MQTT message won’t be published.

Parameters

brightness – The new brightness of the light.
force – Forces to update the value without comparing it to a previous known value.

Returns

Returns true if MQTT message has been published successfully.

bool setColorTemperature(const uint16_t temperature, const bool force = false)¶

Changes the color temperature of the light and publishes MQTT message. Please note that if a new value is the same as previous one, the MQTT message won’t be published.

Parameters

temperature – The new color temperature of the light.
force – Forces to update the value without comparing it to a previous known value.

Returns

Returns true if MQTT message has been published successfully.

bool setRGBColor(const RGBColor &color, const bool force = false)¶

Changes the RGB color of the light and publishes MQTT message. Please note that if a new color is the same as previous one, the MQTT message won’t be published.

Parameters

color – The new RGB color of the light.
force – Forces to update the value without comparing it to a previous known value.

Returns

Returns true if MQTT message has been published successfully.

inline bool turnOn()¶: Alias for setState(true).

inline bool turnOff()¶: Alias for setState(false).

inline void setCurrentState(const bool state)¶

Sets current state of the light without publishing it to Home Assistant. This method may be useful if you want to change state before connection with MQTT broker is acquired.

Parameters: state – New state of the light.

inline bool getCurrentState() const¶: Returns last known state of the light. By default it’s false.

inline void setCurrentBrightness(const uint8_t brightness)¶

Sets the current brightness of the light without pushing the value to Home Assistant. This method may be useful if you want to change the brightness before the connection with the MQTT broker is acquired.

Parameters: brightness – The new brightness of the light.

inline uint8_t getCurrentBrightness() const¶: Returns the last known brightness of the light. By default brightness is set to 0.

inline void setCurrentColorTemperature(const uint16_t temperature)¶

Sets the current color temperature of the light without pushing the value to Home Assistant. This method may be useful if you want to change the color temperature before the connection with the MQTT broker is acquired.

Parameters: colorTemp – The new color temperature (mireds).

inline uint16_t getCurrentColorTemperature() const¶: Returns the last known color temperature of the light. By default temperature is set to 0.

inline void setCurrentRGBColor(const RGBColor &color)¶

Sets the current RGB color of the light without pushing the value to Home Assistant. This method may be useful if you want to change the color before the connection with the MQTT broker is acquired.

Parameters: color – The new RGB color.

inline const RGBColor &getCurrentRGBColor() const¶: Returns the last known RGB color of the light. By default the RGB color is set to 0,0,0.

inline void setIcon(const char *icon)¶

Sets icon of the light. Any icon from MaterialDesignIcons.com (for example: mdi:home).

Parameters: icon – The icon name.

inline void setRetain(const bool retain)¶

Sets retain flag for the light’s command. If set to true the command produced by Home Assistant will be retained.

Parameters: retain –

inline void setOptimistic(const bool optimistic)¶

Sets optimistic flag for the light state. In this mode the light state doesn’t need to be reported back to the HA panel when a command is received. By default the optimistic mode is disabled.

Parameters: optimistic – The optimistic mode (true - enabled, false - disabled).

inline void setBrightnessScale(const uint8_t scale)¶

Sets the maximum brightness value that can be set via HA panel. By default it’s 255.

Parameters: scale – The maximum value of the brightness.

inline void setMinMireds(const uint16_t mireds)¶

Sets the minimum color temperature (mireds) value that can be set via HA panel. By default it’s 153.

Parameters: mireds – The minimum value of the brightness.

inline void setMaxMireds(const uint16_t mireds)¶

Sets the maximum color temperature (mireds) value that can be set via HA panel. By default it’s 500.

Parameters: mireds – The maximum value of the brightness.

inline void onStateCommand(void (*callback)(bool state, HALight *sender))¶

Registers callback that will be called each time the state command from HA is received. Please note that it’s not possible to register multiple callbacks for the same light.

Note

In non-optimistic mode, the state must be reported back to HA using the HALight::setState method.

Parameters: callback –

inline void onBrightnessCommand(void (*callback)(uint8_t brightness, HALight *sender))¶

Registers callback that will be called each time the brightness command from HA is received. Please note that it’s not possible to register multiple callbacks for the same light.

Note

In non-optimistic mode, the brightness must be reported back to HA using the HALight::setBrightness method.

Parameters: callback –

inline void onColorTemperatureCommand(void (*callback)(uint16_t temperature, HALight *sender))¶

Registers callback that will be called each time the color temperature command from HA is received. Please note that it’s not possible to register multiple callbacks for the same light.

Note

In non-optimistic mode, the color temperature must be reported back to HA using the HALight::setColorTemperature method.

Parameters: callback –

inline void onRGBColorCommand(void (*callback)(HALight::RGBColor color, HALight *sender))¶

Registers callback that will be called each time the RGB color command from HA is received. Please note that it’s not possible to register multiple callbacks for the same light.

Note

In non-optimistic mode, the color must be reported back to HA using the HALight::setRGBColor method.

Parameters: callback –

Public Static Attributes

static const uint8_t RGBStringMaxLength¶

Protected Functions

virtual void buildSerializer() override¶

virtual void onMqttConnected() override¶

virtual void onMqttMessage(const char *topic, const uint8_t *payload, const uint16_t length) override¶

Private Functions

bool publishState(const bool state)¶

Publishes the MQTT message with the given state.

Parameters: state – The state to publish.
Returns: Returns true if the MQTT message has been published successfully.

bool publishBrightness(const uint8_t brightness)¶

Publishes the MQTT message with the given brightness.

Parameters: brightness – The brightness to publish.
Returns: Returns true if the MQTT message has been published successfully.

bool publishColorTemperature(const uint16_t temperature)¶

Publishes the MQTT message with the given color temperature (mireds).

Parameters: temperature – The color temperature to publish.
Returns: Returns true if the MQTT message has been published successfully.

bool publishRGBColor(const RGBColor &color)¶

Publishes the MQTT message with the given RGB color.

Parameters: color – The color to publish.
Returns: Returns true if the MQTT message has been published successfully.

void handleStateCommand(const uint8_t *cmd, const uint16_t length)¶

Parses the given state command and executes the callback with proper value.

Parameters

cmd – The data of the command.
length – Length of the command.

void handleBrightnessCommand(const uint8_t *cmd, const uint16_t length)¶

Parses the given brightness command and executes the callback with proper value.

Parameters

cmd – The data of the command.
length – Length of the command.

void handleColorTemperatureCommand(const uint8_t *cmd, const uint16_t length)¶

Parses the given color temperature command and executes the callback with proper value.

Parameters

cmd – The data of the command.
length – Length of the command.

void handleRGBCommand(const uint8_t *cmd, const uint16_t length)¶

Parses the given RGB color command and executes the callback with proper value.

Parameters

cmd – The data of the command.
length – Length of the command.

Private Members

const uint8_t _features¶: Features enabled for the light.

const char *_icon¶: The icon of the button. It can be nullptr.

bool _retain¶: The retain flag for the HA commands.

bool _optimistic¶: The optimistic mode of the light (true - enabled, false - disabled).

HANumeric _brightnessScale¶: The maximum value of the brightness. By default it’s 255.

bool _currentState¶: The current state of the light. By default it’s false.

uint8_t _currentBrightness¶: The current brightness of the light. By default it’s 0.

HANumeric _minMireds¶: The minimum color temperature (mireds). By default the value is not set.

HANumeric _maxMireds¶: The maximum color temperature (mireds). By default the value is not set.

uint16_t _currentColorTemperature¶: The current color temperature (mireds). By default the value is not set.

RGBColor _currentRGBColor¶: The current RBB color. By default the value is not set.

void (*_stateCallback)(bool state, HALight *sender)¶: The callback that will be called when the state command is received from the HA.

void (*_brightnessCallback)(uint8_t brightness, HALight *sender)¶: The callback that will be called when the brightness command is received from the HA.

void (*_colorTemperatureCallback)(uint16_t temperature, HALight *sender)¶: The callback that will be called when the color temperature command is received from the HA.

void (*_rgbColorCallback)(HALight::RGBColor color, HALight *sender)¶: The callback that will be called when the RGB command is received from the HA.

struct RGBColor¶

Public Functions

inline RGBColor()¶

inline RGBColor(uint8_t r, uint8_t g, uint8_t b)¶

inline void operator=(const RGBColor &a)¶

inline bool operator==(const RGBColor &a) const¶

inline bool operator!=(const RGBColor &a) const¶

void fromBuffer(const uint8_t *data, const uint16_t length)¶

Public Members

uint8_t red¶

uint8_t green¶

uint8_t blue¶

bool isSet¶