Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-04-14 20:13:36 +02:00
Code Issues Projects Releases Wiki Activity

CLI user experience improvements updated docs (#1183)

Browse Source
This commit is contained in:
Oxan van Leeuwen 2021-06-08 01:21:53 +02:00 committed by GitHub
parent 8effe590d1
commit de95a4d210
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 37 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
components/mqtt.rst
View File

@ -149,7 +149,7 @@ With Docker:
.. code-block:: bash
docker run --rm -v "${PWD}":/config -it esphome/esphome configuration.yaml clean-mqtt
docker run --rm -v "${PWD}":/config -it esphome/esphome clean-mqtt configuration.yaml
This will remove all retained messages with the topic
``<DISCOVERY_PREFIX>/+/NODE_NAME/#``. If you want to purge on another

55
guides/cli.rst
View File

@ -11,16 +11,16 @@ ESPHome's command line interface always has the following format
.. code-block:: console
esphome [OPTIONS] <CONFIGURATION...> <COMMAND> [ARGUMENTS]
esphome [OPTIONS] <COMMAND> <CONFIGURATION...> [ARGUMENTS]
.. note::
You can specify multiple configuration files in the command line interface,
just list all files in front of the <COMMAND> like so:
You can specify multiple configuration files in the command line interface for some commands,
just list all files after the <COMMAND> like so:
.. code-block:: console
esphome livingroom.yaml kitchen.yaml run
esphome run livingroom.yaml kitchen.yaml
``--help`` Option
--------------------
@ -61,7 +61,7 @@ Please see :ref:`command line substitutions <command-line-substitutions>` for de
``run`` Command
---------------
The ``esphome <CONFIG> run`` command is the most common command for ESPHome. It
The ``esphome run <CONFIG>`` command is the most common command for ESPHome. It
* Validates the configuration
* Compiles a firmware
@ -70,9 +70,10 @@ The ``esphome <CONFIG> run`` command is the most common command for ESPHome. It
.. program:: esphome run
.. option:: --upload-port UPLOAD_PORT
.. option:: --device UPLOAD_PORT
Manually specify the upload port/ip to use. For example ``/dev/cu.SLAB_USBtoUART``.
Manually specify the upload port/IP to use. For example ``/dev/cu.SLAB_USBtoUART``, or ``192.168.1.176``
to perform an OTA.
.. option:: --no-logs
@ -103,7 +104,7 @@ The ``esphome <CONFIG> run`` command is the most common command for ESPHome. It
.. program:: esphome config
The ``esphome <CONFIG> config`` validates the configuration and displays the validation result.
The ``esphome config <CONFIG>`` validates the configuration and displays the validation result.
``compile`` Command
@ -111,7 +112,7 @@ The ``esphome <CONFIG> config`` validates the configuration and displays the val
.. program:: esphome compile
The ``esphome <CONFIG> compile`` validates the configuration and compiles the firmware.
The ``esphome compile <CONFIG>`` validates the configuration and compiles the firmware.
.. option:: --only-generate
@ -122,11 +123,12 @@ The ``esphome <CONFIG> compile`` validates the configuration and compiles the fi
.. program:: esphome upload
The ``esphome <CONFIG> upload`` validates the configuration and uploads the most recent firmware build.
The ``esphome upload <CONFIG>`` validates the configuration and uploads the most recent firmware build.
.. option:: --upload-port UPLOAD_PORT
.. option:: --device UPLOAD_PORT
Manually specify the upload port/IP to use. For example ``/dev/cu.SLAB_USBtoUART``.
Manually specify the upload port/IP address to use. For example ``/dev/cu.SLAB_USBtoUART``, or ``192.168.1.176``
to perform an OTA.
.. option:: --host-port HOST_PORT
@ -137,7 +139,7 @@ The ``esphome <CONFIG> upload`` validates the configuration and uploads the most
.. program:: esphome clean-mqtt
The ``esphome <CONFIG> clean-mqtt`` cleans retained MQTT discovery messages from the MQTT broker.
The ``esphome clean-mqtt <CONFIG>`` cleans retained MQTT discovery messages from the MQTT broker.
See :ref:`mqtt-using_with_home_assistant`.
.. option:: --topic TOPIC
@ -162,14 +164,14 @@ See :ref:`mqtt-using_with_home_assistant`.
.. program:: esphome wizard
The ``esphome <CONFIG> wizard`` command starts the ESPHome configuration creation wizard.
The ``esphome wizard <CONFIG>`` command starts the ESPHome configuration creation wizard.
``mqtt-fingerprint`` Command
----------------------------
.. program:: esphome mqtt-fingerprint
The ``esphome <CONFIG> mqtt-fingerprint`` command shows the MQTT SSL fingerprints of the remote used
The ``esphome mqtt-fingerprint <CONFIG>`` command shows the MQTT SSL fingerprints of the remote used
for SSL MQTT connections. See :ref:`mqtt-ssl_fingerprints`.
``version`` Command
@ -177,30 +179,23 @@ for SSL MQTT connections. See :ref:`mqtt-ssl_fingerprints`.
.. program:: esphome version
The ``esphome <CONFIG> version`` command shows the current ESPHome version and exits.
The ``esphome version`` command shows the current ESPHome version and exits.
``clean`` Command
-----------------
.. program:: esphome clean
The ``esphome <CONFIG> clean`` command cleans all build files and can help with some build issues.
``hass-config`` Command
-----------------------
.. program:: esphome hass-config
The ``esphome <CONFIG> hass-config`` command shows an auto-generated Home Assistant configuration for the ESPHome
node configuration file. This is useful if you're not using MQTT discovery.
The ``esphome clean <CONFIG>`` command cleans all build files and can help with some build issues.
``dashboard`` Command
---------------------
.. program:: esphome dashboard
The ``esphome <CONFIG> dashboard`` command starts the ESPHome dashboard server for using ESPHome
through a graphical user interface.
The ``esphome dashboard <CONFIG>`` command starts the ESPHome dashboard server for using ESPHome
through a graphical user interface. This command accepts a configuration directory instead of a
single configuration file.
.. option:: --port PORT
@ -223,7 +218,7 @@ through a graphical user interface.
.. program:: esphome logs
The ``esphome <CONFIG> logs`` command validates the configuration and shows all logs.
The ``esphome logs <CONFIG>`` command validates the configuration and shows all logs.
.. option:: --topic TOPIC
@ -241,7 +236,7 @@ The ``esphome <CONFIG> logs`` command validates the configuration and shows all
Manually set the client id.
.. option:: --serial-port SERIAL_PORT
.. option:: --device SERIAL_PORT
Manually specify a serial port to use. For example ``/dev/cu.SLAB_USBtoUART``.
Manually specify a serial port/IP to use. For example ``/dev/cu.SLAB_USBtoUART``.

12
guides/faq.rst
View File

@ -19,13 +19,13 @@ Tips for using ESPHome
.. code-block:: bash
esphome livingroom.yaml config
esphome config livingroom.yaml
3. To view the logs from your node without uploading, run
.. code-block:: bash
esphome livingroom.yaml logs
esphome logs livingroom.yaml
4. You can always find the source ESPHome generates under ``<NODE_NAME>/src/``.
@ -142,7 +142,7 @@ by installing the tested beta:
pip3 install --pre -U esphome
# For docker-based installs
docker run [...] -it esphome/esphome:beta livingroom.yaml run
docker run [...] -it esphome/esphome:beta run livingroom.yaml
For Home Assistant supervised installs add the community addons beta repository by
adding
@ -259,13 +259,13 @@ Command reference:
.. code-block:: bash
# Start a new file wizard for file livingroom.yaml
docker run --rm -v "${PWD}":/config -it esphome/esphome livingroom.yaml wizard
docker run --rm -v "${PWD}":/config -it esphome/esphome wizard livingroom.yaml
# Compile and upload livingroom.yaml
docker run --rm -v "${PWD}":/config -it esphome/esphome livingroom.yaml run
docker run --rm -v "${PWD}":/config -it esphome/esphome run livingroom.yaml
# View logs
docker run --rm -v "${PWD}":/config -it esphome/esphome livingroom.yaml logs
docker run --rm -v "${PWD}":/config -it esphome/esphome logs livingroom.yaml
# Map /dev/ttyUSB0 into container
docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome ...

10
guides/getting_started_command_line.rst
View File

@ -40,7 +40,7 @@ file called ``livingroom.yaml``:
esphome livingroom.yaml wizard
# On Docker:
docker run --rm -v "${PWD}":/config -it esphome/esphome livingroom.yaml wizard
docker run --rm -v "${PWD}":/config -it esphome/esphome wizard livingroom.yaml
At the end of this step, you will have your first YAML configuration
file ready. It doesn't do much yet and only makes your device connect to
@ -80,7 +80,7 @@ the device via USB and type the following command (replacing
.. code-block:: bash
esphome livingroom.yaml run
esphome run livingroom.yaml
You should see ESPHome validating the configuration and telling you
about potential problems. Then ESPHome will proceed to compile and
@ -93,7 +93,7 @@ to your docker command to map a local USB device.
.. code-block:: bash
docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome livingroom.yaml run
docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome run livingroom.yaml
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 (although this can take up to 5 minutes).
@ -137,7 +137,7 @@ for docker you need to supply an additional parameter:
esphome livingroom.yaml run
# On docker
docker run --rm -v "${PWD}":/config -it esphome/esphome livingroom.yaml run
docker run --rm -v "${PWD}":/config -it esphome/esphome run livingroom.yaml
.. figure:: /components/binary_sensor/images/gpio-ui.png
@ -170,7 +170,7 @@ To start the ESPHome dashboard, simply start ESPHome with the following command
# Install dashboard dependencies
pip install tornado esptool
esphome config/ dashboard
esphome dashboard config/
# On Docker, host networking mode is required for online status indicators
docker run --rm --net=host -v "${PWD}":/config -it esphome/esphome