Skip to main content

Section 2: Setting Up Home Assistant

This section covers how to complete the Home Assistant initial setup (creating an admin account, setting location, etc.) and installing the ESPHome app in HA.

1. Complete the Home Assistant Initial Setup​

  1. On the welcome page, click the language dropdown in the bottom-right corner and select your preferred language.

    Switch Language

  2. Follow the guided steps to complete:

    • Create admin account: Set up a username and password.

    • Set location and time zone: Affects sunrise/sunset, weather, automations, and other location-based features.

    • Data sharing: Whether to send anonymous usage statistics to the Home Assistant project. Optional — can be changed at any time in settings.

    • Device discovery: HA will scan the local network for supported devices (routers, smart home brands, etc.). Simply click Finish to complete the initial setup — this tutorial does not depend on this step.

      Create Admin Account

  3. After clicking "Finish," you will be automatically redirected to the default dashboard. Home Assistant initial setup is now complete.

    Default Dashboard

2. Install the ESPHome App​

ESPHome runs as a Home Assistant app.

  1. In the HA main interface, click Settings → Apps in the bottom-left corner.

    Navigate to Apps Page

  2. Click the Install App button in the bottom-right corner.

    ESPHome Search Results

    Type ESPHome in the search box, find ESPHome Device Builder, and click to open it.

    ESPHome App Details Page

  3. Click Install.

    First Installation Requires Waiting

    The first installation pulls the ESPHome image from GitHub Container Registry and extracts it, which may take more than 10 minutes. You can click "Log" to view the installation progress.

    ESPHome App Installing

  4. After installation completes, it is recommended to enable the following options, then click Start to start the ESPHome app:

    • Start on boot: Automatically start the ESPHome app when HA starts.
    • Auto restart: Automatically restart the app if it unexpectedly exits.
    • Show in sidebar: Add a permanent ESPHome entry to the HA left sidebar.
    App Options

  5. After starting, click ESPHome Builder in the sidebar (or click Open Web UI on the app page). Seeing the ESPHome welcome page confirms the app is running properly.

    ESPHome App Started
    ESPHome Web UI Welcome Page

ESPHome is now ready. The next section will use the ESP32-S3-Zero as an example to create and flash your first device in ESPHome.

3. Common Issues in This Section​

  • App store list is empty / won't load: HA may be unable to communicate with GitHub. Check if HA can access the internet.
  • ESPHome app installation stuck at a certain progress: The ghcr.io image download may have failed. Check the specific error in the app page → Log.
  • ESPHome entry not visible in the sidebar: The "Show in sidebar" option was not enabled. Go back to the app page to enable it, then refresh the browser.
  • Clicking "Open Web UI" has no response or shows an error: The app may not be started. Click Start on the app page and wait for Dashboard is running on port 6052 to appear in the "Log."

4. References​