diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/core-components.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/core-components.md new file mode 100644 index 0000000000..963108a139 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/core-components.md @@ -0,0 +1,70 @@ +--- +title: Core Components +description: A guide to the Web Server and Accessory Power Rail components that ship enabled by default on the Apollo ESPHome Starter Kit. +--- +# Core Components + +When you create a new Apollo ESPHome Starter Kit project in **ESPHome Device Builder**, two components are included for you by default: + +- **Web Server**, which gives your device its own local web page at `esphome-starter-kit.local`. +- **Accessory Power Rail**, which powers the Onboard RGB LED and any modules connected to the accessory header. + +You don't have to do anything to turn these on. This page explains what each one does, why Apollo ships them enabled, and the settings most users want to know about. + +--- + +## Web Server + +The **Web Server** component runs a small website directly on your ESP32-C6. As soon as your device is on Wi-Fi, you can open esphome-starter-kit.local (or its IP address) on any phone or PC on the same network and control the device. + +Apollo ships it on by default so the kit works without Home Assistant. If you only want a smart LED on your desk, you never have to touch HA, you just visit the device's page in a browser. + +#### Common Settings + +- **Version (v2 vs v3).** The Apollo project pins **Version 3**, the newer single-page interface that loads faster, looks cleaner, and shows controls and sensors in a sensible order. v2 is the older multi-page layout. There's almost no reason to switch back. +- **Port.** Defaults to **80** so plain `esphome-starter-kit.local` works. Change it only if something else on your network is already serving on port 80 and you want to avoid a clash. +- **Username and password.** Off by default. Set them under **Show advanced settings → Auth** if you want to gate the page so anyone on your Wi-Fi can't toggle your LED. Pair this with `secrets.yaml` so the credentials don't sit in your shared YAML. See What is secrets.yaml? for the pattern. +- **OTA over the web page.** The v3 web server can accept firmware uploads straight from the browser. Helpful for quick experiments, but turn it off (or behind auth) if your device sits on an untrusted network. +- **Including/excluding entities.** Advanced setting that lets you hide specific entities from the web page without removing them from Home Assistant. Useful if you have internal helpers you don't want users to see. + +#### Add Component + +If you remove the Web Server component, the device still works, but `esphome-starter-kit.local` will stop responding. To add it back: + +1. In **ESPHome Device Builder**, open your device and go to **Core configuration**. +2. Click **Add component**, scroll to **Web Server**, and click **Add**. +3. Click **Add** once more to confirm. +4. Toggle **Show advanced settings**, scroll to **Version**, and select **3**. + + ESPHome Web Server docs + +--- + +## Accessory Power Rail + +The **Accessory Power Rail** is a software switch that controls power to the kit's accessory header, the connector where the Onboard RGB LED, button, motion, temperature/humidity, and LED/buzzer modules get their 3.3V. + +When the rail is **on**, your modules and the Onboard RGB LED have power and respond. When the rail is **off**, those accessories go dark. The ESP32-C6 itself stays on. + +Apollo ships the rail enabled and set to come back on after a reboot, so the kit "just works" out of the box. The reason it exists as a switch (rather than always-on) is that turning the rail off briefly is the cleanest way to reset a misbehaving module without unplugging the kit, and it can be automated from Home Assistant. + +#### Common Settings + +- **Restore mode.** Controls what happens to the rail when the device powers back on after losing power. The Apollo default is **restore the last state, default to on**, so a power blip won't leave your modules dark. Other options like "always on" or "always off" are available if you want a specific boot behavior. +- **Hide it from Home Assistant.** By default the rail shows up as a controllable switch entity in HA, handy for power-cycling a flaky module from an automation. If you'd rather it not clutter your dashboard, mark it `internal: true` under the advanced settings. +- **Icon and name.** Cosmetic, but you can rename the entity or change its icon if "Accessory Power Rail" isn't how you want it to appear in HA. +- **GPIO pin.** Informational, not something you should change. The pin is fixed in hardware on the ESPHome Starter Kit board, so editing it will just stop the rail from working. + +#### How It Works + +The Accessory Power Rail is an ESPHome **GPIO switch** under the hood. Apollo gives it a friendly name and pre-fills the pin so you don't have to know that, but if you ever want to see the raw configuration, look at the GPIO switch component in the ESPHome docs. + +#### Add Component + +If you remove the rail, **the Onboard RGB LED and any plugged-in modules will stop working properly** because they get their power from it. To add it back: + +1. In **ESPHome Device Builder**, open your device and go to the **Components** section. +2. Click **Add component**, scroll to **Accessory Power Rail**, and click **Add**. +3. Click **Add** once more to confirm. + + ESPHome GPIO Switch docs diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md index fa30cdfc85..968d72b7fe 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md @@ -6,7 +6,7 @@ description: Step by step guide for getting started with the ESPHome Starter Kit This guide walks you through installing the ESPHome Device Builder app, and making your first ESPHome YAML configuration from scratch. -By the end you'll have your ESPHome Starter Kit flashed with a working configuration and showing up in Home Assistant and with a working web server accessible at its IP address or esphome-starter-kit.local in a browser. +By the end you'll have your ESPHome Starter Kit flashed with a working configuration, showing up in Home Assistant, and reachable in a browser at its IP address or esphome-starter-kit.local via its built-in web server. --- @@ -135,31 +135,9 @@ If you make a mistake or want to change this later, click the 3 dots menu in the ### Configure Components -When you install ESPHome Device builder, you will see a list of components under **Core Configuration**. We will add three more components for our tutorial below. +When you create a new ESPHome Starter Kit project in ESPHome Device Builder, the **Web Server** and **Accessory Power Rail** components are already configured for you, so there's nothing extra to do for those. In this tutorial we'll add one more component: the **Onboard RGB LED**. -#### Accessory Power Rail - -The Accessory Power Rail is used behind the scenes to give power to your optional modules including the Onboard RGB LED. - -1. In the ESPHome Device Builder, navigate to the **Components** section. -2. Click **Add component**. -3. Scroll to **Accessory Power Rail** and click **Add**. -4. Click **Add** once more to confirm. - -![](../../../assets/device-builder-add-accessory-power-rail.gif) - -#### Web Server Component - -The Web Server is used to broadcast a local website using your device. This allows you to navigate to the IP address of your device or hostname such as esphome-starter-kit.local to easily control your new device! - -1. In the ESPHome Device Builder, navigate to the **Core configuration** section. -2. Click **Add component**. -3. Scroll to **Web Server** and click **Add**. -4. Click **Add** once more to confirm. -5. Toggle **Show advanced settings**. -6. Scroll down to **Version** and select **3** from the dropdown. - -![](../../../assets/device-builder-install-web-server-v3.gif) + Learn about the Web Server Learn about the Accessory Power Rail #### Onboard RGB LED @@ -209,7 +187,7 @@ Before we continue, confirm that you installed the ESPHome Device Builder, confi ### Test your LED -Above we installed the web\_server component which allows us to navigate to the ip address of our device or the hostname.local such as esphome-starter-kit.local +Your kit's default project includes the web\_server component, which lets you navigate to the IP address of your device or the hostname.local such as esphome-starter-kit.local It should load your new device and show you the Onboard RGB LED. We can click the toggle button to make sure the RGB LED turns on and off on our device! diff --git a/mkdocs.yml b/mkdocs.yml index 5609f413fd..895403091a 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -513,6 +513,7 @@ nav: - 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 + - Core Components: products/ESPHome-Starter-Kit/learning-the-basics/core-components.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: