Skip to content

Commit

Permalink
Release 1.3.0 (#36)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
dawidchyrzynski authored Apr 17, 2021
1 parent 15562fa commit a4e50b7
Show file tree
Hide file tree
Showing 40 changed files with 977 additions and 442 deletions.
20 changes: 17 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,35 @@
# Changelog

## 1.3.0

**New features:**
* Added `onMessage()` method to HAMqtt class
* Added support for HA Covers
* Added support for setting different prefix for non-discovery topics (see [Advanced MQTT example](examples/mqtt-advanced/mqtt-advanced.ino))
* Added `setName` method to HASensor
* Added `setName` method to HASwitch
* Added `onBeforeStateChanged` callback to HASwitch

**Updates:**
* Removed legacy properties from HAFan (Home Assistant 2021.4.4). Deprecated methods will be removed after a quarter (2021.7)
* Separated `uniqueID` field from `name` in all devices types

## 1.2.0

**Breaking changes:**
* Refactored HASensor implementation. Please take a look at updated example in `examples/sensor/sensor.ino`
* Refactored HASensor implementation. Please take a look at [updated example](examples/sensor/sensor.ino)

**New features:**
* Added support for HVAC
* Added support for excluding devices types from the compilation using defines (see `src/ArduinoHADefines.h`)
* Added support for excluding devices types from the compilation using defines (see [src/ArduinoHADefines.h](src/ArduinoHADefines.h))
* Added support for setting icon in HASwitch and HASensor
* Added support for setting retain flag in HASwitch
* Added support for text (const char*) payload in HASensor
* Added support for fans (HAFan)
* Added support for connecting to the MQTT broker using hostname
* Added `onConnected()` method in the HAMqtt
* Added `onConnectionFailed()` method in the HAMqtt
* Added support for MQTT LWT (see `examples/advanced-availability/advanced-availability.ino`)
* Added support for MQTT LWT (see [Advanced Availability example](examples/advanced-availability/advanced-availability.ino))

**Updates:**
* Optimized codebase and logic in all devices types
Expand Down
39 changes: 25 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,25 @@ but I successfully use it on ESP8266/ESP8255 boards in my projects.

* MQTT discovery (device is added to the Home Assistant panel automatically)
* MQTT Last Will and Testament
* Support for custom MQTT messages (publishing and subscribing)
* Auto reconnect with MQTT broker
* Reporting availability (online/offline states) of a device

## Supported HA types

* Binary sensors
* Covers
* Fans
* Device triggers
* Switches
* Sensors
* Tag scanner
* HVACs *(side note: HVACs requires more flash size than other HA types. It's not suitable for Arduino Nano/Uno)*

## Examples

* [Binary Sensor](examples/binary-sensor/binary-sensor.ino)
* [Cover](examples/cover/cover.ino)
* [Fan](examples/fan/fan.ino)
* [LED switch](examples/led-switch/led-switch.ino)
* [Multi-state button](examples/multi-state-button/multi-state-button.ino)
Expand All @@ -24,40 +38,37 @@ but I successfully use it on ESP8266/ESP8255 boards in my projects.
* [Availability feature](examples/availability)
* [Advanced availability (MQTT LWT)](examples/advanced-availability/advanced-availability.ino)
* [MQTT with credentials](examples/mqtt-with-credentials/mqtt-with-credentials.ino)
* [MQTT events](examples/mqtt-events/mqtt-events.ino)
* [MQTT advanced](examples/mqtt-advanced/mqtt-advanced.ino)

## Tested boards

* Arduino Uno
* Arduino Mega
* Controllino Maxi (standard/pure/automation/power)
* Controllino Mega (standard/pure)
* NodeMCU
* ESP-01
* Generic ESP8266/ESP8255
* Arduino Nano 33 IoT (SAMD)

## Tested Arduino Shields
## Tested devices

* Arduino Ethernet Shield (WizNet W5100)
* Controllino Maxi (standard/pure/automation/power)
* Controllino Mega (standard/pure)
* Sonoff Dual R2
* Sonoff Basic
* Sonoff Mini
* Tuya Wi-Fi switch module
* Tuya Wi-Fi curtain module

## Supported HA types
## Tested Arduino Shields

* Binary sensors
* Fans
* Device triggers
* Switches
* Sensors
* Tag scanner
* HVACs *(side note: HVACs requires more flash size than other HA types. It's not suitable for Arduino Nano/Uno)*
* Arduino Ethernet Shield (WizNet W5100)

## Roadmap

* FAQ + Home Assistant setup instructions
* Documentation of the library
* Unit tests
* Reduce flash memory usage
* Add support for HA covers
* Add support for HA lights

## Unsupported features
Expand Down
4 changes: 3 additions & 1 deletion examples/advanced-availability/advanced-availability.ino
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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
Expand Down
4 changes: 3 additions & 1 deletion examples/availability/availability.ino
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -36,6 +36,8 @@ void setup() {
device.setName("Arduino");
device.setSoftwareVersion("1.0.0");

sensor.setName("Door sensor"); // optional

mqtt.begin(BROKER_ADDR);
}

Expand Down
4 changes: 3 additions & 1 deletion examples/binary-sensor/binary-sensor.ino
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -28,6 +28,8 @@ void setup() {
device.setName("Arduino");
device.setSoftwareVersion("1.0.0");

sensor.setName("Door sensor"); // optional

mqtt.begin(BROKER_ADDR);
}

Expand Down
49 changes: 49 additions & 0 deletions examples/cover/cover.ino
Original file line number Diff line number Diff line change
@@ -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();
}
19 changes: 7 additions & 12 deletions examples/fan/fan.ino
Original file line number Diff line number Diff line change
Expand Up @@ -11,27 +11,22 @@ 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) {
Serial.print("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);

Expand All @@ -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);
Expand Down
10 changes: 9 additions & 1 deletion examples/led-switch/led-switch.ino
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand All @@ -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);
Expand Down
56 changes: 56 additions & 0 deletions examples/mqtt-advanced/mqtt-advanced.ino
Original file line number Diff line number Diff line change
@@ -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();
}
32 changes: 0 additions & 32 deletions examples/mqtt-events/mqtt-events.ino

This file was deleted.

3 changes: 2 additions & 1 deletion examples/mqtt-with-credentials/mqtt-with-credentials.ino
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand All @@ -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);
}
Expand Down
Loading

0 comments on commit a4e50b7

Please sign in to comment.