diff --git a/docs/products/ESPHome-Starter-Kit/everyday-use/button-toggles-room-light.md b/docs/products/ESPHome-Starter-Kit/everyday-use/button-toggles-room-light.md new file mode 100644 index 0000000000..a634931c62 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/everyday-use/button-toggles-room-light.md @@ -0,0 +1,85 @@ +--- +title: Button Toggles a Room Light +description: >- + Build a Home Assistant automation that uses your ESPHome Starter Kit's + button to toggle any light in your home. +--- +# Button Toggles a Room Light + +Difficulty: Level 1 + +The Starter Kit's button already controls the kit's own RGB LEDs in [Button Controlled LEDs](../automations/button-controlled-leds.md). This tutorial takes it further: pressing the button fires a **Home Assistant automation** that toggles any light in your home. Same physical button, but now it reaches across your whole house. + +!!! note "Before you start" + + Work through these pages first. This tutorial assumes your device is flashed, the Button module is wired up, and the kit is connected to Home Assistant: + + * [First Steps](../setup/first-steps.md) to create your starter kit device in ESPHome Device Builder. + * [Adding the Button Module](../modules/button-module.md) to wire up the input. + * [Connect to Home Assistant](../tutorials/connect-to-home-assistant.md) to bring the device's entities into HA. + +## Find your button entity + +The Button module shows up in Home Assistant as a binary sensor. You need its entity ID before building the automation. + +1. Open [Settings → Devices & services → ESPHome](https://my.home-assistant.io/redirect/integration/?domain=esphome) in Home Assistant. +2. Click your Starter Kit device. +3. Under **Entities**, look for a binary sensor named **Button Module**. Click it to open the entity detail, then note the entity ID shown near the top of the dialog - it will look something like `binary_sensor.esphome_starter_kit_button_module`. Keep that ID handy. + +## Build the automation + +1. Open [Settings → Automations & scenes](https://my.home-assistant.io/redirect/automations/) in Home Assistant. +2. Click **+ Create automation** in the bottom right, then choose **Create new automation**. +3. Under **Triggers**, click **+ Add trigger** and choose **Entity → State**. + +
+ + - **Entity** → select your button entity (the binary sensor you found above) + - **To** → `On` (1) + +
+ + 1. The button registers as a binary sensor. `On` maps to a pressed state - the moment you push the button down. Home Assistant fires the automation at that instant. + +4. Under **Then do**, click **+ Add action** and choose **Perform action** (labeled **Call service** in older versions of Home Assistant). + +
+ + - Search for and select **light.toggle** (1) + - Under **Targets**, click **Choose entity** and pick the light you want to control. + +
+ + 1. `light.toggle` turns the light on if it is off, and off if it is on - one action handles both directions. If you want to always turn on or always turn off, use `light.turn_on` or `light.turn_off` instead. + +5. Give the automation a name like `Button toggles room light`. +6. Click **Save**. + +??? note "What the automation looks like in YAML" + + Home Assistant stores automations as YAML. Select **Edit in YAML** from the three-dot menu on the automation to see or paste the raw config. Your entity IDs will differ from the example below. + + ```yaml + alias: Button toggles room light + triggers: + - trigger: state + entity_id: binary_sensor.esphome_starter_kit_button_module + to: "on" + actions: + - action: light.toggle + target: + entity_id: light.your_room_light + mode: single + ``` + +## Test the automation + +Press the button on the Button module. The light you targeted toggles. Press again and it toggles back. + +!!! success "Your kit is now a physical remote for Home Assistant!" + + Any light in your home - a bedside lamp, a ceiling group, a smart bulb strip - is one button press away. Swap `light.toggle` for `light.turn_on` with a `brightness_pct` to land on a specific brightness, or target a light group to control a whole room at once. + + Next - Trash Night Reminder + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/everyday-use/trash-night-reminder.md b/docs/products/ESPHome-Starter-Kit/everyday-use/trash-night-reminder.md new file mode 100644 index 0000000000..be035dd9c7 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/everyday-use/trash-night-reminder.md @@ -0,0 +1,223 @@ +--- +title: Trash Night Reminder +description: >- + Use two Home Assistant Local Calendars and the LED & Buzzer module's RGB + LEDs to light up your Starter Kit on trash and recycle night. +--- +# Trash Night Reminder + +Difficulty: Level 2 + +

🌱 New here? Try these first:

+
+
+ Button Toggles a Room Light + Difficulty: Level 1 +
+
+ Motion-Activated Room Lights + Difficulty: Level 1 +
+
+ +Never miss bin night again. Two **Home Assistant Local Calendars** - one for trash, one for recycle - drive a single automation that lights up the Starter Kit's RGB LEDs in a different color for each pickup. When the event starts the LEDs come on; when the event ends they go off. + +!!! note "Before you start" + + Work through these pages first. This tutorial assumes your device is flashed, the LED & Buzzer module is wired up, and the kit is connected to Home Assistant: + + * [First Steps](../setup/first-steps.md) to create your starter kit device in ESPHome Device Builder. + * [Adding the LED & Buzzer Module](../modules/rgb-buzzer-module.md) to wire up the RGB output. + * [Connect to Home Assistant](../tutorials/connect-to-home-assistant.md) to bring the device's entities into HA. + +## Find your RGB LED entity + +The LED & Buzzer module's RGB strip shows up in Home Assistant as a light entity. + +1. Open [Settings → Devices & services → ESPHome](https://my.home-assistant.io/redirect/integration/?domain=esphome) in Home Assistant. +2. Click your Starter Kit device. +3. Under **Entities**, look for a light entity named **RGB LEDs**. Click it and note the entity ID near the top of the dialog - it will look something like `light.esphome_starter_kit_rgb_leds`. Keep that ID handy. + +## Create the calendars + +Home Assistant's **Local Calendar** integration stores events entirely inside Home Assistant - no Google account or external service required. + +**Add the Trash calendar** + +1. Open [Settings → Devices & services](https://my.home-assistant.io/redirect/integrations/) and click **+ Add integration**. +2. Search for **Local Calendar** and select it. +3. Name it `Trash` and click **Submit**. Home Assistant creates a calendar entity called `calendar.trash`. + +**Add the Recycle calendar** + +4. Click **+ Add integration** again, search for **Local Calendar**, and repeat with the name `Recycle`. This creates `calendar.recycle`. + +**Add recurring events** + +Add a repeating event to each calendar to match your actual pickup schedule. + +5. Open the **Calendar** view in your Home Assistant sidebar. If you do not see it, go to [Settings → Dashboards](https://my.home-assistant.io/redirect/lovelace_dashboards/) and add the **Calendar** panel. +6. Click the first day your trash goes out to open the new-event dialog. + +
+ + - **Calendar** → **Trash** + - **Title** → `Trash pickup` + - Set the **start time** to the evening before your pickup day (for example, 7 PM the night before). (1) + - Set the **end time** to the morning of pickup day (for example, 9 AM). (2) + - Enable **Repeat** and set it to **Weekly** on the correct day. + +
+ + 1. The event start is when the RGB LEDs light up. Setting it to the evening before means the reminder is on while you are home and can act on it. + 2. The event end is when the LEDs turn back off. Make sure the end time falls after you would normally get the bins back in. + +7. Click **Save**. +8. Repeat for the **Recycle** calendar on your recycle pickup day and time. + +## Build the automation + +One automation handles both calendars. Four triggers - event start and event end for each calendar - feed into a **Choose** action that picks the right color or turns the LEDs off depending on which trigger fired. + +**Create the automation** + +1. Open [Settings → Automations & scenes](https://my.home-assistant.io/redirect/automations/) and click **+ Create automation** → **Create new automation**. + +**Add the triggers** + +Add four triggers, one at a time. Each one is a **Calendar** trigger, and each gets a **Trigger ID** so the action block can tell them apart. You set the ID from the trigger's three-dot menu, the same way the [Motion-Activated Room Lights](motion-activated-room-lights.md) automation does. + +2. Click **+ Add trigger**, search **Calendar**, and pick the **Calendar** trigger. + + - **Calendar** → `Trash` + - **Event** → **Start** + - Open the trigger's three-dot menu, choose **Rename**, and set the **Trigger ID** to `trash_start`. + +3. Click **+ Add trigger** and add another **Calendar** trigger. + + - **Calendar** → `Trash` + - **Event** → **End** + - Three-dot menu, **Rename**, **Trigger ID** → `trash_end`. + +4. Click **+ Add trigger** and add another **Calendar** trigger. + + - **Calendar** → `Recycle` + - **Event** → **Start** + - Three-dot menu, **Rename**, **Trigger ID** → `recycle_start`. + +5. Click **+ Add trigger** and add another **Calendar** trigger. + + - **Calendar** → `Recycle` + - **Event** → **End** + - Three-dot menu, **Rename**, **Trigger ID** → `recycle_end`. + +**Add the choose action** + +6. Under **Then do**, click **+ Add action** and search for **Choose**. + + The **Choose** block works like a branching decision: it checks each option's condition in order and runs the first one that matches. + +7. On the first **Option**, click **+ Add condition** and choose **Triggered by**. Set the **Trigger ID** to `trash_start`. Under the option's **Sequence**, click **+ Add action** → **Perform action** → `light.turn_on`: + +
+ + - **Target** → your RGB LED entity + - **RGB color** → Red `255`, Green `140`, Blue `0` (amber) (1) + - **Brightness** → `100%` + +
+ + 1. Amber is a warm, high-visibility "take out the trash" color that's easy to tell apart from the blue recycle night across a room. See [Tune the colors](#tune-the-colors) below to match your local bin colors. + +8. Click **+ Add option**. Condition: **Triggered by** → `recycle_start`. Sequence: `light.turn_on` targeting the same RGB LED entity: + + - **RGB color** → Red `0`, Green `128`, Blue `255` (blue) + - **Brightness** → `100%` + +9. Click **+ Add option**. Condition: **Triggered by** → set both `trash_end` and `recycle_end`. Sequence: `light.turn_off` targeting the RGB LED entity. + +10. Name the automation `Trash night reminder` and click **Save**. + +??? note "What the automation looks like in YAML" + + Select **Edit in YAML** from the three-dot menu on the automation to see or paste the raw config. Your entity IDs will differ from the example below. + + ```yaml + alias: Trash night reminder + description: Light up the RGB LEDs when a trash or recycle calendar event starts + triggers: + - trigger: calendar + event: start + entity_id: calendar.trash + id: trash_start + - trigger: calendar + event: end + entity_id: calendar.trash + id: trash_end + - trigger: calendar + event: start + entity_id: calendar.recycle + id: recycle_start + - trigger: calendar + event: end + entity_id: calendar.recycle + id: recycle_end + conditions: [] + actions: + - choose: + - conditions: + - condition: trigger + id: trash_start + sequence: + - action: light.turn_on + target: + entity_id: light.esphome_starter_kit_rgb_leds + data: + rgb_color: [255, 140, 0] + brightness_pct: 100 + - conditions: + - condition: trigger + id: recycle_start + sequence: + - action: light.turn_on + target: + entity_id: light.esphome_starter_kit_rgb_leds + data: + rgb_color: [0, 128, 255] + brightness_pct: 100 + - conditions: + - condition: trigger + id: + - trash_end + - recycle_end + sequence: + - action: light.turn_off + target: + entity_id: light.esphome_starter_kit_rgb_leds + mode: single + ``` + +## Test it + +Rather than waiting for your next pickup night, add a short test event to confirm everything fires. + +1. Open the **Calendar** view and add a new event on the **Trash** calendar starting one minute from now and ending two minutes from now. +2. Watch the RGB LEDs. They should turn amber at the start time and go off at the end time. +3. Delete the test event once you're done. + +!!! success "Your kit is now a physical reminder for Home Assistant events!" + + The same pattern works for any calendar-driven reminder - medication schedules, bin days for a second home, watering days for the garden. Swap the colors, the calendar name, or the action and you have a new reminder with no extra hardware. + +## Tune the colors + +Change the `rgb_color` values in the automation to match your local bin colors or whatever stands out best in your home. + +| Color | RGB values | Suggested use | +| --- | --- | --- | +| Amber | `255, 140, 0` | General trash | +| Blue | `0, 128, 255` | Recycling | +| Green | `0, 200, 0` | Compost or yard waste | +| White | `255, 255, 255` | Bulk pickup or a second reminder | + +--8<-- "_snippets/community-help.md" diff --git a/mkdocs.yml b/mkdocs.yml index 87e7efeb93..d6cc92c8af 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -545,6 +545,8 @@ nav: - Everyday Use: - Motion-Activated Room Lights: products/ESPHome-Starter-Kit/everyday-use/motion-activated-room-lights.md - Temperature on Your Dashboard: products/ESPHome-Starter-Kit/everyday-use/temperature-on-your-dashboard.md + - Button Toggles a Room Light: products/ESPHome-Starter-Kit/everyday-use/button-toggles-room-light.md + - Trash Night Reminder: products/ESPHome-Starter-Kit/everyday-use/trash-night-reminder.md - Learn the Basics: - Explaining ESPHome: products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md - Device Builder Tour: products/ESPHome-Starter-Kit/learning-the-basics/device-builder-tour.md