HassIO -> Hass.io

esphomeyaml/changelog/v1.7.0.rst

@@ -64,7 +64,7 @@ New Features
   triggered when an active WiFi and MQTT connection existed. Large parts of the WiFi and MQTT clients has now
   been rewritten to allow for automations to be executed asynchronously, while the device is still connecting to WiFi.
 
-- The HassIO add-on now has a new ``password`` option with which you can secure your installation. See
+- The Hass.io add-on now has a new ``password`` option with which you can secure your installation. See
   :doc:`/esphomeyaml/guides/getting_started_hassio`. 🔒
 
 - Binary Sensors now have filters too. They can now be used to debounce any binary sensor and do some more
@@ -81,7 +81,7 @@ New Features
   :ref:`esphomeyaml.on_shutdown <esphomeyaml-on_shutdown>` with which you can do some advanced cleanup/setup
   on boot and shutdown of the node.
 
-- All HassIO add-on builds have now been more or less completely automated using a private Gitlab server. You
+- All Hass.io add-on builds have now been more or less completely automated using a private Gitlab server. You
   can find all the new docker files `here <https://github.com/OttoWinter/esphomeyaml/tree/master/docker>`__.
 
 - Added a new ``build_path`` option in the ``esphomeyaml`` section with which you can customize where

esphomeyaml/changelog/v1.8.0.rst

@@ -110,7 +110,7 @@ Other notable changes
 - Fixed HTU21D readings only working in very verbose mode
 - Sometimes the ESP would create a WiFi hotspot even though it was not configured to do so. That should be fixed now.
 - You can now also have conditional actions. See :ref:`if_action`.
-- The esphomeyaml dashboard and HassIO add-on now can be configured with a password.
+- The esphomeyaml dashboard and Hass.io add-on now can be configured with a password.
 - Fixed YAML anchors not working (you can now prefix keys with ``.`` to make esphomeyaml ignore them)
 - Made Dallas and DHT temperature sensor a bit more reliable by making the code a bit more efficient and thus resolving some timing issues.
 - A ``heartbeat`` filter has been added to :ref:`binary sensors <binary_sensor-filters>`.

esphomeyaml/components/binary_sensor/custom.rst

@@ -9,6 +9,7 @@ very similar to sensors internally.
 
 .. code-block:: cpp
 
+    #include "esphomelib.h"
     using namespace esphomelib;
 
     class MyCustomBinarySensor : public PollingComponent, public binary_sensor::BinarySensor {
@@ -30,14 +31,17 @@ very similar to sensors internally.
       }
     };
 
-    void setup() {
-      // ...
+(Store this file in your configuration directory, for example ``my_binary_sensor.h``)
 
 And in YAML:
 
 .. code-block:: yaml
 
     # Example configuration entry
+    esphomeyaml:
+      includes:
+        - my_binary_sensor.h
+
     binary_sensor:
     - platform: custom
       lambda: |-

esphomeyaml/components/display/index.rst

@@ -165,7 +165,7 @@ Configuration variables:
 .. note::
 
     To use fonts you will need to have the python ``pillow`` package installed, as esphomeyaml uses that package
-    to translate the truetype files into an internal format. If you're running this as a HassIO add-on or with
+    to translate the truetype files into an internal format. If you're running this as a Hass.io add-on or with
     the official esphomeyaml docker image, it should already be installed. Otherwise you need to install it using
     ``pip2 install pillow``.
 
@@ -334,7 +334,7 @@ Configuration variables:
 .. note::
 
     To use images you will need to have the python ``pillow`` package installed.
-    If you're running this as a HassIO add-on or with the official esphomeyaml docker image, it should already be
+    If you're running this as a Hass.io add-on or with the official esphomeyaml docker image, it should already be
     installed. Otherwise you need to install it using ``pip2 install pillow``.
 
 And then later in code:

esphomeyaml/components/esphomeyaml.rst

@@ -44,6 +44,11 @@ Advanced options:
   but you can customize this behavior using this option.
 - **use_custom_code** (*Optional*, boolean): Whether to configure the project for writing custom components.
   This sets up some flags so that custom code should compile correctly
+- **includes** (*Optional*, list of files): A list of files to include in the main (auto-generated) sketch file
+  for custom components. The paths in this list are relative to the directory where the YAML configuration file
+  is in.
+- **libraries** (*Optional*, list of libraries): A list of `platformio libraries <https://platformio.org/lib>`__
+  to include in the project. See `platformio lib install <https://docs.platformio.org/en/latest/userguide/lib/cmd_install.html>`__.
 
 Automations:
 

esphomeyaml/components/sensor/custom.rst

@@ -34,31 +34,30 @@ If you have any problems, I'm here to help: https://discord.gg/KhAMKrd
 Step 1: Custom Sensor Definition
 --------------------------------
 
-At this point, you might have a main source file like this:
+To create your own custom sensor, you just have to create your own C++ class. If you've never heard of that
+before, don't worry, at the end of this guide you can just copy the example source code and modify it to your needs
+- learning the intricacies of C++ classes won't be required.
+
+Before you can create your own custom sensors, let's first take a look at the basics: How sensors (and components)
+are structured in the esphomelib ecosystem.
+
+In esphomelib, a **sensor** is some hardware device (like a BMP180) that periodically
+sends out numbers, for example a temperature sensor that periodically publishes its temperature **state**.
+
+Another important abstraction in esphomelib is the concept of a **component**. In esphomelib,
+a **component** is an object with a *lifecycle* managed by the :cpp:class:`Application` class.
+What does this mean? Well if you've coded in Arduino before you might know the two special methods
+``setup()`` and ``loop()``. ``setup()`` is called one time when the node boots up and ``loop()`` is called
+very often and this is where you can do things like read out sensors etc.
+
+Components have something similar to that: They also have ``setup()`` and ``loop()`` methods which will be
+called by the application kind of like the arduino functions.
+
+So, let's now take a look at some code: This is an example of a custom component class (called ``MyCustomSensor`` here):
 
 .. code-block:: cpp
 
-    // ...
-    using namespace esphomelib;
-
-    void setup() {
-      // ===== DO NOT EDIT ANYTHING BELOW THIS LINE =====
-      // ========== AUTO GENERATED CODE BEGIN ===========
-      App.set_name("livingroom");
-      App.init_log();
-      // ...
-      // =========== AUTO GENERATED CODE END ============
-      // ========= YOU CAN EDIT AFTER THIS LINE =========
-      App.setup();
-    }
-
-    void loop() {
-      App.loop();
-    }
-
-To create your own custom sensor, you just have define a C++ class that extends ``Component`` and ``Sensor`` like this:
-
-.. code-block:: cpp
+    #include "esphomelib.h"
 
     using namespace esphomelib;
 
@@ -72,23 +71,9 @@ To create your own custom sensor, you just have define a C++ class that extends
       }
     };
 
-    void setup() {
-      // ...
-
-You've just created your first esphomelib sensor class 🎉. It doesn't do very much right now and is never instantiated,
-but it's a first step.
-
-Let's now take a look at how a sensor works in esphomelib: A sensor is some hardware device (like a BMP180)
-that sends out new values like temperatures.
-
-Like any "Component" in esphomelib, if it's registered in the Application, the ``setup()`` method
-in your custom component will be called when the ESP boots up (similar to how the ``setup()`` method in
-Arduino is called).. ``setup()`` is also the place where you should do hardware initialization like setting
-``pinMode()`` etc.
-
-Next, every time ``App.loop()`` is called, your component will also receive a ``loop()`` method call.
-This is the place where you should do stuff like querying a sensor for a new value like you might be used
-to do in an Arduino sketch.
+In the first two lines, we're importing esphomelib so you can use the APIs and telling the compiler that
+we want to use the esphomelib "namespace" (you don't need to know what this is now, it's basically just
+there to have a clean, well-structured codebase).
 
 Let's now also take a closer look at this line, which you might not be too used to when writing Arduino code:
 
@@ -96,18 +81,22 @@ Let's now also take a closer look at this line, which you might not be too used
 
     class MyCustomSensor : public Component, public sensor::Sensor {
 
-What this line is essentially saying is that we're defining our own class that's called ``CustomSensor``
+What this line is essentially saying is that we're defining our own class that's called ``MyCustomSensor``
 which is also a subclass of ``Component`` and ``Sensor`` (in the namespace ``sensor::``).
-``Component`` is there so that we can register it in our application and so that we will receive ``setup()``
-and ``loop()`` calls. And we're also inheriting from ``Sensor`` because, well, we're creating a sensor that will
-publish values to the frontend.
+As described before, these two "parent" classes have special semantics that we will make use of.
 
-The thing is, ``loop()`` gets called *very often*, like 60 times per second. Most sensors do not support
-reading out values at this speed! That's why there's ``PollingComponent``. If you replace the ``Component`` above
-with ``PollingComponent``, you can replace the ``loop()`` method with a method called ``update()``.
+We *could* go implement our own sensor code now by replacing the contents of ``setup()`` and ``loop()``.
+In ``setup()`` we would initialize the sensor and in ``loop()`` we would read out the sensor and publish
+the latest values.
 
-Contrary to ``loop()``, for ``update()`` you can tell esphomelib with what **interval** the method should be called.
-Let's look at some more code:
+However, there's a small problem with that approach: ``loop()`` gets called very often (about 60 times per second).
+If we would publish a new state each time that method is called we would quickly make the node unresponsive
+since the MQTT protocol wasn't really designed for 60 messages per second.
+
+So this fix this, we will use an alternative class to ``Component``: ``PollingComponent``. This class
+is for situations where you have something that should get called repeatedly with some **update interval**.
+In the code above, we can simply replace ``Component`` by ``PollingComponent`` and ``loop()`` by a special
+method ``update()`` which will be called with an interval we can specify.
 
 .. code-block:: cpp
 
@@ -126,9 +115,11 @@ Let's look at some more code:
 
 
 Our code has slightly changed, as explained above we're now inheriting from ``PollingComponent`` instead of
-just ``Component``. Additionally, we now have a new line: the constructor. In this constructor we're telling
-the compiler that we want ``PollingComponent`` to be instantiated with an *update interval* of 15s, or
-15000 milliseconds (esphomelib uses milliseconds internally).
+just ``Component``. Additionally, we now have a new line: the constructor. You also don't really need to
+know much about constructors here, so to simplify let's just say this is where we "initialize" the custom sensor.
+
+In this constructor we're telling the compiler that we want ``PollingComponent`` to be instantiated with an
+*update interval* of 15s, or 15000 milliseconds (esphomelib uses milliseconds internally).
 
 Let's also now make our sensor actually publish values in the ``update()`` method:
 
@@ -149,8 +140,20 @@ Step 2: Registering the custom sensor
 -------------------------------------
 
 Now we have our Custom Sensor set up, but unfortunately it doesn't do much right now.
-Actually ... it does nothing because it's never instantiated. In your YAML configuration, create
-a new sensor platform entry like this:
+Actually ... it does nothing because it's never included nor instantiated.
+First, create a new file called ``my_custom_sensor.h`` in your configuration directory and copy the source code
+from above into that file.
+
+Then in the YAML config, *include* that file in the top-level ``esphomeyaml`` section like this:
+
+.. code-block:: yaml
+
+    esphomeyaml:
+      # ... [Other options]
+      includes:
+        - my_custom_sensor.h
+
+Next, create a new ``custom`` sensor platform entry like this:
 
 .. code-block:: yaml
 
@@ -183,7 +186,7 @@ Now all that's left to do is upload the code and let it run :)
 If you have Home Assistant MQTT discovery setup, it will even automatically show up in the frontend 🎉
 
 .. figure:: images/custom-ui.png
-:align: center
+    :align: center
     :width: 60%
 
 Step 3: BMP180 support
@@ -198,28 +201,29 @@ use the `Adafruit BMP085 Library <https://platformio.org/lib/show/525/Adafruit%2
 library to implement support for the BMP085 sensor. But you can find other libraries too on the
 `platformio library index <https://platformio.org/lib>`__
 
-First we'll need to add the library to our project dependencies. To do so, put the following in
-the ``common`` section of your ``<NODE_NAME>/platformio.ini`` file:
+First we'll need to add the library to our project dependencies. To do so, put ``Adafruit BMP085 Library``
+in your global ``libraries``:
 
-.. code-block:: ini
+.. code-block:: yaml
 
-    [common]
-    lib_deps = Adafruit BMP085 Library
-    build_flags =
-    upload_flags =
+    esphomeyaml:
+      includes:
+        - my_custom_sensor.h
+      libraries:
+        - "Adafruit BMP085 Library"
 
-Next, include the library at the top of you main sketch file (``<NODE_NAME>/src/main.cpp``):
+Next, include the library at the top of your custom sensor file you created previously:
 
 .. code-block:: cpp
 
-    #include "esphomelib/application.h"
-    #include <Adafruit_BMP085.h>
+    #include "esphomelib.h"
+    #include "Adafruit_BMP085.h"
 
     using namespace esphomelib;
 
     // ...
 
-Then update our sensor for BMP180 support:
+Then update the sensor for BMP180 support:
 
 .. code-block:: cpp
 

esphomeyaml/components/sensor/misc/custom-empty.h

@@ -0,0 +1,15 @@
+#include "esphomelib.h"
+
+using namespace esphomelib;
+
+class MyCustomSensor : public PollingComponent, public sensor::Sensor {
+ public:
+  MyCustomSensor() : PollingComponent(15000) {}
+
+  void setup() override {
+    // This will be called by App.setup()
+  }
+  void update() override {
+    publish_state(42.0);
+  }
+};

esphomeyaml/components/time.rst

@@ -40,7 +40,7 @@ Configuration variables:
 .. note::
 
     To use the automatic timezone detection you will need to have the python ``tzlocal`` package installed.
-    If you're running this as a HassIO add-on or with the official esphomeyaml docker image, it should already
+    If you're running this as a Hass.io add-on or with the official esphomeyaml docker image, it should already
     be installed. Otherwise you need to install it using ``pip2 install tzlocal``.
 
 Use In Lambdas

esphomeyaml/devices/sonoff_4ch.rst

@@ -47,7 +47,7 @@ For this guide you will need:
 - An USB to UART Bridge for flashing the device. These can be bought on Amazon for less than 5 dollars.
   Note that the bridge *must* be 3.3V compatible. Otherwise you will destroy your Sonoff.
 - Jumper wires to connect the UART bridge to the header pins.
-- Computer running esphomeyaml or HassIO add-on.
+- Computer running esphomeyaml or Hass.io add-on.
 - Screwdriver to open up the Sonoff 4CH.
 
 Have everything? Great! Then you can start.

esphomeyaml/devices/sonoff_s20.rst

@@ -46,7 +46,7 @@ For this guide you will need:
 -  Sonoff S20 😉
 -  An USB to UART Bridge for flashing the device. These can be bought on Amazon for less than 5 dollars.
    Note that the bridge *must* be 3.3V compatible. Otherwise you will destroy your S20.
--  Computer running esphomeyaml HassIO add-on.
+-  Computer running esphomeyaml Hass.io add-on.
 -  Screwdriver to open up the S20.
 -  Soldering iron and a few header pins to connect the UART interface.
 

esphomeyaml/guides/faq.rst

@@ -52,7 +52,7 @@ the ESP. This can sometimes fail (driver missing, inside docker container, ...).
 Starting with esphomelib 1.9.0, the esphomelib suite provides
 `esphomeflasher <https://github.com/OttoWinter/esphomeflasher>`__, a tool to flash ESPs over USB.
 
-First, you need to get the firmware file to flash. For HassIO add-on based installs you can
+First, you need to get the firmware file to flash. For Hass.io add-on based installs you can
 use the ``COMPILE`` button and then press ``Download Binary``. For command line based installs you
 can access the file under ``<CONFIG_DIR>/<NODE_NAME>/.pioenvs/<NODE_NAME>/firmware.bin``.
 
@@ -141,7 +141,7 @@ It's simple. Run:
     # From docker:
     docker pull ottowinter/esphomeyaml:latest
 
-And in HassIO, there's a simple UPDATE button when there's an update available as with all add-ons
+And in Hass.io, there's a simple UPDATE button when there's an update available as with all add-ons
 
 .. _faq-beta:
 
@@ -162,7 +162,7 @@ by installing the esphomeyaml beta:
     # In each command:
     docker run [...] -it ottowinter/esphomeyaml:rc livingroom.yaml run
 
-And for HassIO, you will see a "esphomeyaml Beta" Add-On for the beta channel.
+And for Hass.io, you will see a "esphomeyaml Beta" Add-On for the beta channel.
 
 The beta docs can be viewed at `https://beta.esphomelib.com <https://beta.esphomelib.com>`__
 
@@ -176,7 +176,7 @@ Installing the latest bleeding edge version of esphomelib is also quite easy. It
 if there was a bug somewhere and I didn't feel like building & pushing a whole new release out (this often
 takes up to 2 hours!). To install the dev version of esphomeyaml:
 
-- In HassIO: In the esphomeyaml add-on repository there's also a second add-on called ``esphomeyaml-edge``.
+- In Hass.io: In the esphomeyaml add-on repository there's also a second add-on called ``esphomeyaml-edge``.
   Install that and stop the stable version (both can't run at the same time without port collisions).
 - From ``pip``: Run ``pip install git+git://github.com/OttoWinter/esphomeyaml.git``
 - From docker: Run ``docker pull ottowinter/esphomeyaml:dev`` and use ``ottowinter/esphomeyaml:dev`` in all

esphomeyaml/guides/getting_started_command_line.rst

@@ -23,7 +23,7 @@ Installing esphomeyaml is very easy. All you need to do is have `Python
 
 Alternatively, there’s also a docker image available for easy
 installation (the docker hub image is only available for amd64 right now; if you have
-an RPi, please install esphomelib through ``pip`` or use :doc:`the HassIO add-on <getting_started_hassio>`:
+an RPi, please install esphomelib through ``pip`` or use :doc:`the Hass.io add-on <getting_started_hassio>`:
 
 .. code:: bash
 
@@ -172,7 +172,7 @@ Bonus: esphomeyaml dashboard
 
 Starting with version 1.6.0, esphomeyaml features a dashboard that you can use to
 easily manage your nodes from a nice web interface. It was primarily designed for
-:doc:`the HassIO add-on <getting_started_hassio>`, but also works with a simple command.
+:doc:`the Hass.io add-on <getting_started_hassio>`, but also works with a simple command.
 
 To start the esphomeyaml dashboard, simply start esphomeyaml with the following command
 (with ``config/`` pointing to a directory where you want to store your configurations)

esphomeyaml/guides/getting_started_hassio.rst

@@ -1,13 +1,13 @@
-Getting Started with esphomeyaml through HassIO
-===============================================
+Getting Started with esphomeyaml through Hass.io
+================================================
 
 .. seo::
-    :description: Getting Started guide for installing esphomeyaml as a HassIO Add-on and creating a basic configuration.
+    :description: Getting Started guide for installing esphomeyaml as a Hass.io Add-on and creating a basic configuration.
     :image: home-assistant.svg
 
 esphomeyaml is the perfect solution for creating custom firmwares for
 your ESP8266/ESP32 boards. In this guide we’ll go through how to setup a
-basic "node" by use of the HassIO add-on.
+basic "node" by use of the Hass.io add-on.
 
 But first, here's a very quick introduction of how esphomeyaml works:
 esphomeyaml is a *tool* which reads in YAML configuration files (just like Home Assistant)
@@ -19,7 +19,7 @@ Assistant's UI.
 Installation
 ------------
 
-Installing the esphomeyaml HassIO add-on is easy. Just navigate to the HassIO
+Installing the esphomeyaml Hass.io add-on is easy. Just navigate to the Hass.io
 panel in your Home Assistant frontend and add the esphomeyaml add-on repository:
 https://github.com/OttoWinter/esphomeyaml
 
@@ -57,7 +57,7 @@ there are three basic actions you can perform:
 
   .. warning::
 
-      The HassIO Add-On is currently not capable of discovering new USB ports after the add-on
+      The Hass.io Add-On is currently not capable of discovering new USB ports after the add-on
       has started due to some docker restrictions. Please go to the add-on details page
       and restart the add-on if a new USB device is not automatically found.
 
@@ -84,11 +84,11 @@ Now go ahead and use one of the :ref:`devices guides <devices>` to extend your c
 intend to flash an esphomeyaml firmware onto. Then proceed with uploading the first firmware using the
 upload button.
 
-HassIO add-on options
-*********************
+Hass.io add-on options
+**********************
 
 Since version 1.8.0, you can optionally specify a password to use for all traffic to esphomeyaml
-using the ``password`` option in the HassIO add-on page. By default, this is an empty string
+using the ``password`` option in the Hass.io add-on page. By default, this is an empty string
 (which means no password), but you can enter any string in there to set your password.
 
 

esphomeyaml/guides/migrate_espeasy.rst

@@ -14,7 +14,7 @@ Getting Binary
 First follow the guides for the :ref:`different supported devices <devices>` and create a configuration
 file. Then, generate and download the binary:
 
-- **Using the HassIO add-on/dashboard**: Just click the ``COMPILE`` button, wait for
+- **Using the Hass.io add-on/dashboard**: Just click the ``COMPILE`` button, wait for
   the compilation to end and press the ``DOWNLOAD BINARY`` button.
 
   .. figure:: images/download_binary.png

esphomeyaml/guides/migrate_espurna.rst

@@ -14,7 +14,7 @@ Getting Binary
 First follow the guides for the :ref:`different supported devices <devices>` and create a configuration
 file. Then, generate and download the binary:
 
-- **Using the HassIO add-on/dashboard**: Just click the ``COMPILE`` button, wait for
+- **Using the Hass.io add-on/dashboard**: Just click the ``COMPILE`` button, wait for
   the compilation to end and press the ``DOWNLOAD BINARY`` button.
 
   .. figure:: images/download_binary.png

esphomeyaml/guides/migrate_sonoff_tasmota.rst

@@ -14,7 +14,7 @@ Getting Binary
 First follow the guides for the :ref:`different supported devices <devices>` and create a configuration
 file. Then, generate and download the binary:
 
-- **Using the HassIO add-on/dashboard**: Just click the ``COMPILE`` button, wait for
+- **Using the Hass.io add-on/dashboard**: Just click the ``COMPILE`` button, wait for
   the compilation to end and press the ``DOWNLOAD BINARY`` button.
 
   .. figure:: images/download_binary.png

esphomeyaml/index.rst

@@ -21,7 +21,7 @@ Guides
 .. imgtable::
 
     Getting Started through Command Line, guides/getting_started_command_line, console.svg
-    Getting Started through HassIO Add-On, guides/getting_started_hassio, home-assistant.svg
+    Getting Started through Hass.io Add-On, guides/getting_started_hassio, home-assistant.svg
     Configuration Types, guides/configuration-types, settings.svg
     Migrating from Sonoff-Tasmota, guides/migrate_sonoff_tasmota, tasmota.svg
     Migrating from ESPurna, guides/migrate_espurna, espurna.svg