From c4148445f43815ebbdeb7dcc584616a81c92218c Mon Sep 17 00:00:00 2001 From: bharvey88 <68635811+bharvey88@users.noreply.github.com> Date: Tue, 5 May 2026 15:06:51 -0500 Subject: [PATCH] ESK-1: build out first-steps and getting-started pages Replace placeholder content on the ESPHome Starter Kit landing page and its getting-started walkthrough. Adds the canonical ESPHome logo (sourced from esphome/esphome-docs) so the first-steps page can render a branded call-to-action button linking forward to the build guide. Pages are not added to the mkdocs.yml nav yet, they remain reachable only via direct URL/QR until ready to publish. --- docs/assets/esphome-logo.svg | 1 + .../ESPHome-Starter-Kit/first-steps.md | 52 +++- .../setup/getting-started.md | 293 +++++++++++++++++- 3 files changed, 330 insertions(+), 16 deletions(-) create mode 100644 docs/assets/esphome-logo.svg diff --git a/docs/assets/esphome-logo.svg b/docs/assets/esphome-logo.svg new file mode 100644 index 000000000..038b632c3 --- /dev/null +++ b/docs/assets/esphome-logo.svg @@ -0,0 +1 @@ + \ 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 9a207f5f5..b38195fc0 100755 --- a/docs/products/ESPHome-Starter-Kit/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/first-steps.md @@ -2,24 +2,54 @@ title: ESPHome Starter Kit - First Steps description: Landing page of the ESPHome Starter Kit QR Code. --- -Welcome to the start of your ESPHome journey with the all new ESPHome Starter Kit! -By the end of this wiki you will know how to ***identify*** each part of the kit, how to ***snap*** each part off of the kit, +# Welcome to the ESPHome Starter Kit -  +Welcome to the start of your ESPHome journey with the all-new **ESPHome Starter Kit**! -1. Landing page +By the end of this wiki you'll know how to: -Welcome to the starter kit +- Identify each part of your kit +- Snap the modules off the panel safely +- Get your ESP32-C6 board on Wi-Fi and talking to Home Assistant +- Write your very first ESPHome YAML config from scratch -Picture of panel identifying the different modules +## What's in the kit -How to break panel apart +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. -What the C6 & other contents are ( PIR sensor ) + -Then move to getting started +![](/assets/esk-1-panel-callouts.png) -  +## Snapping the panel apart -[ ::](null){ } \ No newline at end of file +Each module is connected to the panel by small breakaway tabs. To separate them: + +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. + +!!! warning "Take it slow" + + Bend the panel a little at a time rather than forcing it. The PCB is rigid but the components on the modules can be damaged by sharp impacts or twisting. + +## Meet the modules + +The kit includes: + +- **ESP32-C6 main board.** The brain of every project you'll build with the kit. It handles Wi-Fi, runs your ESPHome config, and exposes the GPIO pins the modules plug into. +- **PIR motion sensor module.** Detects movement in a room. + + + +Each module connects to the ESP32-C6 board through the kit's pin headers. You don't need to solder anything to get started. + +## Next: bring it online + +Once you've identified your modules and snapped them off the panel, the next step is to connect the ESP32-C6 to your computer and walk through your first ESPHome configuration. + + + + Open ESPHome Getting Started + diff --git a/docs/products/ESPHome-Starter-Kit/setup/getting-started.md b/docs/products/ESPHome-Starter-Kit/setup/getting-started.md index 5b63d0aea..d4478a6b7 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/getting-started.md +++ b/docs/products/ESPHome-Starter-Kit/setup/getting-started.md @@ -2,12 +2,295 @@ title: Getting Started with the ESPHome Starter Kit description: Step by step guide for getting started with the ESPHome Starter Kit --- -# ESPHome Starter Kit - Button Getting Started -  +# ESPHome Starter Kit - Getting Started -Downloading ESPHome program +This guide walks you through setting up the hardware in your kit, installing the ESPHome Device Builder add-on in Home Assistant, and writing your first ESPHome YAML configuration from scratch. -Plugging in C6 ( need to press boot/reset ) first time +By the end you'll have your ESP32-C6 board flashed with a working configuration and showing up in Home Assistant. -Walkthrough of creating new device, naming, adding wifi info, \ No newline at end of file +--- + +## 1. Setting up your device + +### Identify the ESP32-C6 board + +The ESP32-C6 is the main board in your kit. It is the small module with the USB-C port on one edge and a row of pin headers along the side. Every project you build with the kit starts here. + + + +### Plug a module into the C6 + +For your first project, snap a module off the panel and plug it into the matching pin headers on the ESP32-C6 board. + + + +### Connect the C6 to your computer + +Plug the ESP32-C6 into your computer using a USB-C cable. + +!!! tip "First-time flashing" + + The very first time you flash an ESP32-C6, you may need to put it into bootloader mode manually: + + 1. Hold down the **BOOT** button on the C6. + 2. While still holding **BOOT**, press and release the **RESET** button. + 3. Release the **BOOT** button. + + The board will now stay in bootloader mode until you flash it. After the first flash you usually won't need to do this again. + +!!! success "Use a quality USB-C cable and power source" + + ESP32 boards are sensitive to power. If your device keeps restarting, won't be detected, or won't broadcast its hotspot, try a different USB-C cable or a different USB port. A 5V 1A supply is plenty. + +--- + +## 2. Setting up ESPHome Device Builder + +ESPHome Device Builder is a Home Assistant add-on that gives you a web UI for writing, compiling, and flashing ESPHome configurations. You'll use it to build the firmware for your kit. + +### Install the add-on + +1. In Home Assistant, open **Settings → Add-ons → Add-on Store**. +2. Search for **ESPHome Device Builder** and install it. +3. Once installed, click **Start**, then **Open Web UI**. + +If you don't have Home Assistant set up yet, follow the official Home Assistant installation guide first, then come back here. + +### Fill in your Wi-Fi secrets + +ESPHome keeps your Wi-Fi credentials in a separate `secrets.yaml` file so they aren't pasted into every device config. + +1. In the ESPHome Device Builder dashboard, click **Secrets** in the top right. +2. Add your Wi-Fi name and password: + +```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" +``` + +3. Click **Save**. + +### Add a new device + +1. Click **+ New Device** in the bottom right of the ESPHome Device Builder dashboard. +2. Give your device a name (for example `apollo-esk-1`). +3. When asked for the device type, choose **ESP32-C6**. +4. ESPHome Device Builder will scaffold a starter YAML for you. Don't flash it yet, you're going to replace it in the next section. + +--- + +## 3. Writing your first ESPHome configuration + +ESPHome configs are YAML files. Each top-level block configures a different part of the device. Here's a complete starting config for the kit, broken down section by section. Paste each block into your device's YAML in ESPHome Device Builder as you go, or jump to the [complete config](#complete-configuration) at the bottom and paste the whole thing at once. + +!!! note "YAML basics" + + YAML uses indentation (spaces, not tabs) to define structure. Two spaces per level is the convention used throughout these examples. + +### Substitutions + +Substitutions are reusable variables. Define them once at the top of the file and reference them anywhere with `${name}`. + +```yaml +substitutions: + name: apollo-esk-1 + version: "25.5.5.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. The convention used here is Year.Month.Day.Build. | +| `device_description` | Human-readable description. Notice it references other substitutions with `${}`. | + +### Core ESPHome configuration + +This block tells ESPHome how the device should appear in the dashboard and in Home Assistant. + +```yaml +esphome: + name: "${name}" + friendly_name: Apollo ESPHome Starter Kit + comment: ${device_description} + name_add_mac_suffix: true + platformio_options: + board_build.flash_mode: dio + project: + name: "ApolloAutomation.ESK-1" + version: "${version}" + min_version: 2024.6.0 +``` + +| Option | Description | +|--------|-------------| +| `name` | Internal device name, pulled from substitutions. | +| `friendly_name` | The name shown in Home Assistant's UI. | +| `name_add_mac_suffix` | Appends part of the MAC address to the name, useful when you flash more than one device. | +| `platformio_options` | Low-level build settings. `dio` flash mode is what the ESP32-C6 expects. | +| `project` | Identifies this as an Apollo Automation project. | +| `min_version` | Refuses to compile on ESPHome versions older than this. | + +### ESP32 board + +Tell ESPHome which chip you're targeting. + +```yaml +esp32: + board: esp32-c6-devkitm-1 + variant: esp32c6 + flash_size: 8MB + framework: + type: esp-idf +``` + +!!! warning "ESP32-C6 needs the ESP-IDF framework" + + The older Arduino framework does not fully support the C6. Stick with `esp-idf` here. + +### Home Assistant API + +One line enables the native Home Assistant API connection. ESPHome handles the encryption and discovery for you. + +```yaml +api: +``` + +### Wi-Fi + +This block uses the secrets you saved earlier and sets up a fallback hotspot in case the device can't reach your Wi-Fi. + +```yaml +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + + ap: + ssid: "Apollo ESK-1 Hotspot" +``` + +If the device can't connect to your Wi-Fi at boot, it will broadcast its own network called **Apollo ESK-1 Hotspot**. You can join that network from your phone or laptop to fix the credentials. + +### Captive portal + +Pairs with the fallback hotspot to give you a web page for entering Wi-Fi details when you connect to the hotspot. + +```yaml +captive_portal: +``` + +### Logger + +Enables ESPHome's logging output. You'll see these logs in the ESPHome Device Builder dashboard when viewing the device, and they're invaluable for debugging. + +```yaml +logger: +``` + +### Binary sensors + +Binary sensors report on/off state. The first one tracks whether the device is connected to Home Assistant. The second exposes a GPIO pin so you can wire up the button module or any other digital input. + +```yaml +binary_sensor: + - platform: status + name: Online + id: ha_connected + + - platform: gpio + pin: + number: GPIO9 + inverted: true + mode: + input: true + pullup: true + id: my_button + name: "Button" +``` + +| Option | Description | +|--------|-------------| +| `platform: status` | Reports the HA connection state. Useful for automations that check device availability. | +| `platform: gpio` | A simple digital input. | +| `number: GPIO9` | The physical pin you've wired the input to. | +| `inverted: true` | The pin reads LOW when the button is pressed (active-low). | +| `pullup: true` | Enables the C6's internal pull-up resistor so the pin doesn't float. | + + + +### Complete configuration + +```yaml +substitutions: + name: apollo-esk-1 + version: "25.5.5.1" + device_description: ${name} made by Apollo Automation - version ${version}. + +esphome: + name: "${name}" + friendly_name: Apollo ESPHome Starter Kit + comment: ${device_description} + name_add_mac_suffix: true + platformio_options: + board_build.flash_mode: dio + project: + name: "ApolloAutomation.ESK-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: + ssid: !secret wifi_ssid + password: !secret wifi_password + ap: + ssid: "Apollo ESK-1 Hotspot" + +captive_portal: + +logger: + +binary_sensor: + - platform: status + name: Online + id: ha_connected + + - platform: gpio + pin: + number: GPIO9 + inverted: true + mode: + input: true + pullup: true + id: my_button + name: "Button" +``` + +--- + +## 4. Flash and add to Home Assistant + +1. In ESPHome Device Builder, click **Install** on your device. +2. Choose **Plug into the computer running ESPHome Dashboard** (or **Wirelessly** if you're updating an already-flashed device). +3. Wait for the compile and flash to finish. The first compile can take several minutes. +4. Once it's done, the device will reboot and connect to your Wi-Fi. +5. In Home Assistant, go to **Settings → Devices & Services**. Your new device should appear under **Discovered**. Click **Add**, pick an area, and finish. + +!!! success "You did it!" + + Your ESP32-C6 is now running ESPHome and showing up in Home Assistant. You've written your first ESPHome configuration from scratch. + +## Next steps + +- Add more sensors and modules to your YAML and re-flash to expand the device. +- Browse [Apollo's other product wikis](https://wiki.apolloautomation.com) for more advanced ESPHome examples. +- Join the [Apollo Discord](https://link.apolloautomation.com/discord) to share what you build.