diff --git a/guides/beginners_guide_adding_devices.rst b/guides/beginners_guide_adding_devices.rst new file mode 100644 index 0000000000..e2ff625ace --- /dev/null +++ b/guides/beginners_guide_adding_devices.rst @@ -0,0 +1,704 @@ +Beginner's Guide to Adding Devices +================================== + +.. seo:: + :description: A step-by-step beginner's guide to adding device YAMLs to ESPHome in a running Docker container, with detailed instructions and pictures. + :image: docker-mark-blue.svg + +This guide is for people who are unfamiliar with ESPHome and wish to learn the basics. + +.. note:: + + ESPHome devices usually rely on Home Assistant. It's more than just an excellent way to control and automate your + home. It can also manage many IoT devices. Read more about `Home Assistant `__. + + If you are already running Home Assistant, check out :doc:`getting_started_hassio` to run ESPHome as an add-on. + + If running Home Assistant in Docker, get ESPHome by following instructions in the first part of + :doc:`getting_started_command_line`. + + Or if not running Docker or Home Assistant at all, you can try :doc:`beginners_guide_docker_desktop`. + +Setting up your Secrets +----------------------- + +The ``secrets.yaml`` file is where you'll store information that you don't want to accidentally share or otherwise +hard-code into your device's YAML configuration file(s). It's also useful because it provides a single place in which +to store common values; this way, if you need to change one of them, you won't need to update every individual device's +file, which can save you a lot of time when you have many devices! + +When you keep these secret values in a separate file, you can confidently copy and paste YAML from your files and share +it with others. You don't need to worry about accidentally sharing the details of your home network, such as your Wi-Fi +SSID name and password. + +Click here in the ESPHome Dashboard to edit ``Secrets``. + +.. figure:: images/noob_dashboard_1a.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard window with circle around "Secrets" + +Wi-Fi Network +************* + +Add the next 4 lines, replacing the placeholders with your own values. + +.. code-block:: yaml + + # My Wi-Fi SSID and password + wifi_ssid: "" + wifi_password: "" + ap_password: "" # Super-secret! + +These are the 3 most basic secrets. The wireless network name is set by ``wifi_ssid`` and the password +is set by ``wifi_password``. Actually, the names ``wifi_ssid``, ``wifi_password`` are arbitrary. +You could just as easily use ``home_wifi``, ``home_password`` if you like. +But ``wifi_ssid``, ``wifi_password``, and ``ap_password`` are commonly used in the community. + +Finally, ``ap_password`` sets a password for the hotspot that an ESPHome device creates when it cannot +find the wireless network. + +.. note:: + + Please note in the above example, I have included comments with the ``#`` character. Comments can be + added as their own lines or at the end of lines. + Anything in the line after the ``#`` are ignored. + Often, comments can be used to explain what a particular section of code is doing. + +.. warning:: + + Supported Espressif microcontrollers only support the 2.4 Ghz frequency range for Wi-Fi. + + If you're experiencing connectivity issues, see our :ref:`FAQ `. + +OTA +*** + +.. code-block:: yaml + + ota_password: "" + +An ``ota_password`` is used to securely send Over-the-Air (OTA) updates from ESPHome to a device. +For beginners, it is a good idea to use the same password for all of your ESPHome devices. +This will ensure your updates are not broken by ESPHome's default behavior of creating new passwords +for every device. You can make this password as long and complicated as you like because +you will not have to remember it. + +MQTT +**** + +.. code-block:: yaml + + mqtt_broker: "" + mqtt_name: "" + mqtt_password: "" + +These lines regard the MQTT (Message Queue Telemetry Transport) protocol. +MQTT is a lightweight, publish-subscribe-based messaging protocol that is commonly used in IoT devices. +The ``mqtt_broker`` is the IP address of the MQTT server and the ``mqtt_name`` and ``mqtt_password`` +are the username and password. +If you are not running an MQTT server, you do not need to add these to your secrets yet. + +Save +**** + +Don't forget to click ``Save`` when finished editing. + +.. figure:: images/noob_dashboard_1b.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard Secrets window with circle around "Save" + +Then you can close the Secrets. + +.. figure:: images/noob_dashboard_1c.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard Secrets window with circle around "X" + + +Adding a Device +--------------- + +This example (and everything below) will use +`Athom-E27-7W-Bulb `__ as an example +because it illustrates the basic principals of an ESPHome Configuration and the community's usual/best practices. +Your first use-case will surely be different but the principles will be the same. + +.. note:: + + The YAML was referred to on February 17, 2025. It may have changed since then. + It is important to know that ESPHome is constantly evolving, elements are always changing, + and sometimes what you find by searching may not always be up-to-date for the latest version of ESPHome. + The community is always improving the documentation but there are often discrepancies. + By the time you read this, it's possible some things here may be out-of-date. It's always best to search + :doc:`ESPHome.io ` if something is giving you trouble, + the `Home Assistant forums `__, + ESPHome on `Discord `__, + or search the `Reddit sub `__. + +Adding the Device to ESPHome +**************************** + +First, click "New Device." When you have no devices, it will look like this. + +.. figure:: images/noob_dashboard_2a.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard with no devices and circles around both "New Device" buttons + +Give the device a name. For the example, let's call it "livingroom-light". +The device name should be informative and unique because each and every device +in ESPHome will get it's own YAML file. It's totally up to you how to name it. +After naming it, click "Next". + +.. figure:: images/noob_dashboard_2b.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard "New Device" with a circle around Name and set to "livingroom-light" + +We're not ready to install ESPHome to the device yet so click "Skip this step". + +.. figure:: images/noob_dashboard_2c.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard "New Device" Installation with a circle around "Skip this step" + +Next, we have to choose what type of device this is. In the link for +`Athom-E27-7W-Bulb `__ +there is this snippet: + +.. figure:: images/noob_dashboard_2d.png + :align: center + :width: 50.0% + +So we know it's an ESP8266. + +.. figure:: images/noob_dashboard_2e.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard "New Device" Installation with a circle around "ESP8266" + +You can see that ESPHome has generated a unique key for the device but we're not quite ready to install ESPHome yet, +so click ``skip``. + +.. figure:: images/noob_dashboard_2f.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard "New Device" Installation with a circle around "ESP8266" + +Now we have a device YAML file ready. But we still have to edit it to fit the device. + +.. figure:: images/noob_dashboard_2g.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard showing the new device "livingroom-light" has been added + + +The YAML +******** + +Click ``edit``. + +.. figure:: images/noob_dashboard_3a.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard showing the new device "livingroom-light" has been added + +This is the ESPHome Dashboard editor. This is YAML code and how ESPHome devices are configured. + +.. figure:: images/noob_dashboard_3b.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard editor, opened to "livingroom-light.yaml" + +We need to go back to the profile for `Athom-E27-7W-Bulb `__. + +.. figure:: images/noob_dashboard_3c.png + :align: center + :width: 75.0% + :alt: Code snippet for Athom-E27-7W-Bulb with a circle around "Copy" + +Thankfully, this page has a button we can click "Copy" and just copy the entire YAML from the template. Click "Copy". + +Go back to the ESPHome Dashboard and use your mouse to move your cursor to the end of the file. +Create a marker like ``#-----`` (``#`` means it's a comment) and a few extra lines and make sure your cursor +is at the first column like this. + +.. figure:: images/noob_dashboard_3d.gif + :align: center + :width: 95.0% + :alt: ESPHome Dashboard editor, opened to "livingroom-light.yaml" + +And then paste what you just copied. + +.. note:: + + Hotkeys are very useful when working with plain text. + Get to know them and you will have an easier time with YAML files. + + .. tabs:: + + .. tab:: Windows / Linux + + **Copy** : ``Ctrl + C`` + + **Paste** : ``Ctrl + V`` + + **Cut** : ``Ctrl + X`` + + **Undo** : ``Ctrl + Z`` + + **Redo** : ``Ctrl + Y`` + + .. tab:: Other Linux + + **Copy** : ``Ctrl + Shift + C`` + + **Paste** : ``Ctrl + Shift + V`` + + **Cut** : ``Ctrl + Shift + X`` + + **Undo** : ``Ctrl + Z`` + + **Redo** : ``Ctrl + Shift + Y`` + + .. tab:: MacOS + + **Copy** : ``Command (⌘) + C`` + + **Paste** : ``Command (⌘) + V`` + + **Cut** : ``Command (⌘) + X`` + + **Undo** : ``Command (⌘) + Z`` + + **Redo** : ``Command (⌘) + Shift + Z`` + +What we need to do now is merge the two separate bits together. Fortunately, there isn't a lot to worry about. +Mostly, we will just work with what we pasted. + +Throughout the rest of this tutorial, there will be links to more detailed documentation. +You can click on them to learn more. + +substitutions: +^^^^^^^^^^^^^^ + +First, let's take a look at the very important :doc:`substitutions ` section. + +.. code-block:: yaml + + substitutions: + device_name: "athom-rgbww-light" + friendly_name: "Athom RGBWW Light" + project_name: "athom.rgbww-light" + project_version: "1.0" + +This section is actually pretty short. Some pre-made configurations will include a lot more. + +What this does is set up a bunch of variables which are easy to edit, reusable, and individualize the device. +Perhaps you have two identical bulbs and you want to name them differently. Just change it to something like this: + +.. code-block:: yaml + + substitutions: + device_name: "living-room-light" + friendly_name: "Living Room Light" + project_name: "athom.rgbww-light" + project_version: "1.0" + +Substitutions are very common among YAMLs you find online and they're almost always placed at the top. + + .. collapse:: The Order of Sections + + For almost every other section of a YAML, it's not strictly important what is higher or lower than another. + It's useful to know that they are processed in order but sometimes you will see various sections in a much different arrangement + than what we see here. But almost always, ``substitutions`` is at the top and ``esphome`` is not far below. + +esphome: +^^^^^^^^ + +Next, let's look at the ``esphome`` section and which is immediately after and see what the substitutions do. + +.. code-block:: yaml + + esphome: + name: "${device_name}" + name_add_mac_suffix: true + platform: ESP8266 + board: esp8285 + project: + name: "${project_name}" + version: "${project_version}" + +Wherever you see a dollar-sign ``$`` followed by a variable name, it's a substitution. +In this way, we can easily change the name of the device and the project. +The ``device_name`` may also be needed later in the YAML and it could be pretty irritating to search +every time you copy and paste a YAML for a new device. +In some cases, too, you may see hardware settings or other options defined in the substitutions section +so that you don't have to search for it to change it. + + .. collapse:: Note About Curly Brackets + + Note that usually curly brackets ``{$device_name}`` are usually used when calling the substitution, + although sometimes you may see substitutions that do not use curly brackets like ``$device_name``. + Both are acceptable but curly brackets are used to avoid errors so it's best to use curly brackets. + +There are definitely some edits needed. As of February 2025, ESPHome will no longer support the ``platform`` section. +We need to remove the lines that refer to the ``board`` and ``platform``. There is a new section for that. +But before we get to that, what does ``name_add_mac_suffix: true`` do? +Let's check the documentation regarding :doc:`ESPHome Core Configuration `. + +.. figure:: images/noob_dashboard_3e.png + :align: center + :width: 50.0% + +It adds 3 digits from the hardware's MAC (the serial number of the Wireless interface). +It's useful when flashing multiple devices with the same hardware and similar (but not the same) names. +You may prefer to have a plain name, in which case, delete this line. + +So, we should have this now: + +.. code-block:: yaml + + esphome: + name: "${device_name}" + project: + name: "${project_name}" + version: "${project_version}" + + +esp8266 / esp32: +^^^^^^^^^^^^^^^^ + +Usually, immediately following the ``esphome`` section will be your platform and board. +For the purposes of our Athom bulb, we will need this section: + +.. code-block:: yaml + + esp8266: + board: esp8285 + +In some cases, rather than using an ESP8266, you may need to specify ESP32 like this: + +.. code-block:: yaml + + esp32: + board: esp32dev + +It is critically important to know which platform you are working with. ESP8266 and ESP32 are completely different. +Code for one will not work on the other. + +It is also important to know which board you are working with, as many boards have different hardware configurations, +especially differing in flash memory sizes. +But in most cases, when dealing with ESP8266, it is ``esp8255`` or sometimes ``esp12e`` (which has only 1M of flash memory). +For ESP32, ``esp32dev`` will work for many boards - but not all. + +Under the hood, ESPHome uses PlatformIO to turn YAML into a program, so you need to use the official board name +(lowercase, no spaces) from PlatformIO. + +For ESP8266 boards you can consult the +`platformio/espressif8266 boards list `__. + +For ESP32 boards you can consult +`platformio/espressif32 boards list `__. + +You can also read more about the configuration of the +:doc:`ESP8266 Platform ` +and the :doc:`ESP32 Platform `. + +api: +^^^^ + +Sometimes sections are blank but absolutely crucial they are present. This next bit is one of them. + +.. code-block:: yaml + + api: + +This tells the device that it will be communicating with the :doc:`Home Assistant API `. +If you are running Home Assistant, you need to keep this line, but go back above the ``#-----`` we made earlier and +and copy and paste the encryption key that was generated when the initial YAML was made, so we end up with something like: + +.. code-block:: yaml + + api: + encryption: + key: "" + +If you don't have Home Assistant, you should just delete this entire section. +If left in, the device will continuously try to make a connection to Home Assistant +and reboot every 15 minutes to re-attempt making the connection. + +Also, you don't necessarily need encryption. +It just adds an additional layer of protection to your devices. + +ota: +^^^^ + +.. code-block:: yaml + + ota: + +This section is pretty important. It allows :doc:`Over-the-Air Updates `. +Unless you want to make a physical connection to the device every time you want to update it, you should keep this section. + +Unfortunately, it's incomplete. As of 2024.6.0, ESPHome has changed the way OTA updates are specified. +As a bonus, we finally get to use one of the secrets we created earlier. + +.. code-block:: yaml + + ota: + - platform: esphome + password: !secret ota_password + +logger: +^^^^^^^ + +.. code-block:: yaml + + logger: + +:doc:`Logging ` is important. Leave it in but if you find the messages overwhelming, +you can lower the level to only show errors (the default is DEBUG) with: + +.. code-block:: yaml + + logger: + level: ERROR + +web_server: +^^^^^^^^^^^ + +.. code-block:: yaml + + web_server: + port: 80 + +This section creates a :doc:`web server ` +on the device so you can access and control the device using the mDNS or IP address. +Chances are good that the web address will match what we made the ``name:`` earlier +(which refers to the substitution ``device-name``). +So after flashing the new firmware, we should be able to go to +`http://living-room-light.local `__ and control the light bulb +through it's WebUI. + +.. collapse:: Note About mDNS + + mDNS (Multicast Domain Name System) is available on most networks. + It allows devices to "declare" their name to the network, usually using the top-level domain `.local`. + If mDNS is not functioning on your local network, + it may be simpler to refer to the device's IP address instead. + +wifi: +^^^^^ + +.. code-block:: yaml + + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + ap: + +The :doc:`wifi ` section gives the device the name and password of the local wireless network +(as specified in the secrets). +The ``ap:`` part specifies that it will create a hotspot in case the device cannot connect to the network. +But let's edit that so the hotspot created will have the device's name as the hotspot name +and the password as specified in the secrets file. + +.. code-block:: yaml + + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + ap: + ssid: ${device_name} + password: !secret ap_password + +captive_portal: +^^^^^^^^^^^^^^^ + +.. code-block:: yaml + + captive_portal: + +The :doc:`captive_portal ` section is responsible to create a special web server using +the hotspot created in conjunction with the `ap:` information specified above. +This allows you allows you to give the device new wireless network credentials when the device cannot connect +to the network it expects. + +When you connect to the fallback hotspot, the web interface should open automatically +or there should be a prompt on your phone to open the login. +If that does not work, you can also navigate to `http://192.168.4.1/ `__ manually in your browser. + +Other Sections (Device Configuration) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The rest of the YAML specifies the various components that make the light bulb actually function. +Or, as in the case of ``text_sensor``, provide additional information. + +In this example, they are: +:doc:`binary_sensor `, +:doc:`sensor `, +:doc:`switch `, +:doc:`output `, +:doc:`light `, and +:doc:`text_sensor `. + +Of course, other devices may include other components. + + .. collapse:: The rest of the YAML (which you shouldn't need to edit) + + .. code-block:: yaml + + binary_sensor: + - platform: status + name: "${friendly_name} Status" + + sensor: + - platform: uptime + name: "${friendly_name} Uptime Sensor" + + switch: + - platform: restart + id: restart_switch + name: "${friendly_name} Restart" + + output: + - platform: esp8266_pwm + id: red_output + pin: GPIO4 + - platform: esp8266_pwm + id: green_output + pin: GPIO12 + - platform: esp8266_pwm + id: blue_output + pin: GPIO14 + - platform: esp8266_pwm + id: warm_white_output + pin: GPIO13 + - platform: esp8266_pwm + id: white_output + pin: GPIO5 + + + light: + - platform: rgbww + name: "${friendly_name}" + red: red_output + green: green_output + blue: blue_output + warm_white: warm_white_output + cold_white: white_output + cold_white_color_temperature: 6000 K + warm_white_color_temperature: 3000 K + color_interlock: true + + text_sensor: + - platform: wifi_info + ip_address: + name: "${friendly_name} IP Address" + disabled_by_default: true + +.. note:: + + When it comes to components, a YAML file can only have one section per component. + For example, all switches must be listed under only one ``switch:`` heading. + You can't have two separate ``switch:`` sections. + +Finishing Up +^^^^^^^^^^^^ + +Now you can delete everything above and including the ``#-----`` +so that the first line of your file should be ``substitutions``. + +If you like you can make the first line of your file a comment you can refer to later. + +Don't forget to save! + +.. figure:: images/noob_dashboard_3f.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard window with circle around "Save" + +Then you can close the file. + +.. figure:: images/noob_dashboard_3g.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard window with circle around "X" + +Validate & Download Binary File +------------------------------- + +On the living-room-light's YAML, click the three dots ``⋮`` and select ``Validate``. + +.. figure:: images/noob_dashboard_4a.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard after clicking a YAML's ⋮ showing options with a circle around "Validate" + +If there are errors, read the message, then edit your YAML to fix the problem. +You may need to search :doc:`ESPHome.io` and do some reading. + +If no errors, click ``Install``. + +.. figure:: images/noob_dashboard_4b.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard showing validation screen with circles around "INFO Configuration is valid!" and "Install" + +Even if we're not ready to actually install, ``Manual download`` +will do a deeper check of the code to make sure everything is okay. + +.. figure:: images/noob_dashboard_4c.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard showing install options with a circle around "Manual download" + +It can take a few minutes to download all the dependencies and compile the code, especially the first time. + +.. figure:: images/noob_dashboard_4d.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard showing compilation screen + +If it doesn't say ``[ SUCCESS ]`` then you have to fix an error. +This may involve searching and reading the ESPHome documentation. + +Otherwise, great! You can download the binary and save it somewhere useful. +Actually you don't need to download it now. Compilation next time will be much faster. + +.. figure:: images/noob_dashboard_4e.png + :align: center + :width: 95.0% + :alt: ESPHome Dashboard showing compilation finished screen with circles around "[ SUCCESS ]" and "Download" + +.. collapse:: Blocked Download + + There is a chance that some browsers (Brave Browser, for example) or an Antivirus program will block the download. + If this happens, you may need to add an exception or override the block. + + +What's Next? +------------ + +Now you're ready to actually flash the device with your fresh ESPHome binary! + +If you're lucky, the device already has ESPHome, +you can actually just connect to it via web browser and upload your new binary file. +If your device already has :doc:`Tasmota `, +:doc:`ESPEasy `, +or :doc:`ESPurna `, +it's also pretty easy. + +Harder, but possibly necessary, make a :doc:`physical connection to the device `! + +See Also +-------- + +- :doc:`ESPHome index ` +- :doc:`getting_started_hassio` +- :doc:`faq` +- :doc:`diy` +- :ghedit:`Edit` diff --git a/guides/beginners_guide_docker_desktop.rst b/guides/beginners_guide_docker_desktop.rst new file mode 100644 index 0000000000..1db2000577 --- /dev/null +++ b/guides/beginners_guide_docker_desktop.rst @@ -0,0 +1,249 @@ +Beginner's Guide to Installing ESPHome on Docker Desktop +======================================================== + +.. seo:: + :description: A step-by-step beginner's guide to installing and running ESPHome on Docker Desktop, with detailed instructions for Windows, Mac, and Linux users. + :image: docker-mark-blue.svg + +This guide is for people who are unfamiliar with ESPHome, but need Docker to begin. + +Docker Desktop +-------------- + +Probably the easiest way to start with ESPHome, especially when you're not familiar with Home Assistant, +is to start with Docker Desktop. + +Docker Desktop can run Linux containers like ESPHome very well, +although it may be slow on under-powered machines like lower-performance laptops. + +Running the command-line version of ESPHome might be enjoyable for the Linux-savvy but can be a headache, +especially when it comes to Python and its dependencies. +The Docker version of ESPHome will take care of all the dependencies +and make it a lot easier to at least get started with ESPHome. + +Prepare Location for Docker and ESPHome Files +--------------------------------------------- + +You will need to make folders where Docker can use config files for ESPHome (and other containers). +This makes it painless to update the ESPHome container. + +I recommend something easy to find. Here are examples for different operating systems: + +* Windows: ``D:\Docker\esphome`` +* Linux: ``~/docker/esphome`` or ``/home/username/docker/esphome`` +* Mac: ``~/docker/esphome`` or ``/Users/username/docker/esphome`` + +Choose any location that's easy for you to find and remember. + +Install Docker Desktop +---------------------- + +Download and install the appropriate version of Docker Desktop from +`the official site `__. +On Windows, this will also install any needed dependencies like WSL (Windows Subsystem for Linux). +On Mac, it will make sure you have Apple Virtualization Framework. +You should accept any required other installs. + +If you have installation issues, please refer to the docker documentation for + +`Windows `__, +`Linux `__, or +`Mac `__. + +Please note that although Docker Desktop is not particularly large, containers like ESPHome can be. +And the compilation of ESPHome binaries can take up a lot of space, too. +You might be okay with 5GB free space but 10GB or more is highly recommended as a minimum since building +binaries can also take up space. + +If Docker asks you to login, you can skip this. + +Docker may also require a reboot to finalize the installation. + +Add the ESPHome container +------------------------- + +In Docker Desktop, you first need to download the ESPHome image. +Click ``Images`` and then ``Search images to run``. + +.. figure:: images/noob_docker_1.png + :align: center + :width: 95.0% + :alt: Docker Desktop window with circle around "Images" and "Search images to run" + +Type ``esphome`` in the search box. +The official ESPHome image belongs to the DockerHub member ``esphome`` +so it should appear at the top as ``esphome/esphome``. + +Next to that image, you can select the version but unless you have a specific problem, +the ``latest`` is the best to use. Click ``Pull`` to download the image. + +It will take a few moments to download the image. + +.. figure:: images/noob_docker_2.png + :align: center + :width: 95.0% + :alt: Docker Desktop search window with circle around "esphome" in the search box, a circle around "esphome/esphome", and a circle around "Pull" + +Click on ``Images`` again and it should now show that you have the image ``esphome/esphome`` ready to use. +Click the ``Run`` button. + +.. figure:: images/noob_docker_3.png + :align: center + :width: 95.0% + :alt: Docker Desktop window with circle around "Images" and "Run" button + +Before actually running, expand the optional settings. +Give the container a name like ``esphome`` (you can use capital letters here if you like). +Also, set the port to use to access the GUI. The default is ``6052``. + +.. note:: + + If port 6052 is already in use on your system, you can use a different port number. + Just remember to use the new port number when accessing the ESPHome dashboard in your browser. + +In the ``Volumes`` options, enter the locations ``Host path`` (set to the location created earlier) +and ``Container path`` (Set to ``/config`` - it **MUST** be exactly like this). +Also, add an environment variable called ``TZ`` and set to your local timezone. +If you're not sure what yours is called, check +`Wikipedia `_ under ``TZ identifier``. +Try to use a TZ indentifier that is listed under "Type" as "Canonical". + +After all that is done, click ``Run`` and the container will start. + +.. figure:: images/noob_docker_4.png + :align: center + :width: 95.0% + :alt: Docker Desktop run window with Optional Settings expanded and a circles around "Container Name" set to "esphome" and "Host port" set to 6052 and "Host path" set to "D:\Docker\esphome" and "Container path" set to "/config" and Variable set to "TZ" and "Value" set to "Asia/Seoul" + +Windows may ask if Docker can access the network. Click ``Allow``. + +.. figure:: images/noob_docker_4b.png + :align: center + :width: 50.0% + :alt: Windows Security warning asking if Docker Desktop Backend should have network access + +If your window looks like something like this, congratulations! You are now running ESPHome on your computer! + +.. figure:: images/noob_docker_5.png + :align: center + :width: 95.0% + :alt: Docker Desktop showing the container running + +Go back to the Containers tab to manage the ESPHome container and ``Open with browser`` anytime the container is running. + +.. figure:: images/noob_docker_6.png + :align: center + :width: 95.0% + :alt: Docker Desktop showing running containers with a circle around "Containers" and another circle around ⋮ and an arrow pointing to "Open with browser" + +The gear in the top right corner allows you to manage Docker Desktop settings. +Docker usually is not set to start with Windows but you can change that if you like. + +You can also update Docker Desktop itself by clicking on the gear and then clicking on ``Software updates``. + +.. figure:: images/noob_docker_7.png + :align: center + :width: 95.0% + :alt: Docker Desktop showing running containers with circles around the Settings gear icon and the Run icon and the delete icon + +Also when starting Docker Desktop again, you may also need to run the container again using this screen. +When it is running the run ``▶`` icon will change to a stop ``⯀`` icon. + +.. note:: + + Also in this screen are options to stop and delete the container. + You **MUST** stop the container AND delete the container before updating the ESPHome image. + +To update the ESPHome container (so you can run the latest version of ESPHome), +click ``Settings`` then three dots ``⋮``, and select ``Pull``. +Docker Desktop will check if there is a new ``latest`` image to pull. +If there is, it will download it. +If not, it will tell you ``Image is up to date``. + +.. figure:: images/noob_docker_8.png + :align: center + :width: 95.0% + :alt: Docker Desktop showing Images with a circle around "Images" and another circle around ⋮ and an arrow pointing to "Pull" + +You will have to recreate the container as illustrated above. +As long as you point to the correct folder with your ESPHome ``config`` files, +your configuration and all your device files will remain unchanged. +Automatically Update the ESPHome Container +****************************************** + +If you wish to automate the process (without deleting your esphome container or even stopping it), +there's an easier way. + +Search for images to add, enter ``adamus1red/ouroboros`` (the original is ``pyouroboros/ouroboros`` but it hasn't been updated in years), +``Pull`` the image, then ``Run`` with these options: + + +.. figure:: images/noob_docker_9.png + :align: center + :width: 95.0% + :alt: Docker Desktop showing Images with arrow pointing to the "search bar" + +As before, we need to specify some optional settings. + +.. figure:: images/noob_docker_9b.png + :align: center + :width: 95.0% + :alt: Docker Desktop showing Run a New Container named "ouroboros" with "Host Path" and "Container Path" set and 4 environment variables + +Because Ouroboros needs access to Docker's core, we should enter ``/var/run/docker.sock`` +as the Container Path but where docker.sock resides on your computer depends on the operating system you are using. + +.. tabs:: + + .. tab:: Windows + + Enter ``//var/run/docker.sock`` as the Host Path. + + *Note the double //.* + + .. tab:: Linux + + Enter ``/var/run/docker.sock`` as the Host Path. + + *This should work for most cases.* + + .. tab:: MacOS + + Enter ``/var/run/docker.sock`` as the Host Path. + + *The author does not have a Mac so this is untested.* + +Also, set 4 environment variables (use the ``+`` to add more) ``SELF_UPDATE`` : ``true`` and ``CLEANUP`` : ``true`` and ``RUN_ONCE`` : ``true`` and ``LATEST`` : ``true``. + +Now, to automatically update all containers, just run the ``ouroboros`` container. +It will automatically stop a container, pull the ``latest`` image, +and restart the container with your previous settings. +It will do this to all existing containers. Then, it will stop. + +.. note:: + + While automatic updates can be convenient, they come with risks: + + 1. Breaking changes in new versions could affect your devices + 2. Updates might occur at inconvenient times + 3. Rollback might be needed if issues occur + + It's recommended to: + + * Review ESPHome's :doc:`Release Notes ` before updates + * Consider manual updates for better control + * Keep backups of your configuration + + If you choose automatic updates, monitor your devices after updates for any issues. + +What's Next? +------------ + +Now you can add your :doc:`first ESPHome device `! + +See Also +-------- + +- :doc:`ESPHome index ` +- :doc:`getting_started_hassio` +- :ghedit:`Edit` diff --git a/guides/images/noob_dashboard_1a.png b/guides/images/noob_dashboard_1a.png new file mode 100644 index 0000000000..12456ca030 Binary files /dev/null and b/guides/images/noob_dashboard_1a.png differ diff --git a/guides/images/noob_dashboard_1b.png b/guides/images/noob_dashboard_1b.png new file mode 100644 index 0000000000..dcf228990e Binary files /dev/null and b/guides/images/noob_dashboard_1b.png differ diff --git a/guides/images/noob_dashboard_1c.png b/guides/images/noob_dashboard_1c.png new file mode 100644 index 0000000000..c15b36d04e Binary files /dev/null and b/guides/images/noob_dashboard_1c.png differ diff --git a/guides/images/noob_dashboard_2a.png b/guides/images/noob_dashboard_2a.png new file mode 100644 index 0000000000..c754bd3ee0 Binary files /dev/null and b/guides/images/noob_dashboard_2a.png differ diff --git a/guides/images/noob_dashboard_2b.png b/guides/images/noob_dashboard_2b.png new file mode 100644 index 0000000000..9e5cb01e36 Binary files /dev/null and b/guides/images/noob_dashboard_2b.png differ diff --git a/guides/images/noob_dashboard_2c.png b/guides/images/noob_dashboard_2c.png new file mode 100644 index 0000000000..fb64f3c4ef Binary files /dev/null and b/guides/images/noob_dashboard_2c.png differ diff --git a/guides/images/noob_dashboard_2d.png b/guides/images/noob_dashboard_2d.png new file mode 100644 index 0000000000..5c2b5399b5 Binary files /dev/null and b/guides/images/noob_dashboard_2d.png differ diff --git a/guides/images/noob_dashboard_2e.png b/guides/images/noob_dashboard_2e.png new file mode 100644 index 0000000000..226e6cb45b Binary files /dev/null and b/guides/images/noob_dashboard_2e.png differ diff --git a/guides/images/noob_dashboard_2f.png b/guides/images/noob_dashboard_2f.png new file mode 100644 index 0000000000..03cf9125d6 Binary files /dev/null and b/guides/images/noob_dashboard_2f.png differ diff --git a/guides/images/noob_dashboard_2g.png b/guides/images/noob_dashboard_2g.png new file mode 100644 index 0000000000..3961fa510f Binary files /dev/null and b/guides/images/noob_dashboard_2g.png differ diff --git a/guides/images/noob_dashboard_3a.png b/guides/images/noob_dashboard_3a.png new file mode 100644 index 0000000000..46b0eccb1d Binary files /dev/null and b/guides/images/noob_dashboard_3a.png differ diff --git a/guides/images/noob_dashboard_3b.png b/guides/images/noob_dashboard_3b.png new file mode 100644 index 0000000000..20af86dee8 Binary files /dev/null and b/guides/images/noob_dashboard_3b.png differ diff --git a/guides/images/noob_dashboard_3c.png b/guides/images/noob_dashboard_3c.png new file mode 100644 index 0000000000..0ea15b818d Binary files /dev/null and b/guides/images/noob_dashboard_3c.png differ diff --git a/guides/images/noob_dashboard_3d.gif b/guides/images/noob_dashboard_3d.gif new file mode 100644 index 0000000000..daeabecaa9 Binary files /dev/null and b/guides/images/noob_dashboard_3d.gif differ diff --git a/guides/images/noob_dashboard_3d.png b/guides/images/noob_dashboard_3d.png new file mode 100644 index 0000000000..81fe6e1851 Binary files /dev/null and b/guides/images/noob_dashboard_3d.png differ diff --git a/guides/images/noob_dashboard_3e.png b/guides/images/noob_dashboard_3e.png new file mode 100644 index 0000000000..8d48ca1cb6 Binary files /dev/null and b/guides/images/noob_dashboard_3e.png differ diff --git a/guides/images/noob_dashboard_3f.png b/guides/images/noob_dashboard_3f.png new file mode 100644 index 0000000000..1bc95a9362 Binary files /dev/null and b/guides/images/noob_dashboard_3f.png differ diff --git a/guides/images/noob_dashboard_3g.png b/guides/images/noob_dashboard_3g.png new file mode 100644 index 0000000000..73b2dae80f Binary files /dev/null and b/guides/images/noob_dashboard_3g.png differ diff --git a/guides/images/noob_dashboard_4a.png b/guides/images/noob_dashboard_4a.png new file mode 100644 index 0000000000..88c4210dc6 Binary files /dev/null and b/guides/images/noob_dashboard_4a.png differ diff --git a/guides/images/noob_dashboard_4b.png b/guides/images/noob_dashboard_4b.png new file mode 100644 index 0000000000..97a6d5b228 Binary files /dev/null and b/guides/images/noob_dashboard_4b.png differ diff --git a/guides/images/noob_dashboard_4c.png b/guides/images/noob_dashboard_4c.png new file mode 100644 index 0000000000..756a92597b Binary files /dev/null and b/guides/images/noob_dashboard_4c.png differ diff --git a/guides/images/noob_dashboard_4d.png b/guides/images/noob_dashboard_4d.png new file mode 100644 index 0000000000..75bee3b1fd Binary files /dev/null and b/guides/images/noob_dashboard_4d.png differ diff --git a/guides/images/noob_dashboard_4e.png b/guides/images/noob_dashboard_4e.png new file mode 100644 index 0000000000..95a1114be7 Binary files /dev/null and b/guides/images/noob_dashboard_4e.png differ diff --git a/guides/images/noob_docker_1.png b/guides/images/noob_docker_1.png new file mode 100644 index 0000000000..a1ba2a9941 Binary files /dev/null and b/guides/images/noob_docker_1.png differ diff --git a/guides/images/noob_docker_2.png b/guides/images/noob_docker_2.png new file mode 100644 index 0000000000..ae9eb6746c Binary files /dev/null and b/guides/images/noob_docker_2.png differ diff --git a/guides/images/noob_docker_3.png b/guides/images/noob_docker_3.png new file mode 100644 index 0000000000..e659db2a45 Binary files /dev/null and b/guides/images/noob_docker_3.png differ diff --git a/guides/images/noob_docker_4.png b/guides/images/noob_docker_4.png new file mode 100644 index 0000000000..7814fa81d1 Binary files /dev/null and b/guides/images/noob_docker_4.png differ diff --git a/guides/images/noob_docker_4b.png b/guides/images/noob_docker_4b.png new file mode 100644 index 0000000000..e9e6e33907 Binary files /dev/null and b/guides/images/noob_docker_4b.png differ diff --git a/guides/images/noob_docker_5.png b/guides/images/noob_docker_5.png new file mode 100644 index 0000000000..4cd4f9d628 Binary files /dev/null and b/guides/images/noob_docker_5.png differ diff --git a/guides/images/noob_docker_6.png b/guides/images/noob_docker_6.png new file mode 100644 index 0000000000..4099daa8d1 Binary files /dev/null and b/guides/images/noob_docker_6.png differ diff --git a/guides/images/noob_docker_7.png b/guides/images/noob_docker_7.png new file mode 100644 index 0000000000..f9bdec124e Binary files /dev/null and b/guides/images/noob_docker_7.png differ diff --git a/guides/images/noob_docker_8.png b/guides/images/noob_docker_8.png new file mode 100644 index 0000000000..c814f884d3 Binary files /dev/null and b/guides/images/noob_docker_8.png differ diff --git a/guides/images/noob_docker_9.png b/guides/images/noob_docker_9.png new file mode 100644 index 0000000000..bb333282f2 Binary files /dev/null and b/guides/images/noob_docker_9.png differ diff --git a/guides/images/noob_docker_9b.png b/guides/images/noob_docker_9b.png new file mode 100644 index 0000000000..86a10e75f7 Binary files /dev/null and b/guides/images/noob_docker_9b.png differ diff --git a/images/docker-mark-blue.svg b/images/docker-mark-blue.svg new file mode 100644 index 0000000000..eba6cc41e6 --- /dev/null +++ b/images/docker-mark-blue.svg @@ -0,0 +1,12 @@ + + + + + + + \ No newline at end of file diff --git a/index.rst b/index.rst index 425fcd9070..1f22ee75ec 100644 --- a/index.rst +++ b/index.rst @@ -35,8 +35,8 @@ or MQTT.
  • - - using the command line + + adding devices (for beginners)
  • diff --git a/svg2png/docker-mark-blue.png b/svg2png/docker-mark-blue.png new file mode 100644 index 0000000000..fc9e3c193b Binary files /dev/null and b/svg2png/docker-mark-blue.png differ