release

2023-03-22 12:15:18 +01:00
parent 3e12414a87
commit adb5102869
203 changed files with 35010 additions and 0 deletions
--- a/lib/home-assistant-integration/docsrc/source/documents/getting-started/compatible-hardware.rst
+++ b/lib/home-assistant-integration/docsrc/source/documents/getting-started/compatible-hardware.rst
@@ -0,0 +1,27 @@
+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.
--- a/lib/home-assistant-integration/docsrc/source/documents/getting-started/examples.rst
+++ b/lib/home-assistant-integration/docsrc/source/documents/getting-started/examples.rst
@@ -0,0 +1,60 @@
+Examples
+========
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+   :class: examples-table
+
+   * - Example
+     - Description
+   * - :example:`Binary sensor <binary-sensor/binary-sensor.ino>`
+     - Using the binary sensor as a door contact sensor.
+   * - :example:`Button <button/button.ino>`
+     - Adding simple buttons to the Home Assistant panel.
+   * - :example:`Camera <esp32-cam/esp32-cam.ino>`
+     - Publishing the preview from the ESP32-CAM module.
+   * - :example:`Cover <cover/cover.ino>`
+     - Controlling a window cover (open / close / stop).
+   * - :example:`Device trigger <multi-state-button/multi-state-button.ino>`
+     - Implementation of a simple wall switch that reports press and hold states.
+   * - :example:`Fan <fan/fan.ino>`
+     - Controlling a simple fan (state + speed).
+   * - :example:`HVAC <hvac/hvac.ino>`
+     - HVAC controller with multiple modes, power control and target temperature.
+   * - :example:`Lock <lock/lock.ino>`
+     - A simple door lock that's controlled by the Home Assistant.
+   * - :example:`Light <light/light.ino>`
+     - A simple light that allows changing brightness, color temperature and RGB color.
+   * - :example:`Number <number/number.ino>`
+     - Adding an interactive numeric slider in the Home Assistant panel.
+   * - :example:`Scene <scene/scene.ino>`
+     - Adding a custom scene in the Home Assistant panel. 
+   * - :example:`Select <select/select.ino>`
+     - A dropdown selector that's displayed in the Home Assistant panel.
+   * - :example:`Sensor <sensor/sensor.ino>`
+     - A simple sensor that reports a state in a string representation (open / opening / close).
+   * - :example:`Analog sensor <sensor-analog/sensor-analog.ino>`
+     - Reporting the analog pin's voltage to the Home Assistant.
+   * - :example:`Integer sensor <sensor-integer/sensor-integer.ino>`
+     - Reporting the device's uptime to the Home Assistant.
+   * - :example:`Switch <led-switch/led-switch.ino>`
+     - The LED that's controlled by the Home Assistant.
+   * - :example:`Multi-switch <multi-switch/multi-switch.ino>`
+     - Multiple switches controlled by the Home Assistant.
+   * - :example:`Tag scanner <tag-scanner/tag-scanner.ino>`
+     - Scanning RFID tags using the MFRC522 module.
+   * - :example:`Availability <availability/availability.ino>`
+     - Reporting entities' availability (online / offline) to the Home Assistant.
+   * - :example:`Advanced availability <advanced-availability/advanced-availability.ino>`
+     - Advanced availability reporting with MQTT LWT (Last Will and Testament).
+   * - :example:`MQTT advanced <mqtt-advanced/mqtt-advanced.ino>`
+     - Subscribing to custom topics and publishing custom messages.
+   * - :example:`MQTT with credentials <mqtt-with-credentials/mqtt-with-credentials.ino>`
+     - Establishing connection with a MQTT broker using the credentials. 
+   * - :example:`NodeMCU (ESP8266) <nodemcu/nodemcu.ino>`
+     - Basic example for ESP8266 devices.
+   * - :example:`Arduino Nano 33 IoT <nano33iot/nano33iot.ino>`
+     - Basic example for Arduino Nano 33 IoT (SAMD family).
+   * - :example:`mDNS discovery <mdns/mdns.ino>`
+     - Make your ESP8266 discoverable via the mDNS.
--- a/lib/home-assistant-integration/docsrc/source/documents/getting-started/index.rst
+++ b/lib/home-assistant-integration/docsrc/source/documents/getting-started/index.rst
@@ -0,0 +1,17 @@
+
+Getting started
+===============
+
+Welcome to the ArduinoHA library!
+This documentation is a step-by-step guide that presents all features of the library.
+If you feel that there is anything unclear don't hesitate to open a new GitHub discussion.
+
+Have fun!
+
+.. toctree::
+    :maxdepth: 2
+
+    prerequisites
+    installation
+    compatible-hardware
+    examples
--- a/lib/home-assistant-integration/docsrc/source/documents/getting-started/installation.rst
+++ b/lib/home-assistant-integration/docsrc/source/documents/getting-started/installation.rst
@@ -0,0 +1,44 @@
+Installation
+============
+
+There are two ways to install the library depending on your project.
+If you're using Arduino IDE to compile your project you only need to install the library into the IDE.
+
+The second method is meant for more advanced users that use *makeEspArduino* for building the project for ESP32/ESP8266 devices.
+
+Arduino IDE
+-----------
+
+To install the library into your Arduino IDE you can use Library Manager (available from IDE version 1.6.2).
+Open the IDE and click to the "Sketch" menu and then *Include Library > Manage Libraries*.
+
+.. image:: images/manage-libraries.png
+  :width: 500
+  :align: center
+
+Type "home-assistant-integration" in the search field, select the latest version of the library from the dropdown and then click *Install*.
+  
+.. image:: images/library-search.png
+  :width: 500
+  :align: center
+
+For other installation methods please refer to `Arduino documentation <https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries>`_.
+
+makeEspArduino
+--------------
+
+The library can be installed in an environment managed by `makeEspArduino <https://github.com/plerup/makeEspArduino>`_.
+The best approach is to add the library and its dependency as submodules in the project as follows:
+
+::
+
+    git submodule add https://github.com/dawidchyrzynski/arduino-home-assistant.git arduino-home-assistant
+    cd arduino-home-assistant && git checkout tags/2.0.0 && cd ..
+    git submodule add https://github.com/knolleary/pubsubclient.git pubsubclient
+    cd pubsubclient && git checkout tags/v2.8
+
+Then you just need to add one extra line in your `Makefile`:
+
+::
+
+    LIBS := $(ROOT)/arduino-home-assistant $(ROOT)/pubsubclient
--- a/lib/home-assistant-integration/docsrc/source/documents/getting-started/prerequisites.rst
+++ b/lib/home-assistant-integration/docsrc/source/documents/getting-started/prerequisites.rst
@@ -0,0 +1,8 @@
+Prerequisites
+=============
+
+ArduinoHA uses MQTT protocol over TCP to communicate with your Home Assistant instance.
+The MQTT broker is not installed by default so you will need to install an extra HA addon in order to get the integration working.
+
+The recommended setup method is to use the `Mosquitto Brokker addon <https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md>`_.
+After installing the addon your HA instance acts as a broker for all devices you're going to integrate with it.