Getting Started with the ESPHome Command Line

Edit this page on GitHub

Getting Started with the ESPHome Command Line

ESPHome is the perfect solution for creating custom firmwares for your ESP8266/ESP32 boards. In this guide we’ll go through how to set up a basic “node” in a few simple steps.

Installation

See Installing ESPHome Manually.

If you’re familiar with Docker, you can use that instead! Note that on macOS Docker can not pass USB devices through. You will not be able to flash ESP devices through USB on Mac, all other features will work. Flashing with web dashboard is still possible.

Our image supports AMD64, ARM and ARM64 (AARCH64), and can be downloaded with:

docker pull ghcr.io/esphome/esphome

If you want to use docker-compose instead, here’s a sample file:

version: '3'
services:
  esphome:
    container_name: esphome
    image: ghcr.io/esphome/esphome
    volumes:
      - /path/to/esphome/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: always
    privileged: true
    network_mode: host
    environment:
      - USERNAME=test
      - PASSWORD=ChangeMe

ℹ️ Note

If you are using NFS share to back your container’s config volume, you may need to mount the volume with the nolock option, otherwise platformio may freeze on container startup as per platformIO-core Issue 3089

The project provides multiple docker tags; please pick the one that suits you better:

  • latest and stable point to the latest stable release available. It’s not recommended to automatically update the container based on those tags because of the possible breaking changes between releases.

  • Release-tracking tag YEAR.MONTH (e.g. 2022.8 ) points to the latest stable patch release available within the required version. There should never be a breaking change when upgrading the containers based on tags like that.

  • beta points to the latest released beta version, and to the latest stable release when there is no fresh beta release.

  • dev is the bleeding edge release; built daily based on the latest changes in the dev branch.

Connecting the ESP Device

Follow the instructions in Physically Connecting to your Device to connect to your ESP 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.

Creating a Project

Now let’s setup a configuration file. Fortunately, ESPHome has a 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 :

esphome wizard livingroom.yaml
# On Docker:
docker run --rm -v "${PWD}":/config -it ghcr.io/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 the WiFi network, but still it’s a first step.

Adding some features

So now you should have a file called livingroom.yaml (or similar). Go open that file in an editor of your choice and let’s add a simpleGPIO switch to our app.

switch:
  - platform: gpio
    name: "Living Room Dehumidifier"
    pin: GPIO5

The configuration format should hopefully immediately seem similar to you. ESPHome has tried to keep it as close to Home Assistant’s configuration.yaml schema as possible. In the 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 pin GPIO5. 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 above configuration, if using a NodeMCU board, you could have just as well set D1 as the pin: option.

First uploading

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):

esphome run livingroom.yaml

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 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. Docker on Mac will not be able to access host USB devices.

docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome run livingroom.yaml

ℹ️ Note

Alternatively, you can flash the binary using ESPHome Web or esptool.

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). Alternatively, you can manually add the device by clicking CONFIGURE on the ESPHome integration and entering <NODE_NAME>.local as the host.