diff --git a/docs/assets/esphome-builder-enter-wifi-credentials.gif b/docs/assets/esphome-builder-enter-wifi-credentials.gif new file mode 100755 index 0000000000..c038e765c4 Binary files /dev/null and b/docs/assets/esphome-builder-enter-wifi-credentials.gif differ diff --git a/docs/products/ESPHome-Starter-Kit/buttongettingstarted.md b/docs/products/ESPHome-Starter-Kit/buttongettingstarted.md deleted file mode 100755 index c62cc840c9..0000000000 --- a/docs/products/ESPHome-Starter-Kit/buttongettingstarted.md +++ /dev/null @@ -1,279 +0,0 @@ -# ESPHome Starter Kit - Button Getting Started - -# Setting Up Your Device - -1. Opening Box -2. Identifying the ESP32 board -3. Identifying the button module -4. Plugging in the button module -5. Connecting ESP32 to your computer - -# Setting Up ESPHome Device Builder - -1. Connect to HA ( link to HA getting started ) -2. Install app here -3. Install driver? -4. View it here -5. Creating secrets file for wifi -6. Adding new device from bottom right - -Now you have a new device, lets make YAMLLLLLL - -# Writing Your First ESPHome Configuration - -This guide walks you through building an ESPHome YAML configuration from scratch. By the end, you'll understand each section and have your Apollo Button Dev Kit connected to Home Assistant. - ---- - -## Understanding ESPHome YAML Structure - -ESPHome configurations are written in YAML, a human-readable format that uses indentation to define structure. Each section controls a different aspect of your device's behavior. - -!!! tip "YAML Basics" - Indentation matters - ---- - -## 1\. Substitutions - -Substitutions are variables you define once and reuse throughout your configuration. This keeps your code clean and makes updates simple. In the ESPHome device builder, add this to your YAML config ( picture/link for help ) - -```yaml -substitutions: - name: apollo-button-1 - version: "24.7.15.1" - device_description: ${name} made by Apollo Automation - version ${version}. -``` - -\| Variable \| Purpose \| \|----------\|---------\| \| `name` \| Device identifier used in ESPHome and Home Assistant \| \| `version` \| Track your firmware version. Example is Year.Month.Day.1 \| \| `device_description` \| Human-readable description (note how it references other variables with `${}`) \| - -!!! note "Using Substitutions" Reference any substitution elsewhere in your config using `${variable_name}` syntax. - ---- - -## 2\. ESPHome Core Configuration - -This section defines how your device appears in ESPHome and Home Assistant. - -```yaml -esphome: - name: "${name}" - friendly_name: Apollo Button Dev Kit - comment: Apollo Button Dev Kit - name_add_mac_suffix: true - platformio_options: - board_build.flash_mode: dio - - project: - name: "ApolloAutomation.ButtonDev-1" - version: "${version}" - min_version: 2024.6.0 -``` - -**Key options explained:** - -\| Option \| Description \| \|--------\|-------------\| \| `name` \| Internal device name (pulled from substitutions) \| \| `friendly_name` \| The name displayed in Home Assistant's UI \| \| `comment` \| Optional description shown in ESPHome dashboard \| \| `name_add_mac_suffix` \| Adds unique MAC address suffix—useful when flashing multiple identical devices \| \| `platformio_options` \| Low-level build settings (DIO flash mode for ESP32-C6) \| \| `project` \| Identifies this as an Apollo Automation device for updates \| \| `min_version` \| Ensures compatibility with ESPHome features used \| - ---- - -## 3\. ESP32 Board Definition - -Tell ESPHome which microcontroller you're using. - -```yaml -esp32: - board: esp32-c6-devkitm-1 - variant: esp32c6 - flash_size: 8MB - framework: - type: esp-idf -``` - -\| Option \| Description \| \|--------\|-------------\| \| `board` \| The specific development board type \| \| `variant` \| ESP32 chip variant (C6 in this case) \| \| `flash_size` \| Available flash memory \| \| `framework` \| Build framework—ESP-IDF is recommended for ESP32-C6 \| - -!!! warning "Framework Note" The ESP32-C6 requires `esp-idf` framework. The older `arduino` framework is not fully supported on this chip. - ---- - -## 4\. Home Assistant API - -This single line enables the native Home Assistant API connection. - -```yaml -api: -``` - -That's it! ESPHome handles the encryption and connection automatically. Once your device is online, Home Assistant will discover it. - -!!! info "Encryption" By default, ESPHome generates an encryption key on first install. You'll see this key in the ESPHome dashboard logs during initial setup. - ---- - -## 5\. WiFi Configuration - -Configure how your device connects to your network. - -```yaml -wifi: - # Enable fallback hotspot (captive portal) in case wifi connection fails - ap: - ssid: "Apollo Button Hotspot" -``` - -This minimal configuration creates a **fallback hotspot**. If the device can't connect to WiFi, it broadcasts its own network you can join to configure it. - -### Optional: Hardcode Your WiFi Credentials - -```yaml -wifi: - ssid: "Your_WiFi_Name" - password: "Your_WiFi_Password" - - # Fallback hotspot - ap: - ssid: "Apollo Button Hotspot" -``` - -!!! tip "Secrets File" For better security, store credentials in a separate `secrets.yaml` file: `yaml wifi: ssid: !secret wifi_ssid password: !secret wifi_password ` - ---- - -## 6\. Captive Portal - -Works with the fallback hotspot to provide a web-based configuration interface. - -```yaml -captive_portal: -``` - -When connected to the fallback hotspot, your phone or computer will automatically open a configuration page where you can enter your WiFi credentials. - ---- - -## 7\. Logger - -Enables logging output for debugging. \*What is logger - -```yaml -logger: -``` - -Logs appear in the ESPHome dashboard when viewing device logs. Useful for troubleshooting connection issues or sensor problems. - ---- - -## 8\. Binary Sensors - -Now let's add some actual functionality—sensors that report on/off states. \*What is binart sensor - -```yaml -binary_sensor: - - platform: status - name: Online - id: ink_ha_connected - - - platform: gpio - pin: - number: GPIO9 - inverted: true - mode: - input: true - pullup: true - id: reset_button - name: "Button" -``` - -### Status Sensor - -```yaml -- platform: status - name: Online - id: ink_ha_connected -``` - -Reports whether the device is connected to Home Assistant. Useful for automations that check device availability. - -### Physical Button - -\*Explain this is the GPIO connected to the button module - -```yaml -- platform: gpio - pin: - number: GPIO9 - inverted: true - mode: - input: true - pullup: true - id: my_button - name: "Button" -``` - -\| Option \| Description \| \|--------\|-------------\| \| `platform: gpio` \| A simple digital input \| \| `number: GPIO9` \| The physical pin the button is connected to \| \| `inverted: true` \| Button reads LOW when pressed (active-low) \| \| `pullup: true` \| Enables internal pull-up resistor \| \| `id` \| Internal reference for use in automations \| \| `name` \| How it appears in Home Assistant \| - ---- - -## Complete Configuration - -Here's everything together: - -```yaml -substitutions: - name: apollo-button-1 - version: "24.7.15.1" - device_description: ${name} made by Apollo Automation - version ${version}. - -esphome: - name: "${name}" - friendly_name: Apollo Button Dev Kit - comment: Apollo Button Dev Kit - name_add_mac_suffix: true - platformio_options: - board_build.flash_mode: dio - - project: - name: "ApolloAutomation.ButtonDev-1" - version: "${version}" - min_version: 2024.6.0 - -esp32: - board: esp32-c6-devkitm-1 - variant: esp32c6 - flash_size: 8MB - framework: - type: esp-idf - -api: - -wifi: - ap: - ssid: "Apollo Button Hotspot" - -captive_portal: - -logger: - -binary_sensor: - - platform: status - name: Online - id: ink_ha_connected - - - platform: gpio - pin: - number: GPIO9 - inverted: true - mode: - input: true - pullup: true - id: my_button - name: "Button" -``` - ---- - -## Next Steps - -* **Flash your device** using the ESPHome dashboard -* **Add it to Home Assistant** when prompted -* **Create automations** using your new button entity - -!!! success "You Did It!" You've written your first ESPHome configuration from scratch. The button will now appear in Home Assistant as a binary sensor you can use in automations. \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/first-steps.md b/docs/products/ESPHome-Starter-Kit/first-steps.md index 30c515dd9c..0a7432da69 100755 --- a/docs/products/ESPHome-Starter-Kit/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/first-steps.md @@ -13,7 +13,7 @@ By the end of this wiki you'll know how to: ## What's in the kit -Your kit arrives as a single snap-apart panel that contains the ESP32-C6 main board and a set of modules you can mix and match. +Your kit arrives as a single snap-apart panel that includes the ESP32-C6 main board along with a selection of interchangeable modules. The kit also includes three ribbon cables used to connect the modules together. ![](../../assets/starter-kit-graphic.png) @@ -27,10 +27,9 @@ Each module is connected to the panel by small breakaway tabs. Follow the steps 1. Hold the panel flat on a table with one hand on the module you want to remove. 2. Gently flex the panel along the tab line until the tab snaps cleanly. -3. If a tab leaves a small nub on the module, you can file or sand it smooth. It will not affect how the module works. @@ -41,7 +40,7 @@ The kit includes: * **ESP32-C6 main board.** The brain of every project you'll build with the kit. It handles Wi-Fi and Bluetooth, runs your ESPHome config, and exposes the GPIO pins the modules plug into. * **Motion module.** Detects movement in a room and a great way to get started automating your home. Comes with a separate 3 pin header and PIR motion sensor. * **Button module.** Premium feel button perfect to trigger automations for lights and more. -* **Temperature and Humidity module.** Temperature and humidity module shipped with the starter kit. Extremely accurate temp and humidity sensor trustworthy enough to track a room comfort level with ease! +* **Temperature and Humidity module.** Extremely accurate temp and humidity sensor trustworthy enough to track a room comfort level with ease! Each module connects to the ESP32-C6 board through the FPC connectors which are the thin white ribbon cables. diff --git a/docs/products/ESPHome-Starter-Kit/setup/getting-started.md b/docs/products/ESPHome-Starter-Kit/setup/getting-started.md index 859f9f4845..1dde1cc2a5 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/getting-started.md +++ b/docs/products/ESPHome-Starter-Kit/setup/getting-started.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 writing 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 hostname.local in a browser. +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. --- @@ -18,34 +18,16 @@ Think of it like telling the starter kit about what devices it has connected and Pick the platform you'll be running ESPHome Device Builder on: -=== "Home Assistant App" - - The ESPHome Device Builder runs as a Home Assistant app served right inside your existing HA dashboard. This is the easiest option if you already run Home Assistant OS or a supervised install. - - 1. In Home Assistant, open **Settings → Apps → App Store**. - 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. - - - - !!! info "Already on the new layout" - - The HA app version of Device Builder is already the new beta backend, so you can skip the backend toggle and browser refresh shown in the desktop tabs. - === "Windows" 1. Download the ESPHome Device Builder for Windows. - 2. Open the installer and click **Next** then click **Next** again to start the installation process. Once it shows completed, click **Next** again then **Finish** to complete the installation. - - - If Windows shows a blue **Windows protected your PC** warning, click **More info → Run anyway** to continue. + * If Windows shows a blue **Windows protected your PC** warning, click **More info → Run anyway** to continue. ![](../../../assets/esphome-builder-install-windows.gif) 3. 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. - - - Use a Chromium-based browser such as Chrome or Edge. Firefox does not yet support WebSerial, which is required for the initial flashing of the device over USB. If Firefox is your default, copy the URL into Chrome or Edge instead. - + * Use a Chromium-based browser such as Chrome or Edge. Firefox does not yet support WebSerial, which is required for the initial flashing of the device over USB. If Firefox is your default, copy the URL into Chrome or Edge instead. 4. Navigate to the **system tray** (bottom right of your Windows taskbar). Hover over **Backend** and switch from Classic to the ESPHome Builder Beta with the new layout and features. ![](../../../assets/esphome-builder-backend-switch-to-beta.gif) @@ -77,6 +59,20 @@ Pick the platform you'll be running ESPHome Device Builder on: 5. Wait 30+ seconds, then refresh your browser. You should now see the new ESPHome Device Builder Preview. +=== "Home Assistant App" + + The ESPHome Device Builder runs as a Home Assistant app served right inside your existing HA dashboard. This is the easiest option if you already run Home Assistant OS or a supervised install. + + 1. In Home Assistant, open **Settings → Apps → App Store**. + 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. + + + + !!! info "Already on the new layout" + + The HA app version of Device Builder is already the new beta backend, so you can skip the backend toggle and browser refresh shown in the desktop tabs. + === "Linux" 1. Download the ESPHome Device Builder for Linux. Pick the package that fits your distro: @@ -103,20 +99,17 @@ Pick the platform you'll be running ESPHome Device Builder on: 5. Wait 30+ seconds, then refresh your browser. You should now see the new ESPHome Device Builder Preview. -### Fill in your Wi-Fi secrets +### Set up Wi-Fi Credentials + +1\. Fill in your Wi-Fi network name (SSID) and Wi-Fi password then click Save credentials. -ESPHome keeps your Wi-Fi credentials in a separate `secrets.yaml` file so they aren't pasted into every device config. +![](../../../assets/esphome-builder-enter-wifi-credentials.gif) -1. In the ESPHome Device Builder dashboard, click **Secrets** in the top right. -2. Add your Wi-Fi name and password: +2\. 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. -```yaml -# Replace the values inside the quotes with your own Wi-Fi name and password. -wifi_ssid: "your-wifi-ssid-here" -wifi_password: "your-wifi-password-here" -``` +!!! tip "Protip: You can put all kinds of credentials here that you want kept secret!" -1. Click **Save**. + 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! ### Add a new device diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md new file mode 100644 index 0000000000..dfb91821d4 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md @@ -0,0 +1,226 @@ +--- +title: Using secrets.yaml +description: Store API encryption keys, OTA passwords, MQTT credentials, and more in a single secrets.yaml file so they stay out of your device configs. +--- +# Using `secrets.yaml` + +In [Getting Started](../setup/getting-started.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. + +`secrets.yaml` lives inside ESPHome Device Builder, so the same secrets are available to every device you build there. + +--- + +## 1. Open `secrets.yaml` + +In the ESPHome Device Builder dashboard, click **Secrets** in the top right. + +![](../../../assets/esphome-device-builder-click-secrets.gif) + +You'll see a YAML file with one key per line. If you followed Getting Started you should already see `wifi_ssid` and `wifi_password` here. + +![](../../../assets/esphome-device-builder-secrets.png) + +--- + +## 2. The syntax + +Each entry in `secrets.yaml` is a `key: "value"` pair: + +```yaml +my_secret_name: "the value goes here" +``` + +In your device YAML, reference it with `!secret` followed by the key name: + +```yaml +some_option: !secret my_secret_name +``` + +When the device compiles, ESPHome substitutes the value from `secrets.yaml` in place of the `!secret` tag. + +!!! warning "The key has to exist" + + If you reference `!secret some_name` in a device config but `some_name` isn't defined in `secrets.yaml`, the build will fail. Spelling counts. + +--- + +## 3. What to put in `secrets.yaml` + +Each section below shows the line you add to `secrets.yaml` and the line in your device YAML that references it. + +### Wi-Fi credentials + +You set these up in [Getting Started](../setup/getting-started.md). They're the baseline every device needs. + +In `secrets.yaml`: + +```yaml +wifi_ssid: "your-wifi-ssid-here" +wifi_password: "your-wifi-password-here" +``` + +In your device YAML: + +```yaml +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password +``` + +### Fallback hotspot password + +If you want the device's fallback hotspot to require a password instead of being open, store that here too. + +In `secrets.yaml`: + +```yaml +ap_password: "fallback-hotspot-password" +``` + +In your device YAML: + +```yaml +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + ap: + ssid: "Apollo ESK-1 Hotspot" + password: !secret ap_password +``` + +### 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`. + +In `secrets.yaml`: + +```yaml +api_encryption_key: "your-32-byte-base64-key-here" +``` + +In your device YAML: + +```yaml +api: + encryption: + key: !secret api_encryption_key +``` + +!!! tip "Reuse the same key across devices" + + Using the same `api_encryption_key` for every Apollo device on your network is fine and keeps your secrets file short. Home Assistant prompts for the key the first time it discovers a device, then remembers it. + +### OTA password + +OTA (over-the-air) updates let you re-flash a device wirelessly after the first USB flash. The password protects that endpoint so a stranger on your network can't push firmware to your device. + +In `secrets.yaml`: + +```yaml +ota_password: "a-long-random-string" +``` + +In your device YAML: + +```yaml +ota: + - platform: esphome + password: !secret ota_password +``` + +### Web server username and password + +If you enable the optional `web_server:` component to access your device at `http://device-name.local/`, you can require a login. + +In `secrets.yaml`: + +```yaml +web_server_username: "admin" +web_server_password: "a-strong-password" +``` + +In your device YAML: + +```yaml +web_server: + port: 80 + auth: + username: !secret web_server_username + password: !secret web_server_password +``` + +### MQTT broker, username, and password + +If you publish to an MQTT broker instead of (or in addition to) the Home Assistant API, all three of these belong in `secrets.yaml`. + +In `secrets.yaml`: + +```yaml +mqtt_broker: "192.168.1.50" +mqtt_username: "esphome" +mqtt_password: "broker-password" +``` + +In your device YAML: + +```yaml +mqtt: + broker: !secret mqtt_broker + username: !secret mqtt_username + password: !secret mqtt_password +``` + +--- + +## 4. A complete `secrets.yaml` example + +Putting it all together, a fully loaded `secrets.yaml` looks like this: + +```yaml +# Wi-Fi +wifi_ssid: "your-wifi-ssid-here" +wifi_password: "your-wifi-password-here" +ap_password: "fallback-hotspot-password" + +# Home Assistant API +api_encryption_key: "your-32-byte-base64-key-here" + +# OTA updates +ota_password: "a-long-random-string" + +# Web server auth +web_server_username: "admin" +web_server_password: "a-strong-password" + +# MQTT +mqtt_broker: "192.168.1.50" +mqtt_username: "esphome" +mqtt_password: "broker-password" +``` + +You don't have to include every entry. If a device doesn't use MQTT, leave those lines out (or leave them in for the next device, the unused ones are harmless). + +--- + +## Good practice + +!!! info "Treat `secrets.yaml` like a password manager" + + * Don't share or post the file. Share device YAMLs instead, the `!secret` references are safe. + * Keep a backup somewhere safe (a password manager works well). If you reinstall ESPHome Device Builder you'll need to recreate it. + * Rotating a credential is a one-line edit here, then re-flash anything that uses it. + +## Next steps + +* Re-flash your device in ESPHome Device Builder after editing `secrets.yaml` so the new values take effect. +* Browse [Apollo's other product wikis](https://wiki.apolloautomation.com) for examples of these secrets in real device configs. +* Join the [Apollo Discord](https://link.apolloautomation.com/discord) if you get stuck. diff --git a/mkdocs.yml b/mkdocs.yml index c2d4059004..60f3094f36 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -503,6 +503,8 @@ nav: - ESPHome Starter Kit: - First Steps: products/ESPHome-Starter-Kit/first-steps.md - Getting Started: products/ESPHome-Starter-Kit/setup/getting-started.md + - Tutorials: + - Using Secrets: products/ESPHome-Starter-Kit/tutorials/using-secrets.md - Holiday Ornaments: - H-1: - Introduction: products/h1/introduction.md