diff --git a/docs/assets/esphome-device-builder-add-rgb-buzzer-bundle-module.gif b/docs/assets/esphome-device-builder-add-rgb-buzzer-bundle-module.gif new file mode 100755 index 0000000000..835d74f5ec Binary files /dev/null and b/docs/assets/esphome-device-builder-add-rgb-buzzer-bundle-module.gif differ diff --git a/docs/assets/esphome-device-builder-install-rgb-buzzer-component.gif b/docs/assets/esphome-device-builder-install-rgb-buzzer-component.gif new file mode 100755 index 0000000000..789a3d70b2 Binary files /dev/null and b/docs/assets/esphome-device-builder-install-rgb-buzzer-component.gif differ diff --git a/docs/assets/esphome-device-builder-test-rgb-leds.gif b/docs/assets/esphome-device-builder-test-rgb-leds.gif new file mode 100755 index 0000000000..ba07b81403 Binary files /dev/null and b/docs/assets/esphome-device-builder-test-rgb-leds.gif differ diff --git a/docs/assets/esphome-starter-kit-attach-fpc-to-rgb-buzzer-module.webp b/docs/assets/esphome-starter-kit-attach-fpc-to-rgb-buzzer-module.webp new file mode 100755 index 0000000000..7f5eb2ed20 Binary files /dev/null and b/docs/assets/esphome-starter-kit-attach-fpc-to-rgb-buzzer-module.webp differ diff --git a/docs/products/ESPHome-Starter-Kit/modules/button-module.md b/docs/products/ESPHome-Starter-Kit/modules/button-module.md index 61fb3c66e7..6cadab4c91 100644 --- a/docs/products/ESPHome-Starter-Kit/modules/button-module.md +++ b/docs/products/ESPHome-Starter-Kit/modules/button-module.md @@ -50,14 +50,15 @@ Connect the button module to the ESP32-C6 using one of the FPC ribbon cables tha The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself. -## Add Component to ESPHome Device Builder +## Add to ESPHome Device Builder ESPHome Device Builder ships an **Add Component** flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the binary sensor by hand, and you'll get the right GPIO and inversion settings on the first try. 1. Open your starter kit device in Device Builder and click **Edit**. -2. Click **Add Component** in the editor toolbar. -3. Search for **Button** and select the **Button Module**. -4. Click **Add**. Device Builder inserts the button's binary sensor block into your YAML. +2. In the ESPHome Device Builder, navigate to the **Components** section. +3. Click **Add Component** in the editor toolbar. +4. Search for **Button** and select the **Button Module**. +5. Click **Add**. Device Builder inserts the button's binary sensor block into your YAML. ![](../../../assets/esphome-device-builder-add-button-module.gif) @@ -103,7 +104,7 @@ Flash the device so the new web server and button entity go live. ## Test the Button -With the device back online, the button entity is live on the web server. Open it in a browser on the same network and watch it react in real time. +With the device back online, the button entity is live on the web server. Open it in a browser on the same network and watch it react in real time. ![](../../../assets/esphome-device-builder-launch-webserver-from-visit-button.gif) diff --git a/docs/products/ESPHome-Starter-Kit/modules/casita-module.md b/docs/products/ESPHome-Starter-Kit/modules/casita-module.md deleted file mode 100755 index bba082ade1..0000000000 --- a/docs/products/ESPHome-Starter-Kit/modules/casita-module.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Adding the Button Module -description: >- - Wire up the ESPHome Starter Kit button module, add it through ESPHome Device - Builder, and verify presses in the web server. ---- -# Adding the Casita Module - -The Casita is the starter kit's notification module, a strip of ten addressable RGB LEDs and a small piezo buzzer behind the ESPHome logo silkscreen. By the end of this tutorial you'll have the lights and buzzer wired to your ESP32-C6, surfaced in your YAML, and ready to flash, animate, or sing in response to anything else you build. - -!!! note "Before you start" - - Work through the two prerequisites first: - - * [Start Here](/products/ESPHome-Starter-Kit/start-here/) to snap the button module off the panel. - * [First Steps](/products/ESPHome-Starter-Kit/setup/first-steps/) to install ESPHome Device Builder and create your starter kit device. - -#### Prerequisite - -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) - -## Plug in the Casita module - -Connect the Casita module to the ESP32-C6 using one of the FPC ribbon cables that came with the kit. Either FPC connector on the C6 works, top or bottom. - -1. Unplug the USB-C cable from the ESP32-C6 so the board is powered off. -2. Flip up the latch on the FPC connector on both the C6 and the Casita module. -3. Slide one end of the ribbon cable into each connector with the contacts facing the board, then press each latch back down to lock the cable in. -4. Plug the C6 back into your computer. - -**GIF PLACEHOLDER** - -!!! warning "Handle the FPC connectors gently" The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself. - -## Add the Casita component in ESPHome Device Builder - -ESPHome Device Builder ships an Add Component flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the LED strip and buzzer config by hand, and you'll get the right GPIOs, chipset, and PWM setup on the first try. - -1. Open your starter kit device in Device Builder and click **Edit**. -2. Click **Add Component** in the editor toolbar. -3. Search for **Casita** and select the Apollo Starter Kit Casita notification component. -4. Click **Add**. Device Builder inserts the light, output, and rtttl blocks into your YAML. - -??? note "What the Casita YAML does" - - The blocks Add Component drops into your config look like this: - - ```yaml - light: - - platform: esp32_rmt_led_strip - id: rgb_module - name: "RGB Module Light" - pin: GPIO14 - chipset: WS2812 - num_leds: 10 - rmt_symbols: 48 - rgb_order: grb - default_transition_length: 0s - effects: - - addressable_rainbow: - name: "Rainbow" - - addressable_twinkle: - name: "Twinkle" - - output: - - platform: ledc - pin: GPIO18 - id: buzzer - - rtttl: - id: rtttl_buzzer - output: buzzer - ``` - - Each option does something specific: - - | Option | What it does | - | --- | --- | - | **LED strip** | | - | `light.platform: esp32_rmt_led_strip` | Uses the ESP32's RMT peripheral to drive addressable LEDs with precise timing. | - | `light.pin: GPIO14` | The data line going to the first LED on the Casita. | - | `light.chipset: WS2812` | Which addressable LED protocol to use. WS2812 is the most common, sometimes also called NeoPixel. | - | `light.num_leds: 10` | The number of LEDs on the Casita module. | - | `light.rgb_order: grb` | Color channel order. WS2812 LEDs receive color data in green-red-blue order, so this makes sure red looks red and not green. | - | `light.rmt_symbols: 48` | Low-level RMT setting needed on the ESP32-C6. Leave it at 48. | - | `light.effects` | Pre-loaded animations you can select from the web server or trigger from Home Assistant. | - | **Piezo buzzer** | | - | `output.platform: ledc` | PWM output for driving the buzzer. PWM is how digital pins create audio tones on a piezo. | - | `output.pin: GPIO18` | The pin the buzzer is wired to. | - | `output.id: buzzer` | Internal handle the rtttl component uses to send tones to this output. | - | `rtttl.id: rtttl_buzzer` | Internal handle for triggering tunes from automations and lambdas. | - | `rtttl.output: buzzer` | Tells rtttl to use the buzzer output for playback. | - -## Install the firmware - -Flash the device so the new web server and the Casita entities go live. - -1. Click **Install** on your device card in ESPHome Device Builder. -2. Choose **Plug into the computer running ESPHome Device Builder** for the first flash, or **Wirelessly** if the device is already on your Wi-Fi. -3. Wait for the compile and flash to finish. First builds can take a few minutes. -4. The device reboots and reconnects to your Wi-Fi on its own. - -**GIF PLACEHOLDER** - -## Test it in the web server - -With the device back online, the Casita's light entity is live on the web server. Open it in a browser on the same network and play with it. - -1. In a browser, open `http://.local/`. If you used `esphome-starter-kit` as the device name in Getting Started, that's `http://esphome-starter-kit.local/`. -2. Find the **RGB Module Light** entity in the light list. -3. Use the controls on the page to toggle the LEDs on and off, change brightness and color, or pick **Rainbow** or **Twinkle** from the effect dropdown. - -The buzzer doesn't have its own web server control, since it's an output rather than a switch. Once you've added the device to Home Assistant, you can trigger tunes with the `rtttl.play` action or by exposing your own service. - -> Web server page showing the RGB Module Light controls with an effect running on the Casita. - -**GIF PLACEHOLDER** - -!!! success "Your Casita notification module is wired up" \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md b/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md new file mode 100755 index 0000000000..e9b12e2dc3 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md @@ -0,0 +1,130 @@ +--- +title: Adding the RGB & Buzzer Module +description: >- + Wire up the ESPHome Starter Kit RGB & Buzzer module, add it through ESPHome + Device Builder, then turn the lights and off and change colors. +--- +# Adding the LED & Buzzer Module + +The LED & Buzzer is the starter kit's notification module, a strip of ten addressable RGB LEDs and a small piezo buzzer behind the ESPHome logo silkscreen. By the end of this tutorial you'll have the lights and buzzer wired to your ESP32-C6, surfaced in your YAML, and ready to flash, animate, or sing in response to anything else you build. + +!!! note "Before you start" + + Work through the two prerequisites first: + + * [Start Here](/products/ESPHome-Starter-Kit/start-here/) to snap the button module off the panel. + * [First Steps](/products/ESPHome-Starter-Kit/setup/first-steps/) to install ESPHome Device Builder and create your starter kit device. + +#### Prerequisite + +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) + +## Attach LED & Buzzer module + +Connect the LED & Buzzer module to the ESP32-C6 using one of the FPC ribbon cables that came with the kit. Either FPC connector on the C6 works, top or bottom. + +1\. Unplug the USB-C cable from the ESP32-C6 so the board is powered off. + +![](../../../assets/esphome-starter-kit-remove-usb.webp) + +2\. Flip up the latch on the FPC connector then gently slide the ribbon cable in to the connector. Gently press the latch down to lock it in place + +![](../../../assets/esphome-starter-kit-attach-top-fpc-ribbon.webp) + +3\. Slide the ribbon cable into the button module with the blue side facing upwards then press the latch down to lock it in place. + +![](../../../assets/esphome-starter-kit-attach-fpc-to-rgb-buzzer-module.webp) + +4\. Plug the C6 back into your computer. + +!!! warning "Handle the FPC connectors gently" + + The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself. + +## Add to ESPHome Device Builder + +ESPHome Device Builder ships an **Add Component** flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the LED strip and buzzer config by hand, and you'll get the right GPIOs, chipset, and PWM setup on the first try. + +1. Open your starter kit device in Device Builder and click **Edit**. +2. In the ESPHome Device Builder, navigate to the **Components** section. +3. Click **Add Component** in the editor toolbar. +4. Select the **RGB LED + Buzzer Module Bundle** at the top. +5. Click **Add** -> Click **Add** -> Click **Add** -> Click **Add**. Each section lets you make changes but we will leave them at defaults for now. Device Builder inserts the light, output, and rtttl blocks into your YAML. + +![](../../../assets/esphome-device-builder-add-rgb-buzzer-bundle-module.gif) + +??? note "What the LED & Buzzer Module YAML does" + + The blocks Add Component drops into your config look like this: + + ```yaml + light: + - platform: esp32_rmt_led_strip + id: rgb_module + name: "RGB Module Light" + pin: GPIO14 + chipset: WS2812 + num_leds: 10 + rmt_symbols: 48 + rgb_order: grb + default_transition_length: 0s + effects: + - addressable_rainbow: + name: "Rainbow" + - addressable_twinkle: + name: "Twinkle" + + output: + - platform: ledc + pin: GPIO18 + id: buzzer + + rtttl: + id: rtttl_buzzer + output: buzzer + ``` + + Each option does something specific: + + \| Option \| What it does \| \| --- \| --- \| \| **LED strip** \| \| \| `light.platform: esp32_rmt_led_strip` \| Uses the ESP32's RMT peripheral to drive addressable LEDs with precise timing. \| \| `light.pin: GPIO14` \| The data line going to the first LED on the PCB. \| \| `light.chipset: WS2812` \| Which addressable LED protocol to use. WS2812 is the most common, sometimes also called NeoPixel. \| \| `light.num_leds: 10` \| The number of LEDs on the RGB & Buzzer module. \| \| `light.rgb_order: grb` \| Color channel order. WS2812 LEDs receive color data in green-red-blue order, so this makes sure red looks red and not green. \| \| `light.rmt_symbols: 48` \| Low-level RMT setting needed on the ESP32-C6. Leave it at 48. \| \| `light.effects` \| Pre-loaded animations you can select from the web server or trigger from Home Assistant. \| \| **Piezo buzzer** \| \| \| `output.platform: ledc` \| PWM output for driving the buzzer. PWM is how digital pins create audio tones on a piezo. \| \| `output.pin: GPIO18` \| The pin the buzzer is wired to. \| \| `output.id: buzzer` \| Internal handle the rtttl component uses to send tones to this output. \| \| `rtttl.id: rtttl_buzzer` \| Internal handle for triggering tunes from automations and lambdas. \| \| `rtttl.output: buzzer` \| Tells rtttl to use the buzzer output for playback. \| + +## Install the firmware + +Flash the device so the new web server and the RGB & Buzzer entities go live. + +1. Click **Install** on your device card in ESPHome Device Builder. +2. Choose **Plug into the computer running ESPHome Device Builder** for the first flash, or **On The Network** if the device is already on your Wi-Fi. +3. Wait for the compile and flash to finish. First builds can take a few minutes. +4. The device reboots and reconnects to your Wi-Fi on its own. + +![](../../../assets/esphome-device-builder-install-rgb-buzzer-component.gif) + +## Test the LEDs + +With the device back online, the RGB LED light entity is live on the web server. Open it in a browser on the same network and play with it. + +1. In a browser, open `http://.local/`. If you used `esphome-starter-kit` as the device name in Getting Started, that's `http://esphome-starter-kit.local/`. +2. Toggle the **RGB LEDs** entity and play around with the colors and brightness. + +![](../../../assets/esphome-device-builder-test-rgb-leds.gif) + +!!! tip "For more effects check out this wiki on how to do advanced configurations with your RGB & Buzzer module!" + + There are a lot of advanced things you can do with a light entity. Click here (NEED-TO-LINK-TO-NEW-LIGHT-COMPONENT-WIKI) to learn more about that! + +The buzzer doesn't have its own web server control, since it's an output rather than a switch. Once you've added the device to Home Assistant, you can trigger tunes with the `rtttl.play` action or by exposing your own service. + +> Web server page showing the RGB Light controls on the LED & Buzzer Module. + +!!! success "Your LED & Buzzer notification module is wired up!" + + Your LED & Buzzer Module is now ready for some fun tasks.. like toggling lights on and off, playing with the colors, or using the buzzer to play fun tunes! \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md index 6fab778d99..e02e7d2a61 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md @@ -4,17 +4,15 @@ description: Step by step guide for getting started with the ESPHome Starter Kit --- # ESPHome Starter Kit - First Steps -This guide walks you through installing the ESPHome Device Builder app, and writing your first ESPHome YAML configuration from scratch. +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. --- - Click Here for the First Steps - ### ESPHome Device Builder -ESPHome Device Builder is the software that gives you a user interface for writing, compiling, and flashing ESPHome configurations. You'll use it to build the firmware for your kit. +ESPHome Device Builder is the software that gives you a user interface for writing, compiling, and flashing ESPHome YAML configurations. You'll use it to build the firmware for your kit. Think of it like telling the starter kit about what devices it has connected and how to use them! @@ -103,7 +101,7 @@ Pick the platform you'll be running ESPHome Device Builder on: #### Set up Wi-Fi Credentials -Fill in your Wi-Fi network name (SSID) and Wi-Fi password then click Save 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 ![](../../../assets/esphome-builder-enter-wifi-credentials.gif) @@ -207,4 +205,6 @@ It should load your new device and show you the Onboard RGB LED. We can click th Example of the light changing colors below! -![](../../../assets/esphome-starter-kit-onboard-rgb-led-light-up.webp) \ No newline at end of file +![](../../../assets/esphome-starter-kit-onboard-rgb-led-light-up.webp) + + Back - Start Here Next - Add Button Module \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/start-here.md b/docs/products/ESPHome-Starter-Kit/start-here.md index c9245cce46..ef586551d1 100755 --- a/docs/products/ESPHome-Starter-Kit/start-here.md +++ b/docs/products/ESPHome-Starter-Kit/start-here.md @@ -31,43 +31,55 @@ Each module is connected to the panel by small breakaway tabs. Follow the steps 2. Gently flex the panel along the tab line until the tab snaps cleanly. ## Meet the modules -**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. +**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. ![](../../assets/esphome-starter-kit-main-board-only.jpg) --- -**Casita LED and Buzzer module.** The starter kit's notification module, a strip of ten addressable RGB LEDs and a small piezo buzzer behind the ESPHome logo silkscreen. *Use the included stand to show it off!* +**Casita LED and Buzzer module** + +* The starter kit's notification module, a strip of ten addressable RGB LEDs and a small piezo buzzer behind the ESPHome logo silkscreen. *Use the included stand to show it off!* ![](../../assets/esphome-starter-kit-casita-module-only.jpg) --- -**Motion module.** Detects movement in a room and a great way to get started automating your home. It comes in two parts, and the PIR sensor easily plugs into the PIR module board. +**Motion module** + +* Detects movement in a room and a great way to get started automating your home. It comes in two parts, and the PIR sensor easily plugs into the PIR module board. ![](../../assets/esphome-starter-kit-pir-module-only.jpg) --- -**Button module.** Premium feel button perfect to trigger automations for lights and more. +**Button module** + +* Premium feel button perfect to trigger automations for lights and more. ![](../../assets/esphome-starter-kit-button-module-only.jpg) --- -**Temperature and Humidity module.** 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! ![](../../assets/esphome-starter-kit-temp-hum-module-only-1.jpg) --- -**FPC cables.** Each module connects to the main board through the FPC connector using one of the three provided cables. *Tear the brown paper bag open from one of the ends. Please DO NOT use scissors as you could accidentally cut the cables!* +**FPC cables** + +* Each module connects to the main board through the FPC connector using one of the three provided cables. *Tear the brown paper bag open from one of the ends. Please DO NOT use scissors as you could accidentally cut the cables!* ![](../../assets/esphome-starter-kit-fpc-cables-only.jpg) @@ -75,4 +87,4 @@ Each module is connected to the panel by small breakaway tabs. Follow the steps Once you've identified your modules and snapped them off the panel, the next step is to connect the main board to your computer and walk through your first ESPHome configuration. - Next - First Steps \ No newline at end of file + Next - First Steps \ No newline at end of file