diff --git a/docs/_snippets/zone-mapper-tool.md b/docs/_snippets/zone-mapper-tool.md index 757c251d59..a6cb0a1136 100644 --- a/docs/_snippets/zone-mapper-tool.md +++ b/docs/_snippets/zone-mapper-tool.md @@ -110,6 +110,10 @@ The card needs to know which X/Y coordinate sensors to track: Changing the card's units instead also works, but then you need to adjust the grid distances to match, so converting the sensors is the recommended path. +!!! tip "Apollo mmWave does this for you" + + With the Apollo mmWave integration 2.4.0 or newer installed, you can skip the conversion above. Apollo mmWave shows the Target X and Y of an Apollo MTR-1 or R PRO-1 in mm on its own: on a new sensor as soon as you add it, and on one you already had once, after Home Assistant starts, with the notification **Apollo mmWave: Target X and Y now in mm**. Zone Mapper's card reads them in mm then too. Apollo mmWave leaves alone a sensor whose unit you picked in its settings, which you change there, and one that an automation, a script, or a helper uses. For a sensor in use, first change any number it's compared to into mm, 25.4 times as large, then, as an administrator, press **Show Target X and Y in mm** on the **Radar setup** card above its zone map. The button switches only sensors whose unit Home Assistant picked on its own, never one whose unit you picked. To go back to inches, choose **in** under **Unit of measurement** in the sensor's settings. See [Target X and Y units](/products/general/setup/apollo-mmwave-dashboard.md#target-x-and-y-units). + ### Add zones 1. Click the **Configure** drop-down, then **Zones**. diff --git a/docs/assets/apollo-mmwave-calibrate-idle.png b/docs/assets/apollo-mmwave-calibrate-idle.png index 73fb0b811c..eb170c4be8 100644 Binary files a/docs/assets/apollo-mmwave-calibrate-idle.png and b/docs/assets/apollo-mmwave-calibrate-idle.png differ diff --git a/docs/assets/apollo-mmwave-calibrate-r-pro-1.png b/docs/assets/apollo-mmwave-calibrate-r-pro-1.png index 733774e889..19b7bc363c 100644 Binary files a/docs/assets/apollo-mmwave-calibrate-r-pro-1.png and b/docs/assets/apollo-mmwave-calibrate-r-pro-1.png differ diff --git a/docs/assets/apollo-mmwave-calibrate-result.png b/docs/assets/apollo-mmwave-calibrate-result.png index ed3ffcc68e..99d8edfdae 100644 Binary files a/docs/assets/apollo-mmwave-calibrate-result.png and b/docs/assets/apollo-mmwave-calibrate-result.png differ diff --git a/docs/assets/apollo-mmwave-gate-energy-engineering-off.png b/docs/assets/apollo-mmwave-gate-energy-engineering-off.png index 6f68051c71..b0994af5e0 100644 Binary files a/docs/assets/apollo-mmwave-gate-energy-engineering-off.png and b/docs/assets/apollo-mmwave-gate-energy-engineering-off.png differ diff --git a/docs/assets/apollo-mmwave-gate-energy-live.png b/docs/assets/apollo-mmwave-gate-energy-live.png index 1113f90c0b..37b9d49870 100644 Binary files a/docs/assets/apollo-mmwave-gate-energy-live.png and b/docs/assets/apollo-mmwave-gate-energy-live.png differ diff --git a/docs/assets/apollo-mmwave-gate-energy.mp4 b/docs/assets/apollo-mmwave-gate-energy.mp4 index 92123a3488..610b3300e5 100644 Binary files a/docs/assets/apollo-mmwave-gate-energy.mp4 and b/docs/assets/apollo-mmwave-gate-energy.mp4 differ diff --git a/docs/assets/apollo-mmwave-ld2450-live-count.png b/docs/assets/apollo-mmwave-ld2450-live-count.png new file mode 100644 index 0000000000..69acb9b361 Binary files /dev/null and b/docs/assets/apollo-mmwave-ld2450-live-count.png differ diff --git a/docs/assets/apollo-mmwave-ld2450-live.png b/docs/assets/apollo-mmwave-ld2450-live.png index bebf5de599..31e88991c5 100644 Binary files a/docs/assets/apollo-mmwave-ld2450-live.png and b/docs/assets/apollo-mmwave-ld2450-live.png differ diff --git a/docs/assets/apollo-mmwave-radar-setup-and-zone-map.png b/docs/assets/apollo-mmwave-radar-setup-and-zone-map.png index a231528084..5527d7dc49 100644 Binary files a/docs/assets/apollo-mmwave-radar-setup-and-zone-map.png and b/docs/assets/apollo-mmwave-radar-setup-and-zone-map.png differ diff --git a/docs/assets/apollo-mmwave-radar-setup-target-units-in-use.png b/docs/assets/apollo-mmwave-radar-setup-target-units-in-use.png new file mode 100644 index 0000000000..4f5997a238 Binary files /dev/null and b/docs/assets/apollo-mmwave-radar-setup-target-units-in-use.png differ diff --git a/docs/assets/apollo-mmwave-start-here.png b/docs/assets/apollo-mmwave-start-here.png index b1f248bf19..7e290b3ebf 100644 Binary files a/docs/assets/apollo-mmwave-start-here.png and b/docs/assets/apollo-mmwave-start-here.png differ diff --git a/docs/assets/apollo-mmwave-zone-list.png b/docs/assets/apollo-mmwave-zone-list.png new file mode 100644 index 0000000000..23d82fe9bd Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-list.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-configure.png b/docs/assets/apollo-mmwave-zone-map-configure.png new file mode 100644 index 0000000000..6a0196c67d Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-configure.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-draw-poster.jpg b/docs/assets/apollo-mmwave-zone-map-draw-poster.jpg new file mode 100644 index 0000000000..49b142c4b1 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-draw-poster.jpg differ diff --git a/docs/assets/apollo-mmwave-zone-map-draw.mp4 b/docs/assets/apollo-mmwave-zone-map-draw.mp4 new file mode 100644 index 0000000000..d90475eb94 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-draw.mp4 differ diff --git a/docs/assets/apollo-mmwave-zone-map-empty.png b/docs/assets/apollo-mmwave-zone-map-empty.png new file mode 100644 index 0000000000..7b92caa65e Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-empty.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-expand-poster.jpg b/docs/assets/apollo-mmwave-zone-map-expand-poster.jpg new file mode 100644 index 0000000000..cebc214ef0 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-expand-poster.jpg differ diff --git a/docs/assets/apollo-mmwave-zone-map-expand.mp4 b/docs/assets/apollo-mmwave-zone-map-expand.mp4 new file mode 100644 index 0000000000..3a53204715 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-expand.mp4 differ diff --git a/docs/assets/apollo-mmwave-zone-map-expanded-phone.png b/docs/assets/apollo-mmwave-zone-map-expanded-phone.png new file mode 100644 index 0000000000..7f63b5eb92 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-expanded-phone.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-history-poster.jpg b/docs/assets/apollo-mmwave-zone-map-history-poster.jpg new file mode 100644 index 0000000000..997787c2b0 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-history-poster.jpg differ diff --git a/docs/assets/apollo-mmwave-zone-map-history.mp4 b/docs/assets/apollo-mmwave-zone-map-history.mp4 new file mode 100644 index 0000000000..ed964e49ee Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-history.mp4 differ diff --git a/docs/assets/apollo-mmwave-zone-map-ignore.png b/docs/assets/apollo-mmwave-zone-map-ignore.png new file mode 100644 index 0000000000..eaf4ac0d3c Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-ignore.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-live-poster.jpg b/docs/assets/apollo-mmwave-zone-map-live-poster.jpg new file mode 100644 index 0000000000..6720544dfc Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-live-poster.jpg differ diff --git a/docs/assets/apollo-mmwave-zone-map-live.mp4 b/docs/assets/apollo-mmwave-zone-map-live.mp4 new file mode 100644 index 0000000000..138768b8ec Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-live.mp4 differ diff --git a/docs/assets/apollo-mmwave-zone-map-offline.png b/docs/assets/apollo-mmwave-zone-map-offline.png new file mode 100644 index 0000000000..ab747cca99 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-offline.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-view-only.png b/docs/assets/apollo-mmwave-zone-map-view-only.png new file mode 100644 index 0000000000..ae266e760d Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-view-only.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-walk-poster.jpg b/docs/assets/apollo-mmwave-zone-map-walk-poster.jpg new file mode 100644 index 0000000000..f95bb7e8a0 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-walk-poster.jpg differ diff --git a/docs/assets/apollo-mmwave-zone-map-walk.mp4 b/docs/assets/apollo-mmwave-zone-map-walk.mp4 new file mode 100644 index 0000000000..cfd4a3556f Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-walk.mp4 differ diff --git a/docs/assets/apollo-mmwave-zone-map-zoom-poster.png b/docs/assets/apollo-mmwave-zone-map-zoom-poster.png new file mode 100644 index 0000000000..28a720f79b Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-zoom-poster.png differ diff --git a/docs/assets/apollo-mmwave-zone-map-zoom.mp4 b/docs/assets/apollo-mmwave-zone-map-zoom.mp4 new file mode 100644 index 0000000000..48329751d7 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-map-zoom.mp4 differ diff --git a/docs/assets/apollo-mmwave-zone-map.png b/docs/assets/apollo-mmwave-zone-map.png index b89eddd574..7fb43f61ce 100644 Binary files a/docs/assets/apollo-mmwave-zone-map.png and b/docs/assets/apollo-mmwave-zone-map.png differ diff --git a/docs/assets/apollo-mmwave-zone-name-poster.jpg b/docs/assets/apollo-mmwave-zone-name-poster.jpg new file mode 100644 index 0000000000..bd0dc78f3b Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-name-poster.jpg differ diff --git a/docs/assets/apollo-mmwave-zone-name.mp4 b/docs/assets/apollo-mmwave-zone-name.mp4 new file mode 100644 index 0000000000..c245f4d7c9 Binary files /dev/null and b/docs/assets/apollo-mmwave-zone-name.mp4 differ diff --git a/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md b/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md index 30733b8ed9..b3ba4261e3 100644 --- a/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md +++ b/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md @@ -4,4 +4,6 @@ description: "Tutorial for MTR-1 Home Assistant Zone Configuration." --- --8<-- "products/mtr1/setup/zones-ha.md:5:6" ---8<-- "products/mtr1/setup/zones-ha.md:11:" +--8<-- "products/mtr1/setup/zones-ha.md:11:57" + +--8<-- "products/mtr1/setup/zones-ha.md:63:" diff --git a/docs/products/general/setup/apollo-mmwave-dashboard-setup.md b/docs/products/general/setup/apollo-mmwave-dashboard-setup.md index 13f4b39c7a..8dde44b21e 100644 --- a/docs/products/general/setup/apollo-mmwave-dashboard-setup.md +++ b/docs/products/general/setup/apollo-mmwave-dashboard-setup.md @@ -103,9 +103,9 @@ The cards on each tab are laid out in columns that stack into one on a phone. He Both sensors use the LD2410 radar chip, so their tabs look the same, and the tuning card titles start with **LD2410**. -- **Start here** sits at the top. It names your sensor and lists five steps, from **Fix anything the Radar setup card flags.** to walking the room while you watch the Gate Energy chart. Its links open the tuning guide on this wiki and your sensor's own page in Home Assistant. +- **Start here** sits at the top. It names your sensor and lists five steps, from **Fix anything the Radar setup card flags.** to walking the room while you watch the Gate Energy chart. Under the steps it says to use **Radar Target** in automations for the whole room, and to raise **Radar Timeout** to 60 s or more if it turns off while someone sits still. Its links open the tuning guide on this wiki and your sensor's own page in Home Assistant. - ![The Start here card for an MSR-1 named MSR-1 Kitchen, with five numbered steps starting Fix anything the Radar setup card flags., followed by the Full tuning guide and All settings for this device links](/assets/apollo-mmwave-start-here.png) + ![The Start here card for an MSR-1 named MSR-1 Kitchen, with five numbered steps starting Fix anything the Radar setup card flags., then the line In automations, use Radar Target for the whole room., followed by the Full tuning guide and All settings for this device links](/assets/apollo-mmwave-start-here.png) - Under it, the **Radar setup** card checks the radar's settings and offers a fix when one is off. On a sensor that's ready to go it reads **Radar settings look good.** - **Auto-calibrate** comes next, with the **Calibrate with empty room** and **Preview only** buttons. If your sensor still has its factory thresholds and has never been calibrated, the card adds **These look like factory thresholds. Calibrating sets them for your room.** @@ -119,26 +119,26 @@ Both sensors use the LD2410 radar chip, so their tabs look the same, and the tun The R PRO-1 tab starts with the same tuning cards, titled **LD2412** instead of **LD2410**, for the optional LD2412 radar addon, and adds a zone map for its LD2450 radar. Without the addon, the LD2412 cards still appear but have no radar behind them, so skip to the zone map, and **Start here** gives the zone map steps instead. The differences from an MSR-2 tab: -- **Start here** says what each radar is for: the LD2412 senses people anywhere in range, even sitting still, and the LD2450 tracks where people are and drives the zone map. +- **Start here** says what each radar is for: the LD2412 senses people anywhere in range, even sitting still, and the LD2450 tracks where people are and drives the zone map. For automations that cover the whole room, it names **Combined Presence** (on while either radar sees someone) on firmware newer than 26.3.2.1, which has that sensor, and **LD2412 Presence** on earlier firmware. - **LD2412 Controls** adds **Start Dynamic Background Correction** and **Background Correction Running**. The Auto-calibrate card reminds you to run background correction first, with the room empty, and wait for its status to turn off before you calibrate. - **LD2412 Detection Range** holds **Radar Timeout**, **Max Gate**, and **Min Gate**, plus **Distance Resolution** if you've enabled that entity (it's hidden on a new sensor). - The thresholds cards and the Gate Energy chart cover 14 gates, **G0** to **G13**. - There's no Zone Config card, and the **LD2412 Distances** chart shows the gates and your **Max Gate** and **Min Gate** limits without distance bars. -- After the first column (**Start here**, the LD2412's **Radar setup** card, **Auto-calibrate**, **LD2412 Controls**, and **LD2412 Target / Occupancy**), a **Zone Map** heading introduces the LD2450's cards: its own **Radar setup** card, the zone map, **Zone presence**, **LD2450 Live**, and **LD2450 Controls**, described below. The rest of the LD2412 cards follow, so on a phone you reach the zone map before the 28 threshold rows. +- After the first column (**Start here**, the LD2412's **Radar setup** card, **Auto-calibrate**, **LD2412 Controls**, and **LD2412 Target / Occupancy**), a **Zone Map** heading introduces the LD2450's cards: its own **Radar setup** card and the zone map, in a section two columns wide, then **Zone presence**, **LD2450 Live**, and **LD2450 Controls**, described below. The rest of the LD2412 cards follow, so on a phone you reach the zone map before the 28 threshold rows. On a screen wide enough for Home Assistant's four columns, the first column, the zone map, and the LD2450's cards make up the first row, and the LD2412's tuning cards fill the second. With room for only two columns, the LD2450's cards move up beside the first column, and the zone map spans the full width under them. ### MTR-1 tabs -An MTR-1 tab is built around the zone map, with everything for its LD2450 radar beside it: +An MTR-1 tab is built around the zone map, with everything for its LD2450 radar beside it. On a computer, **Start here** and **Radar setup** share the row above the zone map, and the map's section is two columns wide: -- **Start here** lists three steps (fix anything the Radar setup card flags, set **Cone rotation**, then draw a zone and walk into it), says which presence sensor to use in automations, and links to your sensor's own page. +- **Start here** lists three steps (fix anything the Radar setup card flags, set **Cone rotation** under **Map settings** on the zone map, then press **Add zone** under the map, draw the zone, and walk into it), says which presence sensor to use in automations, and links to your sensor's own page. - **Radar setup** checks **Zone Type** and **Multi Target Tracking**, the two radar settings that decide whether the map can show people, and fixes them when you press its button. **Zone Type** should be **Disabled**, because the zone map replaces the radar's own built-in zones. -- The zone map, titled with your sensor's name, shows the radar's view, a cone 120 degrees wide and about 6 m (20 ft) out, with a dot for each target the LD2450 is tracking. It's in feet or meters to match Home Assistant, and the **m / ft** switch on the map changes it. A pencil button in the lower left opens the drawing tools, the lower right holds the unit switch and the undo and lock buttons, and a collapsed **Configure** section under the grid holds the cone rotation slider and the zone list. -- **Zone presence**, **LD2450 Live**, and **Occupancy History** show each zone's presence sensor, what the radar reports right now, and the last 24 hours. +- The zone map, titled with your sensor's name, shows the radar's view, a cone 120 degrees wide and about 6 m (20 ft) out, with a numbered dot for each target the LD2450 is tracking, and fills in each zone while someone is in it. It's in feet or meters to match Home Assistant, and the **m / ft** switch on the map changes it. A pencil button in the lower left opens the drawing tools, and the lower right holds the unit switch and the undo and lock buttons, with the zoom buttons (โˆ’, +, and **Fit**) above them. Under the grid are the **Coverage** button (on a phone or tablet, with **๐Ÿšถ Mark corners by walking** before it for administrators), the **Zones** panel, and a collapsed **Map settings** section. **Zones** holds **Add zone**, a button for each zone, and an editor for the zone you pick, with its name, size, **Type**, **Hold** time, and **Delete zone**. **Map settings** holds the cone rotation slider with the hint to mount the sensor first, **Flip the map left to right (display only)**, **Movement history** (for administrators), and **Clear all shapes**. The expand button in the map's top-right corner (**Expand map**) gives the map the whole window when the card feels cramped. +- **Zone presence**, **LD2450 Live**, and **Occupancy History** show each zone's presence sensor, what the radar reports right now, and the last 24 hours. **LD2450 Presence**, the first row of **LD2450 Live** and a line in **Occupancy History**, is on while the radar sees anyone anywhere in its view, whether or not they're in a zone. - **LD2450 Controls**, the radar's built-in zones (only while Zone Type isn't **Disabled**), and the **Device** card end the tab. The integration finds the sensor's target entities itself, so there's nothing to pick before you start drawing. The R PRO-1's zone map and the cards beside it work the same way. -![The Radar setup card above the zone map on an R PRO-1: the card reads Zone Type is Filter. This radar ignores people inside its built-in zones. Disabled is recommended because the zone map replaces them., with a Set Zone Type to Disabled button, and the map below it shows the radar's view cone in feet, the caption Radar range 20 ft (6 m), 120ยฐ, three drawn zones, and the m / ft switch and Locked button](/assets/apollo-mmwave-radar-setup-and-zone-map.png) +![The Radar setup card above the zone map on an R PRO-1: the card reads LD2450 ยท R PRO-1 Server Rack and Zone Type is Filter. This radar ignores people inside its built-in zones. Disabled is recommended because the zone map replaces them., with a Set Zone Type to Disabled button, and the map below it shows the radar's view cone in feet, the caption Radar range 20 ft (6 m), 120ยฐ, three drawn zones with a pale fill and a dashed outline because nobody is in them, the expand button in the map's top-right corner, the zoom buttons (a dimmed minus, + and Fit) above the m / ft switch and the Locked button, and under the grid the Coverage button, then the Zones heading with the Add zone button and the Zone 1, Zone 2, and Zone 3 buttons, each with its zone's color dot, with Zone 1 selected](/assets/apollo-mmwave-radar-setup-and-zone-map.png) ### What to do first @@ -147,23 +147,24 @@ Your dashboard is working. Follow the **Start here** card on each tab, from the 1. Look at the **Radar setup** card near the top of the tab. If it flags a setting, follow what it says: most problems have a button that fixes them, and the card changes nothing until you press one. An R PRO-1 tab has a second one above the zone map, for the LD2450. 2. On an MSR-1 or MSR-2 tab, or an R PRO-1 tab with the LD2412 addon, calibrate the radar. Skip this step on an R PRO-1 without the LD2412. On an R PRO-1, first clear the room, press **Start Dynamic Background Correction** on the **LD2412 Controls** card, and wait for **Background Correction Running** to turn off. Then press **Calibrate with empty room** on the **Auto-calibrate** card and leave the room for about a minute and a half. You don't need to turn on Radar Engineering Mode: the calibration does that for you. The [tuning guide](apollo-mmwave-dashboard.md#calibrate-with-an-empty-room) walks you through it. - ![The Auto-calibrate card on an MSR-1, ready to run, with the Calibrate with empty room and Preview only buttons](/assets/apollo-mmwave-calibrate-idle.png) + ![The Auto-calibrate card on an MSR-1, ready to run, with the reminder to raise Radar Timeout to 60 s or more if Radar Target turns off while someone sits still, and the Calibrate with empty room and Preview only buttons](/assets/apollo-mmwave-calibrate-idle.png) -3. On an MTR-1 or R PRO-1 tab, [draw your zones](apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1). +3. On an MTR-1 or R PRO-1 tab, press **Add zone** under the zone map and draw your first zone. The [eight zone steps](apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) take you from **Cone rotation** to a zone that lights up when you walk into it. The rest of this page covers managing the dashboard, upgrading from an older setup, and troubleshooting, so come back to it when you need it. ## Manage the dashboard -After setup, Apollo mmWave changes its dashboard only when you ask it to, from the integration options: add the dashboard, remove it, or choose which sensors get a tab. Open **Settings โ†’ Devices & services โ†’ Apollo mmWave โ†’ Configure** to reach the **Apollo mmWave options** menu. It reads **These actions change only the Apollo mmWave dashboard this integration created. Dashboards you made yourself are never changed.** and lists the actions that fit: +After setup, Apollo mmWave changes its dashboard only when you ask it to, from the integration options: add the dashboard, remove it, restore it, or choose which sensors get a tab. Open **Settings โ†’ Devices & services โ†’ Apollo mmWave โ†’ Configure** to reach the **Apollo mmWave options** menu. It reads **These actions change only the Apollo mmWave dashboard this integration created. A dashboard you made on another URL is never touched.** and lists the actions that fit: [![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=apollo_mmwave) - **Add the Apollo mmWave dashboard** is listed while the integration has no dashboard of its own: you unticked the box during setup, setup couldn't create it, or you deleted it. It describes the dashboard it creates and asks **Only administrators can see it** again. Click **Submit** to create it, once, with the sensors you chose under **Choose the dashboard's devices**. - **Remove the Apollo mmWave dashboard** is listed while the integration has one. Click **Submit** to delete the **Apollo mmWave** dashboard at `/apollo-mmwave` that the integration created, along with any title, icon, or strategy options you changed on it. Your sensors, zones, and calibration values stay, and the cards still work on your own dashboards. You can add the dashboard again from the same menu. +- **Restore the automatic dashboard** is listed instead of those two while the dashboard is a saved copy, made with **Take control**. Click **Submit** to keep your copy as a dashboard of its own and put the automatic one back, as [If your dashboard is missing cards](#if-your-dashboard-is-missing-cards) describes. - **Choose the dashboard's devices** opens **Dashboard devices**, which is empty by default and shows every Apollo mmWave device Home Assistant knows about, online or not. Select one or more devices to show exactly those and hide the rest; a selected device keeps its tab even while it's offline. Clear the selection to go back to automatic detection. The picker only lists Apollo MSR-1, MSR-2, MTR-1, and R PRO-1 sensors added through ESPHome. -Each action takes effect as soon as you click **Submit**, with no restart, and an open dashboard picks up a new device selection without a reload. The device selection is written only into the dashboard the integration created. Without one, the selection is kept and used when you add the dashboard from the options. +Each action takes effect as soon as you click **Submit**, with no restart, and an open dashboard picks up a new device selection without a reload. The device selection is written only into the dashboard the integration created, while it still builds itself. Otherwise the selection is kept and used when you add or restore the dashboard from the options. You can also delete the dashboard under **Settings โ†’ Dashboards**, like any other. It stays deleted until you add it again from the options. @@ -178,16 +179,59 @@ Want a second dashboard, say one with only the bedroom sensors, or one at anothe 2. Pick **Apollo Radar Tuning** under **Community dashboards**. 3. Give it a title and a URL other than `apollo-mmwave`, then click **Create**. -A dashboard you add this way is yours from the start, and the integration options never change it. It shows every detected Apollo mmWave device; to limit it, set `devices` in its raw configuration, as the [Apollo mmWave configuration guide](https://github.com/ApolloAutomation/apollo-mmwave-main/blob/main/docs/configuration.md#choosing-which-devices-appear) shows. The URL matters: if you delete the integration's dashboard and add one of these at `apollo-mmwave`, Apollo mmWave can mistake it for the dashboard it created, and its options and removal would then act on yours. +A dashboard you add this way is yours from the start, and the integration options never change it. It shows every detected Apollo mmWave device; to limit it, set `devices` in its raw configuration, as the [Apollo mmWave configuration guide](https://github.com/ApolloAutomation/apollo-mmwave-main/blob/main/docs/configuration.md#choosing-which-devices-appear) shows. The URL matters. Apollo mmWave forgets its own dashboard when you delete it, but not while the integration isn't running, for example while it's disabled. If you delete the integration's dashboard then and add one of these at `apollo-mmwave`, Apollo mmWave can mistake it for the dashboard it created, and its options and removal would then act on yours. ### Use your own layout -Want to rearrange the cards? Click the pencil icon in the upper right corner of the dashboard and choose **Take control** in the dialog that opens. From then on the layout is yours: the integration stops offering to remove the dashboard, writes no device selection into it, and leaves it in place when you remove the integration. The dashboard also stops adding and removing tabs as sensors come and go. Changed your mind? Delete the dashboard under **Settings โ†’ Dashboards**, then choose **Add the Apollo mmWave dashboard** in the integration options to get a fresh one. If you add the Apollo tabs to a dashboard of your own, take control of that dashboard before you edit them; editing an auto-built tab directly discards its cards. +Want to rearrange the cards? Click the pencil icon in the upper right corner of the dashboard and choose **Take control** in the dialog that opens. From then on the layout is yours: the integration stops offering to remove the dashboard, writes no device selection into it, and leaves it in place when you remove the integration. The dashboard also stops adding and removing tabs as sensors come and go. Changed your mind? Choose **Restore the automatic dashboard** in the integration options: you get the automatic dashboard back, and your layout is kept as a dashboard of its own (see [If your dashboard is missing cards](#if-your-dashboard-is-missing-cards)). If you add the Apollo tabs to a dashboard of your own, take control of that dashboard before you edit them; editing an auto-built tab directly discards its cards. -A dashboard you took control of keeps the cards it had, so it doesn't pick up new cards from later releases, such as the updated **Start here** steps, the **Radar setup** cards, the **Device** card, and the slider lock that came with 2.3.0. To get them, delete it and add a fresh one from the options as described above. +A dashboard you took control of keeps the cards it had, so it doesn't pick up new cards from later releases, such as the updated **Start here** steps, the **Radar setup** cards, the **Device** card, and the slider lock that came with 2.3.0, or the wider zone map section, the **Radar Target** advice, the **LD2450 Presence** label, and **Target Count** as a whole number, which came with 2.4.0. Nothing on the dashboard says so, so from 2.4.0 Apollo mmWave checks for it and offers to restore it (see [If your dashboard is missing cards](#if-your-dashboard-is-missing-cards)). The zone map card itself always runs the current version, so its **Zones** panel and other new tools show up on a dashboard you took control of too. The cards also work on their own: in the card picker they're listed as **Apollo Radar Auto-Calibrate**, **Apollo Radar Distance Chart**, **Apollo Radar Gate Energy Chart**, **Apollo Radar Setup**, and **Apollo Zone Map**. The [Apollo mmWave configuration guide](https://github.com/ApolloAutomation/apollo-mmwave-main/blob/main/docs/configuration.md#use-your-own-dashboards-instead) has the YAML for placing them. +For a phone or a wall tablet where nobody draws zones, use the zone map's view-only mode. Add the **Apollo Zone Map** card to a dashboard of your own, pick your sensor under **Radar**, and turn on **View only (the map without drawing tools)**, or set `view_only: true` in the card's YAML. The card then shows its title and the live map, with lit zones, numbered dots and their trails, and the **Radar offline** note, but no drawing tools, buttons, zoom, **Zones** panel, or **Map settings**, and a swipe on it scrolls the page. The Apollo mmWave dashboard keeps the full map. + +```yaml +type: custom:apollo-radar-zone-map-card +device_id: your_device_id +view_only: true +``` + +![A view-only zone map at phone width: the title R PRO-1 Living Room and the live map, with no buttons on the map or under it. Dot 1 sits in the filled-in Couch zone with a short red trail back to the doorway behind it, and dot 2 sits in the filled-in Desk zone](/assets/apollo-mmwave-zone-map-view-only.png) + +### If your dashboard is missing cards + +Is your **Apollo mmWave** dashboard missing cards this guide describes, such as the **Radar setup** card, **LD2450 Controls** with **Zone Type** and **Multi Target Tracking**, **Zone presence**, or the **Device** card? Then someone used **Take control** on it under an earlier release, and it's a saved copy: it holds the cards it had at that moment and no longer builds itself. + +From Apollo mmWave 2.4.0, the integration checks for this each time it starts and whenever you save its options. While the dashboard it created is a saved copy, still made of Apollo mmWave cards, you get two ways to put the automatic dashboard back. Both say what they do, and neither changes anything until you click **Submit**: + +- **Settings โ†’ System โ†’ Repairs** lists **The Apollo mmWave dashboard is a saved copy**. Click it to open **Restore the automatic Apollo mmWave dashboard**. +- The integration options (**Settings โ†’ Devices & services โ†’ Apollo mmWave โ†’ Configure**) list **Restore the automatic dashboard**. + +[![Open your Home Assistant instance and show your repairs.](https://my.home-assistant.io/badges/repairs.svg)](https://my.home-assistant.io/redirect/repairs/) + +When you click **Submit**: + +1. Your copy is saved first, as a new dashboard named **Apollo mmWave (saved copy)** at `apollo-mmwave-saved`, or `apollo-mmwave-saved-2` and so on when that address is taken. It isn't in the sidebar, so open it from **Settings โ†’ Dashboards**. It's for administrators only if your dashboard was. +2. Only once the copy is saved does `apollo-mmwave` get the automatic dashboard back, with the sensors you chose under **Choose the dashboard's devices**. Its title, icon, sidebar setting, and admin-only setting stay as they were. + +The repair then reads **The issue is repaired!** and goes away. Open **Apollo mmWave** from the sidebar, or reload it if it's already open, to see every current card. Keep the saved copy as long as you want something from it, and delete it under **Settings โ†’ Dashboards** when you don't. + +If the restore can't finish, it says what happened, and the repair stays so you can try again. The log under **Settings โ†’ System โ†’ Logs** has a warning that starts with **Apollo mmWave:** and says why: + +- **Nothing was changed: your copy could not be saved as a separate dashboard, so the Apollo mmWave dashboard was left as it is.** No copy was made, and your dashboard is as it was. +- **Your copy is saved as the Apollo mmWave (saved copy) dashboard under Settings > Dashboards, but the Apollo mmWave dashboard could not be restored and was left as it is.** The copy is kept, and your dashboard is as it was. Each try keeps another copy, so delete the extra ones under **Settings โ†’ Dashboards**. + +A dashboard you rebuilt with no Apollo mmWave cards on it is yours, and gets no repair. When you delete the Apollo mmWave dashboard, the integration forgets it, so a dashboard you make at `apollo-mmwave` later gets no repair either. The exception is a dashboard you deleted while the integration wasn't running, for example while it was disabled: a new dashboard at that address with Apollo mmWave cards on it then gets the repair too, and still nothing changes until you click **Submit**. Removing the integration removes the repair and keeps the saved copy. + +**No repair, and no Restore in the options?** The check only looks at the dashboard Apollo mmWave recorded as the one it created, and it no longer knows yours if you took control of it under Apollo mmWave 2.2.5 or earlier, or saved the integration options after taking control of it, under a release before 2.4.0. To get the automatic dashboard back then: + +1. Open your old dashboard, click **Edit dashboard**, open the three-dot menu, and choose **Raw configuration editor**. Copy its contents somewhere safe if you want to keep anything from it. +2. Delete the dashboard under **Settings โ†’ Dashboards**. +3. In the integration options, choose **Add the Apollo mmWave dashboard** (see [Manage the dashboard](#manage-the-dashboard)). + +Or keep your old dashboard as it is and add a second one that builds itself, at another address, as [Add another Apollo mmWave dashboard](#add-another-apollo-mmwave-dashboard) shows. + ## Upgrade from an older setup If this is your first Apollo dashboard, skip this section and [calibrate your radar](apollo-mmwave-dashboard.md#calibrate-with-an-empty-room) or [draw your zones](apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1). [Troubleshooting](#troubleshooting) is at the end of this page if something didn't load. @@ -227,12 +271,33 @@ An update takes effect after a restart, and a browser or the Home Assistant app - **Android**: **Settings โ†’ Companion app โ†’ Troubleshooting โ†’ Reset frontend cache**. - **iPhone and iPad**: **Settings โ†’ Companion app โ†’ Debugging โ†’ Clear web view cache**, then **Clear Cache**. Older versions of the app call it **Reset frontend cache**. +On updates from Apollo mmWave 2.4.0 or later, the cards tell you when one of these steps is still to do. The **Radar setup** card shows a notice above its checks. A zone map card, view-only ones included, shows it under its title when it comes before any **Radar setup** card on the page, as on a dashboard of your own: + +- **Apollo mmWave was updated to 2.4.1, but this page still runs 2.4.0.**, with a **Reload** button and the line **In the Home Assistant app, if Reload does not help, close the app fully and open it again.** The page still runs the cards from before the update. Press **Reload**. +- **Apollo mmWave 2.4.1 is installed, but Home Assistant still runs 2.4.0. Restart Home Assistant to finish updating.** The page already runs the new cards, but Home Assistant hasn't restarted since the update. Restart it as step 1 shows, and the notice turns into the **Reload** one if the page needs it. + +The version numbers are the ones on your system. Only one card on the page shows the notice, and it goes away once the page and Home Assistant run the same version. Cards from earlier releases have no such check, so on the update to 2.4.0 itself, no notice doesn't mean the page runs the new cards: do the steps above anyway. + +### Updating to Apollo mmWave 2.4.0 + +After the restart and a reload, the zone map fills in each zone while someone is in it and numbers the dots, zooms in up to 8 times, and snaps the corners you draw to round values, and administrators get new tools: walking a zone's corners, ignore zones, hold times, a left-to-right flip, and movement history. The expand button in the map's top-right corner gives the map the whole window. Your zones move out of **Configure โ†’ Zones** into a **Zones** panel right under the map, with **Add zone**, a button for each zone, and an editor for the zone you pick. **Configure** is now **Map settings**, at the bottom of the card. Nothing changes on its own: every zone stays a detect zone with no hold, the map isn't flipped, and movement history stays off until an administrator turns it on. A dashboard you took control of gets these too, because they're part of the card. [Draw zones on the R PRO-1 and MTR-1](apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) covers them. + +The Apollo mmWave dashboard also gives the zone map a section two columns wide on a computer, which a dashboard you took control of doesn't get. If the integration's own dashboard is one, Home Assistant lists a repair that restores it and keeps your copy (see [If your dashboard is missing cards](#if-your-dashboard-is-missing-cards)). Check these if they apply to you: + +- **Zone habits from 2.3.0.** A zone's name has no **Save** button any more: type it and press Enter, or leave the box. **Clear All Zones** is now **Clear all shapes** under **Map settings**. It and **Delete zone** ask before they act, and a double-click on a zone's button no longer clears its shape. [Pick a zone in the Zones panel](apollo-mmwave-dashboard.md#pick-a-zone-in-the-zones-panel) shows the rest. +- **Automations that use zone presence.** A zone's presence sensor now reads unavailable while its radar is offline, and after every Home Assistant restart until the radar connects. Before 2.4.0 it read off. A trigger with `to: "off"` and no `from:` now also fires when the radar comes back, after every restart. That's harmless for lights-off automations, and such a trigger still catches a zone that emptied while the radar was offline. A trigger with `from: "on"` skips both, so use it only where the trigger must see someone leave, such as a notification or a counter. [Use the zone sensors](apollo-mmwave-dashboard.md#use-the-zone-sensors) shows both. A zone can also turn on up to about half a second later than under 2.3.0, because zone presence now waits for both halves of the radar's position report. +- **Automations, templates, and history graphs that use Target X or Y.** Once after the update, Apollo mmWave shows an R PRO-1's or MTR-1's Target X and Y in mm instead of the inches Home Assistant picked on US customary units, and a notification titled **Apollo mmWave: Target X and Y now in mm** lists what it switched. It leaves alone a sensor that an automation, a script, or a helper uses. A YAML template sensor, a dashboard card, or another tool that reads them, such as Node-RED, reads mm from then on, 25.4 times the inch value. [Target X and Y units](apollo-mmwave-dashboard.md#target-x-and-y-units) shows how to go back. +- **Automations on an MSR-1 or MSR-2's zone sensors.** The dashboard now recommends **Radar Target** for automations that cover the whole room, instead of **Any zone**: the zone sensors also need the radar's distance, which can read unknown while someone is there. Keep **Any zone** only where you want to ignore people past End Zone 3. +- **A card still looks like 2.3.0.** Reload it as [Load the new cards](#load-the-new-cards) shows: **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac) in a browser, or close the Home Assistant app fully and open it again. +- **Dashboard resources managed in YAML.** Replace both `?v=` addresses with the ones the log warning lists (see [An Apollo card shows an error after an update](#an-apollo-card-shows-an-error-after-an-update)). +- **Going back to 2.3.0.** Before going back to 2.3.0, turn **Movement history** off on every radar. 2.3.0 neither reads nor deletes the history file, so it would stay on disk and in every later backup, even after you remove the integration. Under 2.3.0, ignore zones act as ordinary zones and no zone holds. A zone you redraw, clear, or undo there loses its type and hold, and 2.3.0 forgets the flip the next time it saves your zones. 2.3.0 also ignores view-only mode, so a view-only zone map shows the full map with its drawing tools again, and on a phone a swipe that starts on the map doesn't scroll the page: remove or replace those cards first. A saved copy that a restore kept stays a dashboard of its own. + ### Updating to Apollo mmWave 2.3.0 In most setups 2.3.0 needs nothing from you. After the restart and a reload, each tab gets the new layout: **Start here** and **Radar setup** at the top, locked sliders, the zone map in your units with the LD2450's cards beside it, and the **Device** card at the bottom. Check these if they apply to you: - **Zones drawn before 2.2.7 with Home Assistant in US customary units.** Before 2.2.7, the zone map read the radar's positions in inches as if they were millimeters, so the dots sat at or near the sensor. A zone drawn around those dots may not cover where people show up now. Walk through the room, watch the dots, and redraw any zone that's off. -- **A dashboard you took control of** keeps the cards it had. To get the new ones, see [Use your own layout](#use-your-own-layout). +- **A dashboard you took control of** keeps the cards it had. To get the new ones, see [If your dashboard is missing cards](#if-your-dashboard-is-missing-cards). - **A zone map card you added from the card picker before 2.3.0** keeps the fixed grid saved in its YAML, with no distance labels or range caption. If you didn't choose that grid yourself (the card picker saved `x_min: -6000`, `x_max: 6000`, `y_min: 0`, `y_max: 12000` with `grid_units: mm`), open the card's code editor, delete `grid` and `grid_units`, and set `unit_display: true` to get the map fitted to the radar's view, in your units. A grid you set on purpose can stay. - **Dashboard resources managed in YAML.** Replace both `?v=` addresses with the ones the log warning lists (see [An Apollo card shows an error after an update](#an-apollo-card-shows-an-error-after-an-update)). @@ -373,20 +438,26 @@ The dashboard starts with **No Apollo mmWave devices found.** It found no radar Work through these in order: - If **Dashboard devices** has any devices selected, the dashboard shows only those. Add the missing sensor under **Choose the dashboard's devices** in the integration options, or clear the selection to go back to automatic detection. -- A dashboard you took control of no longer adds tabs on its own. Add the sensor's cards yourself, or delete the dashboard and add a fresh one from the integration options. +- A dashboard you took control of no longer adds tabs on its own. Add the sensor's cards yourself, or restore the automatic dashboard as [If your dashboard is missing cards](#if-your-dashboard-is-missing-cards) shows. - The dashboard only picks up radars added through the ESPHome integration. A copy of the same sensor that another integration created (a network integration tracking it by its MAC address, for example) doesn't get a tab. - A sensor you added a moment ago gets its tab once Home Assistant has registered its entities. It appears on its own, without a page reload. - DIY builds that don't report an Apollo model only get a tab while one of their radar entities is live. +### The dashboard is missing cards + +A tab without the **Radar setup** card, **LD2450 Controls** (with **Zone Type** and **Multi Target Tracking**), **Zone presence**, or the **Device** card, while your sensor has those settings, is on a saved copy: someone used **Take control** on the dashboard under an older release. Look under **Settings โ†’ System โ†’ Repairs** for **The Apollo mmWave dashboard is a saved copy**, or in the integration options for **Restore the automatic dashboard**. [If your dashboard is missing cards](#if-your-dashboard-is-missing-cards) explains both, and what to do when neither is there. + +If the cards are all there but one looks like an older release, the page still runs the old cards: reload it as [Load the new cards](#load-the-new-cards) shows. + ### A tab says the sensor is offline -The **Start here** card adds **Offline right now.**, and the **Radar setup** card reads **Radar is offline. Its settings are checked once it reconnects.** On an MSR-1, MSR-2, or R PRO-1 tab, the Auto-calibrate card reads **Radar is offline. Calibration needs the radar online and its gate entities enabled.** with its buttons disabled. On an MTR-1 or R PRO-1 tab, the zone map shows no targets until the sensor reconnects. The tab stays so the sensor isn't silently missing, and the cards fill in once it reconnects. Check its power and Wi-Fi, and that it shows as online on the ESPHome integration page. If you replaced or reflashed the sensor under a new name, the old device entry is what's showing as offline: delete the old device under **Settings โ†’ Devices & services** and its tab goes away. +The **Start here** card adds **Offline right now.**, and the **Radar setup** card reads **Radar is offline. Its settings are checked once it reconnects.** On an MSR-1, MSR-2, or R PRO-1 tab, the Auto-calibrate card reads **Radar is offline. Calibration needs the radar online and its gate entities enabled.** with its buttons disabled. On an MTR-1 or R PRO-1 tab, the zone map shows **Radar offline** and no targets until the sensor reconnects. The tab stays so the sensor isn't silently missing, and the cards fill in once it reconnects. Check its power and Wi-Fi, and that it shows as online on the ESPHome integration page. If you replaced or reflashed the sensor under a new name, the old device entry is what's showing as offline: delete the old device under **Settings โ†’ Devices & services** and its tab goes away. If the sensor works but its tab still says **Offline right now.**, reload the page: from Apollo mmWave 2.4.0, a tab keeps that note until the page reloads, for example when you opened the dashboard while the radars were reconnecting after a restart. [![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=esphome) ### An Apollo card shows an error after an update -After you update Apollo mmWave and restart, a browser that still holds the previous version's files can show the Apollo cards as error boxes that read **Custom element doesn't exist**. Refresh the page. Each release loads its cards under a new versioned address, so a fresh page load picks up the current version. If the error is still there, do a hard refresh with **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac). In the Home Assistant app on a phone or tablet, close the app fully and open it again, then clear its cache if the error stays, as [Load the new cards](#load-the-new-cards) shows. If that doesn't clear it either, check **Settings โ†’ System โ†’ Logs** for a warning that starts with **Apollo mmWave:** about Lovelace resources. On a system that manages its dashboard resources in YAML, the warning lists the two resource addresses to add by hand. +After you update Apollo mmWave and restart, a browser that still holds the previous version's files can show the Apollo cards as error boxes that read **Custom element doesn't exist**. Refresh the page. Each release loads its cards under a new versioned address, so a fresh page load picks up the current version. If the error is still there, do a hard refresh with **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac). In the Home Assistant app on a phone or tablet, close the app fully and open it again, then clear its cache if the error stays, as [Load the new cards](#load-the-new-cards) shows. On updates from Apollo mmWave 2.4.0 or later, a card that does load, such as the **Radar setup** card, or a zone map that shows an error instead of its map, says which version the page runs and which one Home Assistant runs, with a **Reload** button when a reload fixes it. If that doesn't clear it either, check **Settings โ†’ System โ†’ Logs** for a warning that starts with **Apollo mmWave:** about Lovelace resources. On a system that manages its dashboard resources in YAML, the warning lists the two resource addresses to add by hand. [![Open your Home Assistant instance and show your Home Assistant logs.](https://my.home-assistant.io/badges/logs.svg)](https://my.home-assistant.io/redirect/logs/) diff --git a/docs/products/general/setup/apollo-mmwave-dashboard.md b/docs/products/general/setup/apollo-mmwave-dashboard.md index 126e3a4c14..b482c98778 100644 --- a/docs/products/general/setup/apollo-mmwave-dashboard.md +++ b/docs/products/general/setup/apollo-mmwave-dashboard.md @@ -7,16 +7,29 @@ description: Check the radar's settings, calibrate the radar in your Apollo MSR- The Apollo mmWave dashboard puts every setting your radar has on one screen, with live charts that show what the radar sees. On an Apollo MSR-1, Apollo MSR-2, or Apollo R PRO-1 with the optional LD2412 radar addon, it can teach the radar what your empty room looks like in about a minute and a half, so it stops reacting to the room itself and starts reacting to people. On an R PRO-1 or an Apollo MTR-1 it is also where you draw occupancy zones on a map of the room. -Every tab starts with a **Start here** card that lists your sensor's first steps in order, and this guide follows the same order: check the **Radar setup** card, calibrate, set how far the radar looks and how long presence stays on, then fine-tune by hand. If you only do one thing today, press **Calibrate with empty room** and leave the room: [Calibrate with an empty room](#calibrate-with-an-empty-room) shows what to expect. On an MTR-1, or an R PRO-1 without the LD2412, go straight to [drawing zones](#draw-zones-on-the-r-pro-1-and-mtr-1). +Every tab starts with a **Start here** card that lists your sensor's first steps in order, and this guide follows the same order: check the **Radar setup** card, calibrate, set how far the radar looks and how long presence stays on, then fine-tune by hand. If you only do one thing today, press **Calibrate with empty room** and leave the room: [Calibrate with an empty room](#calibrate-with-an-empty-room) shows what to expect. On an MTR-1, or an R PRO-1 without the LD2412, go straight to the [eight steps to your first zone](#draw-zones-on-the-r-pro-1-and-mtr-1). + +!!! info "What's new in 2.4.0" + + Most of 2.4.0 is on the zone map of R PRO-1 and MTR-1 tabs, and the [eight zone steps](#draw-zones-on-the-r-pro-1-and-mtr-1) walk you through it. + + - **A Zones panel under the map.** Add a zone, then name it and set its **Type** and **Hold** right there: [Add a zone](#add-a-zone). + - **Expand map.** One press gives the zone map the whole window, with the **Zones** panel beside it: [Expand the map](#expand-the-map). + - **A map that shows what's happening.** Zones light up while someone is in them, and each target is a numbered dot with a trail: [Read the map](#read-the-map). + - **Ignore zones and hold times**, for a fan or a curtain, and for someone who sits still: [Ignore a spot or hold a zone](#ignore-a-spot-or-hold-a-zone). + - **Zoom up to 8x** with corners that snap to round values, plus [marking corners by walking](#mark-corners-by-walking) and [movement history](#replay-movement-history): [Zoom in and move the map](#zoom-in-and-move-the-map). + - **Target X and Y in mm.** Apollo mmWave switches an R PRO-1's or MTR-1's position sensors to mm for you: [Target X and Y units](#target-x-and-y-units). + - **On MSR-1 and MSR-2 tabs**, a line under the Gate Energy chart says whether the radar reports a target: [Third column](#third-column). + - **After an update**, the cards tell you when the page needs a reload: [Load the new cards](apollo-mmwave-dashboard-setup.md#load-the-new-cards). Here's the **Start here** card on an MSR-1. On an MTR-1, or an R PRO-1 without the LD2412, it lists three zone map steps instead, and on an R PRO-1 with the LD2412 it covers both radars. -![The Start here card for an MSR-1 named MSR-1 Kitchen, with five numbered steps: fix anything the Radar setup card flags, press Calibrate with empty room, set Max Move Gate and Max Still Gate (each gate is about 2.5 ft), set Radar Timeout, and walk the room while you watch the Gate Energy chart, followed by the Full tuning guide and All settings for this device links](/assets/apollo-mmwave-start-here.png) +![The Start here card for an MSR-1 named MSR-1 Kitchen, with five numbered steps: fix anything the Radar setup card flags, press Calibrate with empty room, set Max Move Gate and Max Still Gate (each gate is about 2.5 ft), set Radar Timeout, and walk the room while you watch the Gate Energy chart, then the line In automations, use Radar Target for the whole room. If it turns off while someone sits still, raise Radar Timeout to 60 s or more. To ignore people past End Zone 3, use Any zone instead., followed by the Full tuning guide and All settings for this device links](/assets/apollo-mmwave-start-here.png) !!! note "Before you start" - The Apollo mmWave integration is installed and its **Apollo mmWave** dashboard is in your Home Assistant sidebar. If it isn't, sign in as an administrator (from Apollo mmWave 2.2.6, the dashboard is for administrators only unless you unticked that box), or follow the [Apollo mmWave dashboard setup guide](apollo-mmwave-dashboard-setup.md) to add it. - - This guide shows Apollo mmWave 2.3.0. On an older version some cards look different, so [update it](apollo-mmwave-dashboard-setup.md#upgrade-from-an-older-setup) first. + - This guide shows Apollo mmWave 2.4.0. On an older version some cards look different, so [update it](apollo-mmwave-dashboard-setup.md#upgrade-from-an-older-setup) first. If a card this guide describes isn't on your tab, see [If your dashboard is missing cards](apollo-mmwave-dashboard-setup.md#if-your-dashboard-is-missing-cards). - Your radar is online in Home Assistant through ESPHome. - Your sensor is mounted where it will stay. A calibration, and the zones you draw, describe the room from the sensor's position, so moving the sensor later means calibrating again or redrawing your zones. - A calibration needs the room empty for about a minute and a half: people and pets out, robot vacuum docked. @@ -27,7 +40,7 @@ The radar splits the space in front of it into distance bands called *gates*. G0 Each gate has a *move threshold* and a *still threshold*. When a gate's energy rises above its threshold, that gate detects a target (the radar's word for a person, or anything else it picks up) and the radar reports presence. A lower threshold makes the gate more sensitive (and more likely to trigger on a fan or a curtain); a higher one makes it less sensitive. To see the live energy of every gate, the radar has to be in **Radar Engineering Mode**, a diagnostic setting that streams the per-gate readings to Home Assistant. With it off you still get presence, but the Gate Energy chart has nothing to show. It's safe to turn on and off whenever you like: it changes what the radar reports, not how it detects. The calibration turns it on for you while it listens. Left on, it saves every gate's energy to Home Assistant's database about once a second, so the **Radar setup** card reminds you to turn it off. -![The LD2410 Gate Energy chart with Radar Engineering Mode on: a purple move bar and a green still bar for each gate from G0 to G8, and triangles marking each gate's move and still thresholds](/assets/apollo-mmwave-gate-energy-live.png) +![The LD2410 Gate Energy chart with Radar Engineering Mode on, with someone at gate G2: a purple move bar and a green still bar for each gate from G0 to G8, with triangles marking each gate's move and still thresholds. Both G2 bars are above their thresholds and outlined. G7 and G8 are faded because Max Move Gate and Max Still Gate are 6, so the tall move bar at G8 is not outlined. The legend ends with outlined bar = above threshold and faded = outside the radar's range (ignored), and the line under it reads The radar reports a moving and a still target.](/assets/apollo-mmwave-gate-energy-live.png) !!! tip "How far away is each gate?" @@ -48,6 +61,8 @@ The card changes nothing on its own. When it flags something, it says what's wro The last two have no button: the card explains them and leaves the new values to you. On an MTR-1, the **Radar setup** card under **Start here** checks the LD2450 instead, and an R PRO-1 tab has a second **Radar setup** card above the zone map for its LD2450. Both are covered in [Check the LD2450's Radar setup card](#check-the-ld2450s-radar-setup-card). +After you update Apollo mmWave, the **Radar setup** card can also show a notice above its checks, such as **Apollo mmWave was updated to 2.4.1, but this page still runs 2.4.0.** with a **Reload** button. It means the page still runs the cards from before the update. [Load the new cards](apollo-mmwave-dashboard-setup.md#load-the-new-cards) explains each notice. + ## Calibrate with an empty room Calibration is the fastest way to a well-tuned radar. Home Assistant listens to every gate while nobody is in the room, notes the highest energy each gate reaches from the room itself (fans, curtains, plants), and sets each threshold a little above that. Your current thresholds are saved first, so you can always put them back. @@ -64,7 +79,7 @@ On an MSR-1 or MSR-2 that has never been tuned, the card may also say **These lo A threshold of 100 means that gate never triggers, so some people set a gate to 100 to turn it off. Calibration sets every gate the radar uses, including those, and the card warns you first, for example **The G2 still threshold is off (set to 100). Calibrating will turn it back on.** If you turned that gate off on purpose, calibrate anyway and set it back to 100 afterward on the **Still Thresholds** (or **Move Thresholds**) card. -![The Auto-calibrate card on an MSR-1 before a run, with its checklist, the warning The G2 still threshold is off (set to 100). Calibrating will turn it back on., and the Calibrate with empty room and Preview only buttons](/assets/apollo-mmwave-calibrate-idle.png) +![The Auto-calibrate card on an MSR-1 before a run, with its checklist, the warning The G2 still threshold is off (set to 100). Calibrating will turn it back on., the reminder If Radar Target turns off while someone sits still, raise Radar Timeout to 60 s or more on the Detection Range card., and the Calibrate with empty room and Preview only buttons](/assets/apollo-mmwave-calibrate-idle.png) ### Run a calibration @@ -105,7 +120,7 @@ When the run finishes, the card shows **Thresholds updated** and a summary such Below the summary is a table with one row per gate and the columns **Gate**, **Move peak**, **Move threshold**, **Still peak**, and **Still threshold**. The peak is the highest energy that gate reached while the room was empty. The new threshold is that peak plus some headroom, capped at 100. From Apollo mmWave 2.2.4, the headroom is 15 points or 35% of the peak, whichever is larger: a move peak of 14 becomes a threshold of 29, and a still peak of 60 becomes 81. Earlier versions used 10 points or a quarter of the peak, so calibrate again after updating to get the extra headroom. -![The result of a calibration on an MSR-1: Thresholds updated, Calibrated at 01:04 PM from 60 samples. 18 of 18 thresholds changed., the result table with each gate's peak and its old and new threshold, such as G2 move peak 6 and 16 โ†’ 21, the walk-test line, and the Undo (restore your previous values), Calibrate again, and Close buttons](/assets/apollo-mmwave-calibrate-result.png) +![The result of a calibration on an MSR-1: Thresholds updated, Calibrated at 01:04 PM from 60 samples. 18 of 18 thresholds changed., the result table with each gate's peak and its old and new threshold, such as G2 move peak 6 and 16 โ†’ 21, the walk-test line, the reminder to raise Radar Timeout to 60 s or more if Radar Target turns off while someone sits still, and the Undo (restore your previous values), Calibrate again, and Close buttons](/assets/apollo-mmwave-calibrate-result.png) What the threshold cells mean: @@ -126,10 +141,12 @@ Under the table, the card suggests a walk test: **Now walk around, then sit still for a minute: the Radar Target row in Target / Occupancy should stay on the whole time you are in the room and turn off a few seconds after you leave (Radar Timeout).** 1. Press **Turn on Radar Engineering Mode** on the Gate Energy chart if you'd like to watch the gates as well. -2. Walk through the room, then sit where you usually sit and stay still for a minute or two. **Radar Target** covers still presence as well as movement, so it should stay on the whole time. With Radar Engineering Mode on, the bars of the gates you're in should be outlined. -3. Leave the room. **Radar Target** should turn off a few seconds later, once **Radar Timeout** runs out, and no gate inside the radar's range should stay outlined. +2. Walk through the room, then sit where you usually sit and stay still for a minute or two. **Radar Target** covers still presence as well as movement, so it should stay on the whole time. With Radar Engineering Mode on, the bars of the gates you're in should be outlined, and the line under the chart should say the radar reports a target, such as **The radar reports a still target.** +3. Leave the room. **Radar Target** should turn off a few seconds later, once **Radar Timeout** runs out, no gate should stay outlined, and the line under the chart should read **The radar reports no target.** 4. If you turned on Radar Engineering Mode, press **Turn off Radar Engineering Mode** on the **Radar setup** card, or use the switch on the **Controls** card. +If **Radar Target** turns off while you sit still, see [Radar Target turns off while someone sits still](#radar-target-turns-off-while-someone-sits-still). + Below the walk-test line are three buttons: **Undo (restore your previous values)**, **Calibrate again** (a fresh calibration with a new countdown and listen), and **Close**. If the radar now misses you, or behaves worse than before, press **Undo (restore your previous values)**. The card shows **Restoring saved thresholds... 3 of 16** and then **Restored your previous values.** Undo saves the values it replaces first, so the button then reads **Redo (put the calibrated values back)**, and pressing it puts the calibrated values back. The saved copy survives a Home Assistant restart. ![The Auto-calibrate card after Undo: Restored your previous values., the checklist, and the Redo (put the calibrated values back) and Calibrate with empty room buttons](/assets/apollo-mmwave-calibrate-restored.png) @@ -154,18 +171,18 @@ Open **Apollo mmWave** from your sidebar and, if you have more than one radar, p ### First column -- **Start here**: your sensor's name and its first steps, pictured at the top of this guide. It ends with two links. **Full tuning guide โ†’** opens this guide on the wiki: on an MSR-1 or MSR-2 the general version, the one that covers every Apollo radar, and on an R PRO-1 [the R PRO-1 version](/products/rpro1/setup/apollo-mmwave-dashboard.md#r-pro-1-and-its-ld2412-radar) at its LD2412 section. **All settings for this device โ†’** opens the sensor's own page in Home Assistant, where every setting the dashboard leaves out lives. On an R PRO-1, the card also says what each radar is for and which presence sensor to use in automations. +- **Start here**: your sensor's name and its first steps, pictured at the top of this guide. It ends with two links. **Full tuning guide โ†’** opens this guide on the wiki: on an MSR-1 or MSR-2 the general version, the one that covers every Apollo radar, and on an R PRO-1 [the R PRO-1 version](/products/rpro1/setup/apollo-mmwave-dashboard.md#r-pro-1-and-its-ld2412-radar) at its LD2412 section. **All settings for this device โ†’** opens the sensor's own page in Home Assistant, where every setting the dashboard leaves out lives. On an MSR-1 or MSR-2, a line under the steps says which sensor to use in automations: **In automations, use Radar Target for the whole room. If it turns off while someone sits still, raise Radar Timeout to 60 s or more.** With the **Any zone** sensor, it adds **To ignore people past End Zone 3, use Any zone instead.** On an R PRO-1, the card also says what each radar is for and which presence sensor to use in automations (see [Use the zone sensors](#use-the-zone-sensors)). - **Radar setup**: checks the radar's settings and offers a fix (see [Start with the Radar setup card](#start-with-the-radar-setup-card)). -- **Auto-calibrate**: the calibration card. It shows the chip and the device name under its title, a short checklist, and the **Calibrate with empty room** button. Everything about it is in [Calibrate with an empty room](#calibrate-with-an-empty-room) above. +- **Auto-calibrate**: the calibration card. It shows the chip and the device name under its title, a short checklist, and the **Calibrate with empty room** button. Under the checklist, and under the result of a calibration, it reminds you: **If Radar Target turns off while someone sits still, raise Radar Timeout to 60 s or more on the Detection Range card. Undo restores the thresholds from before a calibration.** Everything else about it is in [Calibrate with an empty room](#calibrate-with-an-empty-room) above. - **LD2410 Controls**: the **Radar Engineering Mode** switch, plus **Radar Bluetooth (HLK app)**, **Restart Radar**, and **Factory Reset Radar**. On an R PRO-1 the card also has **Start Dynamic Background Correction** and **Background Correction Running** (see [R PRO-1 and its LD2412 radar](#r-pro-1-and-its-ld2412-radar)). **Radar Bluetooth (HLK app)** is the radar chip's own Bluetooth for the HLK phone app, not your sensor's Bluetooth proxy. **Restart Radar** restarts the radar chip without changing any settings. Leave **Factory Reset Radar** alone unless Apollo support asks you to press it: it puts the radar chip's settings, every threshold included, back to factory values, so run **Calibrate with empty room** again if it happens. Both ask before they act. The restart for the whole sensor is on the **Device** card at the bottom of the tab. ![The LD2410 Controls card with the Radar Engineering Mode and Radar Bluetooth (HLK app) switches, a Restart button on the Restart Radar row, and a Reset button on the Factory Reset Radar row](/assets/apollo-mmwave-controls.png) -- **LD2410 Zone Config** (MSR-1 and MSR-2): **Start Zone 1**, **End Zone 1**, **End Zone 2**, and **End Zone 3** split the radar's range into three distance bands, each with its own occupancy sensor (**Radar Zone 1 Occupancy** to **Radar Zone 3 Occupancy**). These are distances from the sensor, not areas you draw like on the R PRO-1 and MTR-1 zone map. The boxes are in cm, even when Home Assistant uses feet, and the zones sit back to back: Zone 1 runs from Start Zone 1 to End Zone 1, Zone 2 from there to End Zone 2, and Zone 3 from there to End Zone 3. They're optional: leave them as they are unless you want separate sensors for, say, the couch and the far end of the room. +- **LD2410 Zone Config** (MSR-1 and MSR-2): **Start Zone 1**, **End Zone 1**, **End Zone 2**, and **End Zone 3** split the radar's range into three distance bands, each with its own occupancy sensor (**Radar Zone 1 Occupancy** to **Radar Zone 3 Occupancy**). These are distances from the sensor, not areas you draw like on the R PRO-1 and MTR-1 zone map. The boxes are in cm, even when Home Assistant uses feet, and the zones sit back to back: Zone 1 runs from Start Zone 1 to End Zone 1, Zone 2 from there to End Zone 2, and Zone 3 from there to End Zone 3. They're optional: leave them as they are unless you want separate sensors for, say, the couch and the far end of the room. The note under the card ends with **For the whole room, use Radar Target in automations: the zone sensors also need the radar's distance, which can read unknown while someone is there.** The zone sensors only know which band someone is in from the distance the radar reports, while **Radar Target** comes from the radar's own detection. ### Second column -- **LD2410 Distances**: a chart laid out along the radar's range. From top to bottom it can show a **Zones** row with your three distance bands (**Z1** to **Z3**, with a filled circle when someone is in that band), bars for the current **Detection**, **Moving**, and **Still** distance, the **Gates** row, and bars that mark how far the radar is set to look (**Max Move** and **Max Still**, or **Max Gate** and **Min Gate** on an R PRO-1). On a computer, hover over a row for a short explanation. Distances show in meters, or in inches if Home Assistant uses US units. +- **LD2410 Distances**: a chart laid out along the radar's range. From top to bottom it can show a **Zones** row with your three distance bands (**Z1** to **Z3**, with a filled circle when someone is in that band), bars for the current **Detection**, **Moving**, and **Still** distance, the **Gates** row, and bars that mark how far the radar is set to look (**Max Move** and **Max Still**, or **Max Gate** and **Min Gate** on an R PRO-1). On a computer, hover over a row for a short explanation. Distances show in meters, or in inches if Home Assistant uses US units. When the radar reports a target but its distance reads unknown, the row reads **distance unknown** instead of a length, and its explanation adds **The radar reports a target, but its distance reads unknown.** The three zone sensors need that distance, so they can read clear at that moment while **Radar Target** is on. ![The LD2410 Distances chart with nobody in the room: the Zones row with Z1 to Z3, Detection, Moving and Still rows that read no target, the Gates row from G1 to G8, and the Max Move and Max Still bars, on a scale in inches](/assets/apollo-mmwave-distances.png) @@ -173,11 +190,16 @@ Open **Apollo mmWave** from your sidebar and, if you have more than one radar, p ![The LD2410 Detection Range card with the Radar Timeout box set to 10s, the row Sliders locked, A scroll cannot move them. with an Unlock button, and the Max Move Gate and Max Still Gate sliders grayed out at 8](/assets/apollo-mmwave-detection-range-locked.png) -- **LD2410 Target / Occupancy**: **Radar Target** (anyone detected), **Radar Moving Target**, **Radar Still Target**, and on an MSR-1 or MSR-2 **Radar Zone 1 Occupancy** to **Radar Zone 3 Occupancy** and **Any zone**, which is on while someone is in any of the three zones. A row lights up while it's on. On an R PRO-1 this card sits in the first column instead. +- **LD2410 Target / Occupancy**: **Radar Target** (anyone detected), **Radar Moving Target**, **Radar Still Target**, and on an MSR-1 or MSR-2 **Radar Zone 1 Occupancy** to **Radar Zone 3 Occupancy** and **Any zone**, which is on while someone is in any of the three zones. A row lights up while it's on. On an R PRO-1 this card sits in the first column instead. For an automation that covers the whole room, use **Radar Target**. ### Third column -- **LD2410 Gate Energy**: the chart you tune with. Each gate has two bars, a purple one for move energy and a green one for still energy, on a 0 to 100 scale. While Radar Engineering Mode is on, a right-pointing triangle marks each gate's move threshold and a left-pointing triangle its still threshold, and a bar that rises above its threshold gets an outline in the threshold's color: **outlined bar = above threshold (detecting)**. While Radar Engineering Mode is off, the chart is dimmed with **Turn on Radar Engineering Mode to see gate energy values** and a **Turn on Radar Engineering Mode** button you can press right there. +- **LD2410 Gate Energy**: the chart you tune with. Each gate has two bars, a purple one for move energy and a green one for still energy, on a 0 to 100 scale. While Radar Engineering Mode is on, a right-pointing triangle marks each gate's move threshold and a left-pointing triangle its still threshold, and a bar that rises above its threshold gets an outline in the threshold's color: **outlined bar = above threshold**. Gates outside the range the radar uses are faded and never outlined, because the radar ignores their energy: past **Max Move Gate** for move bars and **Max Still Gate** for still bars, or outside **Min Gate** to **Max Gate** on an R PRO-1. While a gate is faded, the legend adds **faded = outside the radar's range (ignored)**. + + Under the chart, a line gives the radar's own answer while Radar Engineering Mode is on: **The radar reports a moving and a still target.**, **The radar reports a moving target.**, **The radar reports a still target.**, or **The radar reports no target.** An outlined bar and the radar's answer usually agree. On an MSR-1 or MSR-2, when the radar reports no target while a bar in its range is outlined, the chart adds **Energy above a threshold does not always mean a target. Once the LD2410 loses someone who sits still, it often needs them to move before it detects them again.** (see [Radar Target turns off while someone sits still](#radar-target-turns-off-while-someone-sits-still)). + + While Radar Engineering Mode is off, the chart is dimmed with **Turn on Radar Engineering Mode to see gate energy values** and a **Turn on Radar Engineering Mode** button you can press right there. + - **LD2410 Move Thresholds**: one slider per gate (**G0** to **G8** on an MSR-1 or MSR-2, **G0** to **G13** on an R PRO-1) to set each gate's move threshold. Each row is named for how far out its gate reaches, from **G0 (at the sensor)** to **G8 (about 6 m)**, in feet when Home Assistant uses US customary units. The sliders start locked, like the Detection Range ones. A note underneath recaps how thresholds work. ### Fourth column @@ -203,7 +225,7 @@ Every R PRO-1 has an LD2450 radar, and the optional LD2412 addon adds a second o - There is no Zone Config card, and the Distances chart shows the gates and the Max Gate and Min Gate bars without live distance bars. - Before it writes, the calibration asks the radar for its current thresholds (**Reading the radar's current thresholds...**), so what it saves for Undo matches the radar. -![The Auto-calibrate card on an R PRO-1, titled LD2412 ยท R PRO-1 Server Rack, with a fourth checklist item asking you to run Start Dynamic Background Correction first](/assets/apollo-mmwave-calibrate-r-pro-1.png) +![The Auto-calibrate card on an R PRO-1, titled LD2412 ยท R PRO-1 Server Rack, with a fourth checklist item asking you to run Start Dynamic Background Correction first, and under the checklist the reminder to raise Radar Timeout to 60 s or more if Radar Target turns off while someone sits still](/assets/apollo-mmwave-calibrate-r-pro-1.png) The LD2412 also has its own background learning, **Start Dynamic Background Correction** on the **LD2412 Controls** card. It runs on the radar chip and stores its result inside the radar. **Background Correction Running** shows whether it is still working. Use both, in this order: @@ -226,7 +248,7 @@ Steps 3 and 4 on **Start here** point at the **Detection Range** card: how far t 2. Lower **Max Move Gate** and **Max Still Gate** (**Max Gate** on an R PRO-1) to stop the radar looking past a certain distance, such as a hallway beyond the doorway. The note under the card gives each gate's depth. On an R PRO-1, raise **Min Gate** to ignore anything right next to the sensor. -3. Raise **Radar Timeout** if lights turn off while you sit still. It's how long **Radar Target** (**LD2412 Presence** on an R PRO-1) stays on after the radar last detects someone. It's a number box, so it's never locked. +3. Raise **Radar Timeout**, to 60 s or more, if lights turn off while you sit still (see [Radar Target turns off while someone sits still](#radar-target-turns-off-while-someone-sits-still)). It's how long **Radar Target** (**LD2412 Presence** on an R PRO-1) stays on after the radar last detects someone. It's a number box, so it's never locked. The sliders lock again on their own after 5 minutes without a change, when you leave the tab, and each time the page loads, but never while you're dragging one. **Lock** on the same row locks them right away. @@ -236,13 +258,13 @@ The sliders lock again on their own after 5 minutes without a change, when you l ## Fine-tune gates by hand -Calibration gets most rooms right. If one spot still misbehaves, the Gate Energy chart shows you which gate to change. The outline is the signal to read: an outlined bar is a gate whose energy is above its threshold right now. Inside the range the radar uses, that means the gate is detecting a target. +Calibration gets most rooms right. If one spot still misbehaves, the Gate Energy chart shows you which gate to change. The outline is the signal to read: an outlined bar is a gate whose energy is above its threshold right now, inside the range the radar uses. The line under the chart says whether the radar reports a target. 1. Press **Turn on Radar Engineering Mode** on the Gate Energy chart. The bars and threshold triangles appear. - + -2. Leave the room and watch the chart from your phone, somewhere out of the radar's view (it can see through drywall, so step away from the wall too). A bar that is outlined while nobody is there is a gate causing false triggers. Gates outside the range the radar uses can be outlined too, but the radar ignores them: that range runs up to **Max Move Gate** for move bars and **Max Still Gate** for still bars, or from **Min Gate** to **Max Gate** on an R PRO-1. +2. Leave the room and watch the chart from your phone, somewhere out of the radar's view (it can see through drywall, so step away from the wall too). A bar that is outlined while nobody is there, with a line under the chart that says the radar reports a target, is a gate causing false triggers. Gates outside the range the radar uses are faded and never outlined, because the radar ignores them: that range runs up to **Max Move Gate** for move bars and **Max Still Gate** for still bars, or from **Min Gate** to **Max Gate** on an R PRO-1. 3. Press **Unlock** above the sliders, then raise the threshold of each gate causing false triggers on **Move Thresholds** (purple bar) or **Still Thresholds** (green bar) until its triangle sits a few points above the highest point the bar reaches. 4. Sit or stand where the radar misses you. Your gate is the one whose bars rise when you shift in place; each threshold row names how far out its gate reaches, and the **Gates** row on the Distances chart shows it too. Lower that gate's threshold a few points at a time until its bar is outlined while you are there, but not after you leave. 5. Turn off **Radar Engineering Mode** when you are done: press **Turn off Radar Engineering Mode** on the **Radar setup** card, or use the switch on the **Controls** card. The chart has no off button. @@ -257,81 +279,331 @@ The **Detection Range** card helps too: [Set the range and timeout](#set-the-ran The LD2450 radar in the R PRO-1 and MTR-1 tracks where up to three people are in the room. The zone map lets you draw areas on that map, such as the couch or the desk, and gives each area its own occupancy sensor. On an MTR-1 the tab is built around the zone map: **Start here**, the **Radar setup** card, and the map come first, with the radar's live status and controls beside them. On an R PRO-1, the LD2450's **Radar setup** card, the map, and the radar's live status and controls sit under the **Zone Map** heading, right after the first column of LD2412 cards, and its **Start here** card stays at the top of the tab. -The MTR-1's **Start here** card has three steps, and this section follows them: fix anything the **Radar setup** card flags, set **Cone rotation** to match how the sensor is mounted, then draw a zone and walk into it. An R PRO-1 without the optional LD2412 gets the same steps. +Your first zone takes eight steps. The sections below follow them in order, each with a picture or a short clip of what you'll see: + +1. **Install Apollo mmWave and open its dashboard.** The [setup guide](apollo-mmwave-dashboard-setup.md) covers both, and your sensor's tab holds the zone map. +2. **Fix anything the Radar setup card flags.** Its button sets the radar up for the map: [Check the LD2450's Radar setup card](#check-the-ld2450s-radar-setup-card). +3. **Set Cone rotation** so the map faces the way the sensor does: [Match the map to how the sensor is mounted](#match-the-map-to-how-the-sensor-is-mounted). +4. **Add a zone and draw it** over the spot it covers: [Add a zone](#add-a-zone), then [Draw a zone](#draw-a-zone). +5. **Name the zone, and choose Detect or Ignore and a hold time** in its editor under the map: [Pick a zone in the Zones panel](#pick-a-zone-in-the-zones-panel), [Rename a zone](#rename-a-zone), and [Ignore a spot or hold a zone](#ignore-a-spot-or-hold-a-zone). +6. **Walk into the zone to check that it works.** It lights up on the map while you're in it: [Read the map](#read-the-map), then [Use the zone sensors](#use-the-zone-sensors) in your automations. +7. **Expand the map** whenever the card feels cramped: [Expand the map](#expand-the-map). +8. **Check the Target X and Y units.** Apollo mmWave shows them in mm for you, and for a radar you already had, a notification lists the sensors it switched: [Target X and Y units](#target-x-and-y-units). -The zone map card shows your radar's name and the area the radar can see: a view cone 120 degrees wide and about 6 m (20 ft) out, with a caption at its edge such as **Radar range 6 m (20 ft), 120ยฐ**, and a dot for each person it tracks. The map fits that area, turned the way you set **Cone rotation**, plus any zone you drew outside it. Buttons sit in the bottom corners of the grid, with a row of zone buttons and a **Configure** section underneath. +The **Start here** card on an MTR-1, or on an R PRO-1 without the optional LD2412, lists steps 2, 3, 4, and 6 in short. After the steps come the map's other tools: [zoom](#zoom-in-and-move-the-map), [the lock](#lock-and-unlock), [marking corners by walking](#mark-corners-by-walking), [deleting zones](#clear-or-delete-a-zone), and [movement history](#replay-movement-history). -![The zone map for an R PRO-1 named R PRO-1 Server Rack, in feet: the radar's view cone fills the grid from -16 ft to 16 ft across, with the caption Radar range 20 ft (6 m), 120ยฐ, a rectangle named Zone 1 at the sensor, a circle named Zone 2, and a polygon named Zone 3. Along the bottom of the grid are the โœŽ button, the m / ft switch with ft selected, the dimmed โ†ถ undo button, and the Locked button, and under the grid the Zone 1, Zone 2, Zone 3, and Clear All Zones buttons and the collapsed Configure section](/assets/apollo-mmwave-zone-map.png) +The zone map card shows your radar's name and the area the radar can see: a view cone 120 degrees wide and about 6 m (20 ft) out, with a caption at its edge such as **Radar range 6 m (20 ft), 120ยฐ**, and a numbered dot for each person it tracks. The map fits that area, turned the way you set **Cone rotation**, plus any zone you drew outside it. Buttons sit in the bottom corners of the grid, with the zoom buttons above the ones on the right, and the expand button sits in its top-right corner (see [Expand the map](#expand-the-map)). Underneath are: -The map is in feet when Home Assistant uses US customary units (**Settings โ†’ System โ†’ General**), and in meters otherwise. The **m / ft** switch in the bottom-right corner of the map changes it. When an administrator presses it, the choice is saved for that radar, so everyone who opens its map sees that unit. Anyone else changes only their own view, until they reload the page. Zones are stored in millimeters either way, so switching units never moves a zone. +- The **Coverage** button, and for administrators **History** once movement history is on, and **๐Ÿšถ Mark corners by walking** before it on a phone or tablet. +- The **Zones** panel, which is always open. It holds **Add zone**, a button for each zone, and an editor for the zone you picked: its name, size, **Type**, **Hold**, whether someone is in it right now, how to draw it, and **Delete zone** (see [Pick a zone in the Zones panel](#pick-a-zone-in-the-zones-panel)). +- **Map settings**, a collapsed section at the bottom of the card, with **Cone rotation**, the left-to-right flip, **Movement history**, and **Clear all shapes**. + +On the Apollo mmWave dashboard the zone map's section is two columns wide, so on a computer the map is about twice as wide as the cards beside it. On a phone it fills the screen's one column as before. The map is never taller than the window less about 200 px, so the page around it stays in view. In a wide, short window it gets narrower instead and sits in the middle of the card, though that limit never makes it shorter than 240 px, so a phone on its side still gets a map. + +![The zone map for an R PRO-1 named R PRO-1 Server Rack, in feet: the radar's view cone fills the grid from -16 ft to 16 ft across, with the caption Radar range 20 ft (6 m), 120ยฐ, and a rectangle named Zone 1 at the sensor, a circle named Zone 2, and a polygon named Zone 3, each with a pale fill and a dashed outline because nobody is in it. The expand button sits in the map's top-right corner. Along the bottom of the grid are the โœŽ button, the m / ft switch with ft selected, the dimmed โ†ถ undo button, and the Locked button, with the zoom buttons above those on the right: a dimmed minus, + and Fit. Under the grid are the Coverage button and the Zones panel: the Zones heading with the Add zone button, a button for each zone with its color dot, Zone 1 selected, and Zone 1's editor, edged in red, with the Name box reading Zone 1, Size 6 ft 7 in ร— 3 ft 3 in, the Type list at Detect and the Hold list at Off, the hint Detect: its presence sensor turns on while someone is inside. Hold keeps it on for a while after someone inside goes still and the radar loses them., Now Nobody is in this zone, the note The map is locked, so drawing is off. Unlock it to draw this zone or change its shape. with an Unlock button, and a Delete zone button. The collapsed Map settings section ends the card](/assets/apollo-mmwave-zone-map.png) + +The map is in feet when Home Assistant uses US customary units (**Settings โ†’ System โ†’ General**), and in meters otherwise. The **m / ft** switch in the bottom-right corner of the map changes it. When an administrator presses it, the choice is saved for that radar, so everyone who opens its map sees that unit. Anyone else changes only their own view, until they reload the page. Zones are stored in millimeters either way, so switching units never moves a zone. The switch changes only the map, never the radar's Target X and Y sensors (see [Target X and Y units](#target-x-and-y-units)). ### Check the LD2450's Radar setup card The **Radar setup** card right above the map checks the two LD2450 settings that decide whether the map can show people. The radar chip keeps these itself, and Apollo firmware never sets them: -- **Zone Type** should be **Disabled**, because the zone map replaces the radar's own built-in zones. On **Detection**, the radar reports only people inside those built-in zones, and with none set it reports nobody, so the map stays empty. On **Filter**, it hides people inside them. +- **Zone Type** should be **Disabled**, because the zone map replaces the radar's own built-in zones. On **Detection**, the radar reports only people inside those built-in zones, and with none set it reports nobody, so the map stays empty. On **Filter**, it hides people inside them. To keep a fan or a curtain from turning your zones on, draw an [ignore zone](#ignore-a-spot-or-hold-a-zone) over it on the map. - **Multi Target Tracking** should be on. Off, the radar tracks only one person. ![The Radar setup card on an R PRO-1, with LD2450 ยท R PRO-1 Server Rack under the title, the line Zone Type is Filter. This radar ignores people inside its built-in zones. Disabled is recommended because the zone map replaces them., and a Set Zone Type to Disabled button](/assets/apollo-mmwave-radar-setup-ld2450.png) Press the button the card shows: **Set Zone Type to Disabled**, **Turn on Multi Target Tracking**, or **Use recommended settings** when both need fixing. The card changes nothing until you press one, and reads **Radar settings look good.** once both are right. On an R PRO-1, Home Assistant hides Multi Target Tracking by default, so the card checks only Zone Type until you enable that setting (see [The zone map shows nobody, or only one person](#the-zone-map-shows-nobody-or-only-one-person)). +For administrators, the card can also show a note about the radar's **Target X** and **Target Y** units under its checks, with a **Show Target X and Y in mm** button. The map works with either unit, and [Target X and Y units](#target-x-and-y-units) explains when to press it. + ### Match the map to how the sensor is mounted -Turn the map so its view cone points the way your sensor faces. The tracked dots turn with it. +Turn the map so its view cone points the way your sensor faces. The tracked dots turn with it. Mount the sensor where it will stay before you start: the radar can't tell the map how it's mounted, so the hint under the slider reads **Mount the sensor first, then set this. Zones match the room only while the sensor stays mounted that way.** Turn the sensor on its side, or pick it up, and the room moves under your zones. -1. Open **Configure** under the grid. +1. Open **Map settings** at the bottom of the card. On a radar with no zones yet, the **Zones** panel reminds you: **Is the sensor turned, or mounted in a corner? Set Cone rotation under Map settings first.** 2. If the **Cone rotation:** slider is gray, the map is locked: press **Locked** on the map first (see [Lock and unlock](#lock-and-unlock)). 3. Drag **Cone rotation:** (from -180ยฐ to 180ยฐ) until the view cone points the way your sensor faces. When you let go, the angle is saved for the radar and the map fits the turned cone. Double-click the slider to reset it. +4. Hold your phone so the map's view cone points the way your sensor faces in the room (at **Cone rotation** 0ยฐ, that's with the sensor at the top of the screen while you face it). Stand about 2 m (6 ft) in front of the sensor and take a step to one side. If your dot moves the other way on the screen, tick **Flip the map left to right (display only)** under the slider. The hint under the box says the same: **Turn this on if, with the map turned the way the room is, a dot moves the opposite way from you.** With the phone turned any other way, a map that's right can look mirrored, so turn it to match the room before you decide. -### Lock and unlock - -The bottom-right corner has a lock toggle that reads **Unlocked** (๐Ÿ”“) or **Locked** (๐Ÿ”’). The map starts locked once the radar has zones, and your browser remembers your choice for each radar. A radar with no zones yet starts unlocked, so you can set **Cone rotation** and draw right away. While the map is locked: +The flip mirrors the whole map, zones and dots alike, for everyone who opens it. It only changes how the map is drawn: your zones, their presence sensors, and movement history stay as they are. While it's on, the distances across the grid read from high to low, and **Cone rotation:** drags the other way, so the cone still follows your finger. Only administrators can change it; other users see it grayed out. -- Drawing on it shows **Unlock the grid before drawing.** -- The **Cone rotation** slider is gray, and a scroll that starts on it scrolls the page. A tap or drag on it outlines **Locked** and shows **Cone rotation is locked. Press Locked on the map to change it.** -- **Clear All Zones**, double-clicking a zone's button, โ†ถ (**Undo last zone change**), and **Configure โ†’ Zones** still change your zones. +![The zone map's Map settings section opened at the bottom of the card: the Cone rotation: slider at 0ยฐ with the hint Mount the sensor first, then set this. Zones match the room only while the sensor stays mounted that way., an unticked Flip the map left to right (display only) box with the hint Turn this on if, with the map turned the way the room is, a dot moves the opposite way from you., a ticked Movement history box with the hint Keeps up to 24 hours of target positions so administrators can replay them here. Backups include them. Turning it off deletes them from Home Assistant., the line Using this radar's own detected targets (3)., the Clear all shapes button, and the line Grid units: ft (X: -18..18, Y: 0..28). Target sensors: mm. Radar range: 20 ft (6 m), 120ยฐ](/assets/apollo-mmwave-zone-map-configure.png) -On a phone or tablet, the grid takes every touch, so a swipe on it doesn't scroll the page, even while the map is locked. Scroll with your finger outside the grid, for example on the radar's name above it. Stay off the zone buttons while you scroll: a stray tap on **Clear All Zones** clears every zone's shape. Keep the map on **Locked** when you're not drawing: on an unlocked map, a swipe across the grid can draw a new shape for the selected zone and replace its old one. +### Add a zone -From Apollo mmWave 2.2.6, only administrators can save zone changes. Other users still see the zones and their presence sensors, and a change they try to make shows a **Could not save** message. +The **Zones** panel sits right under the map, below **Coverage**. A radar with no zones yet reads **No zones yet. Press Add zone, then drag on the map to draw it.**, with the reminder about **Cone rotation** under it, and a press on its map shows **Press Add zone under the map first.** -### Add a zone +![The zone map for an R PRO-1 named R PRO-1 Living Room with no zones yet, in feet and unlocked: the radar's view cone with the caption Radar range 20 ft (6 m), 120ยฐ, the expand button in the map's top-right corner, the Coverage button under the grid, then the Zones heading with the Add zone button, the line No zones yet. Press Add zone, then drag on the map to draw it., the hint Is the sensor turned, or mounted in a corner? Set Cone rotation under Map settings first., and the collapsed Map settings section at the bottom of the card](/assets/apollo-mmwave-zone-map-empty.png) -Open **Configure โ†’ Zones** and press **Add Zone**. The new zone is named **Zone 1** (then Zone 2, and so on), gets its own button under the grid, and is selected and ready to draw. +Press **Add zone** beside the **Zones** heading. The new zone is named **Zone 1** (then Zone 2, and so on), gets its own button under the heading, and is picked and ready to draw. Its sensors are created right away. The map holds up to 32 zones: after that, **Add zone** is grayed out and the panel reads **The map holds up to 32 zones. Delete one to add another.** ### Draw a zone -You draw each zone on the grid as a rectangle, ellipse, or polygon. +You draw each zone on the grid as a rectangle, ellipse, or polygon, or mark its corners by walking them (see [Mark corners by walking](#mark-corners-by-walking)). -1. Unlock the map and press the zone's button to select it. -2. Press โœŽ (**Drawing modes**) in the bottom-left corner and pick a shape: โ–ญ (**Rectangle**), โ—ฏ (**Ellipse**), or โฌ  (**Polygon**). -3. For a rectangle or ellipse, drag across the grid and let go to save. +1. Pick the zone with its button under **Zones**. A zone you added a moment ago is picked already. If the lock button in the map's bottom-right corner reads **Locked**, press it to unlock the map (see [Lock and unlock](#lock-and-unlock)). A radar with no zones yet starts unlocked. +2. Press โœŽ (**Drawing modes**) in the bottom-left corner and pick a shape: โ–ญ (**Rectangle**), โ—ฏ (**Ellipse**), or โฌ  (**Polygon**). The zone's editor says how to draw in the mode you picked. The map starts on **Rectangle** each time the page loads. +3. For a rectangle or ellipse, drag across the grid and let go to save. A tap without a drag draws nothing, and a tap on another zone picks that zone. 4. For a polygon, click each corner, then double-click or press โœ“ (**Finish polygon**) to save. A polygon can have up to 32 points. โ†บ (**Undo last point**) or **Backspace** removes the last point, and **Esc** cancels the shape. -Drawing a new shape for a zone replaces its old one. Made a mistake? โ†ถ (**Undo last zone change**) in the bottom-right corner puts the last change back. Drawing works with touch too, so you can draw zones from a phone or tablet. +Here's a first zone on a radar with no zones yet, from **Add zone** to the saved rectangle: + + + +Corners snap to round values, about a tenth of the space between the grid lines you see: 10 cm at 1 m lines, 2 in at 2 ft lines, and finer as you zoom in, down to 1 cm or 1 in. So a corner lands on a round number instead of somewhere between two lines. Hold **Alt** (**Option** on a Mac) to place a corner exactly where the pointer is, even partway through a drag. Corners you mark by walking never snap. + +While you draw, a readout above the pointer shows the size the zone will get, width by depth, such as **2.4 m ร— 1.8 m**, or **7 ft 11 in ร— 9 ft 10 in** in feet. Zoomed in far enough that corners snap finer than 10 cm, it reads to the centimeter, such as **2.45 m ร— 1.80 m**. On a touchscreen it sits higher, clear of your finger, and near the top of the map, where there's no room above your finger, it moves beside your finger instead, on the side with more room. An ellipse's size is its full width and depth, and a polygon's is the box around it. Once the zone is saved, its editor under **Zones** shows the same size to the tenth of a meter, such as **Size 2.4 m ร— 1.8 m**. A zone without a shape reads **Not drawn yet**. + +Finishing a polygon that can't be saved shows why: **A polygon needs at least 3 different points.** With no zone selected, it shows **Select a zone first.** + +Drawing a new shape for a zone replaces its old one. Made a mistake? โ†ถ (**Undo last zone change**) in the bottom-right corner puts the last change back. Drawing works with touch too, so you can draw zones from a phone or tablet. Zoom in first for a small zone, such as a chair (see [Zoom in and move the map](#zoom-in-and-move-the-map)). If a second finger touches the screen before the first has moved, the two fingers zoom the map instead: a rectangle or ellipse you had started is dropped, and a polygon keeps the corners you already placed. With a mouse, a Shift-drag or a middle-button drag moves the map, so neither draws or places a corner. + +### Pick a zone in the Zones panel + +Each zone has a button under the **Zones** heading, with a dot in the zone's color on the map. The dot is hollow while the zone isn't drawn yet, and gray and hatched for an ignore zone. The picked zone's button has a colored ring around it. Press a zone's button to pick it. You can also tap the zone on the map: on a locked map, and in Rectangle or Ellipse mode on an unlocked one, a tap picks the zone under it, the smallest one where zones overlap. When the card opens, the first zone is picked. While the map is unlocked, the picked zone's outline is thicker. + +The picked zone's editor sits under the buttons, with the zone's number as its heading, such as **Zone 2**: + +- **Name**. Type a new name and press Enter (see [Rename a zone](#rename-a-zone)). +- The zone's size, such as **Size 2.4 m ร— 1.8 m**, or **Not drawn yet**. +- **Type** and **Hold**, with a line under them that says what they do for this zone (see [Ignore a spot or hold a zone](#ignore-a-spot-or-hold-a-zone)). +- **Now**, what the zone's presence sensor reads right now: **Someone is in this zone**, **On, held for someone who went still**, **Nobody is in this zone**, or **Radar offline**. An ignore zone reads **Never turns on, since it ignores targets**, a zone with no shape **Turns on once the zone is drawn**, and a zone whose sensor isn't there yet **No presence sensor yet**. +- How to draw the zone in the drawing mode you picked with โœŽ, such as **Drag on the map to draw this zone as a rectangle. โœŽ on the map offers an ellipse or a polygon. A tap on another zone picks it.** While the map is locked, the lock note and its **Unlock** button take its place. +- **Delete zone** (see [Clear or delete a zone](#clear-or-delete-a-zone)). + +A name, a **Type**, or a **Hold** saves on its own, with no **Save** button. Beside the zone's heading the card shows **Saving...**, then **Saved**. A shape you draw shows a message with the zone's name instead, such as **Couch saved**. + +![The Zones panel under the zone map: the Zones heading with the Add zone button, then the Desk, Couch, Doorway, and Fan buttons, each with its zone's color dot and Fan's hatched, with Couch selected, and the Couch zone's editor, titled Zone 2 and edged in blue: the Name box reading Couch, Size 4 ft 3 in ร— 7 ft 10 in, the Type list at Detect and the Hold list at 5 min, the hint Detect: its presence sensor turns on while someone is inside. Hold keeps it on for a while after someone inside goes still and the radar loses them., Now Nobody is in this zone, the drawing hint To change its shape, drag on the map to draw this zone as a rectangle. โœŽ on the map offers an ellipse or a polygon. A tap on another zone picks it., and a Delete zone button](/assets/apollo-mmwave-zone-list.png) ### Rename a zone -In **Configure โ†’ Zones**, type a new name next to the zone and press **Save**. The name appears on the zone's button. +1. Pick the zone with its button under **Zones**, or tap it on the map. +2. Type the new name in the **Name** box of its editor. +3. Press **Enter**, or click or tap outside the box. On a phone, the keyboard's Enter key also closes the keyboard. -### Clear or delete a zone +Here a new zone gets the name Couch, then a 5 min **Hold** (see [Ignore a spot or hold a zone](#ignore-a-spot-or-hold-a-zone)): + + + +The name saves on its own: **Saving...** and then **Saved** show beside the zone's heading, and the zone's button and its label on the map change. **Esc** puts the saved name back, and an empty box saves the zone's default name, such as **Zone 2**. If the save fails, the card shows **Not saved** in red with a **Could not save** message, and what you typed stays in the box so you can try again. The name works whether the map is locked or not. + +### Ignore a spot or hold a zone + +Each zone's editor in the **Zones** panel has two lists, **Type** and **Hold**, and a line under them that says what they do for that zone. For a detect zone it reads **Detect: its presence sensor turns on while someone is inside. Hold keeps it on for a while after someone inside goes still and the radar loses them.**, and for an ignore zone **Ignore: targets inside, such as a fan or a curtain, are dropped before the other zones are checked. Ignore zones never hold.** A change saves as soon as you pick it, and **Saved** shows beside the zone's heading. A zone keeps its type and hold when you redraw, clear, or undo it. Only administrators can change them. + +**Ignore a spot.** Draw a zone over something that moves but isn't a person, such as a fan, a curtain, or a plant in a draft, and set its **Type** to **Ignore**. Home Assistant then drops every target inside that zone before it checks the radar's other zones, so nothing there turns a zone on, even where the zones overlap. On the map the zone is hatched and its label ends in **(ignored)**, and a target inside it is a hollow gray ring. The zone's own presence sensor always reads off, with a `zone_type` attribute of `ignore`, and never holds. Targets inside it don't count for walking corners and aren't recorded in movement history. -Double-click a zone's button to clear its shape, or press **Clear All Zones** to clear every shape while keeping the zones. To remove a zone completely, along with its sensors, press **Delete** next to it in **Configure โ†’ Zones**. +![The zone map for an R PRO-1 named R PRO-1 Living Room with an ignore zone named Fan, hatched in gray with a dashed outline and labeled Fan (ignored), and a hollow gray ring numbered 3 inside it, its number outlined so the hatching doesn't run through it. The Desk zone beside it keeps its pale fill and dashed outline, while the Couch zone, with the red dot 1 in it, is filled in with a solid outline. The expand button sits in the map's top-right corner. Under the map are the Coverage button and the Zones heading with the Add zone button, above the Desk, Couch, Doorway, and Fan buttons, with Desk selected and Fan's color dot hatched](/assets/apollo-mmwave-zone-map-ignore.png) + +An ignore zone is not the radar's **Zone Type** setting (**LD2450 Zone Type** on an R PRO-1), and nothing is written to the radar. The radar keeps reporting the target, so **LD2450 Presence** and the **LD2450 Live** card still count it. Keep **Zone Type** on **Disabled**, as the [Radar setup card](#check-the-ld2450s-radar-setup-card) recommends. + +**Hold a zone.** The LD2450 can lose someone who sits very still, such as on a couch, and the zone then turns off with them still in it. Pick a **Hold** time (**15 s**, **30 s**, **1 min**, **2 min**, **5 min**, **10 min**, or **30 min**), and the zone stays on for that long after the radar loses someone who sat still inside it, counted from when the zone emptied. While it holds, the zone's label on the map ends in **(held)**, and its presence sensor's `held` attribute reads `true`. **Off**, the default, turns the zone off as soon as nobody is in it. Ignore zones never hold, so their **Hold** list is grayed out. + +??? note "How a hold ends, and where it can stay on too long" + + A hold is for someone who sat still, so the zone doesn't wait out its hold when everyone who was in it walked out. Home Assistant sees someone walk out in two ways: + + - **Walking out into the room.** In the 3 seconds after the zone empties, the radar tracks a target outside the zone near where the person was, no farther than a brisk walk would have taken them by then. Walking out of a zone into the room turns it off within about 3 seconds, usually as soon as the radar reports you outside it. + - **Walking out of the radar's view.** The radar loses the person while they're walking near the zone's edge or the edge of its view: within 0.3 m (1 ft), plus as far ahead as they walk in a second or two, up to 1.5 m (5 ft). An edge behind or beside them counts only within 0.3 m (1 ft). The zone then turns off as soon as the radar loses them, as it would without a hold. The radar reports each position about once a second, so Home Assistant needs about two seconds of walking in the zone to tell that someone is walking. Someone seen in the zone for under about 1.2 seconds counts only within 0.3 m (1 ft) of an edge, unless the radar saw them move at 0.85 m/s (2.8 ft/s) or faster. So someone who walks into a couch or bed zone and is lost as they sit down is held. + + A hold also ends when someone is in the zone again, when the radar goes offline or reconnects, when Home Assistant restarts or Apollo mmWave reloads, and when you change the zone's shape, an ignore zone, or **Cone rotation**. + + Home Assistant only sees positions, not who is who, so a hold has limits: + + - A person or thing the radar was already tracking elsewhere when the zone emptied, such as someone across the room, a plant, a chair, or a ghost, ends a hold only if it comes within 0.6 m (2 ft) of where the person was. Someone it starts tracking in the next 3 seconds, such as a person walking into the room, can end it early from up to about 7 m (23 ft) away. + - Someone walking through the zone ends the hold: when they leave, the zone turns off, even if the person who sat still never left. + - If two people are in the zone and the radar loses one of them while the other stays, the zone turns off once the other one leaves. + - When the radar swaps the numbers of two people inside the zone, it can look like movement for a second or two, and losing one of them near the edge right then turns the zone off. + - A ghost target that shows up in the middle of the zone for about a second and vanishes holds the zone too. Put an ignore zone over whatever causes it. + - Before it loses someone who sat still, the radar can shift their position about half a meter (1.5 ft) in its last report. That alone doesn't count as walking, but if the shift puts them outside the zone, they count as having walked out, so a seat within about half a meter of the zone's edge can still turn the zone off early. Draw the zone with at least that much room around the seat. + - Someone the radar loses as they walk out of its view, or through a doorway at the zone's edge, before Home Assistant can tell they're walking, for example a few steps from a seat beside the door, can keep the zone held for the whole hold time. + - Someone who walks slowly through 1 to 1.5 m (3 to 5 ft) of a zone and out of the radar's view, which takes about 2 to 2.5 seconds at 0.6 m/s (2 ft/s), often keeps the zone held for its whole hold time. In Apollo's simulations of such walks, the hold ended right away in only about 43 to 48% of them. That's the price of holding a couch or bed zone for someone who sits down right after walking in. + - Home Assistant takes the radar's view as 6 m (20 ft) and 120 degrees. Where a wall, or the radar's own built-in zones, end the view sooner, someone who walks out of view there, away from the zone's edge, holds the zone for the whole hold time. + - A radar reconnect, even a short Wi-Fi drop, and a Home Assistant restart end every hold. + +For a hold time the list doesn't offer, such as 45 seconds, set `hold_s` (0 to 3600 seconds) with the `apollo_mmwave.update_zone` action, and the list then shows it too. The button below opens **Settings โ†’ Tools โ†’ Actions** with that action selected. + +[![Open your Home Assistant instance and show your action tools with a specific action selected.](https://my.home-assistant.io/badges/tools_perform_action.svg)](https://my.home-assistant.io/redirect/tools_perform_action/?service=apollo_mmwave.update_zone) + +Switch to YAML mode and perform it with your radar and the zone's number. To fill in the device without looking up its ID, pick your radar under **Radar Device** in the visual editor instead. + +```yaml +action: apollo_mmwave.update_zone +data: + device_id: your_device_id + zone_id: 1 + hold_s: 45 +``` + +### Read the map + +Walk into the zone you drew to check that it works: it fills in on the map while you're inside, and **Now** in its editor reads **Someone is in this zone**. The map follows the radar live, so you can watch people move through your zones: + +- **Numbered dots.** Each target the radar tracks is a dot with its number, so dot 2 is **Target 2** on the **LD2450 Live** card. A number belongs to the radar's target slot, not to a person: when two people cross, the radar can swap their numbers. A moving dot leaves a trail that fades over about 3 seconds. +- **Zones that light up.** A zone fills in with a stronger color and a solid outline while its presence sensor is on, and goes back to a pale fill with a dashed outline when it's off. Each zone keeps its own color, the same as the dot on its button under **Zones**. While a zone holds for someone the radar lost, its label ends in **(held)** (see [Ignore a spot or hold a zone](#ignore-a-spot-or-hold-a-zone)). +- **Ignore zones.** An ignore zone is hatched in gray with a dashed outline, and its label ends in **(ignored)**. A target inside one is a hollow gray ring with a gray number. +- **Radar offline.** While the radar is offline, the zones turn gray with short dashes, and **Radar offline** shows in the top-left corner (see [Zone presence reads unavailable](#zone-presence-reads-unavailable)). + + + +Press **Coverage** under the map to paint every spot where the radar has seen a target since you opened the page, in orange under the zones: the more often a target was there, the stronger the paint. It shows what the radar covers, and where a fan or a curtain shows up, because targets inside ignore zones count too. **Clear coverage** starts it over. Trails and coverage live in your browser page, so they start over when you reload, and another browser keeps its own. Your browser remembers whether **Coverage** is on for each radar. ### Use the zone sensors Each zone gets an occupancy sensor named **Zone 1 presence** (and so on) on the radar's device page in Home Assistant. It turns on when a tracked person is inside the zone, ready to use in your automations. When you rename a zone on the card, its sensors follow, so a zone named Couch gets **Zone 1 presence - Couch**. A name you gave the sensor yourself in Home Assistant is kept. -To try a zone, reload the page after you draw it, then walk into it. The **Zone presence** card next to the map lists each zone's sensor and colors it while someone is in the zone, and **Occupancy History** adds a line for the zone, covering the last 24 hours. +Reload the page after you add a zone, and the **Zone presence** card next to the map lists its sensor too, colored while someone is in the zone, and **Occupancy History** adds a line for it, covering the last 24 hours. Until a radar has a zone, **Zone presence** reads **Press Add zone under the zone map to get a presence sensor for a zone. Reload this page to see it here.** + +Under it, **LD2450 Live** shows what the radar reports right now, with the radar's **Target Count** under its rows as a whole number. If the map shows no dot with you in the room, look here first: **LD2450 Presence** off means the radar itself reports nobody. It covers the radar's whole view, not one zone, and **Occupancy History** names its line **LD2450 Presence** too. + +![The LD2450 Live card on an R PRO-1 with nobody in the room: LD2450 Presence, Moving Target, and Still Target read Clear, and Target 1 to 3 Distance read Unknown with their Direction rows reading NA. A second card under it reads Target Count: 0, with the 0 in bold](/assets/apollo-mmwave-ld2450-live-count.png) + +For an automation that covers the whole room rather than one zone, **Start here** names the sensor to use. On an MTR-1 it's **LD2450 Presence**. On an R PRO-1 whose firmware has **Combined Presence** (firmware newer than 26.3.2.1), it's **Combined Presence**, which is on while either radar sees someone. On earlier R PRO-1 firmware it's **LD2412 Presence**, or **LD2450 Presence** on an R PRO-1 without the LD2412. + +**LD2450 Controls** holds **Zone Type**, **Multi Target Tracking**, **Radar Timeout**, **Radar Bluetooth (HLK app)**, **Restart Radar**, and **Factory Reset Radar**, whichever your sensor has (the MTR-1 has no Restart Radar). The restart and the reset ask before they act. **Radar Timeout** is how long **LD2450 Presence** stays on after the radar last sees someone. It doesn't hold the zones you draw: a zone turns off as soon as nobody is in it, unless you give it a hold time (see [Ignore a spot or hold a zone](#ignore-a-spot-or-hold-a-zone)). While Zone Type isn't **Disabled**, a **Radar's built-in zones** card shows the radar chip's own zones, which are not the zones on the map: each zone's **X1**, **Y1**, **X2**, and **Y2** corners, and a table of how many targets each zone counts (**All**, **Still**, and **Moving**), in whole numbers. + +While the radar is offline, its zones' presence sensors read unavailable. They also read unavailable after every Home Assistant restart until the radar connects, then off or on again from what the radar sees. Before Apollo mmWave 2.4.0 they read off. The **Zone presence** rows hide while the sensors are unavailable, and an ignore zone's sensor reads off the whole time. + +Home Assistant gets each target's position from the radar as two separate updates, X and Y. On an R PRO-1 each comes about once a second, with Y usually about half a second after X. Zone presence waits for both halves of a report before it checks your zones, so a zone beside a path people walk along doesn't turn on for a point between two reports, where nobody was. That wait can delay a zone turning on by up to about half a second. When someone moves along only one axis, the radar sends only that one, and zone presence counts the move about half a second after it arrives. Both apply to every zone, with or without a hold, with one exception: when the radar loses someone between their X and Y updates, a zone with a hold time checks their last X with the old Y once, as the spot where they were lost. So a zone with a hold time beside a walking path can still turn on there and stay on for its hold time. + +To turn something off once a zone empties, such as the lights, trigger on its presence sensor turning off: + +```yaml +triggers: + - trigger: state + entity_id: binary_sensor.apollo_mtr_1_abc123_zone_1_presence + to: "off" + for: "00:05:00" +``` + +Replace `binary_sensor.apollo_mtr_1_abc123_zone_1_presence` with your zone's presence sensor. This trigger fires once the zone has been empty for 5 minutes. It also fires 5 minutes after the radar comes back with nobody in the zone, which happens after every restart. For lights, that extra off is harmless, and the same trigger catches a zone that emptied while the radar was offline, whose sensor went from on to unavailable to off. + +Where the trigger must see someone leave, such as for a notification or a counter, add `from: "on"` (or `not_from: unavailable`) under `entity_id`. It then fires only when the zone empties while the radar is online, not when the radar comes back after a restart, and not for a zone that emptied while the radar was offline. + +### Expand the map + +When the card feels cramped, give the map the whole window: press the expand button (**Expand map**) in the map's top-right corner, under the distance labels. Its tooltip reads **Expand the map to fill the window. Press Esc to return.** The map fills the browser or app window, and everything under it in the card moves beside it: **Coverage**, the **Zones** panel with the picked zone's editor, and **Map settings**. Draw, pick, rename, and delete zones there as you do in the card. -Under it, **LD2450 Live** shows what the radar reports right now. If the map shows no dot with you in the room, look here first: **Presence** off means the radar itself reports nobody. + -![The LD2450 Live card on an R PRO-1 with nobody in the room: Presence, Moving Target, and Still Target read Clear, Target Count reads 0.0, and Target 1 to 3 Distance read Unknown with their Direction rows reading NA](/assets/apollo-mmwave-ld2450-live.png) +- **Layout.** In a wide window, the panel sits beside the map and takes 30% of the width. On a phone held upright, it sits under the map instead and scrolls on its own, and the map is never narrower than it was in the card. In a short window, such as a small phone held sideways, the panel stays beside the map so the zone buttons and the editor have room, even where the map is then narrower than in the card. +- **Nothing is lost.** Your zoom, the picked zone, an unfinished polygon, a walk or a replay in progress, **Coverage**, whether **Map settings** is open, and text you're typing stay as they were when the map expands and when it closes. Only a rectangle or an ellipse you're dragging at that moment is dropped. +- **A finer grid on a large screen.** Where the expanded map is wider than the card's 800 px drawing, as on a large monitor, it's drawn as wide as it shows, up to 1600 px, so its grid lines and the snap can get finer, while labels and lines keep their size. On a phone, and in feet on most laptop and 1080p screens, they stay as in the card. +- **Getting back.** Press ร— before the radar's name (**Close expanded map**), the same corner button, Esc, or Back in a browser, the Android app, or Chrome for Android. In the iPhone and iPad app, press ร—. If you're in the middle of something, Esc first undoes it: it puts back a zone name you were changing, drops an unfinished polygon's corners, or closes a **Delete zone** or **Clear all shapes** question. The next Esc closes the map. -**LD2450 Controls** holds **Zone Type**, **Multi Target Tracking**, **Radar Timeout**, **Radar Bluetooth (HLK app)**, **Restart Radar**, and **Factory Reset Radar**, whichever your sensor has (the MTR-1 has no Restart Radar). The restart and the reset ask before they act. **Radar Timeout** is how long **LD2450 Presence** stays on after the radar last sees someone. It doesn't hold the zones you draw: a zone turns off as soon as nobody is in it. While Zone Type isn't **Disabled**, a **Radar's built-in zones** card shows the radar chip's own zones, which are not the zones on the map. +Here's the same map expanded on a phone held upright, with the panel under the map: -While the radar is offline, or still reconnecting after a restart, zone presence reads off, not unavailable. An automation that waits for a zone to be clear for some minutes can't tell that apart from an empty zone, so have it also check that the radar itself is online. +![The same zone map expanded on a phone held upright: ร— and the title R PRO-1 Living Room at the top, then the map across the screen's width with the collapse button in its top-right corner and the Armchair zone filled in around dot 3, and under the map the ๐Ÿšถ Mark corners by walking and Coverage buttons, the Zones heading with the Add zone button, the Desk, Couch, Doorway, Fan, and Armchair buttons with Armchair picked, and the top of the Armchair zone's editor: Zone 5, the Name box reading Armchair, Size 3 ft 8 in ร— 5 ft, and the Type and Hold lists at Detect and Off](/assets/apollo-mmwave-zone-map-expanded-phone.png){ .phone-media } + +The expand button isn't on a view-only map, in the card editor's preview, on a dashboard in edit mode, or on a map shown in a pop-up. Showing another radar on the card, or switching it to view only, closes the expanded map. + +### Target X and Y units + +The LD2450 reports each target's position as a **Target X** and a **Target Y** sensor, six in all for its three targets, and it reports them in mm. Home Assistant picks the unit a distance sensor shows on its own, and with US customary units it picks inches. The zone map and zone presence read either unit, but the radar's built-in zone corners and Apollo's zone guides use mm, so from Apollo mmWave 2.4.0 the integration shows the Target X and Y of every Apollo R PRO-1 and MTR-1 in mm for you: + +- **A new radar** shows mm about 2 seconds after Home Assistant adds it, with no message. +- **A radar you already had** is switched once, after Home Assistant starts with 2.4.0. A notification titled **Apollo mmWave: Target X and Y now in mm** lists each radar and the sensors it switched, and says **Nothing was written to the radar.** +- **Left as they are:** a sensor whose unit you picked in its settings, a sensor that an automation, a script, or a helper uses, the sensors of a metric install, which show mm already, and every other sensor and device, such as a radar's Target Distance and Speed. +- **Once only.** Apollo mmWave decides each sensor once and never changes it again, also one it left alone. A disabled sensor is decided after you enable it, the next time Home Assistant starts or Apollo mmWave reloads. + +After the switch, automations, templates, and history graphs read these sensors in mm. A number an automation compares Target X or Y to in inches needs to be in mm, 25.4 times as large, and a history graph that spans the switch shows a step of 25.4 times. A YAML template sensor, a dashboard card, or another tool that reads them, such as Node-RED, reads mm from then on too. The zone map's **m / ft** switch changes only the map, never the sensors, and the grid line at the bottom of **Map settings** names the unit they show, such as **Target sensors: mm.** + +When some of a radar's Target X and Y still show another unit because Apollo mmWave left them alone, the **Radar setup** card above the zone map tells administrators so under its checks, with a **Show Target X and Y in mm** button. The line above the button says **After the change, automations and templates that use these sensors read mm.**, and when an automation, a script, or a helper uses them, it adds **An automation, a script or a helper uses them: check any number it compares them to.** + +![The Radar setup card on an R PRO-1, with LD2450 ยท R PRO-1 Living Room under the title and the line Radar settings look good., then the note Home Assistant shows this radar's Target X and Y in inches. The zone map reads them either way. In mm they match the radar's built-in zone corners and Apollo's zone guides., the hint After the change, automations and templates that use these sensors read mm. An automation, a script or a helper uses them: check any number it compares them to., and a Show Target X and Y in mm button](/assets/apollo-mmwave-radar-setup-target-units-in-use.png) + +1. Check the automations, scripts, and helpers that use the radar's Target X or Y, and change any number they compare them to into mm. +2. Press **Show Target X and Y in mm**. It switches the sensors whose unit Home Assistant picked on its own, never one whose unit you picked in its settings, and the note goes away. + +To go back to inches, open the sensor on the radar's device page, open its settings (โš™), choose **in** under **Unit of measurement**, and select **Update**. Apollo mmWave leaves it that way. Other users don't see the note or the button. + +### Zoom in and move the map + +The map shows the radar's whole view, about 12 m (40 ft) across, so on a laptop or a phone each meter gets little room. Zoom in to draw or check a zone up close. The zoom controls are the row in the bottom-right corner of the map, above the **m / ft** switch: โˆ’ (**Zoom out**), + (**Zoom in**), and **Fit**. While the map is zoomed in, a readout such as **2x** sits before them. + + + +- **Buttons.** + and โˆ’ zoom in and out around the middle of the view, about 1.4 times a press (the square root of 2), from 1x, the whole map, to 8x. At 8x, a map 12 m (40 ft) across shows 1.5 m (5 ft). +- **Fit** zooms to the zones you drew, with a margin of a tenth of their longer side and at least 30 cm (1 ft). Its tooltip says what the next press does: **Fit the zones in view**, or **Show the whole map** once the zones fill the view or when there are none, which goes back to 1x. With no zones and the map at 1x, it's grayed out. +- **Mouse or trackpad.** Hold **Ctrl** (**Cmd** on a Mac) and scroll over the map to zoom in or out around the pointer. A trackpad pinch over the map does the same in Chrome, Edge, and Firefox. A scroll without Ctrl or Cmd still scrolls the page. To move the zoomed map, drag it with **Shift** held, or with the middle mouse button. +- **Phone or tablet.** Pinch with two fingers to zoom, and drag with two fingers to move the map. Two fingers work on every map: locked or unlocked, while you mark corners by walking, and with no zone selected. One finger works as before. + +Zoomed in, the grid draws finer lines, down to 10 cm in meters and 3 in (a quarter of a foot) in feet, and keeps its distance labels on the screen. Hover over the readout for a reminder of how to move the map: **Move the map by dragging with Shift held, with the middle mouse button, or with two fingers.** + +The zoom belongs to your page: live updates, the **m / ft** switch, and saving a zone keep it, and reloading the page, changing **Cone rotation**, or opening another radar's map go back to the whole map. While you [mark corners by walking](#mark-corners-by-walking), a zoomed map moves along with your dot so it stays in view, and a [movement history](#replay-movement-history) replay plays at the zoom you're at. A view-only zone map doesn't zoom. + +On a Mac, Safari doesn't pass a trackpad pinch to the map. Use **Cmd** and scroll, or the buttons. + +### Lock and unlock + +The bottom-right corner has a lock toggle that reads **Unlocked** (๐Ÿ”“) or **Locked** (๐Ÿ”’). Pressing it shows **Drawing and cone rotation locked. Unlock the map to change them.** or **Drawing and cone rotation unlocked. You can edit zones now.** The map starts locked once the radar has zones, and your browser remembers your choice for each radar. A radar with no zones yet starts unlocked, so you can set **Cone rotation** and draw right away. While the map is locked: + +- A tap on a zone picks it. Drawing anywhere else, or pressing ๐Ÿšถ (**Mark corners by walking**), outlines **Locked** and shows **Unlock the map to draw zones.** +- The **Cone rotation** slider under **Map settings** is gray, and a scroll that starts on it scrolls the page. A tap or drag on it outlines **Locked** and shows **Cone rotation is locked. Press Locked on the map to change it.** +- **Clear all shapes** under **Map settings** is dimmed and clears nothing: it outlines **Locked** and shows **Unlock the map to clear zones.** +- **Add zone**, a zone's **Name**, **Type**, and **Hold**, **Delete zone**, and โ†ถ (**Undo last zone change**) still work. Instead of how to draw, the zone's editor reads **The map is locked, so drawing is off. Unlock it to draw this zone or change its shape.**, and its **Unlock** button unlocks the map, as **Locked** does. + +On a phone or tablet, a one-finger swipe that starts on a locked map scrolls the page. A tap on a zone picks it, and a tap anywhere else on the map shows the reminder. Two fingers zoom and move the map whether it's locked or not (see [Zoom in and move the map](#zoom-in-and-move-the-map)). An unlocked map takes every one-finger touch for drawing while a zone is selected. Scroll with your finger outside the grid then, for example on the radar's name above it or on the **Zones** panel under it. Keep the map on **Locked** when you're not drawing: on an unlocked map, a swipe across the grid can draw a new shape for the selected zone and replace its old one. For a phone or a wall tablet where nobody draws zones, a view-only zone map has no drawing tools at all and always lets the page scroll (see [Use your own layout](apollo-mmwave-dashboard-setup.md#use-your-own-layout)). + +From Apollo mmWave 2.2.6, only administrators can save zone changes. Other users still see the zones and their presence sensors, and a change they try to make shows a **Could not save** message. From 2.4.0 the card tells them up front: in the zone's editor, **Name**, **Type**, and **Hold** are grayed out, with **Only an administrator can change these.** under them, and the flip under **Map settings** is grayed out too. They get no **Add zone**, **Delete zone**, **Clear all shapes**, ๐Ÿšถ button, or movement history. On a radar with no zones, the panel tells them **No zones yet. An administrator can add them.** + +### Mark corners by walking + +Can't tell where the couch ends on the map? Mark the zone's corners with your own position: stand in each corner of the area while the radar tracks you, and the card turns your corners into the zone's shape. Take a phone or tablet with the dashboard open, and be the only person in the radar's view. Like drawing, it's for administrators, on an unlocked map. + +1. Unlock the map and pick the zone with its button under **Zones**. +2. Press โœŽ (**Drawing modes**), then ๐Ÿšถ (**Mark corners by walking**). On a phone or tablet, you can press **๐Ÿšถ Mark corners by walking** under the map instead, before **Coverage**. A panel opens under the map with a hint, **Corner here**, **Undo corner**, **Finish**, and **Cancel**, and the zone's editor reads **Marking this zone's corners by walking. Follow the steps under the map.** +3. Stand still in one corner of the area for about 3 seconds and press **Corner here**. The corner is where the radar placed you, on average, over the last 1.5 seconds, and the radar updates your position about once a second, so a corner pressed sooner can land short of where you stand. +4. Walk along the edge to the next corner, stand still for about 3 seconds, and press **Corner here** again. Go around the zone in order, not across it. The map numbers each corner and draws a dashed preview of the shape with its size. +5. Press **Finish**. Two corners make a rectangle, with the two as opposite corners, and three or more make a polygon of up to 32 corners. The zone saves like one you drew, and the card confirms it with the zone's name, such as **Couch saved**. + + + +The hint tells you what to do next, and **Corner here** stays grayed out until exactly one person is on the map. Until then the hint reads **Nobody is on the map. Walk into the radar's view.** or **More than one target is on the map. Only the person marking corners should be in view. If you are alone, a fan or curtain may be moving: add an ignore zone over it.** Targets inside ignore zones don't count. The card also refuses a corner that would spoil the shape, and keeps the ones you marked: + +- **That is too close to the last corner. Walk farther, then press Corner here.** Corners need to be about 30 cm (1 ft) apart. +- **That is where you started. Press Finish to save the zone.** You don't need to walk back to the first corner: **Finish** closes the shape. +- **Those corners make a zone too thin to use. Mark corners on opposite sides of the area.** This one comes from **Finish**. For a rectangle, mark two corners diagonally across from each other. + +With no zone selected, **Finish** shows **Select a zone first.** and keeps your corners, so press the zone's button and **Finish** again. **Undo corner** removes the last corner, and **Cancel** leaves without saving. With two or more corners marked, **Cancel** asks **Drop the corners you marked?** first: press **Drop them** to leave, or **Keep marking** to go on. Locking the map or picking another drawing mode also leaves, and drops the corners without asking. While you walk, **History** is closed and grayed out, **๐Ÿšถ Mark corners by walking** under the map is hidden, and a one-finger swipe on the map scrolls the page. A zoomed map moves along with your dot, so you stay in view. + +### Clear or delete a zone + +To remove a zone completely, along with its sensors, pick it and press **Delete zone** at the bottom of its editor. The card asks first. For a zone named Couch it reads **Delete Couch? Its sensors leave Home Assistant, so automations that use them stop working. This cannot be undone.** Press **Delete** to delete it, or **Keep it** (or **Esc**) to keep it. โ†ถ doesn't bring a deleted zone back. **Delete zone** works whether the map is locked or not. + +To clear the shapes of every zone and keep the zones, open **Map settings** and press **Clear all shapes**. It's there while any zone has a shape, and it asks first: **Clear every zone's shape? The zones keep their names, types and hold times, and โ†ถ on the map brings the shapes back.** Press **Clear shapes** to clear them, and the card shows **All shapes cleared**, or press **Keep them**. On a locked map it's dimmed and clears nothing: it shows **Unlock the map to clear zones.** + +No button clears a single zone's shape. To change one, draw the new shape over it, which replaces the old one. A double-click on a zone's button doesn't clear it either. + +**Add zone** takes the lowest zone number that's free, so a zone you add after deleting one can get the deleted zone's number. From Apollo mmWave 2.4.0, it starts with fresh sensor names: names Apollo mmWave gave the old zone, such as **Zone 1 presence - Couch**, are cleared, and a name you typed in the sensor's settings stays. Home Assistant gives the new zone's sensors the old ones' entity IDs, though, such as `binary_sensor.couch_presence` if you had changed it, and Apollo mmWave can't prevent that. An automation written for the deleted zone then follows the new one, so check those automations. + +### Replay movement history + +Movement history lets an administrator play back where the radar tracked people over the last day: to see where people walk and sit before you draw zones, or what turned a zone on in the night. It's off until you turn it on, one radar at a time. + +1. Open **Map settings** at the bottom of the card and tick **Movement history**. The card confirms **Movement history is on. Open History under the map to replay it.** From then on, Home Assistant records where each target the radar tracks is: up to twice a second while it moves, and every 15 seconds while it stays in view. +2. Press **History** under the map. The **Movement history** panel opens on the last hour. +3. Press **Play**, or drag the slider to any moment. **1x**, **10x**, and **60x** set the speed, **1 h**, **6 h**, and **24 h** change the range, and the small chart above the slider shows when the radar saw people. + +During a replay, the map's top-right corner reads **Replay** and the time, such as **Replay 2:14:05 PM**. Each target is a numbered dot with a short trail, and a zone fills in while a replayed dot is inside it. **Heatmap** paints where people spent their time over the whole range, so a spot where someone sat outweighs one they walked through. The panel reminds you: **Zones are drawn with their current shapes, rotation and flip.** A zone you redrew today lights up by its new shape. **Back to live** closes the panel. A range with nothing in it reads **No movement recorded in this range yet.** + + + +Before you turn it on, know what it keeps and where: + +- **Who can see it.** Only administrators can turn it on, open **History**, or clear it. That includes any dashboard signed in as an administrator, such as a wall tablet, so sign a shared screen in as a regular user, with a [view-only zone map](apollo-mmwave-dashboard-setup.md#use-your-own-layout) on its dashboard. Other users don't see the option or the **History** button, and nothing on their map says history is on. +- **Where it's kept.** In `.storage/apollo_mmwave.movement` in your Home Assistant configuration folder. Home Assistant never serves it on the web, but anything that can open that folder can read it, such as the **Samba share** and **Terminal & SSH** apps. Targets inside ignore zones aren't recorded. +- **How long.** Up to 24 hours. Each radar keeps about 100,000 records (up to 105,000 before the oldest are dropped back to 100,000) and drops the oldest first, so a busy room keeps less: as little as about 4.6 hours with three people moving all the time. +- **Backups.** Home Assistant backups include the file, even backups that leave out the database. Turning history off doesn't remove it from backups you already made. +- **Not the recorder.** It's separate from Home Assistant's recorder, which saves the history of your entities. A `recorder:` exclude or the `recorder.purge_entities` action, such as the ones in [Minimize activity spam](/products/general/tutorials/minimize-mmwave-activity-spam.md#stop-recording-ld2450-target-positions), neither stops it nor deletes it. +- **Deleting it.** Untick **Movement history**, and the card warns **Turning this off deletes this radar's movement history from Home Assistant. Backups made while it was on keep their copy.** Press **Turn off and delete** to delete it, or **Keep it** to leave it on. **Clear history** in the panel deletes what's been recorded and keeps recording, once you confirm **Delete this radar's movement history?** with **Delete**. Removing the Apollo mmWave integration deletes the file, and removing a radar from Home Assistant deletes that radar's history. While the integration is disabled, the file stays as it was until the next start. +- **SD cards.** While anyone is in view, Home Assistant writes the whole file again about once a minute. For a busy radar at its cap, that's about 1.3 MB a minute, which wears an SD card, so turn history on where you need it and off when you're done. +- **Support file.** A [support file](#send-apollo-a-support-file) says only whether history is on and how many points it holds, never the positions. + +Because Home Assistant saves the history about once a minute, a crash or a power cut can lose up to the last minute of it. If Home Assistant ever finds the file damaged, it sets the file aside and raises a repair, **Storage corruption detected for apollo_mmwave.movement**, that suggests restoring a backup. You don't need to: Apollo mmWave deletes the damaged copy, because it holds positions, and starts a new history. Open the repair under **Settings โ†’ System โ†’ Repairs** and select **Submit** to dismiss it. + +[![Open your Home Assistant instance and show your repairs.](https://my.home-assistant.io/badges/repairs.svg)](https://my.home-assistant.io/redirect/repairs/) ## Calibrate from an automation @@ -408,6 +680,14 @@ A calibration sets each threshold a margin above the highest energy it heard dur If the radar now misses you instead, press **Undo (restore your previous values)**, or calibrate again with a smaller `margin`. +### Radar Target turns off while someone sits still + +On an MSR-1 or MSR-2, the LD2410 can lose someone who sits very still: once their still energy stays under the threshold for longer than **Radar Timeout** (5 s from the factory), it stops reporting them. After that it often needs them to move before it detects them again, even while their still energy is back above the threshold. With Radar Engineering Mode on, the Gate Energy chart shows it: an outlined still bar at their gate, the line **The radar reports no target.** under the chart, and the line about the LD2410 needing movement under that. + +1. Raise **Radar Timeout** on the **Detection Range** card to 60 s or more. A longer timeout carries **Radar Target** through short dips, and only delays the lights going off after everyone leaves. Changing it restarts the radar, which can lose someone sitting still until they move, so change it while nobody's sitting in the room. +2. If it started after a calibration, press **Undo (restore your previous values)** on the **Auto-calibrate** card. A calibration leaves headroom above the empty room's energy, and at the gate where someone sits, that headroom can be enough to lose them. Or lower that gate's still threshold a few points, as [Fine-tune gates by hand](#fine-tune-gates-by-hand) shows. +3. Run your automations from **Radar Target**, not the zone sensors. The zone sensors also need the radar's distance, which can read unknown while someone is there. + ### Calibration will not start The **Calibrate with empty room** button is disabled when the card cannot run a calibration. The card says why: @@ -474,11 +754,15 @@ If the chart instead reads **Radar unavailable** and **Waiting for the device to The HLKRadarTool app connects over the radar's Bluetooth (the **Radar Bluetooth (HLK app)** row on the **Controls** card, or on **LD2450 Controls** for the LD2450) and has its own auto-calibration. Each sensor has its own guide: [MSR-1](/products/msr1/setup/zones-hlk.md), [MSR-2](/products/msr2/setup/zones-hlk.md), [R PRO-1](/products/rpro1/setup/zones-hlk.md), and [MTR-1](/products/mtr1/setup/zones-hlk.md). +### Can't find a zone's name, Type, or Hold + +They're in the **Zones** panel right under the map. Press the zone's button there, or tap the zone on the map, and its editor opens under the buttons (see [Pick a zone in the Zones panel](#pick-a-zone-in-the-zones-panel)). **Cone rotation**, the flip, **Movement history**, and **Clear all shapes** are under **Map settings** at the bottom of the card. If the map shows a **Configure** section instead, with the zones inside it, the page still runs cards from an earlier release: reload it as [Load the new cards](apollo-mmwave-dashboard-setup.md#load-the-new-cards) shows. + ### The zone map shows nobody, or only one person Start with the LD2450's **Radar setup** card, right above the map. -**No dot at all.** The usual cause is **Zone Type** set to **Detection**: the radar then reports only people inside its own built-in zones, and with none set it reports nobody. Press **Set Zone Type to Disabled**, or **Use recommended settings** if the card shows that instead. If Zone Type is already **Disabled** and **Presence** on the **LD2450 Live** card stays off with you in front of the sensor, the radar itself sees nobody: check that it's online and facing the room. +**No dot at all.** The usual cause is **Zone Type** set to **Detection**: the radar then reports only people inside its own built-in zones, and with none set it reports nobody. Press **Set Zone Type to Disabled**, or **Use recommended settings** if the card shows that instead. If Zone Type is already **Disabled** and **LD2450 Presence** on the **LD2450 Live** card stays off with you in front of the sensor, the radar itself sees nobody: check that it's online and facing the room. **One dot with several people in the room.** Usually **Multi Target Tracking** is off. Press **Turn on Multi Target Tracking** (or **Use recommended settings** if the card shows that instead) on the Radar setup card. On an R PRO-1, Home Assistant hides that setting by default, so the card can't check it and shows no button. Enable it once: @@ -489,17 +773,54 @@ Start with the LD2450's **Radar setup** card, right above the map. ### The dots sit at the sensor, or a zone misses you -Apollo mmWave 2.2.7 fixed this. Before it, when Home Assistant used US customary units (or you changed a Target X or Target Y sensor's unit), the zone map read the radar's positions in inches as if they were millimeters. The dots sat at or right around the sensor, and zone presence didn't turn on. Update Apollo mmWave (see [Upgrade from an older setup](apollo-mmwave-dashboard-setup.md#upgrade-from-an-older-setup)) and the dots land where people are. +Apollo mmWave 2.2.7 fixed this. Before it, when Home Assistant used US customary units (or you changed a Target X or Target Y sensor's unit), the zone map read the radar's positions in inches as if they were millimeters. The dots sat at or right around the sensor, and zone presence didn't turn on. Update Apollo mmWave (see [Upgrade from an older setup](apollo-mmwave-dashboard-setup.md#upgrade-from-an-older-setup)) and the dots land where people are. From 2.4.0, Apollo mmWave also shows the radar's Target X and Y in mm itself (see [Target X and Y units](#target-x-and-y-units)). A zone you drew while the dots were in the wrong place may not cover where people show up now. Walk through the room, watch the dots, and redraw any zone that's off. +**A dot moves the opposite way from you.** First hold your phone so the map's view cone points the way your sensor faces in the room: turned any other way, a map that's right can look mirrored. If the dot still moves the other way, tick **Flip the map left to right (display only)** under **Map settings**, as [Match the map to how the sensor is mounted](#match-the-map-to-how-the-sensor-is-mounted) describes. It only changes how the map is drawn, so your zones flip with the dots and keep working as before. + +### Target X or Y reads 25.4 times larger, or still shows inches + +- **An automation or a history graph shows Target X or Y 25.4 times larger.** From 2.4.0, Apollo mmWave shows an R PRO-1's or MTR-1's Target X and Y in mm instead of the inches Home Assistant picked, and its notification **Apollo mmWave: Target X and Y now in mm** names the sensors it switched. Change the numbers your automation compares them to into mm. Or, to keep inches, open the sensor's settings (โš™), choose **in** under **Unit of measurement**, and select **Update**: Apollo mmWave doesn't change it again. A history graph shows the step only where it spans the switch. +- **Target X and Y still show inches.** Apollo mmWave left them as they were: you picked their unit in their settings, an automation, a script, or a helper uses them, Home Assistant used metric units when Apollo mmWave decided them and US customary units later, or a sensor was disabled then. As an administrator, check those automations, then press **Show Target X and Y in mm** on the **Radar setup** card above the zone map. It switches the ones Home Assistant picked on its own; a unit you picked changes only in the sensor's settings. The zone map and zone presence work in either unit. + +[Target X and Y units](#target-x-and-y-units) explains what Apollo mmWave switches and what it leaves alone. + +### Zone presence reads unavailable + +From Apollo mmWave 2.4.0, a zone's presence sensor reads unavailable while its radar is offline, and after every Home Assistant restart until the radar connects. Then it reads off or on again from what the radar sees. While it's unavailable, the map turns the zones gray with short dashes and shows **Radar offline** in its top-left corner, and the **Zone presence** rows on the dashboard hide. Ignore zones read off the whole time. + +![The zone map for an R PRO-1 named R PRO-1 Living Room while the radar is offline: the note Radar offline in the top-left corner, under the top row of distance labels, no dots, the Couch, Desk, and Doorway zones gray with short dashes, and the Fan (ignored) zone still hatched. The expand button sits in the map's top-right corner. Under the map are the Coverage button and the Zones heading with the Add zone button, above the Desk, Couch, Doorway, and Fan buttons, with Desk selected](/assets/apollo-mmwave-zone-map-offline.png) + +If it stays unavailable, check the radar's power and Wi-Fi, and that it shows as online under **Settings โ†’ Devices & services โ†’ ESPHome**. + +[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=esphome) + +An automation that must not fire when the radar comes back, such as a notification, needs `from: "on"` in its trigger, as [Use the zone sensors](#use-the-zone-sensors) shows. Leave it out of lights-off automations, so they still turn the lights off for a zone that emptied while the radar was offline. + +**A tab says the radar is offline, but it works.** The **Start here** card keeps the **Offline right now.** note it was built with, for example on a dashboard you opened while the radars were reconnecting after a restart. Reload the page. + +### A zone stays on after everyone left + +Look at the zone on the map: + +- **Its label ends in (held).** The zone has a **Hold** time and is holding for someone the radar lost while they sat still (see [Ignore a spot or hold a zone](#ignore-a-spot-or-hold-a-zone)). It turns off when the hold time runs out, counted from when the zone emptied. If everyone had left, the radar lost the last person before it saw them walk out of the zone: they walked for less than about two seconds in its view, for example from a seat beside the door, walked slowly through the zone and out of view soon after entering it, or left where a wall or the radar's own built-in zones end its view. Pick a shorter **Hold**, or **Off**, for that zone. **Settings โ†’ Tools โ†’ States** shows the hold too: the zone's presence sensor has a `held` attribute of `true` while it holds. + + [![Open your Home Assistant instance and show your state tools.](https://my.home-assistant.io/badges/tools_states.svg)](https://my.home-assistant.io/redirect/tools_states/) + +- **A dot is still inside it.** The radar still tracks something there. A dot that stays where nobody is, such as at a fan, a curtain, or a plant, is a ghost target: draw an ignore zone over that spot. A ghost that flickers in the middle of a zone with a hold time can also start a hold. + ### A slider won't move -The sliders on **Detection Range**, **Move Thresholds**, and **Still Thresholds** start locked. Press **Unlock** on the **Sliders locked** row above them (see [Set the range and timeout](#set-the-range-and-timeout)). The **Cone rotation** slider on the zone map locks with the map: press **Locked** on the map first. +The sliders on **Detection Range**, **Move Thresholds**, and **Still Thresholds** start locked. Press **Unlock** on the **Sliders locked** row above them (see [Set the range and timeout](#set-the-range-and-timeout)). The **Cone rotation** slider under **Map settings** on the zone map locks with the map: press **Locked** on the map first. + +### A card this guide describes isn't on your tab + +If your tab has no **Radar setup** card, no **LD2450 Controls** or **Zone presence** card next to the zone map, or no **Device** card at the bottom, your Apollo mmWave dashboard is probably a saved copy from an older release, made with **Take control**. [If your dashboard is missing cards](apollo-mmwave-dashboard-setup.md#if-your-dashboard-is-missing-cards) shows how to get the automatic dashboard back and keep your copy. A card that's there but has fewer rows than this guide shows is something else: a row only appears while its entity is enabled in Home Assistant. ### Send Apollo a support file -Still stuck? Send Apollo a support file with your question. It holds the Apollo mmWave and Home Assistant versions, the dashboard's state, and each radar's model, firmware, settings, zones, and last calibration. It leaves out MAC and IP addresses, Wi-Fi network names, and tokens, and downloading it changes nothing. Only administrators can download it. +Still stuck? Send Apollo a support file with your question. It holds the Apollo mmWave and Home Assistant versions, the dashboard's state, and each radar's model, firmware, settings, zones, and last calibration. For movement history it says only whether it's on and how many points it holds, never the positions. It leaves out MAC and IP addresses, Wi-Fi network names, and tokens, and downloading it changes nothing. Only administrators can download it. 1. Go to **Settings โ†’ Devices & services** and open **Apollo mmWave**. The **Device** card at the bottom of each tab links there too. diff --git a/docs/products/mtr1/faq.md b/docs/products/mtr1/faq.md index c2580e8238..a07f4fccbd 100755 --- a/docs/products/mtr1/faq.md +++ b/docs/products/mtr1/faq.md @@ -47,7 +47,8 @@ description: Frequently asked questions about the MTR-1 mmWave sensor. * The LD2450 radar in the MTR-1 has no sensitivity setting, and ESPHome has none to offer, so it can't be tuned gate by gate like the MSR-2. Here's what you can adjust instead: * **Where it's mounted and where it points.** This decides what the radar sees, including a little of the next room and reflections off mirrors and glass. See the [mounting tips](setup/general-tips.md#mounting). * **Zones.** Draw zones on the [Apollo mmWave zone map](setup/apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) and automate on a zone's presence sensor: only someone inside the zone turns it on. - * **Spots to ignore.** Leave a spot outside every zone, such as a mirror, a fan, or the doorway to the next room, and nobody there turns a zone on. + * **Spots to ignore.** Draw an [ignore zone](setup/apollo-mmwave-dashboard.md#ignore-a-spot-or-hold-a-zone) over a spot such as a mirror, a fan, or the doorway to the next room (Apollo mmWave 2.4.0 or newer), or leave the spot outside every zone, and nobody there turns a zone on. + * **Hold.** Give a zone a [hold time](setup/apollo-mmwave-dashboard.md#ignore-a-spot-or-hold-a-zone) so it stays on for a while after the radar loses someone who sits still (Apollo mmWave 2.4.0 or newer). * **Timeout** (**Radar Timeout** on the Apollo mmWave dashboard). It sets how long **LD2450 Presence** stays on after the radar stops seeing anyone in its whole view. It doesn't hold the zones you draw. * **A delay in your automation.** Give the "turn off" trigger a delay, such as 2 minutes, so a short dropout doesn't turn the lights off. * Judge detection only while the MTR-1 is mounted where it will stay. Held in your hand, the whole room moves around the radar, so the dots and zones won't match the room. diff --git a/docs/products/mtr1/setup/apollo-mmwave-dashboard.md b/docs/products/mtr1/setup/apollo-mmwave-dashboard.md index 958dfdec34..35b61307c6 100644 --- a/docs/products/mtr1/setup/apollo-mmwave-dashboard.md +++ b/docs/products/mtr1/setup/apollo-mmwave-dashboard.md @@ -5,6 +5,6 @@ description: Draw occupancy zones for your Apollo MTR-1 over the radar's live ta # Draw MTR-1 zones with the Apollo mmWave dashboard -On an Apollo MTR-1, the dashboard tab is built around the zone map, so [Draw zones on the R PRO-1 and MTR-1](#draw-zones-on-the-r-pro-1-and-mtr-1) is the section you need, and its troubleshooting starts at [The zone map shows nobody, or only one person](#the-zone-map-shows-nobody-or-only-one-person). The calibration and tuning sections are for the Apollo MSR-1, MSR-2, and R PRO-1. +On an Apollo MTR-1, the dashboard tab is built around the zone map, so [Draw zones on the R PRO-1 and MTR-1](#draw-zones-on-the-r-pro-1-and-mtr-1) is the section you need: its eight steps take you from a new sensor to a zone that lights up when you walk into it. Its troubleshooting starts at [The zone map shows nobody, or only one person](#the-zone-map-shows-nobody-or-only-one-person). The calibration and tuning sections are for the Apollo MSR-1, MSR-2, and R PRO-1. --8<-- "products/general/setup/apollo-mmwave-dashboard.md:7:" diff --git a/docs/products/mtr1/setup/sensor-definitions.md b/docs/products/mtr1/setup/sensor-definitions.md index 76c27ed605..ffc609f4e0 100755 --- a/docs/products/mtr1/setup/sensor-definitions.md +++ b/docs/products/mtr1/setup/sensor-definitions.md @@ -58,7 +58,7 @@ Once added to Home Assistant you can configure different settings for your MTR-1 |---------|:-------:|--------------| | **ESP Reboot** | โ€” | Restarts the device. Helpful for troubleshooting or refreshing the connection. | | **Multi Target Tracking** | from module | Turns multi-target tracking on or off. Initial state is read from the LD2450 at boot. | - | **Timeout** | 5 s | How long **LD2450 Presence**, **LD2450 Moving Target**, and **LD2450 Still Target** stay on after the radar stops seeing a target of their kind. **LD2450 Presence** starts counting only once the radar sees nobody anywhere in its view, so it stays on while any target is in view. **LD2450 Moving Target** and **LD2450 Still Target** each count on their own, from the last moving or the last still target. It holds only those three, not zones: a zone you draw on the Apollo mmWave zone map turns off as soon as nobody is in it, because Apollo mmWave 2.3.0 zones have no hold. The Apollo mmWave dashboard calls this setting **Radar Timeout**. See the ESPHome LD2450 docs. | + | **Timeout** | 5 s | How long **LD2450 Presence**, **LD2450 Moving Target**, and **LD2450 Still Target** stay on after the radar stops seeing a target of their kind. **LD2450 Presence** starts counting only once the radar sees nobody anywhere in its view, so it stays on while any target is in view. **LD2450 Moving Target** and **LD2450 Still Target** each count on their own, from the last moving or the last still target. It holds only those three, not zones: a zone you draw on the Apollo mmWave zone map turns off as soon as nobody is in it. From Apollo mmWave 2.4.0, a zone's [hold time](/products/mtr1/setup/apollo-mmwave-dashboard.md#ignore-a-spot-or-hold-a-zone) keeps it on for a while after the radar loses someone who sat still inside it, but someone who walks out usually turns it off without waiting for the hold. The Apollo mmWave dashboard calls this setting **Radar Timeout**. See the ESPHome LD2450 docs. | | **Zone Type** | Disabled | Zone detection mode: `Disabled`, `Detection` (only detect targets inside the zone), or `Filter` (exclude the zone from detection). With `Detection` and no zones set, the radar detects nobody, so keep `Disabled` unless you use the radar's own zones (the **Zone-1 / Zone-2 / Zone-3** settings below). | | **Zone-1 / Zone-2 / Zone-3 X1, X2** | โ€” | Start and end X coordinates of the zone in mm (-4860 left to 4860 right). | | **Zone-1 / Zone-2 / Zone-3 Y1, Y2** | โ€” | Start and end Y coordinates of the zone in mm (0 to 7560). | diff --git a/docs/products/mtr1/setup/zones-ha.md b/docs/products/mtr1/setup/zones-ha.md index c212a0647d..51cf89ee2f 100755 --- a/docs/products/mtr1/setup/zones-ha.md +++ b/docs/products/mtr1/setup/zones-ha.md @@ -6,7 +6,7 @@ description: Set up the three radar zones on your MTR-1 in Home Assistant by ent !!! tip "Prefer a guided dashboard?" - The Apollo mmWave integration gives your Apollo MTR-1 its own dashboard tab with a zone map where you draw zones over the radar's live targets, with no Plotly card or YAML to set up. The [Apollo mmWave dashboard guide](/products/mtr1/setup/apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) walks you through it as a guided alternative to the manual steps below. If you draw zones there, leave **Zone Type** on **Disabled** instead of entering zones below: the dashboard's zone map replaces the radar's built-in zones, and its **Radar setup** card offers **Set Zone Type to Disabled** when it isn't. + The Apollo mmWave integration gives your Apollo MTR-1 its own dashboard tab with a zone map where you draw zones over the radar's live targets, with no Plotly card or YAML to set up. The [Apollo mmWave dashboard guide](/products/mtr1/setup/apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) walks you through it as a guided alternative to the manual steps below. If you draw zones there, leave **Zone Type** on **Disabled** instead of entering zones below: the dashboard's zone map replaces the radar's built-in zones, and its **Radar setup** card offers **Set Zone Type to Disabled** when it isn't. To keep a fan or a curtain from turning those zones on, draw an [ignore zone](/products/mtr1/setup/apollo-mmwave-dashboard.md#ignore-a-spot-or-hold-a-zone) over it on the map. This guide shows you how to set up your MTR-1's three zones by entering the X and Y coordinates for each one. First you add a card to your dashboard that shows the radar's live targets, then you use it to work out the coordinates for each zone, in millimeters. You can enter the values in Home Assistant, as shown below, or directly on the device's web page by visiting its IP address or hostname.local. @@ -56,6 +56,10 @@ The target sensors and zone settings are on your MTR-1's page in the ESPHome int If your Home Assistant uses the metric system, go straight to [Enter your zones](#enter-your-zones). +!!! tip "Apollo mmWave does this for you" + + With the Apollo mmWave integration 2.4.0 or newer, you can skip this section too. Apollo mmWave shows your MTR-1's Target X and Y in mm on its own: on a new MTR-1 as soon as you add it, and on one you already had once, after Home Assistant starts, with the notification **Apollo mmWave: Target X and Y now in mm**. It leaves alone a sensor whose unit you picked in its settings, which you change there, and one that an automation, a script, or a helper uses. For a sensor in use, first change any number it's compared to into mm, 25.4 times as large, then, as an administrator, press **Show Target X and Y in mm** on the **Radar setup** card above the zone map. The button switches only sensors whose unit Home Assistant picked on its own, never one whose unit you picked. To go back to inches, choose **in** under **Unit of measurement** in the sensor's settings. The [Apollo mmWave dashboard guide](/products/mtr1/setup/apollo-mmwave-dashboard.md#target-x-and-y-units) has the details. + If you use the imperial system, your Target 1-3 X and Y sensors report in inches (in). For the targets to show up correctly on the card, change all three X and all three Y target sensors to millimeters (mm). 1\. In the **Sensors** section, find the Target 1-3 X and Y sensors and select one of them. diff --git a/docs/products/mtr1/setup/zones-hlk.md b/docs/products/mtr1/setup/zones-hlk.md index 76123c57cc..c54910b737 100755 --- a/docs/products/mtr1/setup/zones-hlk.md +++ b/docs/products/mtr1/setup/zones-hlk.md @@ -42,7 +42,7 @@ With the app installed, you'll turn on the radar's Bluetooth, connect to it from !!! tip "Drawing zones with the Apollo mmWave dashboard?" - In step 4, pick **Close detection** instead of **Area Detection** (Zone Type **Disabled** in Home Assistant). The dashboard's [zone map](/products/mtr1/setup/apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) replaces the app's areas. On **Area Detection**, the radar reports only people inside the app's areas, so anyone else is missing from the map, and **Area Filtering** hides the people inside them. + In step 4, pick **Close detection** instead of **Area Detection** (Zone Type **Disabled** in Home Assistant). The dashboard's [zone map](/products/mtr1/setup/apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) replaces the app's areas. On **Area Detection**, the radar reports only people inside the app's areas, so anyone else is missing from the map, and **Area Filtering** hides the people inside them. To keep a fan or a curtain from turning the map's zones on, draw an [ignore zone](/products/mtr1/setup/apollo-mmwave-dashboard.md#ignore-a-spot-or-hold-a-zone) over it on the map. 4\. Select **Area Detection** (drawing zones on the Apollo mmWave dashboard instead? Pick **Close detection** and skip the areas; see the tip above), then toggle Area 1, 2, or 3 and you will see a box with the corresponding number pop up. Then you can press and hold the box to move it and resize it. When your zones are set then select Submit and you should see Setup successfully. diff --git a/docs/products/rpro1/setup/apollo-mmwave-dashboard.md b/docs/products/rpro1/setup/apollo-mmwave-dashboard.md index bd0b8fcb18..f12626cb77 100644 --- a/docs/products/rpro1/setup/apollo-mmwave-dashboard.md +++ b/docs/products/rpro1/setup/apollo-mmwave-dashboard.md @@ -5,4 +5,6 @@ description: Draw occupancy zones over the live targets of your Apollo R PRO-1, # Draw R PRO-1 zones and tune the LD2412 addon with the Apollo mmWave dashboard +An Apollo R PRO-1 tab has a job for each radar. For the LD2450, [Draw zones on the R PRO-1 and MTR-1](#draw-zones-on-the-r-pro-1-and-mtr-1) takes you from a new sensor to a working zone in eight steps. For the optional LD2412 addon, start at [Calibrate with an empty room](#calibrate-with-an-empty-room), and [R PRO-1 and its LD2412 radar](#r-pro-1-and-its-ld2412-radar) covers what's different from an MSR-1 or MSR-2. + --8<-- "products/general/setup/apollo-mmwave-dashboard.md:7:" diff --git a/docs/products/rpro1/setup/rpro1-sensor-definitions.md b/docs/products/rpro1/setup/rpro1-sensor-definitions.md index 62d0a58024..e76b7c4f92 100755 --- a/docs/products/rpro1/setup/rpro1-sensor-definitions.md +++ b/docs/products/rpro1/setup/rpro1-sensor-definitions.md @@ -35,7 +35,7 @@ The R PRO-1 pairs two radars: an **LD2450** that tracks the position of up to th | Sensor | Default Update | Details | |--------|:--------------:|---------| - | **Combined Presence** | real-time | Combined occupancy: shows **Detected** when either the LD2450 or the LD2412 radar sees a target, and **Clear** when neither does. Use this entity for automations and dashboards instead of the individual radar presence sensors. | + | **Combined Presence** | real-time | Combined occupancy: shows **Detected** when either the LD2450 or the LD2412 radar sees a target, and **Clear** when neither does. Use this entity for automations and dashboards instead of the individual radar presence sensors. It comes with R PRO-1 firmware newer than 26.3.2.1. On 26.3.2.1 and earlier, use **LD2412 Presence** for the whole room, or **LD2450 Presence** on an R PRO-1 without the LD2412. | #### Radar presence (LD2412 mmWave) @@ -55,7 +55,7 @@ The R PRO-1 pairs two radars: an **LD2450** that tracks the position of up to th | Sensor | Default Update | Details | |--------|:--------------:|---------| - | **LD2450 Presence** | real-time | Whether the radar currently detects any target. Great for occupancy automations. | + | **LD2450 Presence** | real-time | Whether the LD2450 currently detects any target, anywhere in its view. For automations, use **Combined Presence** where your firmware has it. | | **LD2450 Moving Target** | real-time | Whether a moving target is detected. | | **LD2450 Still Target** | real-time | Whether a stationary target is detected. | | **LD2450 Presence Target Count** | real-time | Count of all presence targets (max 3). | diff --git a/docs/products/rpro1/setup/zones-ha.md b/docs/products/rpro1/setup/zones-ha.md index b9a1706c1c..edbb6ac8bc 100755 --- a/docs/products/rpro1/setup/zones-ha.md +++ b/docs/products/rpro1/setup/zones-ha.md @@ -14,7 +14,7 @@ description: Tutorial for R PRO-1 Home Assistant Zone Configuration. !!! tip "Prefer a guided dashboard?" - The Apollo mmWave integration gives your R PRO-1 a dashboard tab where you draw LD2450 zones over live targets and tune the LD2412 gates with a **Calibrate with empty room** button. The [Apollo mmWave dashboard guide](/products/rpro1/setup/apollo-mmwave-dashboard.md) walks you through it as a guided alternative to the manual steps below. If you draw zones there, leave **LD2450 Zone Type** on **Disabled** instead of entering zones below: the dashboard's zone map replaces the radar's built-in zones, and its **Radar setup** card offers **Set Zone Type to Disabled** when it isn't. + The Apollo mmWave integration gives your R PRO-1 a dashboard tab where you draw LD2450 zones over live targets and tune the LD2412 gates with a **Calibrate with empty room** button. The [Apollo mmWave dashboard guide](/products/rpro1/setup/apollo-mmwave-dashboard.md) walks you through it as a guided alternative to the manual steps below. If you draw zones there, leave **LD2450 Zone Type** on **Disabled** instead of entering zones below: the dashboard's zone map replaces the radar's built-in zones, and its **Radar setup** card offers **Set Zone Type to Disabled** when it isn't. To keep a fan or a curtain from turning those zones on, draw an [ignore zone](/products/rpro1/setup/apollo-mmwave-dashboard.md#ignore-a-spot-or-hold-a-zone) over it on the map. Manually enter in the X and Y coordinates for each zone in Home Assistant or directly from the device's webserver by visiting the IP address or hostname.local. It's much easier to tune using the HLK Radartool App and we suggest using that to set up your R PRO-1 LD2450. @@ -76,6 +76,10 @@ Follow these steps to add a Plotly card that shows your LD2450 targets, then set * The Plotly chart will still render the rectangles even if the X1/X2 and Y1/Y2 values are reversed. * The zones cannot overlap. +!!! tip "Apollo mmWave does this for you" + + With the Apollo mmWave integration 2.4.0 or newer, you can skip steps 10 to 13. Apollo mmWave shows your R PRO-1's Target X and Y in mm on its own: on a new R PRO-1 as soon as you add it, and on one you already had once, after Home Assistant starts, with the notification **Apollo mmWave: Target X and Y now in mm**. It leaves alone a sensor whose unit you picked in its settings, which you change there, and one that an automation, a script, or a helper uses. For a sensor in use, first change any number it's compared to into mm, 25.4 times as large, then, as an administrator, press **Show Target X and Y in mm** on the **Radar setup** card above the zone map. The button switches only sensors whose unit Home Assistant picked on its own, never one whose unit you picked. To go back to inches, choose **in** under **Unit of measurement** in the sensor's settings. The [Apollo mmWave dashboard guide](/products/rpro1/setup/apollo-mmwave-dashboard.md#target-x-and-y-units) has the details. + 10\. If you use the imperial system (Freedom Units) then you will need to do this step. Metric users can skip this. For the targets to show up correctly we first need to update the Target 1-3 X and Y measurements from inches (in) to millimeters (mm). Find Target 1-3 X and Y under the Sensors section and select them. You will want to update all 3 X and Y target values. ![LD2450 Target-1 X and Y sensors in Home Assistant with their inch values highlighted](/assets/r-pro-1-card-change-units-from-inches.png) diff --git a/docs/products/rpro1/setup/zones-hlk.md b/docs/products/rpro1/setup/zones-hlk.md index 4eb9dd47c6..564b13a66b 100755 --- a/docs/products/rpro1/setup/zones-hlk.md +++ b/docs/products/rpro1/setup/zones-hlk.md @@ -46,7 +46,7 @@ Follow these steps to turn on the LD2450's Bluetooth and set up its zones in the !!! tip "Drawing zones with the Apollo mmWave dashboard?" - In step 4, pick **Close detection** instead of **Area Detection** (**LD2450 Zone Type** **Disabled** in Home Assistant). The dashboard's [zone map](/products/rpro1/setup/apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) replaces the app's areas. On **Area Detection**, the radar reports only people inside the app's areas, so anyone else is missing from the map, and **Area Filtering** hides the people inside them. + In step 4, pick **Close detection** instead of **Area Detection** (**LD2450 Zone Type** **Disabled** in Home Assistant). The dashboard's [zone map](/products/rpro1/setup/apollo-mmwave-dashboard.md#draw-zones-on-the-r-pro-1-and-mtr-1) replaces the app's areas. On **Area Detection**, the radar reports only people inside the app's areas, so anyone else is missing from the map, and **Area Filtering** hides the people inside them. To keep a fan or a curtain from turning the map's zones on, draw an [ignore zone](/products/rpro1/setup/apollo-mmwave-dashboard.md#ignore-a-spot-or-hold-a-zone) over it on the map. 4\. Enable Area Detection (drawing zones on the Apollo mmWave dashboard instead? Pick **Close detection** and skip the areas; see the tip above), then toggle Area 1, 2, and 3 to display a colored box with the matching number. You can press and hold the box to move or resize it as needed. Once your zones are configured, click **Submit**. You should see a confirmation message: **"Setup successfully."**