Getting started guide updates

guides/getting_started_command_line.rst

@@ -211,15 +211,16 @@ want new features, please either create a new issue on the `GitHub issue
 tracker <https://github.com/esphome/issues/issues>`__ or find us on the
 `Discord chat <https://discord.gg/KhAMKrd>`__ (also make sure to read the :doc:`FAQ <faq>`).
 
-Bonus: ESPHome dashboard
-------------------------
+.. _esphome-device-builder-docker:
 
-ESPHome features a dashboard that you can use to easily manage your nodes
-from a nice web interface. It was primarily designed for
-:doc:`the Home Assistant add-on <getting_started_hassio>`, but also works with a simple command.
+Bonus: ESPHome Device Builder
+-----------------------------
 
-To start the ESPHome dashboard, simply start ESPHome with the following command
-(with ``config/`` pointing to a directory where you want to store your configurations)
+The ESPHome Device Builder allows you to easily manage your nodes from a nice web interface. It was primarily designed
+as a :doc:`Home Assistant add-on <getting_started_hassio>`, but can run in docker independently from Home Assistant.
+
+To start the ESPHome Device Builder, simply start ESPHome with the following command (with ``config/`` pointing to a
+directory where you want to store your configurations):
 
 .. code-block:: bash
 
@@ -237,7 +238,7 @@ To start the ESPHome dashboard, simply start ESPHome with the following command
     docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it ghcr.io/esphome/esphome
 
 
-After that, you will be able to access the dashboard through ``localhost:6052``.
+After that, you will be able to access the ESPHome Device Builder at ``localhost:6052``.
 
 .. figure:: images/dashboard_states.png
 

guides/getting_started_hassio.rst

@@ -2,100 +2,126 @@ Getting Started with ESPHome and Home Assistant
 ===============================================
 
 .. seo::
-    :description: Getting Started guide for installing ESPHome Device Compiler as a Home Assistant add-on and creating a basic configuration.
+    :description: Getting Started guide for installing ESPHome Device Builder as a Home Assistant add-on and creating a basic configuration.
     :image: home-assistant.svg
 
-In this guide we’ll go through how to install ESPHome on a device using the ESPHome Device Compiler, installed as a Home Assistant add-on.
+In this guide, we'll walk you through how to install ESPHome onto a device/microcontroller using the ESPHome Device
+Builder, installed as a Home Assistant add-on.
 
-First, here's a very quick introduction to how ESPHome works. ESPHome allows you to write configurations and turn your microcontrollers
-into smart home devices. It reads a YAML configuration file, creates custom firmware, and can install it directly on your device. Any devices
-or sensors defined in the ESPHome configuration will automatically appear in Home Assistant's user interface.
+This is generally the easiest way to get started with ESPHome.
 
-Installing ESPHome Device Compiler
-----------------------------------
+Introduction to ESPHome
+-----------------------
 
-To install the ESPHome Device Compiler in Home Assistant, click the following button to open the ESPHome add-on page and hit the INSTALL button:
+ESPHome allows you to create "configurations" which allow you to turn common microcontrollers into smart home devices.
+
+A device "configuration" consists of one or more `YAML files <https://en.wikipedia.org/wiki/YAML>`__  and, based on the
+content of the file(s), ESPHome creates custom firmware which you can then install directly onto your device. Hardware
+defined in the configuration--such as sensors, switches, lights, and so on--will automatically appear in Home
+Assistant's user interface.
+
+Note that there are two "parts" to ESPHome:
+
+- The part which runs on the device/microcontroller, and...
+- The part which runs on your computer system, whether that's a single-board computer (SBC) such as a Raspberry Pi or
+  a laptop/desktop-class system.
+
+The ESPHome Device Builder provides a simple web user interface (UI) which allows you to create, edit and install your
+device configurations onto your devices.
+
+Installing ESPHome Device Builder
+---------------------------------
+
+To install the ESPHome Device Builder in Home Assistant, click the following button:
 
 .. raw:: html
 
     <a href="https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon" target="_blank">
         <img src="https://my.home-assistant.io/badges/supervisor_addon.svg" alt="Open your Home Assistant instance and show the user interface of the ESPHome add-on." />
     </a>
 
-If you run a Home Assistant installation that does not have access to add-ons, take a look at the other installation methods here.
+This should open the ESPHome add-on page; once you're there, just click the INSTALL button:
 
-It can take a bit until the add-on is installed. Once done, click "Start" and then click "Open Web UI".
-
-.. figure:: images/hassio_addon.png
+.. figure:: images/addon.png
     :align: center
     :width: 75.0%
 
-You should now be greeted by a nice introduction wizard which will step you through
-creating your first configuration.
+Installation of the add-on may take a moment or two. Once done, click "Start" and then click "Open Web UI".
+
+.. note::
+
+    If you're running Home Assistant in a way that does not provide access to add-ons, you may
+    :ref:`run the ESPHome Device Builder independently in Docker<esphome-device-builder-docker>`.
+
+The web UI will present a wizard which will walk you through creating your first configuration:
 
 .. figure:: images/dashboard_empty.png
     :align: center
     :width: 95.0%
 
-The wizard will guide you through creating your first configuration and, depending on your browser, install it on your ESP device. You will need to name your configuration and enter your wireless network settings so that the ESP device can come online and can communicate with Home Assistant.
+After creating your first configuration, you'll need to install it on your device.
 
 .. note::
 
-    The most difficult part of setting up a new ESPHome device is the initial installation. Installation requires that your ESP device is connected with a cable to a computer. Later updates can be installed wirelessly.
+    The initial installation of ESPHome onto a new device is often the most difficult and/or intimidating part -- at
+    least until you've done it a few times.
 
-    For guidance on making this first connection, see :doc:`physical_device_connection`
+    If you haven't done this before, please see :doc:`physical_device_connection`.
 
+If you didn't do so when prompted upon creating your first device, you'll need to enter your Wi-Fi network credentials
+immediately following installation so that your device can connect to your Wi-Fi network and subsequently communicate
+with Home Assistant.
 
-ESPHome Interface
--------------------
+.. _esphome-interface:
 
-Assuming you created your first configuration file with the wizard, let's take a quick
-tour of the ESPHome Device Compiler interface.
+Device Builder Interface
+------------------------
+
+Let's take a quick tour of the ESPHome Device Builder interface.
 
 .. figure:: images/dashboard_states.png
     :align: center
     :width: 95.0%
 
-On the front page you will see all configurations for nodes you created. For each file,
-there are a few basic actions you can perform:
-
-- **UPDATE**: This button will show up if the device has not been installed with the same ESPHome version currently running.
+The main page displays a list of all configuration files for nodes you've created. For each file, there are a few
+actions you can perform:
 
+- **UPDATE**: This button appears when the device is running an ESPHome version which is older than that available in
+  the ESPHome Device Builder add-on.
 - **EDIT**: This will open the configuration editor.
-
-- **LOGS**: With this command you can view all the logs the node is outputting. If a USB device is
-  connected, you can choose to use the serial connection. Otherwise it will use the built-in OTA logs.
-
-- **Overflow menu**: This is a dropdown menu which allows you to perform more actions.
+- **LOGS**: This allows you to view logs emitted by the device. If a device is connected via USB, you can choose to use
+  the USB/serial connection; otherwise, it will attempt to connect to the device and (once connected) display the logs
+  via the Wi-Fi connection.
+- **Overflow menu**: This is a dropdown menu which allows you to perform some additional actions. Of note are:
 
   - **Validate**: This will validate the configuration file.
   - **Install**: Opens the Install dialog.
-  - **Clean Build Files**: This will delete all of the generated build files and is a safe operation to perform. Sometimes old files are not removed and can cause compile issues later on.
+  - **Clean Build Files**: This will delete all of the generated build files; it can help to resolve compile issues
+    should they occur. *This is safe to perform at any time and you should try this before reporting bugs or other
+    issues.*
   - **Delete**: This will delete the configuration file.
 
-The configuration files for ESPHome can be found and edited under ``<HOME_ASSISTANT_CONFIG>/esphome/``.
-For example the configuration for the ``garage-door`` node in the picture above can be found
-in ``/config/esphome/garage-door.yaml``.
+The configuration files for ESPHome are stored in the ``<HOME_ASSISTANT_CONFIG>/esphome/`` directory. For example, the
+configuration for the "Bedroom Light" node in the picture above can be found in ``/config/esphome/bedroom-light.yaml``.
 
 .. note::
 
-    Since Home Assistant add-ons run as individual containers, accessing these through
-    command line is not very straightforward, but it's possible. To do that,
-    install Home Assistant's SSH addon, configure a username and a password,
-    and disable `Protection Mode` (please assess the risks you take with that).
-    Then, for example to access the logs from a device through an SSH client,
-    log in, and you can use a command like
-    `docker exec -it addon_15ef4d2f_esphome esphome logs /config/esphome/garage-door.yaml`.
-    See :doc:`getting_started_command_line` for more.
+    Home Assistant add-ons run as individual containers; this can make accessing your configuration files/logs a bit
+    challenging. If you wish to do so, you'll need to install and configure Home Assistant's
+    `SSH addon <https://www.home-assistant.io/common-tasks/os/#installing-and-using-the-ssh-add-on>`__. You'll need to
+    configure an SSH username and password and disable "Protection Mode" (please assess the risks associated with
+    doing so).
+
+    Then, to access the logs from a device through an SSH client, you can log in and use a command like
+    ``docker exec -it addon_15ef4d2f_esphome esphome logs /config/esphome/bedroom-light.yaml``.
 
-Now go ahead and use one of the :ref:`devices guides <devices>` to extend your configuration.
+    See :doc:`getting_started_command_line` for more detail.
 
-Adding some (basic) features
-----------------------------
+Adding Features
+---------------
 
-So now you should have a file called ``/config/esphome/livingroom.yaml`` (or similar).
-Go open that file (in any text editor) and add a :doc:`simple GPIO switch </components/switch/gpio>`
-to the configuration like this:
+After stepping through the wizard, you should have a device configuration (YAML) file. In the ESPHome Device Builder,
+click on "EDIT" to open that file and add a :doc:`GPIO switch</components/switch/gpio>` to the configuration like this:
 
 .. code-block:: yaml
 
@@ -104,68 +130,85 @@ to the configuration like this:
         name: "Living Room Dehumidifier"
         pin: GPIO5
 
-In above example, we're simply adding a switch that's called "Living Room Dehumidifier" (could control
-anything really, for example lights) and is connected to the pin ``GPIO5``.
-
-.. _connecting-your-device-to-home-assistant:
-
-Connecting your device to Home Assistant
-----------------------------------------
-
-Once your configuration is installed on your ESP device and is online, it will be automatically discovered by Home Assistant and offered to set up on your integrations screen:
-
-.. raw:: html
-
-    <a href="https://my.home-assistant.io/redirect/config_flow_start/?domain=esphome" target="_blank"><img src="https://my.home-assistant.io/badges/config_flow_start.svg" alt="Open your Home Assistant instance and start setting up a new integration." /></a>
-
-Alternatively, you can manually add the device on the Home Assistant Integrations page.  Click on the "Add Integration" button (bottom right), search for esphome, and enter the host name, eg: "<NODE_NAME>.local" as the host.  Use the same process to add multiple esphome devices.
+In Home Assistant, the example code above will look like this:
 
 .. figure:: /components/switch/images/gpio-ui.png
     :align: center
     :width: 75.0%
 
-After the first installation, you will probably never need to use the USB
-cable again, as all features of ESPHome are enabled remotely as well.
+In the example above, we're simply adding a switch that's called "Living Room Dehumidifier" and is connected to the pin
+``GPIO5``. This switch could really control anything -- lights or a tabletop fan, for example. Its name and function is
+arbitrary and should be set as is appropriate for your particular application.
 
 Adding A Binary Sensor
 ----------------------
 
-Next, we’re going to add a very simple binary sensor that periodically
-checks a GPIO pin to see whether it’s pulled high or low - the :doc:`GPIO Binary
-Sensor </components/binary_sensor/gpio>`.
+Next, let's add a :doc:`binary sensor which will monitor a GPIO pin </components/binary_sensor/gpio>` to determine and
+report its state.
 
 .. code-block:: yaml
 
     binary_sensor:
       - platform: gpio
         name: "Living Room Window"
         pin:
-          number: 16
+          number: GPIO0
           inverted: true
           mode:
             input: true
             pullup: true
 
-This time when installing, you don’t need to have the device plugged in
-through USB again. The upload will happen wirelessly (:doc:`"over the air" </components/ota/index>`).
+In Home Assistant, the example code above will look like this:
 
 .. figure:: /components/binary_sensor/images/gpio-ui.png
     :align: center
     :width: 75.0%
 
+After adding this to your device's configuration file, be sure to click "SAVE" to save the changes you've made to your
+configuration...and read on to the next section!
+
+Updating your Device
+--------------------
+
+Any time you make changes to your device's configuration file, you'll need to update the associated physical device
+with your modified configuration. Put another way, just saving the configuration file alone does not update the
+ESPHome device with the changes you've made.
+
+Each time you modify a device's configuration file, you need to update the device by clicking **INSTALL** to recompile
+and reinstall your updated configuration onto the device.
+
+Note that you won't need to have the device connected to your system with a USB data cable again, as (once ESPHome is
+installed on your device) it can update the device :doc:`"over the air" </components/ota/index>`.
+
+.. _connecting-your-device-to-home-assistant:
+
+Connecting your device to Home Assistant
+----------------------------------------
+
+Once your configuration is installed on your device and it's connected to your Wi-Fi, Home Assistant will automatically
+discover it (assuming your network permits this) and offer to configure it:
+
+.. raw:: html
+
+    <a href="https://my.home-assistant.io/redirect/config_flow_start/?domain=esphome" target="_blank"><img src="https://my.home-assistant.io/badges/config_flow_start.svg" alt="Open your Home Assistant instance and start setting up a new integration." /></a>
+
+Alternatively, you can manually add the device on the Home Assistant Integrations page. To do so, click on the "Add
+Integration" button (bottom right), search for "ESPHome" and enter the ESPHome device's host name. The host name is
+based on the name you've given to the device; if you named your device "living-room-lamp", its host name will be
+``living-room-lamp.local``. You can also enter the device's IP address, if for some reason you prefer to use that.
+
+You can repeat this process for each ESPHome device.
+
 Where To Go Next
 ----------------
 
-Great 🎉! You’ve now successfully setup your first ESPHome project
-and installed your first ESPHome custom firmware to your node. You’ve
-also learned how to enable some basic components via the configuration
-file.
+Great! 🎉 You've successfully set up your first ESPHome project and installed your first ESPHome custom firmware to your
+device. You've also learned how to enable some basic components via the configuration file.
 
-So now is a great time to go take a look at the :doc:`Components Index </index>`.
-Hopefully you’ll find all sensors/outputs/… you’ll need in there. If you’re having any problems or
-want new features, please either create a new issue on the `GitHub issue
-tracker <https://github.com/esphome/issues/issues>`__ or find us on the
-`Discord chat <https://discord.gg/KhAMKrd>`__ (also make sure to read the :doc:`FAQ <faq>`).
+Now is a great time to go take a look at the :doc:`Components Index </index>`. Hopefully you'll find all the hardware
+components you need there. If you're having any problems or want to request new features, please either create a new
+issue on the `GitHub issue tracker <https://github.com/esphome/issues/issues>`__ or find us on the
+`Discord chat <https://discord.gg/KhAMKrd>`__. Be sure to read the :doc:`FAQ <faq>`, as well!
 
 See Also
 --------