Skip to content
Get started

Made for ESPHome

Made for ESPHome badge

Made for ESPHome is our stamp of approval for hardware that ships with ESPHome. It tells a buyer three things before they hand over any money: the device runs ESPHome out of the box, its configuration is public, and they can take full control of it whenever they like without opening the case or soldering anything.

Approved devices are listed on devices.esphome.io/made-for-esphome and may carry the logo on the product and its packaging.

  • It runs ESPHome. Not a fork, not a lookalike, and not a cloud service with an ESPHome-compatible mode.
  • The configuration is public. Anyone can read the YAML that builds what ships on the device before buying it.
  • The user can take control. ESPHome Device Builder adopts the device, and the configuration builds and runs unmodified, so nothing breaks the moment ownership changes hands.
  • Updates keep working. The manufacturer ships updates, and the user can push their own builds over the air.

The canonical list is the Made for ESPHome checklist in the devices repository, which is added to your pull request automatically. The sections below explain what each item means and why it is there.

  • The device uses an ESP32 or a supported ESP32 variant such as the C3, C6, S2 or S3. ESP8266 is not eligible.
  • The device ships with ESPHome already installed.

Your product name must not contain ESPHome, except when it ends with for ESPHome. “ESPHome Widget” is not acceptable; “Acme Widget for ESPHome” is.

  • The configuration is open source and published somewhere the public can read it, such as a GitHub repository.
  • Every entity and component (sensor, switch, i2c bus, output, and so on) has an id. Users need those ids to Extend or Remove parts of your configuration when they take control.
  • The configuration you ship contains no !secret references and no passwords, including the wifi_ssid / wifi_password pair. Users provision their own Wi-Fi credentials, so anything baked in only leaves dummy credentials sitting in the device’s storage. Those secrets belong in the configuration a user ends up with after adopting the device, not in what you ship.
  • Network configuration assumes defaults: no static IP addresses (manual_ip) and no hard-coded DNS servers.
  • The configuration is valid, builds and runs without any user changes after adoption. Remote packages are permitted as long as this still holds.

Devices always arrive with no Wi-Fi credentials, so the user needs a way to supply them without a computer or a configuration file:

  • improv_ble provisions credentials over Bluetooth LE.
  • improv_serial does the same over USB, and is required if the device exposes a USB port.

Improv is required whenever wifi: appears in the configuration. That includes devices with wired Ethernet, since Ethernet and Wi-Fi can be configured together with automatic fallback between them. Only a configuration with no wifi: block at all is exempt.

“Taking control” is a user adopting the device into their own ESPHome Device Builder and building ESPHome for it themselves. That requires:

  • dashboard_import with a package_import_url pointing at your public configuration.
  • Project information (esphome → project → name and version), which is what the Device Builder matches on when it offers to adopt the device.
  • The api component, which the adoption flow relies on.
  • The esphome OTA platform, so the user can install their own builds over the air. The only exception is signed firmware.
  • Serial flashing left enabled, as the escape hatch when everything else fails.

A device that ships with signed firmware and has no network OTA endpoint may leave the esphome OTA platform out of the configuration it ships. The device accepts no firmware uploads over the network, so a user who takes control installs their first build over USB. Manufacturer updates still use the http_request update platform and are signed. Every one of these must hold:

  • The configuration enables signed_ota_verification under esp32: → framework: → advanced:. The review detects signed firmware from the published YAML.
  • The configuration has no other network OTA endpoint. The web_server OTA platform does not qualify for this exception.
  • The configuration contains improv_serial. A device without network OTA is flashed over USB, so it has a USB port, and a device with a USB port needs improv_serial. It must run on the USB serial connection (the logger’s port by default, or the UART given by uart_id), so that a user can provision the device through the USB port. It does not control flashing.
  • The device can be flashed over USB without any keys and without opening the case. A human reviewer confirms this, as it cannot be read from the configuration.
  • The package at package_import_url still enables the esphome OTA platform, so a user who takes control can update the device over the network. The automated review checks this.

NOTE

The esphome OTA platform alone does not let a user install their own builds if the imported package still enables signed_ota_verification, because the device rejects any update that is not signed with a key it trusts. We suggest the package contains no signing configuration at all. The user then installs their first build over USB, and after that nothing needs signing. Remove enable_ota_downgrade_protection as well, as it requires signed_ota_verification. See Signed OTA Verification.

Without signature checks, anyone who can reach the device can upload firmware through any unprotected endpoint. Point users to the OTA encryption option of the esphome OTA platform, which we recommend over a password, so they can set it in their own configuration before the first flash. The Web Server and Captive Portal can also accept firmware uploads, so users should disable or separately secure them in the adopted configuration.

Ship updates to devices you have sold using the http_request update platform, which needs http_request and the http_request OTA platform alongside it.

The source URL must point at a publicly reachable JSON manifest whose builds include a chipFamily matching your hardware and an ota.path that resolves to a downloadable binary. Our review tooling fetches the manifest and the binary, so a dead link or a chip family mismatch will fail the review.

The review installs the latest stable ESPHome. If your configuration sets esphome: → min_version higher than that, the review upgrades to the stable release or the newest beta that satisfies it.

The pieces every Made for ESPHome configuration needs:

esphome:
name: "acme-widget"
friendly_name: "Acme Widget"
# One build works for every unit
name_add_mac_suffix: true
project:
name: acme.widget
version: "1.0"
esp32:
variant: esp32c3
# Required by the adoption flow
api:
ota:
- platform: esphome
id: ota_esphome
- platform: http_request
id: ota_http_request
http_request:
id: http_request_id
update:
- platform: http_request
id: update_http_request
name: "ESPHome update"
source: https://acme.example.com/widget/manifest.json
wifi:
ap:
improv_ble:
authorizer: none
logger:
improv_serial:
dashboard_import:
package_import_url: github://acme/acme-widget/widget.yaml@main
switch:
- platform: gpio
id: relay
name: "Relay"
pin: GPIOXX

See Sharing ESPHome devices for a fuller walkthrough of these options.

  1. Publish your configuration in a public repository.

  2. Add your device to devices.esphome.io by opening a pull request in the devices.esphome.io repository. Set made-for-esphome: true in the page’s front matter, and reference your configuration with a live ```yaml url=… fence pointing at the YAML file in your repository, so the page always shows what actually ships. The Adding Devices guide covers the page format.

  3. Email esphome@openhomefoundation.org to apply for permission to carry the logo, and include a link to the pull request so we can tie your application to it.

Opening the pull request labels it made-for-esphome and made-for-esphome-pending, appends the checklist to the description for you to complete, and runs an automated review that downloads your configuration, builds it and posts the results as a comment. Work through anything it reports before asking for a human review.

If something does not meet the requirements we will ask for changes on the pull request. Once your submission is accepted we apply the made-for-esphome-approved label and merge the pull request. Either of those is your confirmation that the device is in the program, so there is no need to wait for a reply to your email. Your device then appears in the Made for ESPHome listing, and you may use the logos.

After your project is approved, you may use these logos on your product and/or its packaging.

Made for ESPHome badge - black on white

Black on white (svg, png)

Made for ESPHome badge - white on black

White on black (svg, png)

Made for ESPHome badge - black on transparent

Black on transparent (svg, png)

Made for ESPHome badge - white on transparent

White on transparent (svg, png)