Release 1.3.0 (#36)

* Add support for HVAC (#15)

* remove HASwitch::triggerCallback method

* fix typo in docs

* HASwitch: simplify callback #define

* work in progress: HVAC

* replace local mqtt instances with singleton

* device types optimization

* cleanup

* finished aux heating and away mode

* wip: HVAC

* finished HVAC implementation

* HVAC implementation

* add ifdefs for all HA components

* wip: optimization

* update readme

* update examples

* remove unused constructor from HAMqtt

* update HAUtils

* remove mqtt from constructors, fix compilation warnings

* finished HVAC

* add HVAC example, add changelog

* update changelog, add documentation

* Add support for icons in HASwitch and HASensor (#16)

* add support for icon in HASwitch

* add support for icon in HASensor

* update changelog

* add support for setting retain flag in HASwitch

* Add support for text payload in HASensor (#17)

* refactored HASensor

* update changelog

* fix sensor example

* Add support for fans (HAFan) (#18)

* finished basic implementation of the HAFan

* add retain method to DeviceTypeSerializer

* finished HAFan implementation

* update HAHVAC

* device types cleanup

* add HAFan example

* update changelog

* update readme

* update fan example

* optimization, add support for ActionFeature in HVAC

* Add support for MQTT LWT (#19)

* add support for hostname in HAMqtt

* add support for LWT and shared availability

* minor fixes

* added advanced availability example

* update examples

* update changelog

* cleanup & bug fix

* bump up version

* minor improvements and fixes

* update readme

* add HAMqtt::onMessage method

* Add support for covers (#28)

* add HACovers

* add cover example, update implementation

* disable debug

* update mqtt-events example

* Add support for setting different prefix for non-discovery topics (#29)

* add support for data prefix

* cleanup

* update comments and logs

* update multi-state-button example

* rename rexample from mqtt-events to mqtt-advanced

* update changelog

* update links in changelog

* Home Assistant 2021.4.5 - MQTT upgrade (#33)

* updae HAFan implementation

* change lib version

* update changelog

* fix setSpeed method

* update HAFan example

* Separate uniqueId from name (#34)

* rename name to uniqueId

* remove legacy labels

* update examples

* rename isMyTopic to compareTopics

* update changelog, rename name to uniqueId

* Implement onBeforeStateChanged callback in HASwitch (#35)

* add low latency mode to HASwitch

* add onBeforeStateChanged callback to HASwitch

* update readme

* rename DEPRECATED macro

* update advanced MQTT example

examples/advanced-availability/advanced-availability.ino

@@ -13,7 +13,7 @@ EthernetClient client;
 HADevice device(mac, sizeof(mac));
 HAMqtt mqtt(client, device);
 
-// "input" may be anything you want to be displayed in HA panel
+// "input" is unique ID of the sensor. You should define you own ID.
 // "door" is device class (based on the class HA displays different icons in the panel)
 // "true" is initial state of the sensor. In this example it's "true" as we use pullup resistor
 HABinarySensor sensor("input", "door", true);
@@ -32,6 +32,8 @@ void setup() {
     device.setName("Arduino");
     device.setSoftwareVersion("1.0.0");
 
+    sensor.setName("Door sensor"); // optional
+
     // This method enables availability for all device types registered on the device.
     // For example, if you have 5 sensors on the same device, you can enable
     // shared availability and change availability state of all sensors using

examples/availability/availability.ino

@@ -13,7 +13,7 @@ EthernetClient client;
 HADevice device(mac, sizeof(mac));
 HAMqtt mqtt(client, device);
 
-// "input" may be anything you want to be displayed in HA panel
+// "input" is unique ID of the sensor. You should define you own ID.
 // "door" is device class (based on the class HA displays different icons in the panel)
 // "true" is initial state of the sensor. In this example it's "true" as we use pullup resistor
 HABinarySensor sensor("input", "door", true);
@@ -36,6 +36,8 @@ void setup() {
     device.setName("Arduino");
     device.setSoftwareVersion("1.0.0");
 
+    sensor.setName("Door sensor"); // optional
+
     mqtt.begin(BROKER_ADDR);
 }
 

examples/binary-sensor/binary-sensor.ino

@@ -12,7 +12,7 @@ EthernetClient client;
 HADevice device(mac, sizeof(mac));
 HAMqtt mqtt(client, device);
 
-// "input" may be anything you want to be displayed in HA panel
+// "input" is unique ID of the sensor. You should define you own ID.
 // "door" is device class (based on the class HA displays different icons in the panel)
 // "true" is initial state of the sensor. In this example it's "true" as we use pullup resistor
 HABinarySensor sensor("input", "door", true);
@@ -28,6 +28,8 @@ void setup() {
     device.setName("Arduino");
     device.setSoftwareVersion("1.0.0");
 
+    sensor.setName("Door sensor"); // optional
+
     mqtt.begin(BROKER_ADDR);
 }
 

examples/cover/cover.ino

@@ -0,0 +1,49 @@
+#include <Ethernet.h>
+#include <ArduinoHA.h>
+
+#define BROKER_ADDR     IPAddress(192,168,0,17)
+
+byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
+
+EthernetClient client;
+HADevice device(mac, sizeof(mac));
+HAMqtt mqtt(client, device);
+HACover cover("my-cover"); // "my-cover" is unique ID of the cover. You should define your own ID.
+
+void onCoverCommand(HACover::CoverCommand cmd) {
+    if (cmd == HACover::CommandOpen) {
+        Serial.println("Command: Open");
+        cover.setState(HACover::StateOpening);
+    } else if (cmd == HACover::CommandClose) {
+        Serial.println("Command: Close");
+        cover.setState(HACover::StateClosing);
+    } else if (cmd == HACover::CommandStop) {
+        Serial.println("Command: Stop");
+        cover.setState(HACover::StateStopped);
+    }
+
+    // Available states:
+    // HACover::StateClosed
+    // HACover::StateClosing
+    // HACover::StateOpen
+    // HACover::StateOpening
+    // HACover::StateStopped
+
+    // You can also report position using setPosition() method
+}
+
+void setup() {
+    Serial.begin(9600);
+    Ethernet.begin(mac);
+
+    cover.onCommand(onCoverCommand);
+    cover.setName("My cover"); // optional
+    // cover.setRetain(true); // optionally you can set retain flag
+
+    mqtt.begin(BROKER_ADDR);
+}
+
+void loop() {
+    Ethernet.maintain();
+    mqtt.loop();
+}

examples/fan/fan.ino

@@ -11,6 +11,7 @@ HAMqtt mqtt(client, device);
 
 // HAFan::SpeedsFeature enables support for setting different speeds of fan.
 // You can skip this argument if you don't need speed management.
+// "ventilation" is unique ID of the fan. You should define your own ID.
 HAFan fan("ventilation", HAFan::SpeedsFeature);
 
 void onStateChanged(bool state) {
@@ -18,20 +19,14 @@ void onStateChanged(bool state) {
     Serial.println(state);
 }
 
-void onSpeedChanged(HAFan::Speed speed) {
+void onSpeedChanged(uint16_t speed) {
     Serial.print("Speed: ");
-    if (speed == HAFan::OffSpeed) {
-        Serial.print("off");
-    } else if (speed == HAFan::LowSpeed) {
-        Serial.print("low");
-    } else if (speed == HAFan::MediumSpeed) {
-        Serial.print("medium");
-    } else if (speed == HAFan::HighSpeed) {
-        Serial.print("high");
-    }
+    Serial.println(speed);
 }
 
 void setup() {
+    Serial.begin(9600);
+
     // you don't need to verify return status
     Ethernet.begin(mac);
 
@@ -40,10 +35,10 @@ void setup() {
     device.setSoftwareVersion("1.0.0");
 
     // configure fan (optional)
-    // default speeds are: Off | Low | Medium | High
-    fan.setSpeeds(HAFan::OffSpeed | HAFan::LowSpeed | HAFan::HighSpeed);
     fan.setName("Bathroom");
     fan.setRetain(true);
+    fan.setSpeedRangeMin(1);
+    fan.setSpeedRangeMax(100);
 
     // handle fan states
     fan.onStateChanged(onStateChanged);

examples/led-switch/led-switch.ino

@@ -9,7 +9,13 @@ byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
 EthernetClient client;
 HADevice device(mac, sizeof(mac));
 HAMqtt mqtt(client, device);
-HASwitch led("led", false); // you can use custom name in place of "led"
+HASwitch led("led", false); // "led" is unique ID of the switch. You should define your own ID.
+
+void onBeforeSwitchStateChanged(bool state, HASwitch* s)
+{
+    // this callback will be called before publishing new state to HA
+    // in some cases there may be delay before onStateChanged is called due to network latency
+}
 
 void onSwitchStateChanged(bool state, HASwitch* s)
 {
@@ -29,8 +35,10 @@ void setup() {
 
     // set icon (optional)
     led.setIcon("mdi:lightbulb");
+    led.setName("My LED");
 
     // handle switch state
+    led.onBeforeStateChanged(onBeforeSwitchStateChanged); // optional
     led.onStateChanged(onSwitchStateChanged);
 
     mqtt.begin(BROKER_ADDR);

examples/mqtt-advanced/mqtt-advanced.ino

@@ -0,0 +1,56 @@
+#include <Ethernet.h>
+#include <ArduinoHA.h>
+
+#define BROKER_ADDR         IPAddress(192,168,0,17)
+
+byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
+
+EthernetClient client;
+HADevice device(mac, sizeof(mac));
+HAMqtt mqtt(client, device);
+
+void onMqttMessage(const char* topic, const uint8_t* payload, uint16_t length) {
+    // This callback is called when message from MQTT broker is received.
+    // Please note that you should always verify if the message's topic is the one you expect.
+    // For example: if (memcmp(topic, "myCustomTopic") == 0) { ... }
+
+    Serial.print("New message on topic: ");
+    Serial.println(topic);
+    Serial.print("Data: ");
+    Serial.println((const char*)payload);
+
+    mqtt.publish("myPublishTopic", "hello");
+}
+
+void onMqttConnected() {
+    Serial.println("Connected to the broker!");
+
+    // You can subscribe to custom topic if you need
+    mqtt.subscribe("myCustomTopic");
+}
+
+void onMqttConnectionFailed() {
+    Serial.println("Failed to connect to the broker!");
+}
+
+void setup() {
+    Serial.begin(9600);
+    Ethernet.begin(mac);
+
+    mqtt.onMessage(onMqttMessage);
+    mqtt.onConnected(onMqttConnected);
+    mqtt.onConnectionFailed(onMqttConnectionFailed);
+
+    // If you use custom discovery prefix you can change it as following:
+    // mqtt.setDiscoveryPrefix("customPrefix");
+
+    // If you want to change prefix only for non-discovery prefix:
+    // mqtt.setDataPrefix("data");
+
+    mqtt.begin(BROKER_ADDR);
+}
+
+void loop() {
+    Ethernet.maintain();
+    mqtt.loop();
+}

examples/mqtt-events/mqtt-events.ino

@@ -1,32 +0,0 @@
-#include <Ethernet.h>
-#include <ArduinoHA.h>
-
-#define BROKER_ADDR         IPAddress(192,168,0,17)
-
-byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
-
-EthernetClient client;
-HADevice device(mac, sizeof(mac));
-HAMqtt mqtt(client, device);
-
-void onMqttConnected() {
-    Serial.println("Connected to the broker!");
-}
-
-void onMqttConnectionFailed() {
-    Serial.println("Failed to connect to the broker!");
-}
-
-void setup() {
-    Serial.begin(9600);
-    Ethernet.begin(mac);
-
-    mqtt.onConnected(onMqttConnected);
-    mqtt.onConnectionFailed(onMqttConnectionFailed);
-    mqtt.begin(BROKER_ADDR);
-}
-
-void loop() {
-    Ethernet.maintain();
-    mqtt.loop();
-}

examples/mqtt-with-credentials/mqtt-with-credentials.ino

@@ -11,7 +11,7 @@ byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
 EthernetClient client;
 HADevice device(mac, sizeof(mac));
 HAMqtt mqtt(client, device);
-HASwitch led("led", false); // you can use custom name in place of "led"
+HASwitch led("led", false); // "led" is unique ID of the switch. You should define your own ID.
 
 void onSwitchStateChanged(bool state, HASwitch* s)
 {
@@ -31,6 +31,7 @@ void setup() {
 
     // handle switch state
     led.onStateChanged(onSwitchStateChanged);
+    led.setName("My LED"); // optional
 
     mqtt.begin(BROKER_ADDR, BROKER_USERNAME, BROKER_PASSWORD);
 }

examples/multi-state-button/multi-state-button.ino

@@ -22,8 +22,6 @@ void setup() {
     // you don't need to verify return status
     Ethernet.begin(mac);
 
-    Serial.println(Ethernet.localIP());
-
     // set device's details (optional)
     device.setName("Arduino");
     device.setSoftwareVersion("1.0.0");

examples/nano33iot/nano33iot.ino

@@ -9,7 +9,7 @@
 WiFiClient client;
 HADevice device;
 HAMqtt mqtt(client, device);
-HASwitch led("led", false); // you can use custom name in place of "led"
+HASwitch led("led", false); // "led" is unique ID of the switch. You should define your own ID.
 
 void onSwitchStateChanged(bool state, HASwitch* s)
 {
@@ -43,6 +43,7 @@ void setup() {
 
     // handle switch state
     led.onStateChanged(onSwitchStateChanged);
+    led.setName("My LED"); // optional
 
     mqtt.begin(BROKER_ADDR);
 }

examples/nodemcu/nodemcu.ino

@@ -9,7 +9,13 @@
 WiFiClient client;
 HADevice device;
 HAMqtt mqtt(client, device);
-HASwitch led("led", false); // you can use custom name in place of "led"
+HASwitch led("led", false); // "led" is unique ID of the switch. You should define your own ID.
+
+void onBeforeSwitchStateChanged(bool state, HASwitch* s)
+{
+    // this callback will be called before publishing new state to HA
+    // in some cases there may be delay before onStateChanged is called due to network latency
+}
 
 void onSwitchStateChanged(bool state, HASwitch* s)
 {
@@ -42,7 +48,9 @@ void setup() {
     device.setSoftwareVersion("1.0.0");
 
     // handle switch state
+    led.onBeforeStateChanged(onBeforeSwitchStateChanged); // optional
     led.onStateChanged(onSwitchStateChanged);
+    led.setName("My LED"); // optional
 
     mqtt.begin(BROKER_ADDR);
 }

examples/sensor/sensor.ino

@@ -10,7 +10,13 @@ double lastValue = 0;
 EthernetClient client;
 HADevice device(mac, sizeof(mac));
 HAMqtt mqtt(client, device);
-HASensor temp("temp");
+HASensor temp("temp"); // "temp" is unique ID of the sensor. You should define your own ID.
+
+void onBeforeSwitchStateChanged(bool state, HASwitch* s)
+{
+    // this callback will be called before publishing new state to HA
+    // in some cases there may be delay before onStateChanged is called due to network latency
+}
 
 void setup() {
     // you don't need to verify return status
@@ -24,6 +30,7 @@ void setup() {
     temp.setUnitOfMeasurement("°C");
     temp.setDeviceClass("temperature");
     temp.setIcon("mdi:home");
+    temp.setName("Home temperature");
 
     mqtt.begin(BROKER_ADDR);
 }