Sharing ESPHome devices

We have added configuration options to ESPHome to make it easier to create, configure, install and distribute devices running ESPHome.

No part of a “template” configuration should have any references to secrets, or have passwords pre-applied. ESPHome makes it easy for the end-user to add these themselves after they adopt the device into their own ESPHome dashboard.

Example configuration

# These substitutions allow the end user to override certain values
  name: "project-template"
  friendly_name: "Project Template"

  name: "${name}"
  # Friendly names are used where appropriate in Home Assistant
  friendly_name: "${friendly_name}"
  # Automatically add the mac address to the name
  # so you can use a single firmware for all devices
  name_add_mac_suffix: true

  # This will allow for (future) project identification,
  # configuration and updates.
    name: esphome.project-template
    version: "1.0"

# To be able to get logs from the device via serial and api.

# API is a requirement of the dashboard import.

# OTA is required for Over-the-Air updating
  platform: esphome

# This should point to the public location of this yaml file.
  package_import_url: github://esphome/esphome-project-template/project-template-esp32.yaml@v6
  import_full_config: false # or true

  # Set up a wifi access point
    password: "12345678"

# In combination with the `ap` this allows the user
# to provision wifi credentials to the device.

# Sets up Bluetooth LE (Only on ESP32) to allow the user
# to provision wifi credentials to the device.
  authorizer: none

# Sets up the improv via serial client for Wi-Fi provisioning

Relevant Documentation

  • name_add_mac_suffix - Adding the MAC address as a suffix to the device name

  • project - Project information

  • esp32_improv - Improv via BLE

  • captive_portal - Captive Portal

  • wifi -> ap allows you to flash a device that will not contain any credentials and they must be set by the user via either the ap + captive_portal or the esp32_improv / improv_serial components.

  • dashboard_import


    The Project information above is required for adoption to work in the Dashboard.

    • package_import_url - This should point to the public repository containing the configuration for the device so that the user’s ESPHome dashboard can autodetect this device and create a minimal YAML using Remote/git Packages.

    • import_full_config - This signals if ESPHome should download the entire YAML file as the user’s config YAML instead of referencing the package. Set this to true if you are creating a tutorial to let users easily tweak the whole configuration or be able to uncomment follow-up tutorial steps.

  • improv_serial - Improv via Serial

See Also