Metadata-Version: 2.4
Name: esphome-device-builder
Version: 0.1.0b19
Summary: ESPHome Device Builder
Author-email: The ESPHome Authors <esphome@openhomefoundation.org>
Maintainer-email: Open Home Foundation <esphome@openhomefoundation.org>
License-Expression: Apache-2.0
Project-URL: Documentation, https://esphome.io
Project-URL: Homepage, https://esphome.io
Project-URL: Issues, https://github.com/esphome/device-builder/issues
Project-URL: Repository, https://github.com/esphome/device-builder
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: esphome-device-builder-frontend==0.1.37
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: mashumaro>=3.13
Requires-Dist: orjson>=3.9.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: esphome
Requires-Dist: esphome>=2024.1.0; extra == "esphome"
Provides-Extra: test
Requires-Dist: blockbuster<1.6,>=1.5.5; extra == "test"
Requires-Dist: codespell==2.4.2; extra == "test"
Requires-Dist: jsonschema>=4.20.0; extra == "test"
Requires-Dist: mypy==1.20.2; extra == "test"
Requires-Dist: pre-commit==4.6.0; extra == "test"
Requires-Dist: pre-commit-hooks==6.0.0; extra == "test"
Requires-Dist: pytest==9.0.3; extra == "test"
Requires-Dist: pytest-aiohttp==1.1.0; extra == "test"
Requires-Dist: pytest-codspeed==4.5.0; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Requires-Dist: pytest-xdist==3.8.0; extra == "test"
Requires-Dist: ruff==0.15.12; extra == "test"
Dynamic: license-file

# ESPHome Device Builder Dashboard

[![PyPI version](https://img.shields.io/pypi/v/esphome-device-builder.svg)](https://pypi.org/project/esphome-device-builder/) [![codecov](https://codecov.io/gh/esphome/device-builder/branch/main/graph/badge.svg)](https://codecov.io/gh/esphome/device-builder) [![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/esphome/device-builder)

> **Status:** in active development. Roughly alpha, closing on beta. Issues
> and feedback welcome — please check existing issues / the
> [project board](https://github.com/orgs/esphome/projects/7/views/1?filterQuery=project%3A%22device-builder-dashboard%22)
> first, and join the [Discord channel](https://discord.gg/Rf2jWGVjaK)
> for live discussion.

A new dashboard for [ESPHome](https://github.com/esphome/esphome) — a guided
interface for composing device configs, exploring components and boards,
managing automations, and pushing firmware updates.

## Try it

The dashboard isn't yet wired into the ESPHome container or the Home Assistant
add-on as an opt-in preview — that's coming soon. In the meantime:

**Install from [PyPI](https://pypi.org/project/esphome-device-builder/):**

```bash
python -m venv .venv && source .venv/bin/activate
pip install esphome-device-builder

esphome-device-builder ~/esphome-configs
```

To try a pre-release (beta), pass `--pre` to `pip install`.

The server starts on `http://localhost:6052`. Run with `--help` for the
full flag set.

<details>
<summary>Install from a GitHub release</summary>

Every build is published to PyPI, so the install above is the
preferred path. The same wheels are mirrored on the
[GitHub releases page](https://github.com/esphome/device-builder/releases) —
handy as a fallback if PyPI is unreachable.

```bash
python -m venv .venv && source .venv/bin/activate

# Replace <version> with a release tag (X.Y.Z stable, X.Y.ZbN beta).
pip install "https://github.com/esphome/device-builder/releases/download/<version>/esphome_device_builder-<version>-py3-none-any.whl"

esphome-device-builder ~/esphome-configs
```

</details>

**From source** (requires [uv](https://docs.astral.sh/uv/)):

```bash
git clone https://github.com/esphome/device-builder
cd device-builder
script/setup
source .venv/bin/activate
esphome-device-builder ./configs --log-level debug --dev
```

`--dev` serves `index.html` with `Cache-Control: no-cache` so a
re-deployed frontend wheel isn't masked by a browser-cached SPA
shell pointing at a now-deleted hashed bundle. Hashed bundles
themselves stay `immutable` regardless. Skip `--dev` in production —
the browser's default heuristic is fine when you're not rebuilding
every few minutes.

## Roadmap

- ✅ Standalone backend with WS-first API, persistent compile queue, mDNS device discovery
- ✅ Curated board + component catalogs (nightly catalog sync from upstream ESPHome)
- ✅ Functional parity with the legacy dashboard
  (one intentional decline: the HA Supervisor `/auth` POST flow —
  the new backend's HA add-on path is ingress-only by design, see
  [issue #85](https://github.com/esphome/device-builder/issues/85))
- 🚧 Beta toggle in the official ESPHome container and Home Assistant add-on
- 🗺️ See the
  [project backlog](https://github.com/orgs/esphome/projects/7/views/1?filterQuery=project%3A%22device-builder-dashboard%22)
  for in-progress work and what's planned next

## Documentation

- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — controllers, event bus,
  firmware queue, catalog sync, deployment.
- **[docs/API.md](docs/API.md)** — every WebSocket command, request/response
  shapes, event types.
- **[esphome_device_builder/definitions/README.md](esphome_device_builder/definitions/README.md)** —
  contributor guide for board manifests.

## Contributing

Contributions welcome — board definitions especially
([definitions/README.md](esphome_device_builder/definitions/README.md)).

Every PR needs **exactly one** label from this set so it lands in the right
release-notes section: `breaking-change`, `new-feature`, `enhancement`,
`bugfix`, `refactor`, `docs`, `maintenance`, `ci`, `dependencies`. CI enforces
the rule via [`pr-labels.yaml`](.github/workflows/pr-labels.yaml).

Bugs / feature ideas: open an issue and the chooser will route you to the
right venue (this repo for dashboard bugs, esphome core for compile/firmware
issues, org Discussions for ideas, Discord for chat).

## License

Apache-2.0 — Maintained by [Open Home Foundation](https://www.openhomefoundation.io/).
