Full Code of esphome/home-assistant-addon for AI

Repository: esphome/home-assistant-addon
Branch: main
Commit: e820a141ff0b
Files: 40
Total size: 60.9 KB

Directory structure:
gitextract_172dazq8/

├── .devcontainer/
│   ├── Dockerfile
│   └── devcontainer.json
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   └── config.yml
│   ├── dependabot.yml
│   └── workflows/
│       ├── bump-version.yml
│       ├── devcontainer-build.yaml
│       └── lint.yml
├── .gitignore
├── .vscode/
│   └── tasks.json
├── README.md
├── esphome/
│   ├── CHANGELOG.md
│   ├── DOCS.md
│   ├── FILES ARE GENERATED DO NOT EDIT
│   ├── README.md
│   ├── config.yaml
│   └── translations/
│       └── en.yaml
├── esphome-beta/
│   ├── CHANGELOG.md
│   ├── DOCS.md
│   ├── FILES ARE GENERATED DO NOT EDIT
│   ├── README.md
│   ├── config.yaml
│   └── translations/
│       └── en.yaml
├── esphome-dev/
│   ├── CHANGELOG.md
│   ├── DOCS.md
│   ├── FILES ARE GENERATED DO NOT EDIT
│   ├── README.md
│   ├── config.yaml
│   └── translations/
│       └── en.yaml
├── repository.json
├── script/
│   ├── NOTES.md
│   ├── bump-version.py
│   ├── generate.py
│   └── requirements.txt
└── template/
    ├── DOCS.md
    ├── README.md
    ├── addon_config.yaml
    ├── beta/
    │   └── README.md
    ├── dev/
    │   ├── DOCS.md
    │   └── README.md
    └── translations/
        └── en.yaml

================================================
FILE CONTENTS
================================================

================================================
FILE: .devcontainer/Dockerfile
================================================
FROM ghcr.io/home-assistant/devcontainer:apps

RUN \
  apt-get update \
  && apt-get install -y --no-install-recommends \
    python3-pip \
    python3-venv

ENV VIRTUAL_ENV=/opt/venv
RUN python3 -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

COPY script/requirements.txt /

RUN pip install -r /requirements.txt


================================================
FILE: .devcontainer/devcontainer.json
================================================
{
  "name": "ESPHome Home Assistant App devcontainer",
  "image": "ghcr.io/esphome/devcontainer:addons",
  "appPort": [
    "7123:8123",
    "7357:4357"
  ],
  "postStartCommand": "bash devcontainer_bootstrap",
  "runArgs": [
    "-e",
    "GIT_EDITOR=code --wait",
    "--privileged"
  ],
  "containerEnv": {
    "WORKSPACE_DIRECTORY": "${containerWorkspaceFolder}"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "timonwong.shellcheck",
        "esbenp.prettier-vscode",
        "ms-python.python"
      ],
      "mounts": [
        "type=volume,target=/var/lib/docker"
      ],
      "settings": {
        "terminal.integrated.profiles.linux": {
          "zsh": {
            "path": "/usr/bin/zsh"
          }
        },
        "terminal.integrated.defaultProfile.linux": "zsh",
        "editor.formatOnPaste": false,
        "editor.formatOnSave": true,
        "editor.formatOnType": true,
        "files.trimTrailingWhitespace": true
      }
    }
  }
}


================================================
FILE: .github/ISSUE_TEMPLATE/config.yml
================================================
blank_issues_enabled: false
contact_links:
  - name: Report an issue with ESPHome
    url: https://github.com/esphome/esphome/issues/new/choose
    about: Report an issue with ESPHome.
  - name: Report an issue with the ESPHome documentation
    url: https://github.com/esphome/esphome-docs/issues/new/choose
    about: Report an issue with the ESPHome documentation.
  - name: Report an issue with the ESPHome web server
    url: https://github.com/esphome/esphome-webserver/issues/new/choose
    about: Report an issue with the ESPHome web server.
  - name: Report an issue with the ESPHome Builder / Dashboard
    url: https://github.com/esphome/dashboard/issues/new/choose
    about: Report an issue with the ESPHome Builder / Dashboard.
  - name: Report an issue with the ESPHome API client
    url: https://github.com/esphome/aioesphomeapi/issues/new/choose
    about: Report an issue with the ESPHome API client.
  - name: Make a Feature Request
    url: https://github.com/orgs/esphome/discussions
    about: Please create feature requests in the dedicated feature request tracker.
  - name: Frequently Asked Question
    url: https://esphome.io/guides/faq.html
    about: Please view the FAQ for common questions and what to include in a bug report.


================================================
FILE: .github/dependabot.yml
================================================
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: daily
    open-pull-requests-limit: 10


================================================
FILE: .github/workflows/bump-version.yml
================================================
name: Publish Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: The version to release
        required: true

permissions:
  contents: read  # actions/checkout only; commits + release writes use the App token

jobs:
  create-release:
    name: Create release
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
          # contents: write covers both GraphQL createCommitOnBranch and
          # ``gh release create`` (which creates the release + lightweight tag).
          permission-contents: write

      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.11"

      - name: Install Python dependencies
        run: pip install -r script/requirements.txt

      - name: Bump version
        run: script/bump-version.py ${{ github.event.inputs.version }}

      - name: Extract major version
        id: extract_version
        run: |
          # Extract major version (e.g., 2025.6.0 from 2025.6.2 or 2025.6.0b3)
          MAJOR_VERSION=$(echo "${{ github.event.inputs.version }}" | sed -E 's/^([0-9]+\.[0-9]+)\.[0-9]+.*/\1.0/')
          echo "major_version=${MAJOR_VERSION}" >> $GITHUB_OUTPUT

      - name: Fetch release body
        # Stored in $RUNNER_TEMP so ``git status --porcelain`` in the commit
        # step doesn't pick it up. Consumed by the changelog writes and the
        # ``Create a Release`` step.
        if: ${{ !contains(github.event.inputs.version, 'dev') }}
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          VERSION: ${{ github.event.inputs.version }}
        run: |
          gh release view "$VERSION" \
            --repo esphome/esphome \
            --json body \
            --jq .body \
            > "$RUNNER_TEMP/release_body.md"

      - name: Write Beta changelog
        if: ${{ !contains(github.event.inputs.version, 'dev') }}
        env:
          VERSION: ${{ github.event.inputs.version }}
          MAJOR: ${{ steps.extract_version.outputs.major_version }}
        run: |
          {
            printf '## %s\n\n[**Read release announcement**](https://beta.esphome.io/changelog/%s)\n\n' "$VERSION" "$MAJOR"
            cat "$RUNNER_TEMP/release_body.md"
          } > esphome-beta/CHANGELOG.md

      - name: Write Stable changelog
        if: ${{ !contains(github.event.inputs.version, 'b') && !contains(github.event.inputs.version, 'dev')  }}
        env:
          VERSION: ${{ github.event.inputs.version }}
          MAJOR: ${{ steps.extract_version.outputs.major_version }}
        run: |
          {
            printf '## %s\n\n[**Read release announcement**](https://esphome.io/changelog/%s)\n\n' "$VERSION" "$MAJOR"
            cat "$RUNNER_TEMP/release_body.md"
          } > esphome/CHANGELOG.md

      - name: Commit version bump
        id: commit
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          VERSION: ${{ github.event.inputs.version }}
        with:
          github-token: ${{ steps.generate-token.outputs.token }}
          script: |
            const fs = require('fs');
            const { execSync } = require('child_process');

            // bump-version.py + the changelog writes only touch files with
            // simple ASCII names, so the default porcelain format (no -z)
            // is sufficient.
            const lines = execSync('git status --porcelain', { encoding: 'utf8' })
              .split('\n')
              .filter(line => line.length > 0);

            const additions = [];
            const deletions = [];
            for (const line of lines) {
              const status = line.substring(0, 2);
              const path = line.substring(3);
              if (status.includes('D')) {
                deletions.push({ path });
              } else {
                additions.push({
                  path,
                  contents: fs.readFileSync(path).toString('base64'),
                });
              }
            }

            if (additions.length === 0 && deletions.length === 0) {
              core.setFailed('No file changes to commit');
              return;
            }

            const headOid = execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
            const repo = context.payload.repository;

            const result = await github.graphql(
              `mutation($input: CreateCommitOnBranchInput!) {
                createCommitOnBranch(input: $input) {
                  commit { oid }
                }
              }`,
              {
                input: {
                  branch: {
                    repositoryNameWithOwner: repo.full_name,
                    branchName: repo.default_branch,
                  },
                  message: { headline: `Bump version to ${process.env.VERSION}` },
                  fileChanges: { additions, deletions },
                  expectedHeadOid: headOid,
                },
              }
            );

            core.setOutput('sha', result.createCommitOnBranch.commit.oid);

      - name: Create a Release
        continue-on-error: true
        if: ${{ !contains(github.event.inputs.version, 'dev') }}
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          VERSION: ${{ github.event.inputs.version }}
          TARGET_SHA: ${{ steps.commit.outputs.sha }}
        run: |
          flags=()
          if [[ "$VERSION" == *b* ]]; then
            flags+=(--prerelease)
          fi

          gh release create "$VERSION" \
            --title "$VERSION" \
            --notes-file "$RUNNER_TEMP/release_body.md" \
            --target "$TARGET_SHA" \
            "${flags[@]}"


================================================
FILE: .github/workflows/devcontainer-build.yaml
================================================
name: Build devcontainer image

on:
  workflow_dispatch:
  push:
    branches:
      - main
    paths:
      - .devcontainer/**
      - script/requirements.txt
      - .github/workflows/devcontainer-build.yaml
  schedule:
    - cron: '0 0 1 * *'
  pull_request:
    branches:
      - main
    paths:
      - .devcontainer/**
      - script/requirements.txt
      - .github/workflows/devcontainer-build.yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Log in to the GitHub container registry
        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
        if: github.event_name != 'pull_request'
        with:
            registry: ghcr.io
            username: ${{ github.repository_owner }}
            password: ${{ secrets.GITHUB_TOKEN }}
      - name: Set up QEMU
        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
      - name: Build and Push
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: .
          file: .devcontainer/Dockerfile
          tags: ghcr.io/${{ github.repository_owner }}/devcontainer:addons
          push: ${{ github.event_name != 'pull_request' }}
          platforms: linux/amd64,linux/arm64


================================================
FILE: .github/workflows/lint.yml
================================================
name: Lint
on:
  push:
    branches:
      - main
  pull_request:
jobs:
  build:
    name: App configuration
    runs-on: ubuntu-latest
    strategy:
      matrix:
        channels:
          - folder: esphome
            channel: stable
          - folder: esphome-beta
            channel: beta
          - folder: esphome-dev
            channel: dev
    steps:
      - name: ⤵️ Check out code from GitHub
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: 🛠 Setup Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: '3.11'
      - name: 🛠 Install dependencies
        run: pip install -r script/requirements.txt
      - name: 🛠 Generate files from template
        run: python script/generate.py ${{ matrix.channels.channel }}
      - name: 🚀 Run Home Assistant App Lint on ${{ matrix.channels.channel }}
        uses: frenck/action-addon-linter@f995494fd84fae6310d23617e66d0e37de4f14eb # v2.21.0
        with:
          path: "./${{ matrix.channels.folder }}"


================================================
FILE: .gitignore
================================================
__pycache__/
*.py[cod]
*$py.class
venv/


================================================
FILE: .vscode/tasks.json
================================================
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start Home Assistant",
      "type": "shell",
      "command": "supervisor_run",
      "group": {
        "kind": "test",
        "isDefault": true
      },
      "presentation": {
        "reveal": "always",
        "panel": "new"
      },
      "problemMatcher": []
    }
  ]
}


================================================
FILE: README.md
================================================
# ESPHome [![Discord Chat](https://img.shields.io/discord/429907082951524364.svg)](https://discord.gg/KhAMKrd) [![GitHub release](https://img.shields.io/github/release/esphome/esphome.svg)](https://GitHub.com/esphome/esphome/releases/)

<a href="https://esphome.io/">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://media.esphome.io/logo/logo-text-on-dark.svg", alt="ESPHome Logo">
    <img src="https://media.esphome.io/logo/logo-text-on-light.svg" alt="ESPHome Logo">
  </picture>
</a>

This is the Home Assistant App repository for ESPHome. For the ESPHome source please go to [esphome](https://github.com/esphome/esphome).

**Documentation:** https://esphome.io/

For issues, please go to [the issue tracker](https://github.com/esphome/esphome/issues).

For feature requests, please see [feature requests](https://github.com/orgs/esphome/discussions).


================================================
FILE: esphome/CHANGELOG.md
================================================
## 2026.5.0

[**Read release announcement**](https://esphome.io/changelog/2026.5.0)

https://esphome.io/changelog/2026.5.0.html


================================================
FILE: esphome/DOCS.md
================================================
# ESPHome App
## Installation

The installation of this App is pretty straightforward and not different in comparison to installing any other Home Assistant App.

1. Search for the "ESPHome" App in the Supervisor App store.
2. Press install to download the App and unpack it on your machine. This can take some time.
3. Optional: If you're using SSL/TLS certificates and want to encrypt your communication to this App, please enter `true` into the `ssl` field and set the `fullchain` and `certfile` options accordingly.
4. Start the App, check the logs of the App to see if everything went well.
5. Click "OPEN WEB UI" to open the ESPHome dashboard. You will be asked for your Home Assistant credentials - ESPHome uses Home Assistant's authentication system to log you in.

You can view the ESPHome documentation at https://esphome.io/

## Configuration

**Note**: _Remember to restart the App when the configuration is changed._

Example App configuration:

```json
{
  "ssl": false,
  "certfile": "fullchain.pem",
  "keyfile": "privkey.pem"
}
```

### Option: `ssl`

Enables or disables encrypted SSL/TLS (HTTPS) connections to the web server of this App.
Set it to `true` to encrypt communications, `false` otherwise.
Please note that if you set this to `true` you must also generate the key and certificate
files for encryption. For example using [Let's Encrypt](https://www.home-assistant.io/addons/lets_encrypt/)
or [Self-signed certificates](https://www.home-assistant.io/docs/ecosystem/certificates/tls_self_signed_certificate/).

### Option: `certfile`

The certificate file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `keyfile`

The private key file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `leave_front_door_open`

Adding this option to the App configuration allows you to disable
authentication by setting it to `true`.

### Option: `relative_url`

Host the ESPHome dashboard under a relative URL, so that it can be integrated
into existing web proxies like NGINX under a relative URL. Defaults to `/`.

### Option: `status_use_ping`

By default the dashboard uses mDNS to check if nodes are online. This does
not work across subnets unless your router supports mDNS forwarding or avahi.

Setting this to `true` will make ESPHome use ICMP ping requests to get the node status. Use this if all nodes always have offline status even when they're connected.

### Option: `streamer_mode`

If set to `true`, this will enable streamer mode, which makes ESPHome hide all
potentially private information. So for example WiFi (B)SSIDs (which could be
used to find your location), usernames, etc. Please note that you need to use
the `!secret` tag in your YAML file to also prevent these from showing up
while editing and validating.


================================================
FILE: esphome/FILES ARE GENERATED DO NOT EDIT
================================================
Any edits should be made to the files in the 'template' directory

================================================
FILE: esphome/README.md
================================================
# ESPHome Device Builder

[![ESPHome logo][logo]][website]

[![GitHub stars][github-stars-shield]][repository]
[![Discord][discord-shield]][discord]

## About

This App allows you to write configurations and turn your microcontrollers
into smart home devices directly through Home Assistant **with no programming experience required**.
All you need to do is write YAML configuration files; the rest (over-the-air updates, compiling) is all
handled by ESPHome.

<p align="center">
<img title="ESPHome Device Builder screenshot" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome/images/screenshot.png" width="700px"></img>
</p>

[View the ESPHome documentation][website]

## Example

With ESPHome, you can go from a few lines of YAML straight to a custom-made
firmware. For example, to include a [DHT22][dht22]
temperature and humidity sensor, you just need to include 8 lines of YAML
in your configuration file:

<img title="ESPHome DHT configuration example" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome/images/dht-example.png" width="500px"></img>

Then just click UPLOAD and the sensor will magically appear in Home Assistant:

<img title="ESPHome Home Assistant discovery" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome/images/temperature-humidity.png" width="600px"></img>

[discord]: https://discord.gg/KhAMKrd
[repository]: https://github.com/esphome/esphome
[discord-shield]: https://img.shields.io/discord/429907082951524364.svg
[github-stars-shield]: https://img.shields.io/github/stars/esphome/esphome.svg?style=social&label=Star&maxAge=2592000
[dht22]: https://esphome.io/components/sensor/dht/
[releases]: https://esphome.io/changelog/
[logo]: https://github.com/esphome/home-assistant-addon/raw/main/esphome/logo.png
[website]: https://esphome.io/


================================================
FILE: esphome/config.yaml
================================================
---
url: https://esphome.io/
arch:
- amd64
- aarch64
hassio_api: true
auth_api: true
host_network: true
ingress: true
ingress_port: 0
panel_icon: mdi:esphome
uart: true
ports:
  6052/tcp: null
map:
- ssl:ro
- config:rw
discovery:
- esphome
schema:
  status_use_ping: bool?
  streamer_mode: bool?
  home_assistant_dashboard_integration: bool?
  default_compile_process_limit: int(1,)?
  ssl: bool?
  certfile: str?
  keyfile: str?
  leave_front_door_open: bool?
  use_new_device_builder: bool?
backup_exclude:
- '*/*/'
init: false
startup: services
options:
  use_new_device_builder: false
name: ESPHome Device Builder
panel_title: ESPHome Builder
version: 2026.5.0
slug: esphome
description: Build your own smart home devices using ESPHome, no programming experience
  required
image: ghcr.io/esphome/esphome-hassio


================================================
FILE: esphome/translations/en.yaml
================================================
---
configuration:
  certfile:
    name: Certificate file
    description: >-
      The certificate file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  default_compile_process_limit:
    name: Default compile process limit
    description: >-
      The default compile process limit. This is the maximum number of
      simultaneous compile processes that ESPHome will run.
  esphome_fork:
    name: Install ESPHome from a fork or branch
    description: >-
      For example to test a pull request, use `pull/XXXX/head` where `XXXX` is
      the PR number, or you can specify the username of the fork owner and
      branch `username:branch` which assumes the repository is named `esphome`
      still.

      If you need to test the latest commit on dev branch before the image is
      updated you can enter `dev` here.

      Please note that the fork or branch you are using **must** be up to
      date with ESPHome dev or the App **will not start**.
  home_assistant_dashboard_integration:
    name: Home Assistant Dashboard Integration
    description: >-
      Enables/Disables the ESPHome dashboard integrating with Home Assistant
      for automatic configuration of devices and device updates. If you use
      multiple version of the ESPHome App, make sure it is enabled on a
      single App only.
  keyfile:
    name: Private key file
    description: >-
      The private key file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  leave_front_door_open:
    name: Disable external authentication
    description: >-
      Disables external authentication when having opened the App
      on an external port. **WARNING**: This is a security risk!
  relative_url:
    name: Relative URL
    description: >-
      Host the ESPHome dashboard under a relative URL, so that it can be
      integrated into existing web proxies like NGINX under a relative URL.
      Defaults to `/`.
  ssl:
    name: SSL
    description: >-
      Enables/Disables SSL (HTTPS) on the web interface.
  status_use_ping:
    name: Use ping for status
    description: >-
      By default the dashboard uses mDNS to check if nodes are online. This does
      not work across subnets unless your router supports mDNS forwarding
      or avahi. Enabling this option will use ICMP ping to check if nodes are
      online.
  streamer_mode:
    name: Streamer mode
    description: >-
      Enables/Disables streamer mode, which makes ESPHome hide all
      potentially private information. So for example WiFi (B)SSIDs (which could
      be used to find your location), usernames, etc.
  use_new_device_builder:
    name: Use new Device Builder Preview
    description: >-
      Use the new ESPHome Device Builder instead of the classic ESPHome
      dashboard. When enabled, the latest prerelease of `esphome-device-builder`
      is installed on container start. **This is experimental and may not yet
      have all the features of the classic dashboard.**
network:
  6052/tcp: Web interface (to use without Home Assistant)


================================================
FILE: esphome-beta/CHANGELOG.md
================================================
## 2026.5.0

[**Read release announcement**](https://beta.esphome.io/changelog/2026.5.0)

https://esphome.io/changelog/2026.5.0.html


================================================
FILE: esphome-beta/DOCS.md
================================================
# ESPHome App
## Installation

The installation of this App is pretty straightforward and not different in comparison to installing any other Home Assistant App.

1. Search for the "ESPHome" App in the Supervisor App store.
2. Press install to download the App and unpack it on your machine. This can take some time.
3. Optional: If you're using SSL/TLS certificates and want to encrypt your communication to this App, please enter `true` into the `ssl` field and set the `fullchain` and `certfile` options accordingly.
4. Start the App, check the logs of the App to see if everything went well.
5. Click "OPEN WEB UI" to open the ESPHome dashboard. You will be asked for your Home Assistant credentials - ESPHome uses Home Assistant's authentication system to log you in.

You can view the ESPHome documentation at https://esphome.io/

## Configuration

**Note**: _Remember to restart the App when the configuration is changed._

Example App configuration:

```json
{
  "ssl": false,
  "certfile": "fullchain.pem",
  "keyfile": "privkey.pem"
}
```

### Option: `ssl`

Enables or disables encrypted SSL/TLS (HTTPS) connections to the web server of this App.
Set it to `true` to encrypt communications, `false` otherwise.
Please note that if you set this to `true` you must also generate the key and certificate
files for encryption. For example using [Let's Encrypt](https://www.home-assistant.io/addons/lets_encrypt/)
or [Self-signed certificates](https://www.home-assistant.io/docs/ecosystem/certificates/tls_self_signed_certificate/).

### Option: `certfile`

The certificate file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `keyfile`

The private key file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `leave_front_door_open`

Adding this option to the App configuration allows you to disable
authentication by setting it to `true`.

### Option: `relative_url`

Host the ESPHome dashboard under a relative URL, so that it can be integrated
into existing web proxies like NGINX under a relative URL. Defaults to `/`.

### Option: `status_use_ping`

By default the dashboard uses mDNS to check if nodes are online. This does
not work across subnets unless your router supports mDNS forwarding or avahi.

Setting this to `true` will make ESPHome use ICMP ping requests to get the node status. Use this if all nodes always have offline status even when they're connected.

### Option: `streamer_mode`

If set to `true`, this will enable streamer mode, which makes ESPHome hide all
potentially private information. So for example WiFi (B)SSIDs (which could be
used to find your location), usernames, etc. Please note that you need to use
the `!secret` tag in your YAML file to also prevent these from showing up
while editing and validating.


================================================
FILE: esphome-beta/FILES ARE GENERATED DO NOT EDIT
================================================
Any edits should be made to the files in the 'template' directory

================================================
FILE: esphome-beta/README.md
================================================
# ESPHome Device Builder Beta

[![ESPHome logo][logo]][website]

[![GitHub stars][github-stars-shield]][repository]
[![Discord][discord-shield]][discord]

## About

This App allows you to write configurations and turn your microcontrollers
into smart home devices directly through Home Assistant **with no programming experience required**.
All you need to do is write YAML configuration files; the rest (over-the-air updates, compiling) is all
handled by ESPHome.

<p align="center">
<img title="ESPHome Device Builder screenshot" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/images/screenshot.png" width="700px"></img>
</p>

[View the ESPHome documentation][website]

## Example

With ESPHome, you can go from a few lines of YAML straight to a custom-made
firmware. For example, to include a [DHT22][dht22]
temperature and humidity sensor, you just need to include 8 lines of YAML
in your configuration file:

<img title="ESPHome DHT configuration example" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/images/dht-example.png" width="500px"></img>

Then just click UPLOAD and the sensor will magically appear in Home Assistant:

<img title="ESPHome Home Assistant discovery" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/images/temperature-humidity.png" width="600px"></img>

[discord]: https://discord.gg/KhAMKrd
[repository]: https://github.com/esphome/esphome
[discord-shield]: https://img.shields.io/discord/429907082951524364.svg
[github-stars-shield]: https://img.shields.io/github/stars/esphome/esphome.svg?style=social&label=Star&maxAge=2592000
[dht22]: https://beta.esphome.io/components/sensor/dht/
[releases]: https://beta.esphome.io/changelog/
[logo]: https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/logo.png
[website]: https://beta.esphome.io/


================================================
FILE: esphome-beta/config.yaml
================================================
---
url: https://beta.esphome.io/
arch:
- amd64
- aarch64
hassio_api: true
auth_api: true
host_network: true
ingress: true
ingress_port: 0
panel_icon: mdi:esphome
uart: true
ports:
  6052/tcp: null
map:
- ssl:ro
- config:rw
discovery:
- esphome
schema:
  status_use_ping: bool?
  streamer_mode: bool?
  home_assistant_dashboard_integration: bool?
  default_compile_process_limit: int(1,)?
  ssl: bool?
  certfile: str?
  keyfile: str?
  leave_front_door_open: bool?
  use_new_device_builder: bool?
backup_exclude:
- '*/*/'
init: false
startup: services
options:
  home_assistant_dashboard_integration: false
  use_new_device_builder: true
name: ESPHome Device Builder (beta)
panel_title: ESPHome Builder (beta)
version: 2026.5.0
slug: esphome-beta
description: Beta version of ESPHome Device Builder
image: ghcr.io/esphome/esphome-hassio
stage: experimental


================================================
FILE: esphome-beta/translations/en.yaml
================================================
---
configuration:
  certfile:
    name: Certificate file
    description: >-
      The certificate file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  default_compile_process_limit:
    name: Default compile process limit
    description: >-
      The default compile process limit. This is the maximum number of
      simultaneous compile processes that ESPHome will run.
  esphome_fork:
    name: Install ESPHome from a fork or branch
    description: >-
      For example to test a pull request, use `pull/XXXX/head` where `XXXX` is
      the PR number, or you can specify the username of the fork owner and
      branch `username:branch` which assumes the repository is named `esphome`
      still.

      If you need to test the latest commit on dev branch before the image is
      updated you can enter `dev` here.

      Please note that the fork or branch you are using **must** be up to
      date with ESPHome dev or the App **will not start**.
  home_assistant_dashboard_integration:
    name: Home Assistant Dashboard Integration
    description: >-
      Enables/Disables the ESPHome dashboard integrating with Home Assistant
      for automatic configuration of devices and device updates. If you use
      multiple version of the ESPHome App, make sure it is enabled on a
      single App only.
  keyfile:
    name: Private key file
    description: >-
      The private key file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  leave_front_door_open:
    name: Disable external authentication
    description: >-
      Disables external authentication when having opened the App
      on an external port. **WARNING**: This is a security risk!
  relative_url:
    name: Relative URL
    description: >-
      Host the ESPHome dashboard under a relative URL, so that it can be
      integrated into existing web proxies like NGINX under a relative URL.
      Defaults to `/`.
  ssl:
    name: SSL
    description: >-
      Enables/Disables SSL (HTTPS) on the web interface.
  status_use_ping:
    name: Use ping for status
    description: >-
      By default the dashboard uses mDNS to check if nodes are online. This does
      not work across subnets unless your router supports mDNS forwarding
      or avahi. Enabling this option will use ICMP ping to check if nodes are
      online.
  streamer_mode:
    name: Streamer mode
    description: >-
      Enables/Disables streamer mode, which makes ESPHome hide all
      potentially private information. So for example WiFi (B)SSIDs (which could
      be used to find your location), usernames, etc.
  use_new_device_builder:
    name: Use new Device Builder Preview
    description: >-
      Use the new ESPHome Device Builder instead of the classic ESPHome
      dashboard. When enabled, the latest prerelease of `esphome-device-builder`
      is installed on container start. **This is experimental and may not yet
      have all the features of the classic dashboard.**
network:
  6052/tcp: Web interface (to use without Home Assistant)


================================================
FILE: esphome-dev/CHANGELOG.md
================================================
See https://github.com/esphome/esphome/commits/dev


================================================
FILE: esphome-dev/DOCS.md
================================================
# ESPHome DEV App

This is **development** version of the ESPHome App.

To deploy production nodes please use mainstream release App.

The App uses a version of ESPHome built automatically every day at 02:00 UTC. and is used to test components in development. See the `esphome_fork` configuration below to properly configure the App. Once you update the configuration make sure to rebuild the image.

## Configuration

**Note**: _Remember to restart the App when the configuration is changed._

### Option: `esphome_fork`

Install ESPHome from a fork or branch.
For example to test a pull request, use `pull/XXXX/head` where `XXXX` is the PR number,
or you can specify the username of the fork owner and branch `username:branch` which
assumes the repository is named `esphome` still.

If you need to test the latest commit on dev branch before the image is updated you can enter `dev` here.

Please note that the fork or branch you are using **must** be up to date with ESPHome dev
or the App **will not start**.


## General ESPHome App configurations

General options also available in other versions.

### Option: `ssl`

Enables or disables encrypted SSL/TLS (HTTPS) connections to the web server of this App.
Set it to `true` to encrypt communications, `false` otherwise.
Please note that if you set this to `true` you must also generate the key and certificate
files for encryption. For example using [Let's Encrypt](https://www.home-assistant.io/addons/lets_encrypt/)
or [Self-signed certificates](https://www.home-assistant.io/docs/ecosystem/certificates/tls_self_signed_certificate/).

### Option: `certfile`

The certificate file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `keyfile`

The private key file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `leave_front_door_open`

Adding this option to the App configuration allows you to disable
authentication by setting it to `true`.

### Option: `relative_url`

Host the ESPHome dashboard under a relative URL, so that it can be integrated
into existing web proxies like NGINX under a relative URL. Defaults to `/`.

### Option: `status_use_ping`

By default the dashboard uses mDNS to check if nodes are online. This does
not work across subnets unless your router supports mDNS forwarding or avahi.

Setting this to `true` will make ESPHome use ICMP ping requests to get the node status. Use this if all nodes always have offline status even when they're connected.

### Option: `streamer_mode`

If set to `true`, this will enable streamer mode, which makes ESPHome hide all
potentially private information. So for example WiFi (B)SSIDs (which could be
used to find your location), usernames, etc. Please note that you need to use
the `!secret` tag in your YAML file to also prevent these from showing up
while editing and validating.


================================================
FILE: esphome-dev/FILES ARE GENERATED DO NOT EDIT
================================================
Any edits should be made to the files in the 'template' directory

================================================
FILE: esphome-dev/README.md
================================================
# ESPHome Device Builder (Development branch)

[![ESPHome logo][logo]][website]

[![GitHub stars][github-stars-shield]][repository]
[![Discord][discord-shield]][discord]

## About

This App allows you to write configurations and turn your microcontrollers
into smart home devices directly through Home Assistant **with no programming experience required**.
All you need to do is write YAML configuration files; the rest (over-the-air updates, compiling) is all
handled by ESPHome.

<p align="center">
<img title="ESPHome Device Builder screenshot" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/images/screenshot.png" width="700px"></img>
</p>

[View the ESPHome documentation][website]

## Example

With ESPHome, you can go from a few lines of YAML straight to a custom-made
firmware. For example, to include a [DHT22][dht22]
temperature and humidity sensor, you just need to include 8 lines of YAML
in your configuration file:

<img title="ESPHome DHT configuration example" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/images/dht-example.png" width="500px"></img>

Then just click UPLOAD and the sensor will magically appear in Home Assistant:

<img title="ESPHome Home Assistant discovery" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/images/temperature-humidity.png" width="600px"></img>

[discord]: https://discord.gg/KhAMKrd
[repository]: https://github.com/esphome/esphome
[discord-shield]: https://img.shields.io/discord/429907082951524364.svg
[github-stars-shield]: https://img.shields.io/github/stars/esphome/esphome.svg?style=social&label=Star&maxAge=2592000
[dht22]: https://next.esphome.io/components/sensor/dht/
[releases]: https://next.esphome.io/changelog/
[logo]: https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/logo.png
[website]: https://next.esphome.io/


================================================
FILE: esphome-dev/config.yaml
================================================
---
url: https://next.esphome.io/
arch:
- amd64
- aarch64
hassio_api: true
auth_api: true
host_network: true
ingress: true
ingress_port: 0
panel_icon: mdi:esphome
uart: true
ports:
  6052/tcp: null
map:
- ssl:ro
- config:rw
discovery:
- esphome
schema:
  status_use_ping: bool?
  streamer_mode: bool?
  home_assistant_dashboard_integration: bool?
  default_compile_process_limit: int(1,)?
  esphome_fork: str?
  ssl: bool?
  certfile: str?
  keyfile: str?
  leave_front_door_open: bool?
  use_new_device_builder: bool?
backup_exclude:
- '*/*/'
init: false
startup: services
options:
  home_assistant_dashboard_integration: false
  use_new_device_builder: true
name: ESPHome Device Builder (dev)
panel_title: ESPHome Builder (dev)
version: 2026.6.0-dev20260521
slug: esphome-dev
description: Development version of ESPHome Device Builder
image: ghcr.io/esphome/esphome-hassio
stage: experimental


================================================
FILE: esphome-dev/translations/en.yaml
================================================
---
configuration:
  certfile:
    name: Certificate file
    description: >-
      The certificate file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  default_compile_process_limit:
    name: Default compile process limit
    description: >-
      The default compile process limit. This is the maximum number of
      simultaneous compile processes that ESPHome will run.
  esphome_fork:
    name: Install ESPHome from a fork or branch
    description: >-
      For example to test a pull request, use `pull/XXXX/head` where `XXXX` is
      the PR number, or you can specify the username of the fork owner and
      branch `username:branch` which assumes the repository is named `esphome`
      still.

      If you need to test the latest commit on dev branch before the image is
      updated you can enter `dev` here.

      Please note that the fork or branch you are using **must** be up to
      date with ESPHome dev or the App **will not start**.
  home_assistant_dashboard_integration:
    name: Home Assistant Dashboard Integration
    description: >-
      Enables/Disables the ESPHome dashboard integrating with Home Assistant
      for automatic configuration of devices and device updates. If you use
      multiple version of the ESPHome App, make sure it is enabled on a
      single App only.
  keyfile:
    name: Private key file
    description: >-
      The private key file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  leave_front_door_open:
    name: Disable external authentication
    description: >-
      Disables external authentication when having opened the App
      on an external port. **WARNING**: This is a security risk!
  relative_url:
    name: Relative URL
    description: >-
      Host the ESPHome dashboard under a relative URL, so that it can be
      integrated into existing web proxies like NGINX under a relative URL.
      Defaults to `/`.
  ssl:
    name: SSL
    description: >-
      Enables/Disables SSL (HTTPS) on the web interface.
  status_use_ping:
    name: Use ping for status
    description: >-
      By default the dashboard uses mDNS to check if nodes are online. This does
      not work across subnets unless your router supports mDNS forwarding
      or avahi. Enabling this option will use ICMP ping to check if nodes are
      online.
  streamer_mode:
    name: Streamer mode
    description: >-
      Enables/Disables streamer mode, which makes ESPHome hide all
      potentially private information. So for example WiFi (B)SSIDs (which could
      be used to find your location), usernames, etc.
  use_new_device_builder:
    name: Use new Device Builder Preview
    description: >-
      Use the new ESPHome Device Builder instead of the classic ESPHome
      dashboard. When enabled, the latest prerelease of `esphome-device-builder`
      is installed on container start. **This is experimental and may not yet
      have all the features of the classic dashboard.**
network:
  6052/tcp: Web interface (to use without Home Assistant)


================================================
FILE: repository.json
================================================
{
  "name": "ESPHome",
  "url": "https://esphome.io",
  "maintainer": "ESPHome <esphome@nabucasa.com>"
}


================================================
FILE: script/NOTES.md
================================================
# Maintainer notes

This repository is pulled by all Hassio installs and contains
the Hassio config for each type of install: latest, beta and dev.

- `latest` always points to the most recent full release.
- `beta` points to the most recent full release or beta release (whichever is newer). This is so that beta image users automatically get upgraded to the stable install once it gets released.
- `dev` is an image that Hassio builds itself and contains the latest ESPHome version straigt from dev branch.

The config.json files are all automatically written with the script in this directory and the `template/addon_config.yaml` file.

To update one of the images: use

```bash
$ pip3 install -r script/requirements.txt
$ python3 script/generate.py [dev|beta|latest]
```

The `esphome-dev/rootfs` folder is shared with the `docker/rootfs` folder in the esphome repo.
This could be solved better, but currently `rsync` is used to copy the files over:

```bash
rsync -av ../esphome/docker/rootfs esphome-dev/
```


================================================
FILE: script/bump-version.py
================================================
#!/usr/bin/env python3

import argparse
import re
from dataclasses import dataclass
import sys
import os

sys.path.append(os.path.dirname(__file__))
import generate


@dataclass
class Version:
    major: int
    minor: int
    patch: int
    beta: int = 0
    dev: str = ""

    def __str__(self):
        return f"{self.major}.{self.minor}.{self.full_patch}"

    @property
    def full_patch(self):
        res = f"{self.patch}"
        if self.beta > 0:
            res += f"b{self.beta}"
        if self.dev:
            res += f"-dev{self.dev}"
        return res

    @classmethod
    def parse(cls, value):
        match = re.match(r"(\d+).(\d+).(\d+)(b\d+)?(-dev\d+)?", value)
        assert match is not None
        major = int(match[1])
        minor = int(match[2])
        patch = int(match[3])
        beta = int(match[4][1:]) if match[4] else 0
        dev = str(match[5][4:]) if match[5] else ""
        return Version(major=major, minor=minor, patch=patch, beta=beta, dev=dev)


def _sub(path, pattern, repl, expected_count=1):
    with open(path, encoding="utf-8") as fh:
        content = fh.read()
    content, count = re.subn(pattern, repl, content, flags=re.NOFLAG)
    if expected_count is not None:
        assert count == expected_count, f"Pattern {pattern} replacement failed!"
    with open(path, "wt", encoding="utf-8") as fh:
        fh.write(content)


def _write_version(target: str, version: Version):
    #  version: "2024.5.0-dev20240412"  # DEV
    #  version: "1.14.5"  # BETA
    #  version: "1.14.5"  # STABLE
    _sub(
        "template/addon_config.yaml",
        f'  version: "[^"]+"  # {target.upper()}',
        f'  version: "{version}"  # {target.upper()}',
    )


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("new_version", type=str)
    args = parser.parse_args()

    version = Version.parse(args.new_version)

    print(f"Bumping to {version}")
    if version.dev:
        _write_version("dev", version)
        generate.main(["dev"])
    elif version.beta:
        _write_version("beta", version)
        generate.main(["beta"])
    else:
        _write_version("stable", version)
        _write_version("beta", version)
        generate.main(["stable", "beta"])
    return 0


if __name__ == "__main__":
    sys.exit(main() or 0)


================================================
FILE: script/generate.py
================================================
#!/usr/bin/env python3

import argparse
from pathlib import Path
from enum import Enum
from shutil import copyfile
import sys
import os

import yaml


class Channel(Enum):
    stable = "stable"
    beta = "beta"
    dev = "dev"


def deep_merge(base, override):
    result = dict(override)
    for key, base_value in base.items():
        if key not in override:
            result[key] = base_value
        elif isinstance(base_value, dict) and isinstance(override[key], dict):
            result[key] = deep_merge(base_value, override[key])
    return result


def main(args):
    parser = argparse.ArgumentParser(
        description="Generate ESPHome Home Assistant config.json"
    )
    parser.add_argument("channels", nargs="+", type=Channel, choices=list(Channel))
    args = parser.parse_args(args)

    root = Path(__file__).parent.parent
    templ = root / "template"

    with open(templ / "addon_config.yaml", "r", encoding="utf-8") as f:
        config = yaml.safe_load(f)

    copyf = config["copy_files"]
    base = config.get("base") or {}

    for channel in args.channels:
        conf = deep_merge(base, config[f"esphome-{channel.value}"])
        dir_ = root / conf.pop("directory")
        path = dir_ / "config.yaml"
        with open(path, "w", encoding="utf-8") as f:
            yaml.dump(conf, f, indent=2, sort_keys=False, explicit_start=True)

        for file_ in copyf:
            os.makedirs(dir_ / Path(file_).parent, exist_ok=True)
            if Path.exists(templ / channel.value / file_):
                copyfile(templ / channel.value / file_, dir_ / file_)
            else:
                copyfile(templ / file_, dir_ / file_)

        path = dir_ / "FILES ARE GENERATED DO NOT EDIT"
        with open(path, "w", encoding="utf-8") as f:
            f.write("Any edits should be made to the files in the 'template' directory")


if __name__ == "__main__":
    main(sys.argv[1:])


================================================
FILE: script/requirements.txt
================================================
PyYAML==6.0.3


================================================
FILE: template/DOCS.md
================================================
# ESPHome App
## Installation

The installation of this App is pretty straightforward and not different in comparison to installing any other Home Assistant App.

1. Search for the "ESPHome" App in the Supervisor App store.
2. Press install to download the App and unpack it on your machine. This can take some time.
3. Optional: If you're using SSL/TLS certificates and want to encrypt your communication to this App, please enter `true` into the `ssl` field and set the `fullchain` and `certfile` options accordingly.
4. Start the App, check the logs of the App to see if everything went well.
5. Click "OPEN WEB UI" to open the ESPHome dashboard. You will be asked for your Home Assistant credentials - ESPHome uses Home Assistant's authentication system to log you in.

You can view the ESPHome documentation at https://esphome.io/

## Configuration

**Note**: _Remember to restart the App when the configuration is changed._

Example App configuration:

```json
{
  "ssl": false,
  "certfile": "fullchain.pem",
  "keyfile": "privkey.pem"
}
```

### Option: `ssl`

Enables or disables encrypted SSL/TLS (HTTPS) connections to the web server of this App.
Set it to `true` to encrypt communications, `false` otherwise.
Please note that if you set this to `true` you must also generate the key and certificate
files for encryption. For example using [Let's Encrypt](https://www.home-assistant.io/addons/lets_encrypt/)
or [Self-signed certificates](https://www.home-assistant.io/docs/ecosystem/certificates/tls_self_signed_certificate/).

### Option: `certfile`

The certificate file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `keyfile`

The private key file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `leave_front_door_open`

Adding this option to the App configuration allows you to disable
authentication by setting it to `true`.

### Option: `relative_url`

Host the ESPHome dashboard under a relative URL, so that it can be integrated
into existing web proxies like NGINX under a relative URL. Defaults to `/`.

### Option: `status_use_ping`

By default the dashboard uses mDNS to check if nodes are online. This does
not work across subnets unless your router supports mDNS forwarding or avahi.

Setting this to `true` will make ESPHome use ICMP ping requests to get the node status. Use this if all nodes always have offline status even when they're connected.

### Option: `streamer_mode`

If set to `true`, this will enable streamer mode, which makes ESPHome hide all
potentially private information. So for example WiFi (B)SSIDs (which could be
used to find your location), usernames, etc. Please note that you need to use
the `!secret` tag in your YAML file to also prevent these from showing up
while editing and validating.


================================================
FILE: template/README.md
================================================
# ESPHome Device Builder

[![ESPHome logo][logo]][website]

[![GitHub stars][github-stars-shield]][repository]
[![Discord][discord-shield]][discord]

## About

This App allows you to write configurations and turn your microcontrollers
into smart home devices directly through Home Assistant **with no programming experience required**.
All you need to do is write YAML configuration files; the rest (over-the-air updates, compiling) is all
handled by ESPHome.

<p align="center">
<img title="ESPHome Device Builder screenshot" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome/images/screenshot.png" width="700px"></img>
</p>

[View the ESPHome documentation][website]

## Example

With ESPHome, you can go from a few lines of YAML straight to a custom-made
firmware. For example, to include a [DHT22][dht22]
temperature and humidity sensor, you just need to include 8 lines of YAML
in your configuration file:

<img title="ESPHome DHT configuration example" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome/images/dht-example.png" width="500px"></img>

Then just click UPLOAD and the sensor will magically appear in Home Assistant:

<img title="ESPHome Home Assistant discovery" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome/images/temperature-humidity.png" width="600px"></img>

[discord]: https://discord.gg/KhAMKrd
[repository]: https://github.com/esphome/esphome
[discord-shield]: https://img.shields.io/discord/429907082951524364.svg
[github-stars-shield]: https://img.shields.io/github/stars/esphome/esphome.svg?style=social&label=Star&maxAge=2592000
[dht22]: https://esphome.io/components/sensor/dht/
[releases]: https://esphome.io/changelog/
[logo]: https://github.com/esphome/home-assistant-addon/raw/main/esphome/logo.png
[website]: https://esphome.io/


================================================
FILE: template/addon_config.yaml
================================================
---
# When changing options in this file, please also run:
#    python3 script/generate.py dev
# to update the dev app config (beta/stable configs will be updated on next release by release script)
base: &base
  url: https://esphome.io/
  arch:
    - amd64
    - aarch64
  # Uses Home Assistant Supervisor API (auth)
  hassio_api: true
  auth_api: true
  # Host network mode for mDNS
  host_network: true
  # Ingress settings
  ingress: true
  ingress_port: 0
  panel_icon: "mdi:esphome"
  # Automatically add UART devices to App
  uart: true
  ports:
    "6052/tcp": null
  map:
    - ssl:ro
    - config:rw
  discovery:
    - esphome
  schema:
    status_use_ping: bool?
    streamer_mode: bool?
    home_assistant_dashboard_integration: bool?
    default_compile_process_limit: int(1,)?
    ssl: bool?
    certfile: str?
    keyfile: str?
    leave_front_door_open: bool?
    use_new_device_builder: bool?
  backup_exclude:
    - "*/*/"
  # Disable docker init for s6
  init: false
  # Make sure dashboard is available for core
  startup: services
  options:
    use_new_device_builder: false

esphome-dev:
  <<: *base
  directory: esphome-dev
  name: ESPHome Device Builder (dev)
  panel_title: ESPHome Builder (dev)
  version: "2026.6.0-dev20260521"  # DEV
  slug: esphome-dev
  description: "Development version of ESPHome Device Builder"
  url: https://next.esphome.io/
  image: ghcr.io/esphome/esphome-hassio
  stage: experimental
  schema:
    status_use_ping: bool?
    streamer_mode: bool?
    home_assistant_dashboard_integration: bool?
    default_compile_process_limit: int(1,)?
    esphome_fork: str?
    ssl: bool?
    certfile: str?
    keyfile: str?
    leave_front_door_open: bool?
  options:
    home_assistant_dashboard_integration: false
    use_new_device_builder: true

esphome-beta:
  <<: *base
  directory: esphome-beta
  name: ESPHome Device Builder (beta)
  panel_title: ESPHome Builder (beta)
  version: "2026.5.0"  # BETA
  slug: esphome-beta
  description: "Beta version of ESPHome Device Builder"
  url: https://beta.esphome.io/
  image: ghcr.io/esphome/esphome-hassio
  stage: experimental
  options:
    home_assistant_dashboard_integration: false
    use_new_device_builder: true

esphome-stable:
  <<: *base
  directory: esphome
  name: ESPHome Device Builder
  panel_title: ESPHome Builder
  version: "2026.5.0"  # STABLE
  slug: esphome
  description: "Build your own smart home devices using ESPHome, no programming experience required"
  image: ghcr.io/esphome/esphome-hassio

copy_files:
  - DOCS.md
  - icon.png
  - logo.png
  - README.md
  - translations/en.yaml
  - images/dht-example.png
  - images/screenshot.png
  - images/temperature-humidity.png


================================================
FILE: template/beta/README.md
================================================
# ESPHome Device Builder Beta

[![ESPHome logo][logo]][website]

[![GitHub stars][github-stars-shield]][repository]
[![Discord][discord-shield]][discord]

## About

This App allows you to write configurations and turn your microcontrollers
into smart home devices directly through Home Assistant **with no programming experience required**.
All you need to do is write YAML configuration files; the rest (over-the-air updates, compiling) is all
handled by ESPHome.

<p align="center">
<img title="ESPHome Device Builder screenshot" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/images/screenshot.png" width="700px"></img>
</p>

[View the ESPHome documentation][website]

## Example

With ESPHome, you can go from a few lines of YAML straight to a custom-made
firmware. For example, to include a [DHT22][dht22]
temperature and humidity sensor, you just need to include 8 lines of YAML
in your configuration file:

<img title="ESPHome DHT configuration example" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/images/dht-example.png" width="500px"></img>

Then just click UPLOAD and the sensor will magically appear in Home Assistant:

<img title="ESPHome Home Assistant discovery" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/images/temperature-humidity.png" width="600px"></img>

[discord]: https://discord.gg/KhAMKrd
[repository]: https://github.com/esphome/esphome
[discord-shield]: https://img.shields.io/discord/429907082951524364.svg
[github-stars-shield]: https://img.shields.io/github/stars/esphome/esphome.svg?style=social&label=Star&maxAge=2592000
[dht22]: https://beta.esphome.io/components/sensor/dht/
[releases]: https://beta.esphome.io/changelog/
[logo]: https://github.com/esphome/home-assistant-addon/raw/main/esphome-beta/logo.png
[website]: https://beta.esphome.io/


================================================
FILE: template/dev/DOCS.md
================================================
# ESPHome DEV App

This is **development** version of the ESPHome App.

To deploy production nodes please use mainstream release App.

The App uses a version of ESPHome built automatically every day at 02:00 UTC. and is used to test components in development. See the `esphome_fork` configuration below to properly configure the App. Once you update the configuration make sure to rebuild the image.

## Configuration

**Note**: _Remember to restart the App when the configuration is changed._

### Option: `esphome_fork`

Install ESPHome from a fork or branch.
For example to test a pull request, use `pull/XXXX/head` where `XXXX` is the PR number,
or you can specify the username of the fork owner and branch `username:branch` which
assumes the repository is named `esphome` still.

If you need to test the latest commit on dev branch before the image is updated you can enter `dev` here.

Please note that the fork or branch you are using **must** be up to date with ESPHome dev
or the App **will not start**.


## General ESPHome App configurations

General options also available in other versions.

### Option: `ssl`

Enables or disables encrypted SSL/TLS (HTTPS) connections to the web server of this App.
Set it to `true` to encrypt communications, `false` otherwise.
Please note that if you set this to `true` you must also generate the key and certificate
files for encryption. For example using [Let's Encrypt](https://www.home-assistant.io/addons/lets_encrypt/)
or [Self-signed certificates](https://www.home-assistant.io/docs/ecosystem/certificates/tls_self_signed_certificate/).

### Option: `certfile`

The certificate file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `keyfile`

The private key file to use for SSL. If this file doesn't exist, the App start will fail.

**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant

### Option: `leave_front_door_open`

Adding this option to the App configuration allows you to disable
authentication by setting it to `true`.

### Option: `relative_url`

Host the ESPHome dashboard under a relative URL, so that it can be integrated
into existing web proxies like NGINX under a relative URL. Defaults to `/`.

### Option: `status_use_ping`

By default the dashboard uses mDNS to check if nodes are online. This does
not work across subnets unless your router supports mDNS forwarding or avahi.

Setting this to `true` will make ESPHome use ICMP ping requests to get the node status. Use this if all nodes always have offline status even when they're connected.

### Option: `streamer_mode`

If set to `true`, this will enable streamer mode, which makes ESPHome hide all
potentially private information. So for example WiFi (B)SSIDs (which could be
used to find your location), usernames, etc. Please note that you need to use
the `!secret` tag in your YAML file to also prevent these from showing up
while editing and validating.


================================================
FILE: template/dev/README.md
================================================
# ESPHome Device Builder (Development branch)

[![ESPHome logo][logo]][website]

[![GitHub stars][github-stars-shield]][repository]
[![Discord][discord-shield]][discord]

## About

This App allows you to write configurations and turn your microcontrollers
into smart home devices directly through Home Assistant **with no programming experience required**.
All you need to do is write YAML configuration files; the rest (over-the-air updates, compiling) is all
handled by ESPHome.

<p align="center">
<img title="ESPHome Device Builder screenshot" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/images/screenshot.png" width="700px"></img>
</p>

[View the ESPHome documentation][website]

## Example

With ESPHome, you can go from a few lines of YAML straight to a custom-made
firmware. For example, to include a [DHT22][dht22]
temperature and humidity sensor, you just need to include 8 lines of YAML
in your configuration file:

<img title="ESPHome DHT configuration example" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/images/dht-example.png" width="500px"></img>

Then just click UPLOAD and the sensor will magically appear in Home Assistant:

<img title="ESPHome Home Assistant discovery" src="https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/images/temperature-humidity.png" width="600px"></img>

[discord]: https://discord.gg/KhAMKrd
[repository]: https://github.com/esphome/esphome
[discord-shield]: https://img.shields.io/discord/429907082951524364.svg
[github-stars-shield]: https://img.shields.io/github/stars/esphome/esphome.svg?style=social&label=Star&maxAge=2592000
[dht22]: https://next.esphome.io/components/sensor/dht/
[releases]: https://next.esphome.io/changelog/
[logo]: https://github.com/esphome/home-assistant-addon/raw/main/esphome-dev/logo.png
[website]: https://next.esphome.io/


================================================
FILE: template/translations/en.yaml
================================================
---
configuration:
  certfile:
    name: Certificate file
    description: >-
      The certificate file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  default_compile_process_limit:
    name: Default compile process limit
    description: >-
      The default compile process limit. This is the maximum number of
      simultaneous compile processes that ESPHome will run.
  esphome_fork:
    name: Install ESPHome from a fork or branch
    description: >-
      For example to test a pull request, use `pull/XXXX/head` where `XXXX` is
      the PR number, or you can specify the username of the fork owner and
      branch `username:branch` which assumes the repository is named `esphome`
      still.

      If you need to test the latest commit on dev branch before the image is
      updated you can enter `dev` here.

      Please note that the fork or branch you are using **must** be up to
      date with ESPHome dev or the App **will not start**.
  home_assistant_dashboard_integration:
    name: Home Assistant Dashboard Integration
    description: >-
      Enables/Disables the ESPHome dashboard integrating with Home Assistant
      for automatic configuration of devices and device updates. If you use
      multiple version of the ESPHome App, make sure it is enabled on a
      single App only.
  keyfile:
    name: Private key file
    description: >-
      The private key file to use for SSL. Note that this file must
      exist in the /ssl/ folder.
  leave_front_door_open:
    name: Disable external authentication
    description: >-
      Disables external authentication when having opened the App
      on an external port. **WARNING**: This is a security risk!
  relative_url:
    name: Relative URL
    description: >-
      Host the ESPHome dashboard under a relative URL, so that it can be
      integrated into existing web proxies like NGINX under a relative URL.
      Defaults to `/`.
  ssl:
    name: SSL
    description: >-
      Enables/Disables SSL (HTTPS) on the web interface.
  status_use_ping:
    name: Use ping for status
    description: >-
      By default the dashboard uses mDNS to check if nodes are online. This does
      not work across subnets unless your router supports mDNS forwarding
      or avahi. Enabling this option will use ICMP ping to check if nodes are
      online.
  streamer_mode:
    name: Streamer mode
    description: >-
      Enables/Disables streamer mode, which makes ESPHome hide all
      potentially private information. So for example WiFi (B)SSIDs (which could
      be used to find your location), usernames, etc.
  use_new_device_builder:
    name: Use new Device Builder Preview
    description: >-
      Use the new ESPHome Device Builder instead of the classic ESPHome
      dashboard. When enabled, the latest prerelease of `esphome-device-builder`
      is installed on container start. **This is experimental and may not yet
      have all the features of the classic dashboard.**
network:
  6052/tcp: Web interface (to use without Home Assistant)