Skip to content
This repository has been archived by the owner on Mar 1, 2024. It is now read-only.

Latest commit

 

History

History
99 lines (86 loc) · 5.02 KB

README.md

File metadata and controls

99 lines (86 loc) · 5.02 KB
Raw

Arduino Home Assistant integration 🏠

ArduinoHA allows to integrate an Arduino/ESP based device with Home Assistant using MQTT. The library is designed to use as low resources (RAM/flash) as possible. Initially, it was optimized to work on Arduino Uno with Ethernet Shield, but I successfully use it on ESP8266/ESP8255 boards in my projects.

📘 Documentation

Features

  • Two-way communication (state reporting and command execution)
  • 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
  • Doxygen documentation for all classes
  • Covered by unit tests (AUnit + EpoxyDuino + AUniter)

Supported HA types

Home Assistant type Supported
Binary sensor ✅
Button ✅
Camera ✅
Cover ✅
Device tracker ✅
Device trigger ✅
Fan ✅
Humidifier ❌
HVAC ✅
Light ✅
Lock ✅
Number ✅
Scene ✅
Select ✅
Sensor ✅
Switch ✅
Tag scanner ✅
Vacuum ❌

Examples

Example Description
Binary sensor Using the binary sensor as a door contact sensor.
Button Adding simple buttons to the Home Assistant panel.
Camera Publishing the preview from the ESP32-CAM module.
Cover Controlling a window cover (open / close / stop).
Device trigger Implementation of a simple wall switch that reports press and hold states.
Fan Controlling a simple fan (state + speed).
HVAC HVAC controller with multiple modes, power control and target temperature.
Lock A simple door lock that's controlled by the Home Assistant.
Light A simple light that allows changing brightness, color temperature and RGB color.
Number Adding an interactive numeric slider in the Home Assistant panel.
Scene Adding a custom scene in the Home Assistant panel.
Select A dropdown selector that's displayed in the Home Assistant panel.
Sensor A simple sensor that reports a state in a string representation (open / opening / close).
Analog sensor Reporting the analog pin's voltage to the Home Assistant.
Integer sensor Reporting the device's uptime to the Home Assistant.
Switch The LED that's controlled by the Home Assistant.
Multi-switch Multiple switches controlled by the Home Assistant.
Tag scanner Scanning RFID tags using the MFRC522 module.
Availability Reporting entities' availability (online / offline) to the Home Assistant.
Advanced availability Advanced availability reporting with MQTT LWT (Last Will and Testament).
MQTT advanced Subscribing to custom topics and publishing custom messages.
MQTT with credentials Establishing connection with a MQTT broker using the credentials.
NodeMCU (ESP8266) Basic example for ESP8266 devices.
Arduino Nano 33 IoT Basic example for Arduino Nano 33 IoT (SAMD family).
mDNS discovery Make your ESP8266 discoverable via the mDNS.

Compatible hardware

The library uses the Arduino Ethernet Client API for interacting with the network hardware. It should work fine as long as the Client class is available.

Here is the list of devices on which the library was tested:

  • Arduino Uno
  • Arduino Mega
  • Arduino Nano
  • Arduino Pro Mini
  • Arduino Nano 33 IoT
  • NodeMCU
  • Controllino Mega (Pure)
  • Controllino Maxi (Pure)
  • ESP-01
  • ESP32-CAM
  • Sonoff Dual R2
  • Sonoff Dual R3
  • Sonoff Basic
  • Sonoff Mini
  • Tuya Wi-Fi switch module
  • Tuya Wi-Fi curtain module

Please note that it's not the complete list of supported devices. You may try to use the library on any device that uses Arduino core.