From 79d75a88d42c025853e443684e517f1d26bf5196 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Mon, 18 May 2026 13:19:24 -0500 Subject: [PATCH] Add Learn the Basics section to ESPHome Starter Kit docs (#820) - New Explaining ESPHome page covering ESPHome vs Device Builder, web server and Home Assistant access, and why the Starter Kit is built on ESPHome - New What is YAML? primer with starter-kit examples and common gotchas - New What is secrets.yaml? concept page paired with the existing Using Secrets tutorial - Trim the Using Secrets tutorial intro to link out to the new concept page - Add a Learn more about ESPHome button under the ESPHome Device Builder heading in First Steps --- .../learning-the-basics/explaining-esphome.md | 48 ++++++++++ .../what-is-secrets-yaml.md | 40 ++++++++ .../learning-the-basics/what-is-yaml.md | 94 +++++++++++++++++++ .../ESPHome-Starter-Kit/setup/first-steps.md | 2 + .../tutorials/using-secrets.md | 11 +-- mkdocs.yml | 4 + 6 files changed, 190 insertions(+), 9 deletions(-) create mode 100644 docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md create mode 100644 docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md create mode 100644 docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md new file mode 100644 index 0000000000..f0609550d5 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md @@ -0,0 +1,48 @@ +--- +title: Explaining ESPHome +description: A short overview of what ESPHome is, how the Device Builder app fits in, and why the ESPHome Starter Kit is built on it. +--- +# Explaining ESPHome + +ESPHome is the open-source firmware project that powers your Apollo ESPHome Starter Kit. You describe what is connected to your board (a button, a sensor, an LED) and ESPHome runs on the device, exposes those parts to Home Assistant, and accepts updates over the network. + +You do not need to write any code to use it. For the Starter Kit, the **ESPHome Device Builder** app does the work for you. + +## ESPHome vs ESPHome Device Builder + +These two names get used interchangeably, but they are different pieces: + +- **ESPHome** is the software that runs on your device after it has been flashed. It is what makes your board talk to Home Assistant, expose its sensors and controls, and accept wireless updates. +- **ESPHome Device Builder** is the app you set everything up in. You pick the components you want (button, LED, sensor, etc.), click **Install**, and the Builder compiles the firmware and flashes it to your device for you. You can run it as a desktop app on Windows, Mac, or Linux, or install it as a Home Assistant app. + +For the Starter Kit, you will spend almost all your time in the Device Builder. + +## How you talk to your device + +Once your device is flashed, there are two ways to interact with it. + +#### From any web browser + +ESPHome's built-in **Web Server** component (the Starter Kit's First Steps walks you through adding it) makes your device serve its own local web page. Open `esphome-starter-kit.local` or its IP address in any browser on your network, on a phone or PC, and you can toggle the LED, view sensor readings, and control everything directly. No Home Assistant required. + +#### From Home Assistant + +Home Assistant discovers your device automatically through the **ESPHome integration**. This surfaces your device's sensors, switches, and lights as entities you can use in dashboards and automations. + +A typical flow looks like this: + +1. In **ESPHome Device Builder**, click **Add component** and pick what is connected to your device. No code or YAML required to get started. +2. Click **Install** to flash the firmware to the device. USB the first time, then wirelessly after that. +3. Home Assistant picks up the device through the **ESPHome integration** and shows its sensors, buttons, and lights as entities you can control or automate. + +If you ever want to fine-tune something the GUI does not expose, the YAML view is always available. It is an option, not a requirement. + +## Why the Starter Kit is built on ESPHome + +ESPHome is part of the **ESPHome ecosystem**, an open-source project with a large community of contributors and direct first-class support in Home Assistant. Apollo builds on **open standards**: public protocols like ESPHome and OpenThread, so your kit is never locked to one vendor. Everything you set up runs under **local control**: your home runs on your own network, and your devices keep working even if your internet goes down or Apollo goes away. + +You get wireless updates, a built-in web page for controlling your device, and direct Home Assistant integration without writing any code. The skills you build on the Starter Kit carry over to any ESPHome project you take on later. + +The official ESPHome documentation covers every component, configuration option, and advanced topic in detail. + + Visit esphome.io Back to First Steps diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md new file mode 100644 index 0000000000..6fd3d6591f --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md @@ -0,0 +1,40 @@ +--- +title: What is secrets.yaml? +description: A short overview of what secrets.yaml is, what it stores, and why ESPHome uses it. +--- +# What is secrets.yaml? + +secrets.yaml is a single file inside **ESPHome Device Builder** that stores values you don't want pasted into every device config: your Wi-Fi password, your Home Assistant API key, OTA passwords, MQTT credentials, and so on. + +You define each value once in secrets.yaml, then reference it from your device YAML using `!secret`: + +```yaml +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password +``` + +When the device compiles, ESPHome substitutes the real value in place of the `!secret` tag. + +## Why it exists + +There are two reasons to use secrets.yaml: + +- **Safety.** You can copy a device YAML to a friend, paste it on a forum, or commit it to a public repo without leaking your Wi-Fi password or API key. The `!secret` references are safe to share. The values they point to never leave your Device Builder. +- **One place to change things.** Rotate a password once in secrets.yaml and every device that references it picks up the new value on the next flash. + +## How it fits in + +secrets.yaml lives inside **ESPHome Device Builder**, not on the device itself. The same secrets file is available to every device you build there. A device only ever sees the substituted values baked into its firmware, not the secrets.yaml file. + +## Good practice + +Treat secrets.yaml like a password manager entry: + +- Don't share or post the file. Share your device YAMLs instead, since the `!secret` references in them are safe. +- Keep a backup somewhere safe (a password manager works well). If you reinstall ESPHome Device Builder, you will need to recreate it. +- Rotating a credential is a one-line edit here, then re-flash anything that uses it. + +Ready to put this into practice? The Using Secrets tutorial walks through opening secrets.yaml in the Device Builder, the `!secret` syntax, and what to store for every common case (Wi-Fi, Home Assistant API, OTA, web server auth, MQTT). + + Using Secrets tutorial Back to First Steps diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md new file mode 100644 index 0000000000..e82c2217a5 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md @@ -0,0 +1,94 @@ +--- +title: What is YAML? +description: A short primer on YAML, the configuration format ESPHome uses, with examples drawn from the ESPHome Starter Kit. +--- +# What is YAML? + +YAML is a plain-text format used to describe configuration in a way that is readable for both people and computers. ESPHome uses YAML to describe what your device is and what it should do. + +You do not have to write YAML yourself when using the **ESPHome Device Builder**. The Builder generates it for you as you click around. Recognising what you are looking at when you peek at the YAML view helps you understand what your device is doing, and a little YAML opens up advanced settings the GUI does not expose. + +## The basics + +YAML is built from three ideas: key-value pairs, indentation, and lists. + +#### Key and value + +Most lines are a name, a colon, then a value: + +```yaml +name: esphome-starter-kit +platform: ESP32 +``` + +#### Indentation groups things together + +Indentation, always with spaces and never tabs, shows which settings belong to which item: + +```yaml +wifi: + ssid: my-wifi-network + password: my-wifi-password +``` + +Here, `ssid` and `password` belong to `wifi`. The two spaces in front are what links them. + +#### Lists use dashes + +A dash at the start of a line means "this is one item in a list": + +```yaml +sensor: + - platform: dht + pin: GPIO4 + - platform: dht + pin: GPIO5 +``` + +That is two sensors, each with its own settings. + +#### Comments + +A `#` starts a comment. Anything after it on that line is ignored, which makes it useful for leaving yourself notes: + +```yaml +# Built-in LED on the ESP32-C6 +light: + - platform: esp32_rmt_led_strip + pin: GPIO8 +``` + +#### Quoting strings + +Most text values do not need quotes. You only need quotes if your value contains special characters, starts with a number, or could be confused for something else (like the word `yes` or `no`). When in doubt, quotes are always safe: + +```yaml +wifi_password: "my-password-with-spaces and symbols!" +``` + +#### Common gotchas + +A few small things trip people up when they start hand-editing YAML. Each of these will cause the Device Builder to refuse to save or compile, so spotting them early saves frustration. + +- **Indentation must be spaces, not tabs.** Most editors handle this, but if you paste from somewhere else and get errors, this is the first thing to check. +- **Be consistent with your indent size.** Two spaces per level is the convention used throughout ESPHome examples. +- **The colon after a key needs a space.** `name: esphome-starter-kit` works; `name:esphome-starter-kit` does not. + +## What this looks like in ESPHome + +When you add the Onboard RGB LED component in the Device Builder, the YAML view shows something like this: + +```yaml +light: + - platform: esp32_rmt_led_strip + name: Onboard RGB LED + pin: GPIO8 + num_leds: 1 + chipset: WS2812 +``` + +You did not type any of that. The Builder wrote it when you clicked **Add**. Once you can read it, you know exactly what your device is doing. + +The official YAML site has the full specification, and the ESPHome docs walk through YAML in the context of ESPHome specifically. + +YAML official site ESPHome YAML guide Back to First Steps diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md index f2257bf40c..fa30cdfc85 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md @@ -16,6 +16,8 @@ ESPHome Device Builder is the software that gives you a user interface for writi Think of it like telling the starter kit about what devices it has connected and how to use them! + Learn more about ESPHome + Pick the platform you'll be running ESPHome Device Builder on: === "Windows" diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md index 037e9aa831..412691ad5f 100644 --- a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md +++ b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md @@ -8,16 +8,9 @@ description: >- 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. ---- - -#### What secrets.yaml is - -secrets.yaml is a single file in ESPHome Device Builder that stores values you don't want pasted into every device config. Two reasons to use it: - -* **Safety.** You can copy a device YAML to a friend, paste it in a forum, or commit it to a public repo without leaking your Wi-Fi password or API key. -* **One place to change things.** Rotate a password once in secrets.yaml and every device that references it picks up the new value on the next flash. +!!! info "New to secrets.yaml?" -secrets.yaml lives inside ESPHome Device Builder, so the same secrets are available to every device you build there. + Read [What is secrets.yaml?](../learning-the-basics/what-is-secrets-yaml.md) first for a quick conceptual overview, then come back here when you're ready to set yours up. --- diff --git a/mkdocs.yml b/mkdocs.yml index 8e94ab9b78..5609f413fd 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -511,6 +511,10 @@ nav: - LED & Buzzer: products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md - Tutorials: - Using Secrets: products/ESPHome-Starter-Kit/tutorials/using-secrets.md + - Learn the Basics: + - Explaining ESPHome: products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md + - What is YAML?: products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md + - What is secrets.yaml?: products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md - Holiday Ornaments: - H-1: - Introduction: products/h1/introduction.md