Sharing ESPHome devices

Edit this page on GitHub

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
substitutions:
  name: "project-template"
  friendly_name: "Project Template"

esphome:
  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.
  project:
    name: esphome.project-template
    version: "1.0"

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

# API is a requirement of the dashboard import.
api:

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

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

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

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

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

# Sets up the improv via serial client for Wi-Fi provisioning
improv_serial:
  next_url: https://example.com/project-template/manual?ip={{ip_address}}&name={{device_name}}&version={{esphome_version}}

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

    ℹ️ Note

    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

Sharing ESPHome devices

Edit this page on GitHub