Made for ESPHome
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.
What the Badge Promises
Section titled “What the Badge Promises”- 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.
Requirements
Section titled “Requirements”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.
Hardware
Section titled “Hardware”- 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.
Naming
Section titled “Naming”Your product name must not contain ESPHome, except when it ends with for ESPHome. “ESPHome Widget” is not acceptable; “Acme Widget for ESPHome” is.
Configuration
Section titled “Configuration”- 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
!secretreferences and no passwords, including thewifi_ssid/wifi_passwordpair. 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.
Wi-Fi Provisioning
Section titled “Wi-Fi Provisioning”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_bleprovisions credentials over Bluetooth LE.improv_serialdoes 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
Section titled “Taking Control”“Taking control” is a user adopting the device into their own ESPHome Device Builder and building ESPHome for it themselves. That requires:
dashboard_importwith apackage_import_urlpointing at your public configuration.- Project information (
esphome→project→nameandversion), which is what the Device Builder matches on when it offers to adopt the device. - The
apicomponent, which the adoption flow relies on. - The
esphomeOTA 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.
Signed Firmware
Section titled “Signed Firmware”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_verificationunderesp32:→framework:→advanced:. The review detects signed firmware from the published YAML. - The configuration has no other network OTA endpoint. The
web_serverOTA 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 needsimprov_serial. It must run on the USB serial connection (the logger’s port by default, or the UART given byuart_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_urlstill enables theesphomeOTA 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.
Updates
Section titled “Updates”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.
Example Configuration
Section titled “Example Configuration”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 flowapi:
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: GPIOXXSee Sharing ESPHome devices for a fuller walkthrough of these options.
Applying
Section titled “Applying”-
Publish your configuration in a public repository.
-
Add your device to devices.esphome.io by opening a pull request in the devices.esphome.io repository. Set
made-for-esphome: truein 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. -
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.
See Also
Section titled “See Also”- Sharing ESPHome devices - the configuration options behind adoption and provisioning
- Made for ESPHome devices - devices already approved
- Made for ESPHome checklist - the exact items we review against
- Adding Devices - how to write the device page