diff --git a/AGENTS.md b/AGENTS.md index 260932ae39..5dbeef18b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,10 @@ Read the full style guide, but these are the ones worth checking twice: all display text. Keep `rpro1`, `r-pro-1`, and `R_PRO-1` only in file names, URLs, hostnames, and literal device names. - **US English** spelling: color, center, meter, behavior. +- Flag must-know info with admonitions (`note` for prerequisites, + `tip`, `warning`, `success` for a "Next step" box with a primary + button to the follow-on guide). See + [Admonitions and next steps](STYLE_GUIDE.md#admonitions-and-next-steps). - **Apollo addons** (hardware modules) and **Home Assistant apps** (formerly add-ons) are different things and not interchangeable. - **ESPHome** is the only correct casing. diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index c0bf884803..f6104caa45 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -353,6 +353,39 @@ ffmpeg -ss 3 -to 26 -i recording.mp4 -an -vf "scale=540:-2,fps=30" -c:v libx264 ``` +### Admonitions and next steps + +Readers skim. Put anything they must not miss in an admonition instead +of burying it in a paragraph, and pick the type by what the box does: + +| Type | Use it for | Example title | +| --- | --- | --- | +| `note` | Prerequisites at the top of a guide | "Before you start" | +| `tip` | A shortcut, or why something works the way it does | "Why taps instead of drags" | +| `warning` | Something that breaks a setup or loses data if ignored | "Install both parts" | +| `danger` | Risk of damaging hardware | "Unplug before opening" | +| `success` | The next step once the reader has finished this one | "Next step: build your first region flow" | + +Keep each box to one idea and a few sentences. A page where every +paragraph is a box has no emphasis left; if a section has more than two +or three, fold the minor ones back into the text. + +**Link guides into a progression.** When one guide naturally leads to +another (draw a zone, then build a flow with it), close the relevant +section with a `success` box: one sentence on what the reader unlocks +next, then a primary button to the follow-on guide. The follow-on guide +links back from its "Before you start" note. + +```markdown +!!! success "Next step: build your first region flow" + + Your regions are drawn. Now make one do something: the step-by-step + guide walks you through a flow that turns a light on when someone + enters a region. + + [Turn on a light when someone enters a region](../../../general/tutorials/region-light-flow-example/){ .md-button .md-button--primary } +``` + ### Internal links Internal links use site-relative paths in wiki-URL form (trailing diff --git a/docs/_snippets/homey-radar-regions.md b/docs/_snippets/homey-radar-regions.md index 33b61dbb85..09ae6fcdac 100644 --- a/docs/_snippets/homey-radar-regions.md +++ b/docs/_snippets/homey-radar-regions.md @@ -67,7 +67,7 @@ Drawing works by tapping, not dragging. Pick a shape, tap its points on the map, 3. Adjust the new region. It appears with a name like Region 1 and its settings open. Use the arrows to move it and **Bigger** or **Smaller** to resize it. 4. Press **Save**, or **Cancel** to throw the unsaved changes away. -Your region now shows on the map, and a matching occupancy tile appears on the device. +Your region now shows on the map, and a matching occupancy tile appears on the device. Once your regions are in place, [put one to work in a flow](#use-regions-in-flows). @@ -108,6 +108,12 @@ Here a polygon is drawn over a fan and set to **Ignore this area**: This is where regions pay off. Every saved detect region is an occupancy tile on the device, named after the region, and the device gets three region flow cards. +!!! success "Next step: build your first region flow" + + Your regions are drawn. Now make one do something: the step-by-step guide walks you through a flow that turns a light on when someone enters a region and off when they leave. + + [Turn on a light when someone enters a region](../../../general/tutorials/region-light-flow-example/){ .md-button .md-button--primary } + | Card | Type | Asks for | Tokens | | --- | --- | --- | --- | | **A region became occupied** | Trigger (When) | The device, then a region or **Any region** | Region name, Target count | diff --git a/docs/homey.md b/docs/homey.md index 398e8d7180..8e60f82c89 100755 --- a/docs/homey.md +++ b/docs/homey.md @@ -22,7 +22,7 @@ description: Guide to integrating Apollo Automation devices with the Homey smart * [Setting up zones on MTR-1 with the HLK app](https://wiki.apolloautomation.com/products/mtr1/setup/zones-hlk/) * [Beta test our new Zone Mapper tool!](https://github.com/ApolloAutomation/zone-mapper) - [Use this custom card along with Zone Mapper!](https://github.com/ApolloAutomation/zone-mapper-card) * [Tune your new R PRO-1 PoE mmWave sensor](https://wiki.apolloautomation.com/products/rpro1/setup/zones-hlk/) -* [Draw occupancy regions in Homey with the Zone Mapper tool for MTR-1](homey/products/mtr1/setup/mtr-1-zone-mapper-tool/) or [R PRO-1](homey/products/rpro1/setup/r-pro-1-zone-mapper-tool/) +* [Draw occupancy regions in Homey with the Zone Mapper tool for MTR-1](products/mtr1/setup/mtr-1-zone-mapper-tool/) or [R PRO-1](products/rpro1/setup/r-pro-1-zone-mapper-tool/) ### Quick References diff --git a/docs/homey/products/general/tutorials/region-light-flow-example.md b/docs/homey/products/general/tutorials/region-light-flow-example.md new file mode 100644 index 0000000000..8eb449217f --- /dev/null +++ b/docs/homey/products/general/tutorials/region-light-flow-example.md @@ -0,0 +1,80 @@ +--- +title: Turn on a light when someone enters a region +description: Build a Homey flow that turns a light on when someone enters a Radar regions area on your MTR-1 or R PRO-1, and off again when they leave. +--- + +# Turn on a light when someone enters a region + +Difficulty: Level 1 + +Regions turn one radar into several spots you can automate on their own: the desk, the sofa, the workbench. In this guide you build two flows in the Homey mobile app. The first turns a light on the moment someone steps into a region; the second turns it off once the region has been empty for a while. The example uses a region called **Server** on an Apollo R PRO-1, and works the same way on an MTR-1 with any region you have drawn. + + + +!!! note "Before you start" + + - Draw at least one region with the Zone Mapper tool, set to **Detect people here**. See the guide for your [R PRO-1](../../../rpro1/setup/r-pro-1-zone-mapper-tool/) or [MTR-1](../../../mtr1/setup/mtr-1-zone-mapper-tool/). + - Add the light you want to control to Homey. + +## Why use the region trigger + +Every detect region gives your sensor three flow cards: **A region became occupied**, **A region became empty**, and **A region is occupied**. Start your flow with **A region became occupied** and pick your region. It fires every time someone walks into that spot, even when someone else is already elsewhere in the room. + +The sensor's whole-room card, **The occupancy alarm turned on**, only fires when the room goes from empty to occupied. Pairing it with a **Server is occupied** condition misses the moment someone who is already in the room walks over to the server, so the light stays off. + +## Flow 1: turn the light on + +This flow has one trigger and one action, so it needs no **And** card. + +1. In the Homey mobile app, tap **Flow** in the bottom bar, then tap **+** at the top right (or **Create a Flow** if you have none yet). +2. Under **When...**, tap **Add Card**. Open **Apollo Automation** under **Apps**, and choose your sensor. +3. Choose the card **A region became occupied**. +4. Tap **Region** and pick **Server**, then tap the check mark at the top right. +5. Under **Then...**, tap **Add Card**. Find your light under **Zones & Devices**, choose **Turn on**, and tap the check mark. +6. Tap **Next**. Name the flow, for example **Server area light on**, and tap **Save Flow**. + + + +The flow now shows in **My Flows**. Walk into the region and the light turns on. + +!!! tip "Only detect regions are listed" + + The region picker lists your **Detect people here** regions. Areas set to **Ignore this area** never report occupied, so they don't appear. + +## Flow 2: turn the light off + +The second flow mirrors the first. Build it the same way, with two changes: + +1. Under **When...**, choose **A region became empty** and pick **Server**. +2. Under **Then...**, choose **Turn off** for the same light. +3. Name it **Server area light off** and tap **Save Flow**. + +Now the light follows the region: on when someone arrives, off when they leave. + +## Set the hold time + +A region stays occupied for its **Hold time** after the last person leaves, 5 seconds by default. That is what stops the light from flickering off when someone leans back or steps away for a moment. + +For a desk or a workbench, raise it. Open the dashboard with your **Radar regions** widget, tap the region with **Select** active, and set **Hold time** under **More** to 60 seconds or longer. Press **Save**. Flow 2 now waits that long before it turns the light off. + +## Test your flows + +Run the flows end to end by walking in and out of the region while you watch the light. To check a single flow without moving, tap the play button next to it in **My Flows**; it runs its **Then** cards once, and a green check mark confirms it ran. + +If a flow doesn't fire: + +- Open the **Radar regions** widget and watch the dots. If your dot doesn't land inside the region, make the region larger with **Bigger** or the arrows. +- Check that the region is set to **Detect people here** and is **Enabled**. +- Check that both flows are switched on in **My Flows**. + +## Take it further + +- **One flow for many regions**: pick **Any region** in the trigger instead of a single region. The **Region name** token tells the flow which one fired, for example in a notification. +- **Count people**: **A region became occupied** also passes a **Target count** token, the number of people in the region. +- **Keep other automations in check**: add **A region is occupied** as an **And** condition. For example, add **Sofa** is not occupied (with **Invert** on) to the flow that turns your living room lights off. + +See [Use regions in flows](../../../rpro1/setup/r-pro-1-zone-mapper-tool/#use-regions-in-flows) for the full list of region cards. diff --git a/mkdocs.yml b/mkdocs.yml index ad8a0041bf..953a94448a 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -643,6 +643,7 @@ nav: - Example Flows: # - Air Quality Notification: homey/products/general/tutorials/air-quality-notification-example.md - High CO2 Notification: homey/products/general/tutorials/high-co2-notification-example.md + - Region Light: homey/products/general/tutorials/region-light-flow-example.md - Additional Info: - Calibrating: - CO2: homey/products/general/calibrating-and-updating/co2-calibration.md