esphome-docs/guides/getting_started_command_line.rst

189 lines
6.7 KiB
ReStructuredText
Raw Normal View History

2019-02-16 23:25:23 +01:00
Getting Started with ESPHome
============================
2018-05-13 11:37:02 +02:00
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Getting Started guide for installing ESPHome using the command line and creating a basic configuration.
:image: console.png
2018-11-14 22:12:27 +01:00
2019-02-16 23:25:23 +01:00
ESPHome is the perfect solution for creating custom firmwares for
2018-05-13 11:37:02 +02:00
your ESP8266/ESP32 boards. In this guide well go through how to setup a
basic “node” in a few simple steps.
Installation
2018-10-12 16:33:22 +02:00
------------
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
Installing ESPHome is very easy. All you need to do is have `Python
2018-05-13 11:37:02 +02:00
2.7 <https://www.python.org/download/releases/2.7/>`__ installed
(because of platformio 😕) and install the console script script through
``pip``.
.. code-block:: bash
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
pip install esphome
2018-05-13 11:37:02 +02:00
Alternatively, theres also a docker image available for easy
installation (the docker hub image is only available for amd64 right now; if you have
2019-02-16 23:25:23 +01:00
an RPi, please install ESPHome through ``pip`` or use :doc:`the Hass.io add-on <getting_started_hassio>`:
2018-05-13 11:37:02 +02:00
.. code-block:: bash
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
docker pull esphome/esphome
2018-05-13 11:37:02 +02:00
Creating A Project
2018-10-12 16:33:22 +02:00
------------------
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
Now lets setup a configuration file. Fortunately, ESPHome has a
2018-05-13 11:37:02 +02:00
friendly setup wizard that will guide you through creating your first
configuration file. For example, if you want to create a configuration
file called ``livingroom.yaml``:
.. code-block:: bash
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
esphome livingroom.yaml wizard
2018-05-13 11:37:02 +02:00
# On Docker:
2019-02-16 23:25:23 +01:00
docker run --rm -v "${PWD}":/config -it esphome/esphome livingroom.yaml wizard
2018-06-01 18:10:00 +02:00
2018-05-13 11:37:02 +02:00
At the end of this step, you will have your first YAML configuration
2018-06-01 18:10:00 +02:00
file ready. It doesn't do much yet and only makes your device connect to
2019-02-16 23:25:23 +01:00
the WiFi network, but still its a first step.
2018-05-13 11:37:02 +02:00
Adding some features
2018-10-12 16:33:22 +02:00
--------------------
2018-05-13 11:37:02 +02:00
So now you should have a file called ``livingroom.yaml`` (or similar).
2018-06-01 18:10:00 +02:00
Go open that file in an editor of your choice and lets add a :doc:`simple
GPIO switch </components/switch/gpio>` to our app.
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
switch:
- platform: gpio
2018-10-20 15:10:26 +02:00
name: "Living Room Dehumidifier"
2018-05-13 11:37:02 +02:00
pin: 5
The configuration format should hopefully immediately seem similar to
2019-02-16 23:25:23 +01:00
you. ESPHome has tried to keep it as close to Home Assistants
``configuration.yaml`` schema as possible. In the above example, were
simply adding a switch thats called “Living Room Dehumidifier” (could control
2018-05-13 11:37:02 +02:00
anything really, for example lights) and is connected to pin ``GPIO5``.
2019-02-16 23:25:23 +01:00
The nice thing about ESPHome is that it will automatically also try
to translate pin numbers for you based on the board. For example in the
2018-05-13 11:37:02 +02:00
above configuration, if using a NodeMCU board, you could have just as
well set ``D1`` as the ``pin:`` option.
First Uploading
2018-10-12 16:33:22 +02:00
---------------
2018-05-13 11:37:02 +02:00
Now you can go ahead and add some more components. Once you feel like
you have something you want to upload to your ESP board, simply plug in
the device via USB and type the following command (replacing
``livingroom.yaml`` with your configuration file):
.. code-block:: bash
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
esphome livingroom.yaml run
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
You should see ESPHome validating the configuration and telling you
about potential problems. Then ESPHome will proceed to compile and
upload the custom firmware. You will also see that ESPHome created a
2018-05-13 11:37:02 +02:00
new folder with the name of your node. This is a new platformio project
that you can modify afterwards and play around with.
If you are running docker on Linux you can add ``--device=/dev/ttyUSB0``
to your docker command to map a local USB device.
2018-05-13 11:37:02 +02:00
.. code-block:: bash
2018-05-13 11:37:02 +02:00
2019-03-24 16:34:41 +01:00
docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome livingroom.yaml run
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
Now when you go to the Home Assistant "Integrations" screen (under "Configuration" panel), you
should see the ESPHome device show up in the discovered section (can take up to 5 minutes).
Alternatively, you can manually add the device by clicking "CONFIGURE" on the ESPHome integration
and entering "<NODE_NAME>.local" as the host.
2018-05-13 11:37:02 +02:00
.. figure:: /components/switch/images/gpio-ui.png
2018-06-01 18:10:00 +02:00
:align: center
2018-05-13 11:37:02 +02:00
After the first upload, you will probably never need to use the USB
2019-02-16 23:25:23 +01:00
cable again, as all features of ESPHome are enabled remotely as well.
2018-05-13 11:37:02 +02:00
No more opening hidden boxes stowed in places hard to reach. Yay!
Adding A Binary Sensor
2018-10-12 16:33:22 +02:00
----------------------
2018-05-13 11:37:02 +02:00
Next, were going to add a very simple binary sensor that periodically
2018-06-01 18:10:00 +02:00
checks a GPIO pin whether its pulled high or low - the :doc:`GPIO Binary
Sensor </components/binary_sensor/gpio>`.
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
binary_sensor:
- platform: gpio
name: "Living Room Window"
pin:
number: 16
inverted: True
mode: INPUT_PULLUP
2019-02-16 23:25:23 +01:00
This is an advanced feature of ESPHome. Almost all pins can
2018-05-13 11:37:02 +02:00
optionally have a more complicated configuration schema with options for
2018-06-01 18:10:00 +02:00
inversion and pinMode - the :ref:`Pin Schema <config-pin_schema>`.
2018-05-13 11:37:02 +02:00
This time when uploading, you dont need to have the device plugged in
through USB again. The upload will magically happen “over the air”.
2019-02-16 23:25:23 +01:00
Using ESPHome directly, this is the same as from a USB cable, but
2018-05-13 11:37:02 +02:00
for docker you need to supply an additional parameter:
.. code-block:: bash
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
esphome livingroom.yaml run
2018-05-13 11:37:02 +02:00
# On docker
2019-02-16 23:25:23 +01:00
docker run --rm -v "${PWD}":/config -it esphome/esphome livingroom.yaml run
2018-05-13 11:37:02 +02:00
.. figure:: /components/binary_sensor/images/gpio-ui.png
2018-05-13 11:37:02 +02:00
Where To Go Next
2018-10-12 16:33:22 +02:00
----------------
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
Great 🎉! Youve now successfully setup your first ESPHome project
and uploaded your first ESPHome custom firmware to your node. Youve
2018-05-13 11:37:02 +02:00
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 youll find all sensors/outputs/… youll need in there. If youre having any problems or
2018-05-13 11:37:02 +02:00
want new features, please either create a new issue on the `GitHub issue
2019-02-16 23:25:23 +01:00
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>`).
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
Bonus: ESPHome dashboard
------------------------
2018-06-01 18:10:00 +02:00
2019-02-16 23:25:23 +01:00
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 Hass.io add-on <getting_started_hassio>`, but also works with a simple command on
2019-02-16 23:33:36 +01:00
\*nix machines (sorry, no windows).
2018-06-01 18:10:00 +02:00
2019-02-16 23:25:23 +01:00
To start the ESPHome dashboard, simply start ESPHome with the following command
2018-06-01 18:10:00 +02:00
(with ``config/`` pointing to a directory where you want to store your configurations)
.. code-block:: bash
2018-06-01 18:10:00 +02:00
# Install dashboard dependencies
pip2 install tornado esptool
2019-02-16 23:25:23 +01:00
esphome config/ dashboard
2018-06-01 18:10:00 +02:00
2019-02-16 23:25:23 +01:00
# On docker, host networking mode is required for online status indicators
docker run --rm --net=host -v "${PWD}":/config -it esphome/esphome
2018-06-01 18:10:00 +02:00
After that, you will be able to access the dashboard through ``localhost:6052``.
.. figure:: images/dashboard.png
See Also
2018-10-12 16:33:22 +02:00
--------
2018-05-13 11:37:02 +02:00
- :doc:`ESPHome index </index>`
2018-06-01 18:10:00 +02:00
- :doc:`getting_started_hassio`
- :ghedit:`Edit`