diff --git a/docs/assets/device-builder-add-onboard-rgb-led-component.gif b/docs/assets/device-builder-add-onboard-rgb-led-component.gif
index f94f356607..9bfe07a80d 100755
Binary files a/docs/assets/device-builder-add-onboard-rgb-led-component.gif and b/docs/assets/device-builder-add-onboard-rgb-led-component.gif differ
diff --git a/docs/assets/device-builder-first-time-install-pick-your-experience.gif b/docs/assets/device-builder-first-time-install-pick-your-experience.gif
new file mode 100644
index 0000000000..cb3ab04222
Binary files /dev/null and b/docs/assets/device-builder-first-time-install-pick-your-experience.gif differ
diff --git a/docs/assets/device-builder-native-api-show-api-key.gif b/docs/assets/device-builder-native-api-show-api-key.gif
new file mode 100644
index 0000000000..f00c419fb8
Binary files /dev/null and b/docs/assets/device-builder-native-api-show-api-key.gif differ
diff --git a/docs/assets/device-builder-select-esk-name-it.gif b/docs/assets/device-builder-select-esk-name-it.gif
deleted file mode 100755
index 0fbbbba189..0000000000
Binary files a/docs/assets/device-builder-select-esk-name-it.gif and /dev/null differ
diff --git a/docs/assets/device-builder-select-kit-name-kit-add-wifi.gif b/docs/assets/device-builder-select-kit-name-kit-add-wifi.gif
new file mode 100644
index 0000000000..d774b7ab03
Binary files /dev/null and b/docs/assets/device-builder-select-kit-name-kit-add-wifi.gif differ
diff --git a/docs/assets/esphome-builder-enter-wifi-credentials.gif b/docs/assets/esphome-builder-enter-wifi-credentials.gif
deleted file mode 100755
index c038e765c4..0000000000
Binary files a/docs/assets/esphome-builder-enter-wifi-credentials.gif and /dev/null differ
diff --git a/docs/assets/esphome-device-builder-click-secrets.gif b/docs/assets/esphome-device-builder-click-secrets.gif
index a7cdc25c46..7b7318c753 100755
Binary files a/docs/assets/esphome-device-builder-click-secrets.gif and b/docs/assets/esphome-device-builder-click-secrets.gif differ
diff --git a/docs/assets/esphome-device-builder-preview-image.png b/docs/assets/esphome-device-builder-preview-image.png
deleted file mode 100755
index 3ef2ba7b22..0000000000
Binary files a/docs/assets/esphome-device-builder-preview-image.png and /dev/null differ
diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md
index 149501edfb..aad5d65e58 100755
--- a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md
+++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md
@@ -47,13 +47,9 @@ Pick the platform you'll be running ESPHome Device Builder on:
- Once installed, a web browser should launch and navigate to http://localhost:6052/. Once you see this page, your ESPHome Device Builder installation is complete.
+ Once installed, a web browser should launch and navigate to http://localhost:6052/. On first launch, ESPHome Device Builder asks how you will use it. Select **Build and manage devices**, then select **New to ESPHome** and click **Finish**.
- !!! info "Browser support"
-
- WebSerial is required for the first USB flash. Chrome, Edge, and the latest version of Firefox all support it. Older Firefox builds do not.
-
- 
+ 
=== "Mac"
@@ -68,13 +64,9 @@ Pick the platform you'll be running ESPHome Device Builder on:
- Once installed, a web browser should launch and navigate to http://localhost:6052/. Once you see this page, your ESPHome Device Builder installation is complete.
-
- !!! info "Browser support"
-
- WebSerial is required for the first USB flash. Chrome, Edge, and the latest version of Firefox all support it. Older Firefox builds do not. Safari does not support WebSerial.
+ Once installed, a web browser should launch and navigate to http://localhost:6052/. On first launch, ESPHome Device Builder asks how you will use it. Select **Build and manage devices**, then select **New to ESPHome** and click **Finish**.
- 
+ 
=== "Home Assistant App"
@@ -92,8 +84,6 @@ Pick the platform you'll be running ESPHome Device Builder on:
2. Search for **ESPHome Device Builder** and click **Install**.
3. Once installed, click **Start**, then **Open Web UI**. The Device Builder will open inside your Home Assistant dashboard.
- 
-
=== "Linux"
1. Open esphome.io/install. The page opens on the **Linux** tab and shows **Download .deb** as the default. Click **Download .deb** to grab the Debian / Ubuntu package.
@@ -126,29 +116,9 @@ Pick the platform you'll be running ESPHome Device Builder on:
- **.rpm (Fedora / RHEL):** `sudo dnf install ./ESPHome.Builder*.rpm`
- **AppImage (any distro):** `chmod +x ESPHome.Builder_*.AppImage` then double-click the file, or run it from a terminal.
- Once installed, a web browser should launch and navigate to http://localhost:6052/. Once you see this page, your ESPHome Device Builder installation is complete.
-
- !!! info "Browser support"
-
- WebSerial is required for the first USB flash. Chrome, Edge, and the latest version of Firefox all support it. Older Firefox builds do not.
-
- 
-
-#### Set up Wi-Fi Credentials
-
-Fill in your Wi-Fi network name (SSID) and Wi-Fi password then click Save credentials. *The password is case sensitive so be careful when entering your password.*
-
-!!! tip "Secrets Folder"
-
- One popular option is to store your encryption keys here. That way, you can share your full YAML with other users without needing to edit and hide your encryption key. See our using secrets wiki for step by step directions!
-
-
-
-If you make a mistake or want to change this later, click the 3 dots menu in the top right then select Secrets. Click the Eye icon to unhide the Wi-Fi SSID and password and change them then click Save in the bottom right.
-
-!!! tip "Get busy!"
+ Once installed, a web browser should launch and navigate to http://localhost:6052/. On first launch, ESPHome Device Builder asks how you will use it. Select **Build and manage devices**, then select **New to ESPHome** and click **Finish**.
- You are done with the install guide and can now use the kit!
+ 
#### Add a new device
@@ -158,13 +128,14 @@ If you make a mistake or want to change this later, click the 3 dots menu in the
-2\. Select the Apollo ESPHome Starter Kit and give it a name such as esphome-starter-kit then click **Finish Setup**. (1)
+2\. Select the Apollo ESPHome Starter Kit and give it a name such as esphome-starter-kit, then click **Next**. (1) Type in your Wi-Fi network name (SSID) and Wi-Fi password, then click **Finish Setup**. (2)
1. Remember the name you choose. You'll use it later to reach your device's web server at `http://your-name.local` (for example, http://esphome-starter-kit.local/).
+2. The password is case sensitive, so double-check it before you continue.
-
+
### Configure Components
@@ -181,7 +152,6 @@ The Onboard RGB LED is a small LED above the Reset button of your ESP32-C6. Usef
1. In the ESPHome Device Builder, navigate to the **Components** section.
2. Click **Add component**.
3. Scroll to **Onboard RGB LED** and click **Add**.
-4. Click **Add** once more to confirm.
diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md
index 2a49a2b822..fef5bffdf8 100644
--- a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md
+++ b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md
@@ -6,7 +6,7 @@ description: >-
---
# Using Secrets
-In [First Steps](../setup/first-steps.md) you saved your Wi-Fi name and password in secrets.yaml. That same file can hold every other sensitive value your device needs, from your Home Assistant API key to your MQTT password. This tutorial walks through what to put in there and how to reference it from your device YAML.
+When you set up your kit in [First Steps](../setup/first-steps.md), the Device Builder saved the Wi-Fi name and password you typed in to secrets.yaml. That same file can hold every other sensitive value your device needs, from your Home Assistant API key to your MQTT password. This tutorial walks through what to put in there and how to reference it from your device YAML.
!!! info "New to secrets.yaml?"
@@ -16,13 +16,15 @@ In [First Steps](../setup/first-steps.md) you saved your Wi-Fi name and password
### Open Secrets
-In the ESPHome Device Builder dashboard, click the 3 dots menu in the top right then **Secrets.**
+
-
+In the ESPHome Device Builder dashboard, click the 3 dots menu in the top right then **Secrets.** (1)
+
+
-You'll see a YAML file with one key per line. If you followed First Steps you should already see `wifi_ssid` and `wifi_password` here.
+1. You'll see a YAML file with one key per line. If you followed First Steps you should already see `wifi_ssid` and `wifi_password` here.
-
+
---
@@ -48,6 +50,26 @@ When the device compiles, ESPHome substitutes the value from secrets.yaml in pla
---
+### Make a Secret in the GUI
+
+
+
+The Device Builder can turn a value into a secret for you, no hand editing required. The API encryption key is the perfect first candidate:
+
+1. Open your device in the ESPHome Device Builder and click the **Core configuration** tab.
+2. Click **Native API**. Your device's API key is shown here. Click the eye icon to reveal it.
+3. Click **Use secret**, then select **Make secret esphome_starter_kit__encryption_key**. (1)
+
+
+
+1. The secret is named after your device, so if you named your kit something else, the entry will match that name instead.
+
+The Device Builder moves the key into secrets.yaml and swaps the device YAML over to a `!secret` reference. You can now share your device YAML without exposing the key.
+
+
+
+---
+
### What to store
Each section below shows the line you add to secrets.yaml and the line in your device YAML that references it.
@@ -94,7 +116,7 @@ wifi:
#### Home Assistant API encryption key
-ESPHome encrypts the connection between your device and Home Assistant. The key is a 32-byte base64 string. The easiest way to get one is to let ESPHome Device Builder generate it for you when you first add the `api:` block, then copy that value into secrets.yaml.
+ESPHome encrypts the connection between your device and Home Assistant. The key is a 32-byte base64 string, and the Device Builder generates one for every new device. The easiest way to make it a secret is the **Use secret** button covered in [Make a Secret in the GUI](#make-a-secret-in-the-gui) above, which names the entry after your device. If you'd rather add it by hand, it looks like this:
In secrets.yaml: