From 439eb2cf27ed0f0c7fb5c538fe7e05a28afe9ce1 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:46:45 -0500 Subject: [PATCH 01/11] docs(air1): rebuild Sensor Definitions with tabbed layout and update intervals (#900) * docs(air1): rebuild Sensor Definitions with tabbed layout and update intervals Replace the old stacked sections with a single Controls/Sensors/ Configuration/Diagnostic tab strip backed by tables. Add a Default Update column sourced from firmware, split the optional MICS gas sensor into its own table with a safety/accuracy warning and a link to the DFRobot SEN0377 wiki, and document the v26.3.2.1 entities (Apollo Firmware Version, ESPHome Version, IP Address, NowCast AQI, DPS310 Pressure Offset). * docs(air1): rename Firmware row to Firmware Update Match the device's actual OTA update entity name and clarify it is separate from the Apollo Firmware Version and ESPHome Version sensors. --- .../products/air1/setup/sensor-definitions.md | 243 ++++++------------ 1 file changed, 78 insertions(+), 165 deletions(-) diff --git a/docs/products/air1/setup/sensor-definitions.md b/docs/products/air1/setup/sensor-definitions.md index 02943924e7..6ba98f22f8 100755 --- a/docs/products/air1/setup/sensor-definitions.md +++ b/docs/products/air1/setup/sensor-definitions.md @@ -4,168 +4,81 @@ description: Full list of definitions for the AIR-1 and its various sensors. --- # Sensor Definitions -Once added to Home Assistant you can configure different settings for your sensor. Below is what each setting does. - -### Controls - -**Calibrate SCD40 to 420ppm** **CO2** - -* A control option to calibrate the SCD40 CO₂ sensor to outdoor baseline levels. - -**Clean SEN55** - -* This control allows you to clean the SEN55 sensor, likely clearing any temporary issues or re-calibrating. - -**RGB Light** - -* Three RGB Neopixel LEDs. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - -### Sensors - -**Ammonia (NH₃)** - -* Measures the concentration of ammonia in the air, which can come from agricultural emissions, cleaning products, or industrial processes. -* **Baseline 0 ppm**. - -**Carbon Monoxide (CO)** - -* Detects the concentration of carbon monoxide, a dangerous, odorless gas typically produced by combustion. -* **Baseline is 4.16ppm not 0 ppm**. - -**(Carbon Dioxide (CO₂)** - -* Tracks CO₂ levels in parts per million (ppm), which can indicate poor ventilation and impact overall air quality and cognitive performance. True NDIR CO2 reading from the SCD40. This will be Unknown if you do not have the CO2 module. You can re-calibrate the SCD40 CO₂ sensor to outdoor baseline levels. - -**DPS310 Pressure** - -* Measures the air pressure in the environment. Note: A small subset of devices do not include a DPS310 sensor. If this sensor is unknown, your device may be one of these units. - -**Ethanol (C₂H₅OH)** - -* Detects ethanol vapors, commonly found in cleaning agents, sanitizers, or alcohol-based products. -* **Baseline is 0 ppm**. - -**Hydrogen (H₂)** - -* Monitors the concentration of hydrogen gas, which can indicate leaks or industrial processes. -* **Baseline is 0 ppm**. - -**Methane (CH₄)** - -* Detects methane concentrations, which can indicate natural gas leaks or emissions from agricultural activities. -* **Detects measurements of greater than 1000ppm**(Methane CH4 ) -* **Baseline is 0 ppm**. - -**Nitrogen Dioxide (NO₂)** - -* Measures the levels of nitrogen dioxide, a harmful gas often produced by vehicle emissions and industrial processes. -* **Baseline is 0.16ppm not 0 ppm**. - -**PM <10µm Weight Concentration** - -* Tracks particulate matter smaller than 10 micrometers (PM10), which includes dust, pollen, and mold. - -**PM <1µm Weight Concentration** - -* Monitors the concentration of ultra-fine particles smaller than 1 micrometer, often present in smoke or exhaust. - -**PM <2.5µm Weight Concentration** - -* Measures particles smaller than 2.5 micrometers (PM2.5), which are generated by combustion and industrial activities. - -**PM <4µm Weight Concentration** - -* Detects particulate matter smaller than 4 micrometers. - -**SEN55 Temperature** - -* Tracks ambient air temperature to help assess comfort levels and environmental conditions. - -**SEN55 Humidity** - -* Measures relative humidity in the air, which impacts comfort and the overall environment. - -**SEN55 NOX Index** - -* Monitors nitrogen oxides (NOX index), harmful gases produced by burning fossil fuels and industrial processes. - -**SEN55 VOC Index** - -Detects volatile organic compounds (VOC Index), which are emitted from paints, cleaning products, and industrial chemicals. VOC index from the SEN55. - -**VOC Quality** -This uses the VOC index and a scale to output an easier to use variable - -0-79: **Improved** -> 80-149: **Normal** -> 150-249: **Abnormal** -> 250-399: **Very abnormal** -> 400+: **Extremely abnormal** - -**PM 0.3 To 1 µm** - -* Monitors particles in the range of 0.3 to 1 micrometer. Disabled by default. - -**PM 1 To 2.5 µm** - -* Tracks particles between 1 and 2.5 micrometers. Disabled by default. - -**PM 2.5 To 4 µm** - -* Measures particulate matter between 2.5 and 4 micrometers. Disabled by default. - -**PM 4 To 10 µm** - -* Detects particles between 4 and 10 micrometers. Disabled by default. - -### Configuration - -* **ESP Reboot** - * Performs a restart of the sensor -* **SEN55 Temperature Offset** - * Allows you to calibrate the SEN55 temperature. Please refer to our [calibration guide](https://wiki.apolloautomation.com/products/general/temp-hum-calibration/ "MSR-1 Temperature & Humidity Offsets"). -* **SEN55 Humidity Offset** - * Allows you to calibrate the SEN55 humidity. Please refer to our [calibration guide](https://wiki.apolloautomation.com/products/general/temp-hum-calibration/ "MSR-1 Temperature & Humidity Offsets"). -* **DPS310 Pressure Offset** - * Allows you to apply a calibration offset (in hPa) to the DPS310 pressure reading. Range is -100 to +100 hPa in 0.1 hPa steps. Disabled by default (0.0 hPa offset). Note: A small subset of devices do not include a DPS310 sensor. If this option is unknown, your device may be one of these units. - -![AIR-1 Sensor Data.jpg](/assets/air-1-device-page-pic-1.png) - -#### Configuration: - -**ESP Reboot** - -* A button to restart the ESP32 microcontroller running the AIR-1 sensor, helpful for troubleshooting or refreshing connections. - -**Prevent Sleep** - -* Ability to put AIR-1 to sleep to get better temperature and humidity measurements. - -**SEN55 Humidity Offset** - -* Allows you to adjust the humidity readings for calibration purposes. - -**SEN55 Temperature Offset** - -* Lets you calibrate the temperature sensor by adjusting the offset in degrees Celsius. - -**DPS310 Pressure Offset** - -* Allows you to apply a calibration offset (in hPa) to the DPS310 pressure reading. Range is -100 to +100 hPa in 0.1 hPa steps. Disabled by default (0.0 hPa offset). Note: A small subset of devices do not include a DPS310 sensor. If this option is unknown, your device may be one of these units. - -#### Diagnostic: - -**ESP Temperature** - -* Displays the internal temperature of the ESP32 microcontroller (112.6°F shown), which is often higher than ambient due to the processor’s activity. - -**Firmware Update** - -* Shows the status of firmware updates (currently unavailable). - -**Online** - -* Shows the connection status of the device (Connected). - -**RSSI** - -* Displays the signal strength of the Wi-Fi connection (-61 dBm shown), which can impact the sensor’s performance if too weak. - -**Uptime** - -* How long the device has been online without rebooting. \ No newline at end of file +Once added to Home Assistant you can configure different settings for your AIR-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +![AIR-1 Sensor Data](/assets/air-1-device-page-pic-1.png) + +!!! note "How often readings update" + + The **Default Update** column is how often each sensor refreshes while the AIR-1 is awake. By default **Prevent Sleep** is on, so the device stays awake and reports continuously at these intervals. If you turn **Prevent Sleep** off (for battery use), the AIR-1 wakes for about 2 minutes, reports, then deep-sleeps for the **Sleep Duration**. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | Three RGB Neopixel LEDs. Click the light bulb or color wheel to change the color. Use the toggle to turn them on or off. | + | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the outdoor baseline (about 420 ppm). Run it outdoors or next to an open window. | + | **Clean SEN55** | Runs the SEN55 fan auto-clean cycle to clear the particulate sensor and refresh its readings. | + +=== "Sensors" + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Carbon Dioxide (CO₂)** | 60s | True NDIR reading from the SCD40. Shows *Unknown* if you do not have the CO₂ module. You can re-calibrate it to the outdoor baseline. | + | **SEN55 Temperature** | 10s | Ambient air temperature. Adjusted by the **SEN55 Temperature Offset**. | + | **SEN55 Humidity** | 10s | Relative humidity in the air. Adjusted by the **SEN55 Humidity Offset**. | + | **SEN55 VOC Index** | 10s | Volatile organic compounds from paints, cleaning products, and solvents. How the VOC Index works. | + | **SEN55 NOX Index** | 10s | Nitrogen oxides produced by burning fossil fuels and other combustion. | + | **VOC Quality** | follows SEN55 VOC | A plain-language scale built on the VOC Index (details): 0-79 **Improved**, 80-149 **Normal**, 150-249 **Abnormal**, 250-399 **Very abnormal**, 400+ **Extremely abnormal**. | + | **DPS310 Pressure** | 30s | Barometric air pressure. A small subset of devices do not include a DPS310 sensor. If this reads *Unknown*, your device may be one of these units. | + | **PM <1µm Weight Concentration** | 10s | Ultra-fine particles smaller than 1 micrometer, often present in smoke or exhaust. | + | **PM <2.5µm Weight Concentration** | 10s | PM2.5, generated by combustion and industrial activity. | + | **PM <4µm Weight Concentration** | 10s | Particulate matter smaller than 4 micrometers. | + | **PM <10µm Weight Concentration** | 10s | PM10, which includes dust, pollen, and mold. | + | **NowCast AQI** | follows PM2.5 / PM10 | US EPA NowCast Air Quality Index, calculated from the PM2.5 and PM10 readings. | + | **PM 0.3 To 1 µm** | 10s | Particles between 0.3 and 1 micrometer. Disabled by default. | + | **PM 1 To 2.5 µm** | 10s | Particles between 1 and 2.5 micrometers. Disabled by default. | + | **PM 2.5 To 4 µm** | 10s | Particles between 2.5 and 4 micrometers. Disabled by default. | + | **PM 4 To 10 µm** | 10s | Particles between 4 and 10 micrometers. Disabled by default. | + + #### MICS Gas Sensor (optional) + + !!! warning "Read this before relying on the gas readings" + + The MICS gas sensor is an optional add-on, so many AIR-1 units do not include it. It's a DFRobot SEN0377 (MICS-4514) module, and it's best treated as a "does it detect this gas or not" indicator rather than a precise measurement. It does **not** meet safety standards for gas monitoring, so do not rely on it as a CO or gas-leak alarm. It also has a known quirk where **methane can spike when other gases are present**. + + | Gas | Default Update | Details | + |-----|:--------------:|---------| + | **Carbon Monoxide (CO)** | 60s | Dangerous, odorless gas produced by combustion. Baseline is **4.16 ppm**, not 0 ppm. | + | **Nitrogen Dioxide (NO₂)** | 60s | Harmful gas from vehicle emissions and industrial processes. Baseline is **0.16 ppm**, not 0 ppm. | + | **Ammonia (NH₃)** | 60s | Comes from agricultural emissions, cleaning products, or industrial processes. Baseline is **0 ppm**. | + | **Ethanol (C₂H₅OH)** | 60s | Vapors from cleaning agents, sanitizers, or alcohol-based products. Baseline is **0 ppm**. | + | **Hydrogen (H₂)** | 60s | Can indicate leaks or industrial processes. Baseline is **0 ppm**. | + | **Methane (CH₄)** | 60s | Can indicate natural-gas leaks or agricultural emissions. Detects concentrations above **1000 ppm**. Baseline is **0 ppm**. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **SEN55 Temperature Offset** | 6.0 °C | Calibrates the SEN55 temperature reading to a known value. See the temperature & humidity calibration guide. | + | **SEN55 Humidity Offset** | 0 % | Calibrates the SEN55 humidity reading to a known value. See the temperature & humidity calibration guide. | + | **DPS310 Pressure Offset** | 0.0 hPa | Applies a calibration offset to the DPS310 pressure reading. Range is -100 to +100 hPa in 0.1 hPa steps. Disabled by default. A small subset of devices do not include a DPS310 sensor; if this option reads *Unknown*, your device may be one of these units. | + | **Sleep Duration** | 5 min | How long the AIR-1 stays in deep sleep between wake cycles (only used when **Prevent Sleep** is off). | + | **Prevent Sleep** | On | Keeps the device awake instead of deep-sleeping, so it reports continuously. Required for OTA updates and live readings; turn it off to save power on battery. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. Separate from the **Apollo Firmware Version** and **ESPHome Version** sensors above. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From 7c286e409a3b9ab5078c5c8845a1a2fbc93a54b5 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:46:49 -0500 Subject: [PATCH 02/11] docs(mtr1): rebuild Sensor Definitions with tabbed layout and update intervals (#901) * docs(mtr1): rebuild Sensor Definitions with tabbed layout and update intervals Convert the stacked collapsibles to a Controls/Sensors/Configuration/ Diagnostic tab strip with tables. Split Sensors into air-quality and radar (LD2450) subsections, add a Default Update column sourced from firmware (v26.3.2.1), and document the firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address) plus the SCD40/DPS310 offsets and LTR390 Update Interval. Fix the title typo. * docs(mtr1): rename Firmware row to Firmware Update Match the device's actual OTA update entity name and clarify it is separate from the Apollo Firmware Version and ESPHome Version sensors. --- .../products/mtr1/setup/sensor-definitions.md | 359 +++++------------- 1 file changed, 85 insertions(+), 274 deletions(-) diff --git a/docs/products/mtr1/setup/sensor-definitions.md b/docs/products/mtr1/setup/sensor-definitions.md index 0a9a4297c4..fa2c5a3050 100755 --- a/docs/products/mtr1/setup/sensor-definitions.md +++ b/docs/products/mtr1/setup/sensor-definitions.md @@ -1,279 +1,90 @@ --- -title: MTR-1 Sensor Definitons +title: MTR-1 Sensor Definitions description: These are all of the entities exposed by the MTR-1 to automate on! --- # Sensor Definitions -???+ info "Controls" - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Calibrate SCD40 to 420ppm** - - * A control option to calibrate the SCD40 CO₂ sensor to outdoor baseline levels. - -???+ info "Sensors" - - **CO2** - - * True CO2 reading from the SCD40. This will be Unknown if you do not have the CO2 module. SDC40 can be calibrated following this guide. - - **ESP Temperature** - - * This is the temperature of the internal microcontroller. Think of it like your measured CPU temp on your PC. - - **DPS310 Pressure** - - * Measures the air pressure in the environment. Note: A small subset of devices do not include a DPS310 sensor. If this sensor is unknown, your device may be one of these units. - - **DPS310 Temperature** - - * Measures the ambient air temperature using the DPS310 sensor. Note: A small subset of devices do not include a DPS310 sensor. If this sensor is unknown, your device may be one of these units. - - **LTR390 Light** - - * Light level measured in lux by LTR390. - - **LTR390 UV Index** - - * UV index measured by LTR390. - - **Moving Target Count** - - * Count of all moving targets. (max 3) - - **Presence Target Count** - - * Count of all presence targets. (max 3) - - **Still Target Count** - - * Count of all still targets. (max 3) - - **Target-1 Angle** - - * Angle of target in `degrees (°)` relative to the `ld2450` sensor. - - **Target-1 Direction** - - * Direction of the target relative to the `ld2450` sensor. Possible values are: `Stationary`, `Moving away`, `Approaching`, `NA`. - - **Target-1 Distance** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **Target-1 Resolution** - - * The `ld2450` target detection range resolution in `millimeter (mm)`. - - **Target-1 Speed** - - * Speed of the moving target in `mm/s`. - - **Target-1 X** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **Target-1 Y** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor in the Y direction (near/far). The `ld2450` module can detect targets from 0 to 6000 mm in `Y` direction. - - **Target-2 Angle** - - * Angle of target in `degrees (°)` relative to the `ld2450` sensor. - - **Target-2 Direction** - - * Direction of the target relative to the `ld2450` sensor. Possible values are: `Stationary`, `Moving away`, `Approaching`, `NA`. - - **Target-2 Distance** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **Target-2 Resolution** - - * The `ld2450` target detection range resolution in `millimeter (mm)`. - - **Target-2 Speed** - - * Speed of the moving target in `mm/s`. - - **Target-2 X** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **Target-2 Y** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor in the Y direction (near/far). The `ld2450` module can detect targets from 0 to 6000 mm in `Y` direction. - - **Target-3 Angle** - - * Angle of target in `degrees (°)` relative to the `ld2450` sensor. - - **Target-3 Direction** - - * Direction of the target relative to the `ld2450` sensor. Possible values are: `Stationary`, `Moving away`, `Approaching`, `NA`. - - **Target-3 Distance** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **Target-3 Resolution** - - * The `ld2450` target detection range resolution in `millimeter (mm)`. - - **Target-3 Speed** - - * Speed of the moving target in `mm/s`. - - **Target-3 X** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **Target-3 Y** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor in the Y direction (near/far). The `ld2450` module can detect targets from 0 to 6000 mm in `Y` direction. - - **Zone-1 All Target Count** - - * Total targets detected in the zone, whether they are stationary or in motion. - - **Zone-1 Moving Target Count** - - * Count of moving targets in the zone. - - **Zone-1 Still Target Count** - - * Count of stationary targets in the zone. - - **Zone-2 All Target Count** - - * Total targets detected in the zone, whether they are stationary or in motion. - - **Zone-2 Moving Target Count** - - * Count of moving targets in the zone. - - **Zone-2 Still Target Count** - - * Count of stationary targets in the zone. - - **Zone-3 All Target Count** - - * Total targets detected in the zone, whether they are stationary or in motion. - - **Zone-3 Moving Target Count** - - * Count of moving targets in the zone. - - **Zone-3 Still Target Count** - - * Count of stationary targets in the zone. - -???+ info "Configuration" - - **DPS310 Temperature Offset** - - * Offset value of the DPS310 Temperature. Note: A small subset of devices do not include a DPS310 sensor. If this option is unknown, your device may be one of these units. - - **ESP Reboot** - - * Performs a restart of the sensor. - - **Firmware** - - * Shows available updates and allows updating inside of Home Assistant. - - **LD2450 Bluetooth** - - * Toggles the Bluetooth of the LD2450 to directly connect with a phone to the HLK Radartool App. - - **Multi Target Tracking** - - * Turn on/off the Multi Target Tracking option. The initial state set based on the corresponding setting as read from LD2450 module at boot. - - **Timeout** - - * The duration, in seconds, for which the [presence states](https://esphome.io/components/sensor/ld2450.html#ld2450-binary-sensors) will persist even after the detection is cleared. Default is `5` seconds. - - **Zone Type** - - * Control the zone detection modes. It can be set to `Disabled`, `Detection` or `Filter`. Selecting the `Disabled` option will disable zone area detection. `Detection` mode is used to detect only targets in the specified area, while `Filter` mode can be used to exclude an area from detection. - - **Zone-1 X1** - - * Start X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **Zone-1 X2** - - * End X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **Zone-1 Y1** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **Zone-1 Y2** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **Zone-2 X1** - - * Start X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **Zone-2 X2** - - * End X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **Zone-2 Y1** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **Zone-2 Y2** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **Zone-3 X1** - - * Start X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **Zone-3 X2** - - * End X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **Zone-3 Y1** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **Zone-3 Y2** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - -??? info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. - - **LD2450 BT MAC** - - * Bluetooth MAC Address of the LD2450 mmWave sensor. - - **LD2450 Firmware** - - * Firmware version installed on the LD2450. Defaults to 2.04.23101915 - - **Online** - - * Shows the connection status. - - **Uptime** - - * Shows the time since last reboot. - - **RSSI** - - * Displays the Wi-Fi signal strength. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +Once added to Home Assistant you can configure different settings for your MTR-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +!!! note "How often readings update" + + The **Default Update** column is how often each entity refreshes. Radar entities update in real time as targets move. The **LTR390 Light** and **LTR390 UV Index** sensors use the interval set by the **LTR390 Update Interval** number (60s by default). + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | One RGB Neopixel LED. Click the light bulb or color wheel to change the color. Use the toggle to turn it on or off. | + | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the outdoor baseline (about 420 ppm). Run it outdoors or next to an open window. | + +=== "Sensors" + + #### Air quality & light + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **CO2** | 60s | True NDIR reading from the SCD40. Shows *Unknown* if you do not have the CO₂ module. You can re-calibrate it to the outdoor baseline. | + | **DPS310 Pressure** | 30s | Barometric air pressure. A small subset of devices do not include a DPS310 sensor. If this reads *Unknown*, your device may be one of these units. | + | **DPS310 Temperature** | 30s | Ambient air temperature from the DPS310. A small subset of devices do not include a DPS310 sensor. | + | **LTR390 Light** | 60s* | Ambient light level in lux. *Polls at the **LTR390 Update Interval** (60s by default). | + | **LTR390 UV Index** | 60s* | UV index measured by the LTR390. *Polls at the **LTR390 Update Interval**. | + | **SCD40 Temperature** | 60s | Temperature from the SCD40. Disabled by default. Adjusted by the **SCD40 Temperature Offset**. | + | **SCD40 Humidity** | 60s | Humidity from the SCD40. Disabled by default. Adjusted by the **SCD40 Humidity Offset**. | + + #### Radar (LD2450 mmWave) + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **LD2450 Presence** | real-time | Whether the radar currently detects any target. Great for occupancy automations. | + | **LD2450 Moving Target** | real-time | Whether a moving target is detected. | + | **LD2450 Still Target** | real-time | Whether a stationary target is detected. | + | **Presence Target Count** | real-time | Count of all presence targets (max 3). | + | **Moving Target Count** | real-time | Count of all moving targets (max 3). | + | **Still Target Count** | real-time | Count of all still targets (max 3). | + | **Target-1 / Target-2 / Target-3 X** | real-time | Distance in mm of the target from the sensor along the X-axis (negative = left, positive = right, range -3000 to 3000). | + | **Target-1 / Target-2 / Target-3 Y** | real-time | Distance in mm of the target from the sensor in the Y direction (near/far, range 0 to 6000). | + | **Target-1 / Target-2 / Target-3 Speed** | real-time | Speed of the moving target in mm/s. | + | **Target-1 / Target-2 / Target-3 Angle** | real-time | Angle of the target in degrees relative to the sensor. | + | **Target-1 / Target-2 / Target-3 Distance** | real-time | Straight-line distance of the target from the sensor. | + | **Target-1 / Target-2 / Target-3 Resolution** | real-time | Target detection range resolution in mm. | + | **Target-1 / Target-2 / Target-3 Direction** | real-time | Direction of the target: `Stationary`, `Moving away`, `Approaching`, or `NA`. | + | **Zone-1 / Zone-2 / Zone-3 All Target Count** | real-time | Total targets in the zone, stationary or moving. | + | **Zone-1 / Zone-2 / Zone-3 Moving Target Count** | real-time | Count of moving targets in the zone. | + | **Zone-1 / Zone-2 / Zone-3 Still Target Count** | real-time | Count of stationary targets in the zone. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **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 presence stays detected after the target is lost. 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). | + | **Zone-1 / Zone-2 / Zone-3 X1, X2** | — | Start and end X coordinates of the zone in mm (-3000 left to 3000 right). | + | **Zone-1 / Zone-2 / Zone-3 Y1, Y2** | — | Start and end Y coordinates of the zone in mm (0 to 6000). | + | **DPS310 Pressure Offset** | 0.0 hPa | Calibration offset for the DPS310 pressure reading. Disabled by default. | + | **DPS310 Temperature Offset** | — | Calibration offset for the DPS310 temperature reading. | + | **SCD40 Temperature Offset** | — | Calibration offset for the SCD40 temperature reading. Disabled by default. | + | **SCD40 Humidity Offset** | — | Calibration offset for the SCD40 humidity reading. Disabled by default. | + | **LTR390 Update Interval** | 60 s | How often the LTR390 light and UV sensors poll (1 to 300 seconds). | + | **LD2450 Bluetooth** | — | Toggles the LD2450's Bluetooth so you can connect with the HLK Radartool phone app. | + | **Baud rate** | from module | Serial baud rate for the LD2450 module. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + | **Factory Reset LD2450** | — | Resets the LD2450 radar module to its factory settings. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. Separate from the **Apollo Firmware Version** and **ESPHome Version** sensors above. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + | **LD2450 Firmware** | on boot | Firmware version installed on the LD2450 radar module. | + | **LD2450 BT MAC** | on boot | Bluetooth MAC address of the LD2450 radar module. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From b7044afeb933f35fa9da6dee4900bddae7b8266a Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:46:54 -0500 Subject: [PATCH 03/11] docs(btn1): rebuild Sensor Definitions with tabbed layout and update intervals (#902) Convert the stacked collapsibles to a Controls/Sensors/Events/ Configuration/Diagnostic tab strip with tables. Add a Default Update column sourced from firmware (v26.3.2.1) and document the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address) plus the ESP Reboot and Factory Reset ESP buttons. --- .../products/btn1/setup/sensor-definitions.md | 114 +++++++----------- 1 file changed, 42 insertions(+), 72 deletions(-) diff --git a/docs/products/btn1/setup/sensor-definitions.md b/docs/products/btn1/setup/sensor-definitions.md index f84ca20118..9a60c3f693 100755 --- a/docs/products/btn1/setup/sensor-definitions.md +++ b/docs/products/btn1/setup/sensor-definitions.md @@ -4,88 +4,58 @@ description: These are all of the entities exposed by the BTN-1 to automate on! --- # Sensor Definitions -This serves as a list of all sensor definitions to help understand what each entity does for your new BTN-1! +Once added to Home Assistant you can configure different settings for your BTN-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. -???+ info "Controls" +!!! note "How often readings update" - **BTN 1 Light** + The BTN-1 is a battery-powered device that deep-sleeps by default. The **Default Update** column is how often each entity refreshes while the BTN-1 is awake. With **Prevent Sleep** off, the BTN-1 wakes for about 90 seconds (on a button press or after the **Sleep Duration**), reports its values, then deep-sleeps again. While asleep it does not respond to Home Assistant. Turn **Prevent Sleep** on to keep it awake and reporting continuously, which is required for OTA updates. - * Controls the light in front of the first button. Defaults to off. +=== "Controls" - **BTN 2 Light** + | Control | What it does | + |---------|--------------| + | **BTN 1 Light** | RGB light behind the first button. Click the light bulb or color wheel to change the color, or use the toggle to turn it on or off. Defaults to off. | + | **BTN 2 Light** | RGB light behind the second button. Click the light bulb or color wheel to change the color, or use the toggle to turn it on or off. Defaults to off. | + | **BTN 3 Light** | RGB light behind the third button. Click the light bulb or color wheel to change the color, or use the toggle to turn it on or off. Defaults to off. | + | **BTN 4 Light** | RGB light behind the fourth button. Click the light bulb or color wheel to change the color, or use the toggle to turn it on or off. Defaults to off. | - * Controls the light in front of the second button. Defaults to off. +=== "Sensors" - **BTN 3 Light** + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Battery level** | per wake cycle | Remaining battery charge as a percentage, from 0 to 100%. Read from the MAX17048 fuel gauge. | + | **Battery voltage** | per wake cycle | Current battery voltage, for real-time monitoring of the cell. | + | **Wake-up Button Pressed** | per wake cycle | Which button woke the device from deep sleep (1 to 4). Resets to 0 after the press is handled. | - * Controls the light in front of the third button. Defaults to off. +=== "Events" - **BTN 4 Light** + | Event | What it reports | + |-------|-----------------| + | **Button 1** | Fires a `click`, `double_click`, `triple_click`, or `hold` event for the first button. Great for automating. | + | **Button 2** | Fires a `click`, `double_click`, `triple_click`, or `hold` event for the second button. Great for automating. | + | **Button 3** | Fires a `click`, `double_click`, `triple_click`, or `hold` event for the third button. Great for automating. | + | **Button 4** | Fires a `click`, `double_click`, `triple_click`, or `hold` event for the fourth button. Great for automating. | - * Controls the light in front of the fourth button. Defaults to off. +=== "Configuration" -???+ info "Sensors" + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Sleep Duration** | 24 h | How many hours the BTN-1 stays in deep sleep between wake cycles (only used when **Prevent Sleep** is off). Range is 0 to 800 hours. | + | **Prevent Sleep** | On | Keeps the device awake instead of deep-sleeping, so it responds to Home Assistant continuously. Required for OTA updates; turn it off to save battery. While the device is asleep it does not respond to Home Assistant until it wakes again. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | - **Battery level** +=== "Diagnostic" - * Displays the remaining battery percentage. Values range from 0-100% + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. Disabled by default. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | - **Battery voltage** - - * Represents the current voltage level of the battery for real-time monitoring. - - **Wake-up Button Pressed** - - * Counter to let you know when the wake-up button is pressed. Defaults to 0. - -???+ info "Events" - - **Button 1** - - * Displays a Single Click, Double Click, Triple Click and Hold Event for Button 1. Great for automating! - - **Button 2** - - * Displays a Single Click, Double Click, Triple Click and Hold Event for Button 2. Great for automating! - - **Button 3** - - * Displays a Single Click, Double Click, Triple Click and Hold Event for Button 3. Great for automating! - - **Button 4** - - * Displays a Single Click, Double Click, Triple Click and Hold Event for Button 4. Great for automating! - -???+ info "Configuration" - - **Prevent Sleep** - - * Prevents the device from going to sleep. When sleeping, your BTN-1 will NOT respond to Home Assistant it is effectively off until it wakes up again. Defaults to ON. - - **Sleep Duration** - - * The number of hours the device should remain in sleep mode before waking up. Defaults to 24 hours. - - **Firmware Update** - - * Indicates whether an update is available or if you are Up-to-date. - -??? info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. (Disabled by Default) - - **Online** - - * Shows the connection status. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From 1fb3eab3af0a10e0fd500462732bd02e108ad33e Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:46:57 -0500 Subject: [PATCH 04/11] docs(pump1): rebuild Sensor Definitions with tabbed layout and update intervals (#903) Convert the stacked collapsibles to a Controls/Sensors/Configuration/ Diagnostic tab strip with tables. Add a Default Update column sourced from firmware (v26.3.2.1), document the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address), and surface the full pump-control/safety settings (Invert Water Logic, Auto Refill, Max Safe Run Time). --- .../pump1/setup/pump1-sensor-definitions.md | 141 +++++++----------- 1 file changed, 50 insertions(+), 91 deletions(-) diff --git a/docs/products/pump1/setup/pump1-sensor-definitions.md b/docs/products/pump1/setup/pump1-sensor-definitions.md index 8a05a3b643..5c79e75565 100755 --- a/docs/products/pump1/setup/pump1-sensor-definitions.md +++ b/docs/products/pump1/setup/pump1-sensor-definitions.md @@ -4,94 +4,53 @@ description: These are all of the entities exposed by the PUMP-1 to automate on! --- # Sensor Definitions -This serves as a list of all sensor definitions to help understand what each entity does for your new PUMP-1! - -???+ info "Controls" - - **Pump Run Time** - - * Amount of time in seconds to run the pump. Defaults to 10s - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Run Pump** - - * Press button for running the PUMP-1 Pump. This will run for the amount of seconds set above in "Pump Run Time". - - **Run Pump Until Output Wet** - - * Press button for running the PUMP-1 Pump. This will run the pump until the Fluid Output changes to Wet. (Disabled by default) - -???+ info "Sensors" - - **Fluid Input** - - * This ultrasonic sensor is located at the bottom of the PUMP-1 water bottle and monitors the presence of fluid. The state remains **"Wet"** while water is present in the bottle, and changes to **"Dry"** once the bottle is completely empty. It reports a state of either **"Wet"** or **"Dry"**. - - **Fluid Output** - - * This ultrasonic sensor can be mounted on the exterior of any container where you need to detect the presence of water on the other side, such as a Keurig reservoir or fish tank. It can be attached using adhesive tape or other mounting methods. The sensor reports **"Wet"** when the water level is above the sensor and **"Dry"** when the level falls below it. It reports a state of either **"Wet"** or **"Dry"**. - -???+ info "Configuration" - - **ESP Reboot** - - * Performs a restart of the sensor. - - **Firmware Update** - - * Shows whether a firmware update is available. - - **Max Safe Run Time** - - * Maximum time the pump will run before shutting off. Defaults to 100 seconds. - - **Pump Control** - - * Allows you to toggle the pump on and off via a switch. This will still be stopped by the Max Safe Run Time interval set above. (Disabled by default) - - **Stop Pump When Input Dry** - - * This will turn the pump off when the ultrasonic sensor at the bottom of the water bottle detects no water. Note: this check is automatically skipped when **Invert Water Logic** is enabled. - - **Stop Pump When Output Wet** - - * This turns the pump off when the ultrasonic sensor (mounted on a Keurig tank, fish tank, or similar container) detects that the water level has risen above its monitoring point. - - **Invert Water Logic** - - * Flips the meaning of the Fluid Input sensor so that **Dry** = destination is low (start pumping) and **Wet** = destination is full (stop pumping). Use this when the Input sensor is placed at the low-water mark inside a destination tank (e.g. a CPAP reservoir) rather than at the bottom of a supply bottle. (Disabled by default) - - **Auto Refill** - - * When enabled together with **Invert Water Logic**, the pump automatically starts a fill cycle whenever the Fluid Input sensor reads **Dry** (tank level has dropped below the sensor). The pump stops when the Fluid Output sensor reads **Wet** or when **Max Safe Run Time** is reached, whichever comes first. Requires **Invert Water Logic** to be enabled. (Disabled by default) - - **Factory Reset ESP** - - * Factory resets the device (Disabled by default). - - **Pump Safety Override** - - * Allows you to disable the safety features (Disabled by default). - -??? info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. (Disabled by Default) - - **Online** - - * Shows the connection status. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } +Once added to Home Assistant you can configure different settings for your PUMP-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +!!! note "How often readings update" + + The **Default Update** column is how often each entity refreshes. The **Fluid Input** and **Fluid Output** sensors are event-driven, so they report the moment water rises above or falls below the sensor rather than on a fixed interval. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | One RGB Neopixel LED. Click the light bulb or color wheel to change the color. Use the toggle to turn it on or off. | + | **Pump Run Seconds** | Amount of time in seconds to run the pump when you press **Run Pump**. Range is 1 to 120 seconds. Defaults to 10s. | + | **Run Pump** | Runs the PUMP-1 pump for the number of seconds set in **Pump Run Seconds**. | + | **Run Pump Until Output Wet** | Runs the pump until the **Fluid Output** sensor changes to **Wet**. Disabled by default. | + +=== "Sensors" + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Fluid Input** | on change | Ultrasonic sensor at the bottom of the PUMP-1 water bottle that monitors the presence of fluid. Reports **Wet** while water is present and **Dry** once the bottle is empty. | + | **Fluid Output** | on change | Ultrasonic sensor you can mount on the exterior of any container to detect water on the other side, such as a Keurig reservoir or fish tank. Reports **Wet** when the water level is above the sensor and **Dry** when it falls below. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Max Safe Run Time** | 60 s | Maximum time the pump will run before shutting off. Range is 5 to 600 seconds. | + | **Pump Control** | — | Toggles the pump on and off via a switch. Still stopped by **Max Safe Run Time**. Disabled by default. | + | **Stop Pump When Input Dry** | Off | Turns the pump off when the ultrasonic sensor at the bottom of the water bottle detects no water. This check is automatically skipped when **Invert Water Logic** is enabled. | + | **Stop Pump When Output Wet** | Off | Turns the pump off when the **Fluid Output** sensor (mounted on a Keurig tank, fish tank, or similar container) detects that the water level has risen above its monitoring point. | + | **Invert Water Logic** | Off | Flips the meaning of the **Fluid Input** sensor so that **Dry** = destination is low (start pumping) and **Wet** = destination is full (stop pumping). Use this when the Input sensor is placed at the low-water mark inside a destination tank (for example, a CPAP reservoir) rather than at the bottom of a supply bottle. Disabled by default. | + | **Auto Refill** | Off | When enabled together with **Invert Water Logic**, the pump automatically starts a fill cycle whenever the **Fluid Input** sensor reads **Dry**. The pump stops when the **Fluid Output** sensor reads **Wet** or when **Max Safe Run Time** is reached, whichever comes first. Requires **Invert Water Logic**. Disabled by default. | + | **Pump Safety Override** | Off | Disables the safety features. Disabled by default. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. Disabled by default. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From 68d0f3d88fa3ca503ffb647f22e17848c91f4475 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:47:01 -0500 Subject: [PATCH 05/11] docs(temp1): rebuild Sensor Definitions with tabbed layout and update intervals (#904) Convert the stacked collapsibles to a Controls/Sensors/Configuration/ Diagnostic tab strip with tables. Add a Default Update column sourced from firmware (v26.3.2.1), document the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address), and correct the Select Probe / offset names and the 8-minute Sleep Duration default. Convert the Homey mirror to a snippet so it inherits the rebuilt page. --- .../temp1/setup/temp1-sensor-definitions.md | 105 +---------- .../temp1/setup/temp1-sensor-definitions.md | 163 +++++++----------- 2 files changed, 60 insertions(+), 208 deletions(-) diff --git a/docs/homey/products/temp1/setup/temp1-sensor-definitions.md b/docs/homey/products/temp1/setup/temp1-sensor-definitions.md index afc9268359..7d0b1839a5 100755 --- a/docs/homey/products/temp1/setup/temp1-sensor-definitions.md +++ b/docs/homey/products/temp1/setup/temp1-sensor-definitions.md @@ -1,104 +1 @@ -# TEMP-1 Sensor Definitions - -Once added to Home Assistant you can configure different settings for your sensor. Below is what each setting does. - -???+ info "Controls" - - **Alarm Outside Temp Range** - - * Alarm that sounds when the thresholds are met for the sensor. - * Click on the toggle to turn on or off. Defaults to OFF. - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Temp Probe Select** - - * Choose the probe connected to the TEMP-1B. The options are Dallas or Food. The Dallas sensor is a temperature probe (available in long or short versions), while the Food probe is a stainless steel, food-safe option suitable for use with a grill. - -???+ info "Sensors" - - **Board Humidity** - - * Measures and reports the current humidity level on the board. - - **Board Temperature** - - * Measures and reports the current temperature of the board. - - **Food Probe** - - * The stainless steel food-safe probe is designed for accurate temperature monitoring during grilling, baking, and other food-related activities. Its durable, non-corrosive construction ensures safe and reliable use for cooking, providing real-time temperature readings to help achieve perfect results. - - **Temperature Probe** - - * The temperature sensor probe, offered in both long and short options, is ideal for monitoring fridge/freezer temperatures and aquatic environments like fish tanks, hot tubs, and covered pools. Its flat cable prevents interference with fridge seals, and it includes a customizable temperature threshold with an onboard buzzer to alert when the limit is exceeded. - -???+ info "Configuration" - - **Board Humidity Offset** - - * Offset for Board Humidity - values between 0-100% - - **Board Temperature Offset** - - * Offset for Board Temperature - values in Celsius. - - **ESP Reboot** - - * Button to press which reboots your TEMP-1. - - **Firmware Update** - - * Indicates whether an update is available or if you are Up-to-date. - - **Food Probe Offset** - - * Offset for the Food Probe's temperature readings. Measured in Celsius. - - **Max Probe Temp** - - * Max Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Min Probe Temp** - - * Min Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Notify Only Outside Temp Difference** - - * Notify on Outside temperature difference ONLY. - * Click on the toggle to turn on or off. Defaults to OFF. - - **Prevent Sleep** - - * Prevents the TEMP-1 from going to sleep. When sleeping, your TEMP-1 will NOT respond to home assistant it is effectively off until it wakes up again. - * Click on the toggle to turn on or off. Defaults to ON. - - **Probe Temp Difference Threshold** - - * Max temperature range threshold used for the *Alarm Outside Temp Range* toggle. Measured in Celsius. - - **Sleep Duration** - - * The number of hours the device should remain in sleep mode before waking up. Defaults to 12 hours. - -???+ info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. - - **Online** - - * Shows the connection status. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +--8<-- "products/temp1/setup/temp1-sensor-definitions.md:5:" diff --git a/docs/products/temp1/setup/temp1-sensor-definitions.md b/docs/products/temp1/setup/temp1-sensor-definitions.md index 7c3f8c5615..26220f7533 100755 --- a/docs/products/temp1/setup/temp1-sensor-definitions.md +++ b/docs/products/temp1/setup/temp1-sensor-definitions.md @@ -2,107 +2,62 @@ title: TEMP-1 Sensor Definitions description: Full list of definitions for the TEMP-1 and its various sensors. --- -# TEMP-1 Sensor Definitions - -Once added to Home Assistant you can configure different settings for your sensor. Below is what each setting does. - -???+ info "Controls" - - **Alarm Outside Temp Range** - - * Alarm that sounds when the thresholds are met for the sensor. - * Click on the toggle to turn on or off. Defaults to OFF. - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Temp Probe Select** - - * Choose the probe connected to the TEMP-1B. The options are Dallas or Food. The Dallas sensor is a temperature probe (available in long or short versions), while the Food probe is a stainless steel, food-safe option suitable for use with a grill. - -???+ info "Sensors" - - **Board Humidity** - - * Measures and reports the current humidity level on the board. - - **Board Temperature** - - * Measures and reports the current temperature of the board. - - **Food Probe** - - * The stainless steel food-safe probe is designed for accurate temperature monitoring during grilling, baking, and other food-related activities. Its durable, non-corrosive construction ensures safe and reliable use for cooking, providing real-time temperature readings to help achieve perfect results. - - **Temperature Probe** - - * The temperature sensor probe, offered in both long and short options, is ideal for monitoring fridge/freezer temperatures and aquatic environments like fish tanks, hot tubs, and covered pools. Its flat cable prevents interference with fridge seals, and it includes a customizable temperature threshold with an onboard buzzer to alert when the limit is exceeded. - -???+ info "Configuration" - - **Board Humidity Offset** - - * Offset for Board Humidity - values between 0-100% - - **Board Temperature Offset** - - * Offset for Board Temperature - values in Celsius. - - **ESP Reboot** - - * Button to press which reboots your TEMP-1. - - **Firmware Update** - - * Indicates whether an update is available or if you are Up-to-date. - - **Food Probe Offset** - - * Offset for the Food Probe's temperature readings. Measured in Celsius. - - **Max Probe Temp** - - * Max Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Min Probe Temp** - - * Min Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Notify Only Outside Temp Difference** - - * Notify on Outside temperature difference ONLY. - * Click on the toggle to turn on or off. Defaults to OFF. - - **Prevent Sleep** - - * Prevents the TEMP-1 from going to sleep. When sleeping, your TEMP-1 will NOT respond to home assistant it is effectively off until it wakes up again. - * Click on the toggle to turn on or off. Defaults to ON. - - **Probe Temp Difference Threshold** - - * Max temperature range threshold used for the *Alarm Outside Temp Range* toggle. Measured in Celsius. - - **Sleep Duration** - - * The number of hours the device should remain in sleep mode before waking up. Defaults to 12 hours. - -???+ info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. - - **Online** - - * Shows the connection status. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +# Sensor Definitions + +Once added to Home Assistant you can configure different settings for your TEMP-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +!!! note "How often readings update" + + The **Default Update** column is how often each sensor refreshes while the TEMP-1 is awake. By default **Prevent Sleep** is on, so the device stays awake and reports continuously at these intervals. If you turn **Prevent Sleep** off (for battery use), the TEMP-1 wakes for about 90 seconds, reports, then deep-sleeps for the **Sleep Duration**. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | One RGB Neopixel LED. Click the light bulb or color wheel to change the color. Use the toggle to turn it on or off. | + | **Alarm Outside Temp Range** | Sounds the onboard buzzer when the selected probe reads outside the **Min Probe Temp** to **Max Probe Temp** range. Use the toggle to turn it on or off. Defaults to off. | + | **Select Probe** | Chooses which probe the TEMP-1 reads: `Temperature` (the Dallas DS18B20 probe, available in long or short versions) or `Food` (the stainless steel, food-safe probe for grilling and cooking). | + +=== "Sensors" + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Board Temperature** | 60s | Onboard air temperature from the AHT20. Adjusted by the **Board Temperature Offset**. | + | **Board Humidity** | 60s | Onboard relative humidity from the AHT20. Adjusted by the **Board Humidity Offset**. | + | **Temperature Probe** | 60s | Reading from the Dallas DS18B20 probe. Active when **Select Probe** is set to `Temperature`. Adjusted by the **Temp Probe Offset**. Ideal for fridge/freezer and aquatic monitoring. | + | **Food Probe** | 3s | Reading from the stainless steel, food-safe NTC probe. Active when **Select Probe** is set to `Food`. Adjusted by the **Food Probe Offset**. Designed for grilling, baking, and other cooking. | + | **Temperature Probe 2** | 60s | Second Dallas DS18B20 probe on the one-wire bus. Disabled by default. | + | **Temperature Probe 3** | 60s | Third Dallas DS18B20 probe on the one-wire bus. Disabled by default. | + | **Temperature Probe 4** | 60s | Fourth Dallas DS18B20 probe on the one-wire bus. Disabled by default. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Board Temperature Offset** | 0.0 °C | Calibrates the **Board Temperature** reading to a known value. Range is -70 to +70 °C. | + | **Board Humidity Offset** | 0 % | Calibrates the **Board Humidity** reading to a known value. Range is -70 to +70 %. | + | **Temp Probe Offset** | 0.0 °C | Calibrates the **Temperature Probe** reading to a known value. Range is -70 to +70 °C. Disabled by default. | + | **Food Probe Offset** | 0.0 °C | Calibrates the **Food Probe** reading to a known value. Range is -70 to +70 °C. Disabled by default. | + | **Max Probe Temp** | 125.0 °C | Upper threshold for the **Alarm Outside Temp Range** toggle. | + | **Min Probe Temp** | -55.0 °C | Lower threshold for the **Alarm Outside Temp Range** toggle. | + | **Probe Temp Difference Threshold** | 0.0 °C | Temperature change that triggers a report when **Notify Only Outside Temp Difference** is on. Disabled by default. | + | **Notify Only Outside Temp Difference** | Off | Wakes the device to report only when the probe temperature changes by more than the **Probe Temp Difference Threshold**, instead of every wake cycle. Disabled by default. | + | **Sleep Duration** | 8 min | How long the TEMP-1 stays in deep sleep between wake cycles (only used when **Prevent Sleep** is off). | + | **Prevent Sleep** | On | Keeps the device awake instead of deep-sleeping, so it reports continuously. Required for OTA updates and live readings; turn it off to save power on battery. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From a89726b7e83178fb948c88b785a1c15f3c5e0030 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:47:06 -0500 Subject: [PATCH 06/11] docs(temp1b): rebuild Sensor Definitions with tabbed layout and update intervals (#905) Convert the stacked collapsibles to a Controls/Sensors/Configuration/ Diagnostic tab strip with tables. Add a Default Update column sourced from firmware (v26.3.2.1), document the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address) and the battery sensors, and correct the Select Probe / Temp Probe Offset names. Convert the Homey mirror to a snippet so it inherits the rebuilt page. --- .../temp1b/setup/temp1b-sensor-definitions.md | 113 +----------- .../temp1b/setup/temp1b-sensor-definitions.md | 170 ++++++------------ 2 files changed, 59 insertions(+), 224 deletions(-) diff --git a/docs/homey/products/temp1b/setup/temp1b-sensor-definitions.md b/docs/homey/products/temp1b/setup/temp1b-sensor-definitions.md index 3cea0c244a..ab059d1154 100755 --- a/docs/homey/products/temp1b/setup/temp1b-sensor-definitions.md +++ b/docs/homey/products/temp1b/setup/temp1b-sensor-definitions.md @@ -1,112 +1 @@ -# TEMP-1B Sensor Definitions - -Once added to Home Assistant you can configure different settings for your sensor. Below is what each setting does. - -???+ info "Controls" - - **Alarm Outside Temp Range** - - * Alarm that sounds when the thresholds are met for the sensor. - * Click on the toggle to turn on or off. Defaults to OFF. - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Temp Probe Select** - - * Choose the probe connected to the TEMP-1B. The options are Dallas or Food. The Dallas sensor is a temperature probe (available in long or short versions), while the Food probe is a stainless steel, food-safe option suitable for use with a grill. - -???+ info "Sensors" - - **Battery level** - - * Displays the remaining battery percentage. Values range from 0-100% - - **Battery voltage** - - * Represents the current voltage level of the battery for real-time monitoring. - - **Board Humidity** - - * Measures and reports the current humidity level on the board. - - **Board Temperature** - - * Measures and reports the current temperature of the board. - - **Food Probe** - - * The stainless steel food-safe probe is designed for accurate temperature monitoring during grilling, baking, and other food-related activities. Its durable, non-corrosive construction ensures safe and reliable use for cooking, providing real-time temperature readings to help achieve perfect results. - - **Temperature Probe** - - * The temperature sensor probe, offered in both long and short options, is ideal for monitoring fridge/freezer temperatures and aquatic environments like fish tanks, hot tubs, and covered pools. Its flat cable prevents interference with fridge seals, and it includes a customizable temperature threshold with an onboard buzzer to alert when the limit is exceeded. - -???+ info "Configuration" - - **Board Humidity Offset** - - * Offset for Board Humidity - values between 0-100% - - **Board Temperature Offset** - - * Offset for Board Temperature - values in Celsius. - - **ESP Reboot** - - * Button to press which reboots your TEMP-1B. - - **Firmware Update** - - * Indicates whether an update is available or if you are Up-to-date. - - **Food Probe Offset** - - * Offset for the Food Probe's temperature readings. Measured in Celsius. - - **Max Probe Temp** - - * Max Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Min Probe Temp** - - * Min Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Notify Only Outside Temp Difference** - - * Notify on Outside temperature difference ONLY. - * Click on the toggle to turn on or off. Defaults to OFF. - - **Prevent Sleep** - - * Prevents the TEMP-1B from going to sleep. When sleeping, your TEMP-1B will NOT respond to home assistant it is effectively off until it wakes up again. - * Click on the toggle to turn on or off. Defaults to ON. - - **Probe Temp Difference Threshold** - - * Max temperature range threshold used for the *Alarm Outside Temp Range* toggle. Measured in Celsius. - - **Sleep Duration** - - * The number of hours the device should remain in sleep mode before waking up. Defaults to 12 hours. - -???+ info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. - - **Online** - - * Shows the connection status. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +--8<-- "products/temp1b/setup/temp1b-sensor-definitions.md:5:" diff --git a/docs/products/temp1b/setup/temp1b-sensor-definitions.md b/docs/products/temp1b/setup/temp1b-sensor-definitions.md index 2f833ee7bf..3fe58f3d84 100755 --- a/docs/products/temp1b/setup/temp1b-sensor-definitions.md +++ b/docs/products/temp1b/setup/temp1b-sensor-definitions.md @@ -2,115 +2,61 @@ title: TEMP-1B Sensor Definitions description: Full list of definitions for the TEMP-1B and its various sensors. --- -# TEMP-1B Sensor Definitions - -Once added to Home Assistant you can configure different settings for your sensor. Below is what each setting does. - -???+ info "Controls" - - **Alarm Outside Temp Range** - - * Alarm that sounds when the thresholds are met for the sensor. - * Click on the toggle to turn on or off. Defaults to OFF. - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Temp Probe Select** - - * Choose the probe connected to the TEMP-1B. The options are Dallas or Food. The Dallas sensor is a temperature probe (available in long or short versions), while the Food probe is a stainless steel, food-safe option suitable for use with a grill. - -???+ info "Sensors" - - **Battery level** - - * Displays the remaining battery percentage. Values range from 0-100% - - **Battery voltage** - - * Represents the current voltage level of the battery for real-time monitoring. - - **Board Humidity** - - * Measures and reports the current humidity level on the board. - - **Board Temperature** - - * Measures and reports the current temperature of the board. - - **Food Probe** - - * The stainless steel food-safe probe is designed for accurate temperature monitoring during grilling, baking, and other food-related activities. Its durable, non-corrosive construction ensures safe and reliable use for cooking, providing real-time temperature readings to help achieve perfect results. - - **Temperature Probe** - - * The temperature sensor probe, offered in both long and short options, is ideal for monitoring fridge/freezer temperatures and aquatic environments like fish tanks, hot tubs, and covered pools. Its flat cable prevents interference with fridge seals, and it includes a customizable temperature threshold with an onboard buzzer to alert when the limit is exceeded. - -???+ info "Configuration" - - **Board Humidity Offset** - - * Offset for Board Humidity - values between 0-100% - - **Board Temperature Offset** - - * Offset for Board Temperature - values in Celsius. - - **ESP Reboot** - - * Button to press which reboots your TEMP-1B. - - **Firmware Update** - - * Indicates whether an update is available or if you are Up-to-date. - - **Food Probe Offset** - - * Offset for the Food Probe's temperature readings. Measured in Celsius. - - **Max Probe Temp** - - * Max Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Min Probe Temp** - - * Min Temperature threshold used for the *Alarm Outside Temp Range* toggle. - - **Notify Only Outside Temp Difference** - - * Notify on Outside temperature difference ONLY. - * Click on the toggle to turn on or off. Defaults to OFF. - - **Prevent Sleep** - - * Prevents the TEMP-1B from going to sleep. When sleeping, your TEMP-1B will NOT respond to home assistant it is effectively off until it wakes up again. - * Click on the toggle to turn on or off. Defaults to ON. - - **Probe Temp Difference Threshold** - - * Max temperature range threshold used for the *Alarm Outside Temp Range* toggle. Measured in Celsius. - - **Sleep Duration** - - * The number of hours the device should remain in sleep mode before waking up. Defaults to 12 hours. - -???+ info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. - - **Online** - - * Shows the connection status. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +# Sensor Definitions + +Once added to Home Assistant you can configure different settings for your TEMP-1B. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +!!! note "How often readings update" + + The **Default Update** column is how often each entity refreshes while the TEMP-1B is awake. The TEMP-1B is a battery deep-sleep device. By default **Prevent Sleep** is on, so it stays awake and reports continuously at these intervals. If you turn **Prevent Sleep** off, the device wakes, reports its values, then deep-sleeps for the **Sleep Duration** before waking again. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | One RGB Neopixel LED. Click the light bulb or color wheel to change the color. Use the toggle to turn it on or off. | + | **Alarm Outside Temp Range** | Sounds the onboard buzzer when the selected probe's temperature crosses the **Min Probe Temp** or **Max Probe Temp** thresholds. Defaults to off. | + | **Select Probe** | Chooses which probe the TEMP-1B reads: `Temperature` (the Dallas DS18B20 probe, available in long or short versions) or `Food` (the stainless steel, food-safe probe for grilling and cooking). | + +=== "Sensors" + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Temperature Probe** | 60s | Reading from the Dallas DS18B20 probe. Active when **Select Probe** is set to `Temperature`. Good for fridge/freezer, aquariums, hot tubs, and covered pools. Adjusted by the **Temp Probe Offset**. | + | **Food Probe** | 3s | Reading from the stainless steel food-safe NTC probe for grilling, baking, and other cooking. Active when **Select Probe** is set to `Food`. Adjusted by the **Food Probe Offset**. | + | **Board Temperature** | 60s | Onboard temperature from the AHT20 sensor. Adjusted by the **Board Temperature Offset**. | + | **Board Humidity** | 60s | Onboard relative humidity from the AHT20 sensor. Adjusted by the **Board Humidity Offset**. | + | **Battery level** | 60s | Remaining battery charge from the MAX17048, reported 0-100%. | + | **Battery voltage** | 60s | Current battery voltage from the MAX17048 for real-time monitoring. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. | + | **Board Temperature Offset** | 0.0 °C | Calibration offset applied to the **Board Temperature** reading. | + | **Board Humidity Offset** | 0 % | Calibration offset applied to the **Board Humidity** reading. | + | **Temp Probe Offset** | 0.0 °C | Calibration offset for the **Temperature Probe** reading. Disabled by default. | + | **Food Probe Offset** | 0.0 °C | Calibration offset for the **Food Probe** reading. Disabled by default. | + | **Max Probe Temp** | 125.0 °C | Upper temperature threshold used by the **Alarm Outside Temp Range** toggle. | + | **Min Probe Temp** | -55.0 °C | Lower temperature threshold used by the **Alarm Outside Temp Range** toggle. | + | **Probe Temp Difference Threshold** | 0.0 °C | How much the probe temperature must change to trigger the **Notify Only Outside Temp Difference** wake. Disabled by default. | + | **Notify Only Outside Temp Difference** | Off | When on, the device only wakes and reports when the probe temperature changes by more than the **Probe Temp Difference Threshold**. Disabled by default. | + | **Prevent Sleep** | On | Keeps the device awake instead of deep-sleeping, so it reports continuously. Required for OTA updates and live readings; turn it off to save power on battery. While sleeping the TEMP-1B will not respond to Home Assistant until it wakes again. | + | **Sleep Duration** | 12 h | How many hours the device stays in deep sleep between wake cycles (only used when **Prevent Sleep** is off). | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From b406f2dc3587465d9276839be6d46350c547f8e8 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:47:10 -0500 Subject: [PATCH 07/11] docs(msr1): rebuild Sensor Definitions with tabbed layout and update intervals (#907) * docs(msr1): rebuild Sensor Definitions with tabbed layout and update intervals Modernize the oldest plain-bullet page into a Controls/Sensors/ Configuration/Diagnostic tab strip with tables (adding frontmatter it never had). Split Sensors into air-quality/light and radar (LD2410) subsections, add a Default Update column sourced from firmware (v26.3.2.1), and document the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address). Drop the stale 'removed in vX' rows and point the radar tuning links at the current zones-ha guide. * docs(msr1): add Firmware Update diagnostic entity Home Assistant auto-creates the firmware update entity from the device's project block; document it alongside the Apollo Firmware Version and ESPHome Version sensors. --- .../products/msr1/setup/sensor-definitions.md | 171 +++++++++--------- 1 file changed, 85 insertions(+), 86 deletions(-) diff --git a/docs/products/msr1/setup/sensor-definitions.md b/docs/products/msr1/setup/sensor-definitions.md index 181926eb2f..a1cd8d9fc3 100755 --- a/docs/products/msr1/setup/sensor-definitions.md +++ b/docs/products/msr1/setup/sensor-definitions.md @@ -1,94 +1,93 @@ +--- +title: MSR-1 Sensor Definitions +description: Full list of definitions for the MSR-1 and its various sensors. +--- # Sensor Definitions -Once added to Home Assistant you can configure different settings for your sensor. Below is what each setting does. +Once added to Home Assistant you can configure different settings for your MSR-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. -### Controls +!!! note "How often readings update" -- **RGB Light** - - A RGB Neopixel. Click on the light bulb to change the color. Click on the toggle to turn on or off + The **Default Update** column is how often each entity refreshes. Radar entities update in real time as targets move. The **LTR390 Light** and **LTR390 UV Index** sensors use the interval set by the **LTR390 Update Interval** number (60s by default). -### Sensors +=== "Controls" -- **BME280 Humidity** - - Humidity reading from the BME280. This is affected by the configuration variable "BME280 Humidity Offset". Changing the offset allows you to dial in the humidity to a known value. -- **BME280 Humidity Calibrated ****- Removed In v23.11.01.1** - - We calibrated the BME280 against a lab-rated reference sensor. We set the linear offset values in the YAML and this variable is the output. -- **BME280 Pressure** - - Atmospheric pressure reading from BME280 -- **BME280 Temperature** - - Temperature reading from BME280. This is affected by the configuration variable "BME280 Temperature Offset". Changing the offset allows you to dial in the temperature to a known value. -- **BME280 Temperature Calibrated ****- Removed In v23.11.01.1** - - We calibrated the BME280 against a lab-rated reference sensor. We set the linear offset values in the YAML and this variable is the output. -- **CO2** - - True CO2 reading from the SCD40. This will be Unknown if you do not have the CO2 module. This can be calibrated following this guide but does come precalibrated: [Here](https://wiki.apolloautomation.cloud/books/general/page/co2-calibration) -- **ESP Temperature** - - This is the temperature of the internal ESP chip. Think of it like your measured CPU temp on your PC -- **LTR390 Ambient Light ****- Removed. Value wasn't useful** - - Light level measured by LTR390 -- **LTR390 Light** - - Light level measured in lux by LTR390 -- **LTR390 UV - Removed. Value wasn't useful** - - UV level measured by LTR390 -- **LTR390 UV Index** - - UV index measured by LTR390 -- **Radar Detection Distance** - - The last detected distance by the radar. This will stay at the last known value so sometimes can be misleading -- **Radar Move Energy** - - The amount of movement measured by the LD2410B. Faster movements have higher % -- **Radar Moving Target** - - Does the radar have a moving target it is tracking -- **Radar Still Distance** - - The last measured distance of a still target. It will hold the last value so sometimes can be misleading -- **Radar Still Energy** - - The energy of the current still target -- **Radar Still Target** - - Does the radar have a still target -- **Radar Target** - - Does the radar have a still or moving target. Good for triggering automation. -- **Radar Zone 1 Occupancy** - - This is a configurable zone. Think of zones like distances from the radar unit. Zone 1 might be from 0 cm to 120 cm from the sensor. This is telling you if there is someone in that zone. The zones can be defined in the configuration section with “Radar End Zone 1” -- **Radar Zone 2 Occupancy** - - Same as zone 1 but just the second zone from the sensor -- **Radar Zone 3 Occupancy** - - Same as zone 1 & 2 but with the third zone. -- **SCD40 Humidity ****- Removed In v23.11.01.1** - - This is the humidity reading from the SCD40. Will be unknown if you do not have the CO2 module -- **SCD40 Temperature ****- Removed In v23.11.01.1** - - This is the temperature reading from the SCD40. Will be unknown if you do not have the CO2 module + | Control | What it does | + |---------|--------------| + | **RGB Light** | Three RGB Neopixel LEDs. Click the light bulb or color wheel to change the color. Use the toggle to turn them on or off. | + | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the outdoor baseline (about 420 ppm). Run it outdoors or next to an open window. | + | **Restart Radar** | Restarts the LD2410 radar module without rebooting the whole device. | -### Configuration +=== "Sensors" -- **BME280 Humidity Offset** - - Allows you to adjust the reading of the “BME280 Humidity” sensor to match a known value -- **BME280 Temperature Offset** - - Allows you to adjust the reading of the “BME280 Temperature” sensor to match a known value -- **CO2 Calibration Number** - - See calibrating CO2: [Here](https://wiki.apolloautomation.cloud/books/general/page/co2-calibration) -- **ESP Reboot** - - Performs a restart of the sensor -- **Factory Reset Radar** - - Sets the radar's move thresholds back to their original values from the manufacturer -- **g0-g8 Move & Still Threshold** - - Please refer to the radar tuning guide: [Here](https://wiki.apolloautomation.cloud/books/msr-1/page/how-to-tune-mmwave-using-home-assistant) -- **Radar Control Bluetooth** - - This allows you to turn on the LD2410's Bluetooth. This allows you to connect to the HLK Radar phone app if you wanted to upload new firmware to the radar unit (Not the MSR-1 in general, just the radar chip) -- **Radar Distance Resolution** - - Best to keep on 0.75m in many cases. If you change it to 0.25m the first few gates become very very sensitive and the maximum detection distance shrinks a lot. -- **Radar Zone 1 Start** - - This sets the starting distance for Zone 1 in cm. This is the distance from the sensor to the start of Zone 1 -- **Radar End Zone 1** - - This defines “Zone 1” of the radar. It is a distance from the sensor that specifies what “Zone 1” is. It connects to the “Radar Zone 1 Occupancy” sensor. So if this number is set to “10” that means from 0 to 10 centimeters from the sensor is zone 1. -- **Radar End Zone 2** - - Same as Zone 1. This defines where zone 2 ends -- **Radar End Zone 3** - - Like Zone 2, this defines where zone 3 ends -- **Radar Max Move Distance** - - Maximum distance gate for movement detection. Value between 2 and 8 inclusive -- **Radar Max Still Distance** - - Maximum distance gate for still detection. Value between 2 and 8 inclusive. Defaults to 8. -- **Radar Timeout** - - The time in seconds that the radar's presence will stay high after the target is lost. -- **SCD40 Humidity Offset ****- Removed In v23.11.01.1** - - Allows you to adjust the reading of the “SCD40 Humidity” sensor to match a known value. -- **SCD40 Temperature Offset ****- Removed In v23.11.01.1** - - Allows you to adjust the reading of the “SCD40 Temperature” sensor to match a known value \ No newline at end of file + #### Air quality & light + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **CO2** | 60s | True NDIR reading from the SCD40. Shows *Unknown* if you do not have the CO₂ module. You can re-calibrate it to the outdoor baseline. | + | **BME280 Temperature** | 60s | Ambient air temperature from the BME280. Adjusted by the **BME280 Temperature Offset**. | + | **BME280 Humidity** | 60s | Relative humidity from the BME280. Adjusted by the **BME280 Humidity Offset**. | + | **BME280 Pressure** | 60s | Barometric air pressure from the BME280. | + | **LTR390 Light** | 60s* | Ambient light level in lux. *Polls at the **LTR390 Update Interval** (60s by default). | + | **LTR390 UV Index** | 60s* | UV index measured by the LTR390. *Polls at the **LTR390 Update Interval**. | + + #### Radar (LD2410 mmWave) + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Radar Target** | real-time | Whether the radar detects a still or moving target. Good for triggering occupancy automations. | + | **Radar Moving Target** | real-time | Whether the radar currently has a moving target it is tracking. | + | **Radar Still Target** | real-time | Whether the radar currently has a still target. | + | **Radar Moving Distance** | real-time | Distance to the moving target. Holds the last value when no moving target is present, so it can be misleading. | + | **Radar Still Distance** | real-time | Distance to the still target. Holds the last value when no still target is present, so it can be misleading. | + | **Radar Detection Distance** | real-time | The last detected distance by the radar. Holds the last known value, so it can sometimes be misleading. | + | **Radar Move Energy** | real-time | The amount of movement measured by the LD2410. Faster movements report a higher percentage. | + | **Radar Still Energy** | real-time | The energy of the current still target. | + | **Radar Zone 1 Occupancy** | real-time | Whether someone is in Zone 1, a configurable distance band from the sensor. Defined by **Radar Zone 1 Start** and **Radar End Zone 1**. | + | **Radar Zone 2 Occupancy** | real-time | Same as Zone 1, for the second distance band (from **Radar End Zone 1** to **Radar End Zone 2**). | + | **Radar Zone 3 Occupancy** | real-time | Same as Zones 1 and 2, for the third distance band (from **Radar End Zone 2** to **Radar End Zone 3**). | + | **Radar Zone Occupancy** | real-time | Whether any of the three zones is currently occupied. | + | **g0-g8 move energy** | real-time | Live move-energy reading for each distance gate (g0 to g8). Used when tuning the radar. | + | **g0-g8 still energy** | real-time | Live still-energy reading for each distance gate (g0 to g8). Used when tuning the radar. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **BME280 Temperature Offset** | 14.54 °C | Calibrates the BME280 temperature reading to a known value. See the temperature & humidity calibration guide. | + | **BME280 Humidity Offset** | -18.86 % | Calibrates the BME280 humidity reading to a known value. See the temperature & humidity calibration guide. | + | **LTR390 Update Interval** | 60 s | How often the LTR390 light and UV sensors poll (1 to 300 seconds). Disabled by default. | + | **Radar Timeout** | — | The time in seconds that the radar's presence stays detected after the target is lost. | + | **Radar Max Move Distance** | — | Maximum distance gate for movement detection. Value between 2 and 8 inclusive. | + | **Radar Max Still Distance** | — | Maximum distance gate for still detection. Value between 2 and 8 inclusive. | + | **Radar Distance Resolution** | — | Best kept at 0.75 m in most cases. At 0.25 m the first few gates become very sensitive and the maximum detection distance shrinks a lot. Disabled by default. | + | **Radar Zone 1 Start** | 0 cm | Starting distance for Zone 1, measured in cm from the sensor. | + | **Radar End Zone 1** | 50 cm | Ending distance for Zone 1 in cm. Sets the band reported by **Radar Zone 1 Occupancy** (for example, 0 to 50 cm from the sensor). | + | **Radar End Zone 2** | 150 cm | Ending distance for Zone 2 in cm, measured from the sensor. | + | **Radar End Zone 3** | 250 cm | Ending distance for Zone 3 in cm, measured from the sensor. | + | **g0-g8 move threshold** | from module | Move-detection sensitivity for each distance gate (g0 to g8). See the radar tuning guide. | + | **g0-g8 still threshold** | from module | Still-detection sensitivity for each distance gate (g0 to g8). See the radar tuning guide. | + | **Radar Control Bluetooth** | Off | Turns on the LD2410's Bluetooth so you can connect with the HLK Radar phone app (for example, to update the radar chip's own firmware, not the MSR-1 in general). | + | **Radar Engineering Mode** | — | Enables the radar's engineering mode, which exposes the per-gate energy readings used for tuning. | + | **Startup Light Blink** | On | Blinks the RGB LED on startup to show the device's connection status. | + | **Reduce DB Reporting** | Off | Filters out small sensor changes so fewer values are logged to your Home Assistant database. | + | **query params** | — | Queries the LD2410 for its current parameters. | + | **Factory Reset Radar** | — | Sets the radar's move and still thresholds back to the manufacturer's original values. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. Separate from the **Apollo Firmware Version** and **ESPHome Version** sensors above. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + | **Radar Firmware Version** | on boot | Firmware version installed on the LD2410 radar module. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From 73d8a69b148d953c00f64fefe1e1ef382804c02b Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:47:14 -0500 Subject: [PATCH 08/11] docs(msr2): rebuild Sensor Definitions with tabbed layout and update intervals (#908) * docs(msr2): rebuild Sensor Definitions with tabbed layout and update intervals Convert the stacked collapsibles to a Controls/Sensors/Configuration/ Diagnostic tab strip with tables, splitting Sensors into air-quality/ light and radar (LD2410) subsections. Add a Default Update column sourced from firmware (v26.3.2.1) and the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address). Preserve the DPS310 'small subset of devices' note and LD2410 firmware-version note. * docs(msr2): add Firmware Update diagnostic entity Home Assistant auto-creates the firmware update entity from the device's project block; document it alongside the Apollo Firmware Version and ESPHome Version sensors. --- .../msr2/setup/msr2-sensor-definitions.md | 421 ++++-------------- 1 file changed, 90 insertions(+), 331 deletions(-) diff --git a/docs/products/msr2/setup/msr2-sensor-definitions.md b/docs/products/msr2/setup/msr2-sensor-definitions.md index 1ca0a09a2e..b5071aa185 100755 --- a/docs/products/msr2/setup/msr2-sensor-definitions.md +++ b/docs/products/msr2/setup/msr2-sensor-definitions.md @@ -4,334 +4,93 @@ description: These are all of the entities exposed by the MSR-2 to automate on! --- # Sensor Definitions -!!! note "Ensure that the LD2410 firmware version is V2.04.23022511 or later for proper integration functionality. " - - The newer version of the firmware includes an "auto calibrate" function so you might want to test it out! - -Once added to Home Assistant you can configure different settings for your sensor. Below is what each setting does. - -???+ info "Controls" - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Calibrate SCD40 to 420ppm** - - * A control option to calibrate the SCD40 CO₂ sensor to outdoor baseline levels. - -???+ info "Sensors" - - **CO2** - - * True CO2 reading from the SCD40. This will be Unknown if you do not have the CO2 module. SDC40 can be calibrated following this guide. - - **ESP Temperature** - - * This is the temperature of the internal microcontroller. Think of it like your measured CPU temp on your PC. - - **DPS310 Pressure** - - * Measures the air pressure in the environment. Note: A small subset of devices do not include a DPS310 sensor. If this sensor is unknown, your device may be one of these units. - - **DPS310 Temperature** - - * Measures the ambient air temperature using the DPS310 sensor. Note: A small subset of devices do not include a DPS310 sensor. If this sensor is unknown, your device may be one of these units. - - **LTR390 Light** - - * Light level measured in lux by LTR390. - - **LTR390 UV Index** - - * UV index measured by LTR390. - - **Radar Detection Distance** - - * The last detected distance by the radar. This will stay at the last known value so sometimes can be misleading. - - **Radar Move Energy** - - * The amount of movement measured by the LD2410B. Faster movements have higher percentage. - - **Radar Moving Target** - - * Does the radar have a moving target it is tracking. - - **Radar Still Distance** - - * The last measured distance of a still target. It will hold the last value so sometimes can be misleading. - - **Radar Still Energy** - - * The energy of the current still target. - - **Radar Still Target** - - * Does the radar have a still target. - - **Radar Target** - - * Does the radar have a still or moving target. Good for triggering automation. - - **Radar Zone 1 Occupancy** - - * This is a configurable zone. Think of zones like distances from the radar unit. Zone 1 might be from 0 cm to 100 cm from the sensor. This is telling you if there is someone in that zone. The zones can be defined in the configuration section with “Radar End Zone 1” - - **Radar Zone 2 Occupancy** - - * This is a configurable zone. Think of zones like distances from the radar unit. Zone 2 might be from 100 cm to 200 cm from the sensor. This is telling you if there is someone in that zone. The zones can be defined in the configuration section with “Radar End Zone 2” - - **Radar Zone 3 Occupancy** - - * This is a configurable zone. Think of zones like distances from the radar unit. Zone 3 might be from 200 cm to 300 cm from the sensor. This is telling you if there is someone in that zone. The zones can be defined in the configuration section with “Radar End Zone 3” - -???+ info "Configuration" - - **ESP Reboot** - - * Performs a restart of the sensor - - **Factory Reset Radar** - - * Sets the radar's move thresholds back to their original values from the manufacturer - - **g0-g8 Move & Still Threshold** - - * Please refer to the radar tuning guide: [Here](https://wiki.apolloautomation.com/products/msr2/setup/zones-ha/) - - **ld2410 Bluetooth** - - * This allows you to turn on the LD2410's Bluetooth. This allows you to connect to the HLK Radar phone app [used for tuning](https://wiki.apolloautomation.com/products/msr2/setup/zones-hlk/). - - **Radar Zone 1 Start** - - * This sets the starting distance for Zone 1 in cm. This is the distance from the sensor to the start of Zone 1 - - **DPS Temperature Offset** - - * Offsets the heat from the ESP chip for a more accurate temperature. Note: A small subset of devices do not include a DPS310 sensor. If this option is unknown, your device may be one of these units. - - **ESP Reboot** - - * A control to reboot the ESP32 system. - - **Factory Reset Radar** - - * Resets the radar to its factory settings. - - **Firmware Update** - - * Shows whether a firmware update is available. - - ??? info "Radar End Zones" - - **Radar End Zone 1** - - * This defines “Zone 1” of the radar. It is a distance from the sensor that specifies what “Zone 1” is. It connects to the “Radar Zone 1 Occupancy” sensor. So if this number is set to “100” that means from 0 to 100 centimeters from the sensor is zone 1. - - **Radar End Zone 2** - - * This defines “Zone 2” of the radar. It is a distance from the sensor that specifies what “Zone 2” is. It connects to the “Radar Zone 2 Occupancy” sensor. So if this number is set to “200” that means from zone 2 end distance to 200 centimeters from the sensor is zone 2. - - **Radar End Zone 3** - - * It is a distance from the sensor that specifies what “Zone 3” is. It connects to the “Radar Zone 3 Occupancy” sensor. So if this number is set to “300” that means from zone 2 end distance to 300 centimeters from the sensor is zone 3. - - **Radar Engineering Mode** - - * Used to enable g0-g8 threshold sliders for mmWave tuning. - - **Radar Timeout** - - * Configures the timeout for the radar in seconds. - - **Reduce DB Reporting** - - * A toggle to enable or disable reduced reporting from various entities on the msr-2. This will make multiple entities use filters and not update their state unless a threshold is met - ultimately using less Wi-Fi airtime and less database usage in home assistant. - - **Startup Light Blink** - - * A toggle to enable or disable the blinking of the RGB LED during MSR-2 initial boot. - - ???+ info "Radar Gate Distance Tuning and Timeout" - - ???+ example "Radar Max Move Distance" - - * Maximum distance gate for movement detection. Value between 2 and 8 inclusive - * Useful in a bathroom or other scenario where you want to avoid detection after a certain gate number (distance). - * Useful for triggering on "radar target" instead of triggering on zone 1/2/3 occupancy instead. - - ???+ example "Radar Max Still Distance " - - * Maximum distance gate for still detection. Value between 2 and 8 inclusive. Defaults to 8. - * Useful in a bathroom or other scenario where you want to avoid detection after a certain gate number (distance). - * Useful for triggering on "radar target" instead of triggering on zone 1/2/3 occupancy instead. - - ???+ info "Radar Timeout" - - The time in seconds that the radar's presence will stay high after the target is lost. - -??? success "Radar Sensors" - - **Radar Detection Distance** - - * Shows the distance to the detected target, measured in cm. - - **Radar Move Energy** - - * Displays the energy of movement detected by the radar, represented as a percentage. - - **Radar Moving Distance** - - * Displays the distance of a moving target, measured in cm. - - **Radar Moving Target** - - * Detects whether a moving target is present. - - **Radar Still Distance** - - * Displays the distance of a still target, measured in cm. - - **Radar Still Energy** - - * Displays the energy detected from still objects. - - **Radar Still Target** - - * Detects whether a still target is present. - - **Radar Target** - - * Overall detection of a target by the radar. - - **Radar Zone 1 Occupancy** - - * Indicates whether Zone 1 is occupied or clear. - - **Radar Zone 2 Occupancy** - - * Indicates whether Zone 2 is occupied or clear. - - **Radar Zone 3 Occupancy** - - * Indicates whether Zone 3 is occupied or clear. - -??? info "Radar Gate Configuration" - - !!! warning "Keeping these enabled permanently is bad" - - Please toggle ld2410 Bluetooth on, configure your sensor, then turn ld2410 Bluetooth back off. Otherwise, your Wi-Fi and database could become overwhelmed with excessive traffic. - - **g0 Move Threshold** - - * Configures the movement sensitivity threshold for gate 0. - - **g0 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 0. - - **g1 Move Threshold** - - * Configures the movement sensitivity threshold for gate 1. - - **g1 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 1. - - **g2 Move Threshold** - - * Configures the movement sensitivity threshold for gate 2. - - **g2 Still Threshold** - - * Configures the stillness sensitivity threshold for for gate 2. - - **g3 Move Threshold** - - * Configures the movement sensitivity threshold for gate 3. - - **g3 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 3. - - **g4 Move Threshold** - - * Configures the movement sensitivity threshold for gate 4. - - **g4 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 4. - - **g5 Move Threshold** - - * Configures the movement sensitivity threshold for gate 5. - - **g5 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 5. - - **g6 Move Threshold** - - * Configures the movement sensitivity threshold for gate 6. - - **g6 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 6. - - **g7 Move Threshold** - - * Configures the movement sensitivity threshold for gate 7. - - **g7 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 7. - - **g8 Move Threshold** - - * Configures the movement sensitivity threshold for gate 8. - - **g8 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 8. - -??? info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. - - **g0 move energy to g8 move energy** - - * Displays the move energy levels for gates g0 through g8 - - **g0 move energy to g8 still energy** - - * Displays the still energy levels for gates g0 through g8 - - **Online** - - * Shows the connection status. - - **Query Params** - - * Button to query parameters for debugging or advanced configurations. - - **Radar Firmware Version** - - * Displays the current firmware version for the radar. - - **Restart Radar** - - * Button to restart the radar sensor. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +Once added to Home Assistant you can configure different settings for your MSR-2. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +!!! note "How often readings update" + + The **Default Update** column is how often each entity refreshes. Radar entities update in real time as targets move. The **LTR390 Light** and **LTR390 UV Index** sensors use the interval set by the **LTR390 Update Interval** number (60s by default). + +!!! note "Ensure that the LD2410 firmware version is V2.04.23022511 or later for proper integration functionality." + + The newer version of the firmware includes an "auto calibrate" function, so you might want to test it out. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | Three RGB Neopixel LEDs. Click the light bulb or color wheel to change the color. Use the toggle to turn them on or off. | + | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the outdoor baseline (about 420 ppm). Run it outdoors or next to an open window. | + +=== "Sensors" + + #### Air quality & light + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **CO2** | 60s | True NDIR reading from the SCD40. Shows *Unknown* if you do not have the CO₂ module. You can re-calibrate it to the outdoor baseline. | + | **DPS310 Pressure** | 30s | Barometric air pressure. A small subset of devices do not include a DPS310 sensor. If this reads *Unknown*, your device may be one of these units. | + | **DPS310 Temperature** | 30s | Ambient air temperature from the DPS310. Adjusted by the **DPS Temperature Offset**. A small subset of devices do not include a DPS310 sensor. | + | **LTR390 Light** | 60s* | Ambient light level in lux. *Polls at the **LTR390 Update Interval** (60s by default). | + | **LTR390 UV Index** | 60s* | UV index measured by the LTR390. *Polls at the **LTR390 Update Interval**. | + + #### Radar (LD2410) + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Radar Target** | real-time | Whether the radar detects a still or moving target. Good for triggering occupancy automations. | + | **Radar Moving Target** | real-time | Whether a moving target is currently detected. | + | **Radar Still Target** | real-time | Whether a stationary target is currently detected. | + | **Radar Moving Distance** | real-time | Distance to a moving target in cm. Reports *Unknown* when no moving target is present. | + | **Radar Still Distance** | real-time | Distance to a still target in cm. Reports *Unknown* when no still target is present. | + | **Radar Detection Distance** | real-time | Last detected distance from the radar in cm. Holds the last value, so it can be misleading when nothing is present. | + | **Radar Move Energy** | real-time | Amount of movement measured by the LD2410. Faster movement reads as a higher percentage. | + | **Radar Still Energy** | real-time | Energy of the current still target. | + | **Radar Zone 1 Occupancy** | real-time | Whether someone is in Zone 1. Zones are distance bands from the sensor, set with **Radar Zone 1 Start** and **Radar End Zone 1**. | + | **Radar Zone 2 Occupancy** | real-time | Whether someone is in Zone 2, from the end of Zone 1 to **Radar End Zone 2**. | + | **Radar Zone 3 Occupancy** | real-time | Whether someone is in Zone 3, from the end of Zone 2 to **Radar End Zone 3**. | + | **Radar Zone Occupancy** | real-time | Whether any of Zone 1, 2, or 3 is occupied. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + | **Factory Reset Radar** | — | Resets the LD2410 radar to its factory move and still thresholds. | + | **Restart Radar** | — | Restarts the LD2410 radar module. | + | **Radar Timeout** | — | How long presence stays detected, in seconds, after the target is lost. | + | **Radar Max Move Distance** | — | Maximum distance gate for movement detection (gate 2 to 8). Use it to ignore movement past a chosen distance. | + | **Radar Max Still Distance** | — | Maximum distance gate for still detection (gate 2 to 8). Use it to ignore still targets past a chosen distance. | + | **Radar Zone 1 Start** | 0 cm | Start distance of Zone 1 from the sensor, in cm (0 to 800). | + | **Radar End Zone 1** | 50 cm | End distance of Zone 1 from the sensor, in cm. From **Radar Zone 1 Start** to this value is Zone 1. | + | **Radar End Zone 2** | 150 cm | End distance of Zone 2, in cm. From the end of Zone 1 to this value is Zone 2. | + | **Radar End Zone 3** | 250 cm | End distance of Zone 3, in cm. From the end of Zone 2 to this value is Zone 3. | + | **Radar Engineering Mode** | — | Enables the g0-g8 threshold sliders for mmWave tuning. | + | **g0-g8 move threshold** | — | Movement sensitivity threshold for each gate (g0 through g8). See the radar tuning guide. | + | **g0-g8 still threshold** | — | Stillness sensitivity threshold for each gate (g0 through g8). See the radar tuning guide. | + | **ld2410 Gate Size** | — | Distance resolution per gate on the LD2410. Disabled by default. | + | **ld2410 Bluetooth** | Off | Turns on the LD2410's Bluetooth so you can connect with the HLK Radartool phone app for tuning. Turned off at boot. | + | **LTR390 Update Interval** | 60 s | How often the LTR390 light and UV sensors poll (1 to 300 seconds). Disabled by default. | + | **DPS310 Pressure Offset** | 0.0 hPa | Calibration offset for the DPS310 pressure reading (-100 to +100 hPa in 0.1 hPa steps). Disabled by default. A small subset of devices do not include a DPS310 sensor; if this reads *Unknown*, your device may be one of these units. | + | **DPS Temperature Offset** | 14.54 °C | Offsets heat from the ESP chip for a more accurate DPS310 temperature reading. A small subset of devices do not include a DPS310 sensor. | + | **Reduce DB Reporting** | Off | Applies filters so many entities only report when they cross a threshold, using less Wi-Fi airtime and less Home Assistant database space. | + | **Startup Light Blink** | On | Blinks the RGB LED during the MSR-2's initial boot. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. Separate from the **Apollo Firmware Version** and **ESPHome Version** sensors above. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + | **Radar Firmware Version** | on boot | Firmware version installed on the LD2410 radar module. | + | **query params** | — | Queries the LD2410's current parameters for debugging and advanced tuning. | + | **g0 move energy to g8 move energy** | real-time | Live move-energy level for each gate (g0 through g8). | + | **g0 still energy to g8 still energy** | real-time | Live still-energy level for each gate (g0 through g8). | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From 95e972e68e3e5ec911bcd47f2cf31ef9402d4837 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:47:18 -0500 Subject: [PATCH 09/11] docs(rpro1): rebuild Sensor Definitions with tabbed layout and update intervals (#909) * docs(rpro1): rebuild Sensor Definitions with tabbed layout and update intervals Convert the nested collapsibles to a Controls/Sensors/Configuration/ Diagnostic tab strip with tables. Split Sensors into air-quality/ light, LD2412 presence, and LD2450 tracking subsections, and split Configuration by radar. Add a Default Update column sourced from firmware (v25.11.20.1) and document the firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address). Consolidate the LD2450 Target/Zone rows and the LD2412 g00-g13 gate rows. * docs(rpro1): restore Combined Presence sensor The live page documents and recommends Combined Presence (Detected when either radar sees a target). It is not in the v25.11.20.1 firmware clone I read, so add it back as its own subsection. * docs(rpro1): bump firmware version reference to 26.3.2.1 Confirmed against the merged R_PRO-1 firmware (26.3.2.1); the only entity delta from the earlier clone was Combined Presence, already documented. --- .../rpro1/setup/rpro1-sensor-definitions.md | 676 ++++-------------- 1 file changed, 137 insertions(+), 539 deletions(-) diff --git a/docs/products/rpro1/setup/rpro1-sensor-definitions.md b/docs/products/rpro1/setup/rpro1-sensor-definitions.md index 497b9423a2..9b01cd52c0 100755 --- a/docs/products/rpro1/setup/rpro1-sensor-definitions.md +++ b/docs/products/rpro1/setup/rpro1-sensor-definitions.md @@ -4,542 +4,140 @@ description: These are all of the entities exposed by the R-PRO-1 to automate on --- # Sensor Definitions -This serves as a list of all sensor definitions to help understand what each entity does for your new R-PRO-1! - -???+ info "Controls" - - **RGB Light** - - * One RGB Neopixel LED. Click on the light bulb or color wheel to change the color. Click on the toggle to turn on or off. - - **Calibrate SCD40 to 420ppm** - - * A control option to calibrate the SCD40 CO₂ sensor to outdoor baseline levels. (disabled by default) - -???+ info "Sensors" - - **CO2** - - * CO2 reading from the SCD40. This will be Unknown if you do not have the CO2 module. SDC40 can be calibrated following this guide. (disabled by default) - - **ESP Temperature** - - * This is the temperature of the internal microcontroller. Think of it like your measured CPU temp on your PC. (disabled by default) - - **Combined Presence** - - * Combined occupancy sensor. Displays `Detected` when either the LD2450 or LD2412 radar detects a target, and `Clear` when neither radar detects a target. Use this entity for automations and dashboards instead of the individual radar presence sensors. - - **LD2412 Moving Target** - - * Displays a status of "Detected" or "Clear" determined by whether the sensor identifies only a moving target. - - **LD2412 Presence** - - * Displays a status of "Detected" or "Clear" determined by whether the sensor observes a moving or stationary target. - - **LD2412 Still Target** - - * Displays a status of "Detected" or "Clear" determined by whether the sensor identifies only a still target. - - **LD2412 Detection Distance** - - * Displays the distance of the target being tracked. Known to not work properly at this time. (disabled by default) - - **LD2412 Move Energy** - - * Displays the energy of the moving target being tracked. (disabled by default) - - **LD2412 Moving Distance** - - * Displays the distance of the moving target being tracked. Known to not work properly at this time. (disabled by default) - - **LD2412 Still Distance** - - * Displays the distance of the still target being tracked. Known to not work properly at this time. (disabled by default) - - **LD2412 Still Energy** - - * Displays the energy of the still target being tracked. (disabled by default) - - **LD2450 Moving Target Count** - - * Count of all moving targets. (max 3) - - **LD2450 Presence Target Count** - - * Count of all presence targets. (max 3) - - **LD2450 Still Target Count** - - * Count of all still targets. (max 3) - - **LD2450 Target-1 Angle** - - * Angle of target in `degrees (°)` relative to the `ld2450` sensor. - - **LD2450 Target-1 Direction** - - * Direction of the target relative to the `ld2450` sensor. Possible values are: `Stationary`, `Moving away`, `Approaching`, `NA`. - - **LD2450 Target-1 Distance** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **LD2450 Target-1 Resolution** - - * The `ld2450` target detection range resolution in `millimeter (mm)`. (disabled by default) - - **LD2450 Target-1 Speed** - - * Speed of the moving target in `mm/s`. - - **LD2450 Target-1 X** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **LD2450 Target-1 Y** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor in the Y direction (near/far). The `ld2450` module can detect targets from 0 to 6000 mm in `Y` direction. - - **LD2450 Target-2 Angle** - - * Angle of target in `degrees (°)` relative to the `ld2450` sensor. - - **LD2450 Target-2 Direction** - - * Direction of the target relative to the `ld2450` sensor. Possible values are: `Stationary`, `Moving away`, `Approaching`, `NA`. - - **LD2450 Target-2 Distance** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **LD2450 Target-2 Resolution** - - * The `ld2450` target detection range resolution in `millimeter (mm)`. (disabled by default) - - **LD2450 Target-2 Speed** - - * Speed of the moving target in `mm/s`. - - **LD2450 Target-2 X** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **LD2450 Target-2 Y** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor in the Y direction (near/far). The `ld2450` module can detect targets from 0 to 6000 mm in `Y` direction. - - **LD2450 Target-3 Angle** - - * Angle of target in `degrees (°)` relative to the `ld2450` sensor. - - **LD2450 Target-3 Direction** - - * Direction of the target relative to the `ld2450` sensor. Possible values are: `Stationary`, `Moving away`, `Approaching`, `NA`. - - **LD2450 Target-3 Distance** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **LD2450 Target-3 Resolution** - - * The `ld2450` target detection range resolution in `millimeter (mm)`. (disabled by default) - - **LD2450 Target-3 Speed** - - * Speed of the moving target in `mm/s`. - - **LD2450 Target-3 X** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor along the X-axis (negative for left side of the sensor, positive for right side of the sensor). The `ld2450` module can detect targets from -3000 to 3000 mm in `X` direction. - - **LD2450 Target-3 Y** - - * Distance in `millimeter (mm)` of the target from the `ld2450` sensor in the Y direction (near/far). The `ld2450` module can detect targets from 0 to 6000 mm in `Y` direction. - - **LD2450 Zone-1 All Target Count** - - * Total targets detected in the zone, whether they are stationary or in motion. - - **LD2450 Zone-1 Moving Target Count** - - * Count of moving targets in the zone. - - **LD2450 Zone-1 Still Target Count** - - * Count of stationary targets in the zone. - - **LD2450 Zone-2 All Target Count** - - * Total targets detected in the zone, whether they are stationary or in motion. - - **LD2450 Zone-2 Moving Target Count** - - * Count of moving targets in the zone. - - **LD2450 Zone-2 Still Target Count** - - * Count of stationary targets in the zone. - - **LD2450 Zone-3 All Target Count** - - * Total targets detected in the zone, whether they are stationary or in motion. - - **LD2450 Zone-3 Moving Target Count** - - * Count of moving targets in the zone. - - **LD2450 Zone-3 Still Target Count** - - * Count of stationary targets in the zone. - - **LTR390 Light** - - * Light level measured in lux by LTR390. - - **LTR390 UV Index** - - * UV index measured by LTR390. - - **SCD40 Humidity** - - * Humidity reading from the optional SCD40 CO2 sensor. - - **SCD40 Temperature** - - * Temperature reading from the optional SCD40 CO2 sensor. - -???+ info "Configuration" - - **ESP Reboot** - - * Performs a restart of the sensor. - - **Firmware Type** - - * Drop-down selector with "WiFi" or "Ethernet" option. Allows you to switch between firmware without re-flashing the device manually. Once you choose the firmware you'd like to use, you then need to click the "PRESS" button next to "Firmware Update". - - **Firmware Update** - - * Button which begins the firmware update process to switch between Wi-Fi and Ethernet firmware options. Process takes around 5 minutes and the sensor reboots with the new firmware once it finishes. - - **Firmware Update** - - * Shows whether a firmware update is available. - - **LD2412 Bluetooth** - - * This allows you to turn on the LD2412 Bluetooth module. This allows you to connect to the HLK Radar Tool phone app [used for tuning](https://wiki.apolloautomation.com/products/msr2/setup/zones-hlk/). - - **LD2412 Factory Reset** - - * Sets the radar's move and still thresholds back to their original values from the manufacturer. - - **LD2412 g0-g13 Move & Still Threshold Sliders** - - * Sliders which can tune out false positives in 0.75 meter increment "gates" starting at zero meters and going up to 9 meters for the g13 slider. - - **LD2412 Max Move Distance** - - * Maximum distance gate for movement detection. Value between 2 and 13 inclusive. - - **LD2412 Max Still Distance** - - * Maximum distance gate for still detection. Value between 2 and 13 inclusive. - - **LD2412 Mode** - - * Drop-down selector for the mode for the LD2412. Choices are Normal, Engineering, or Dynamic background correction. (Defaults to normal) - - **LD2412 Timeout** - - * Time in seconds before the LD2412 Radar detection entities switch from Occupied to Clear. - - **LD2450 Bluetooth** - - * This allows you to turn on the LD2450 Bluetooth module. This allows you to connect to the HLK Radar Tool phone app [used for tuning](https://wiki.apolloautomation.com/products/msr2/setup/zones-hlk/). - - **LD2450 Factory Reset** - - * Sets the radar's move and still thresholds back to their original values from the manufacturer. - - **LD2450 Multi Target Tracking** - - * Turn on/off the Multi Target Tracking option. The initial state set based on the corresponding setting as read from LD2450 module at boot. - - **LD2450 Timeout** - - * Time in seconds before the LD2450 Radar detection entities switch from Occupied to Clear. - - **LD2450 Zone Type** - - * Drop-down of the zone detection modes. It can be set to `Disabled`, `Detection` or `Filter`. Selecting the `Disabled` option will disable zone area detection. `Detection` mode is used to detect only targets in the specified area, while `Filter` mode can be used to exclude an area from detection. - - **LD2450 Zone-1 X1** - - * Start X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **LD2450 Zone-1 X2** - - * End X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **LD2450 Zone-1 Y1** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **LD2450 Zone-1 Y2** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **LD2450 Zone-2 X1** - - * Start X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **LD2450 Zone-2 X2** - - * End X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **LD2450 Zone-2 Y1** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **LD2450 Zone-2 Y2** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **LD2450 Zone-3 X1** - - * Start X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **LD2450 Zone-3 X2** - - * End X coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the X-axis (negative for left side (-3000) of the sensor, positive for right side (3000) of the sensor). - - **LD2450 Zone-3 Y1** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **LD2450 Zone-3 Y2** - - * Start Y coordinate in `millimeter (mm)` of the zone from the `ld2450` sensor along the Y-axis, values range from 0 to 6000. - - **Reduce DB Reporting** - - * A toggle to enable or disable reduced reporting from various entities on the r-pro-1. This will make multiple entities use filters and not update their state unless a threshold is met - ultimately using less Wi-Fi airtime and less database usage in Home Assistant. - - **LD2412 Baud Rate** - - * Baud rate for LD2412 sensor to talk to the R-PRO-1. Defaults to 115200 (disabled by default) no need to ever edit this. - - **LD2412 Distance Resolution** - - * Distance Resolution for LD2412. Disabled by default. - - **LD2412 Hardware output pin level** - - * Hardware outpin pin level for LD2412. Disabled by default. - - **LD2450 Baud Rate** - - * Baud rate for LD2450 sensor to talk to the R-PRO-1. Defaults to 256000 (disabled by default) no need to ever edit this. - - **SCD40 Humidity Offset** - - * Humidity Offset fill in the blank for the optional SCD40 CO2 sensor addon. - - **SCD40 Temperature Offset** - - * Temperature Offset fill in the blank for the optional SCD40 CO2 sensor addon. - - **Radar Engineering Mode** - - * Used to enable g0-g13 threshold sliders for mmWave tuning. - - ???+ info "Radar Gate Distance Tuning and Timeout" - - ???+ example "Radar Max Move Distance" - - * Maximum distance gate for movement detection. Value between 2 and 8 inclusive - * Useful in a bathroom or other scenario where you want to avoid detection after a certain gate number (distance). - * Useful for triggering on "radar target" instead of triggering on zone 1/2/3 occupancy instead. - - ???+ example "Radar Max Still Distance " - - * Maximum distance gate for still detection. Value between 2 and 8 inclusive. Defaults to 8. - * Useful in a bathroom or other scenario where you want to avoid detection after a certain gate number (distance). - * Useful for triggering on "radar target" instead of triggering on zone 1/2/3 occupancy instead. - - ???+ info "Radar Timeout" - - The time in seconds that the radar's presence will stay high after the target is lost. - -??? info "Radar Gate Configuration" - - !!! warning "Keeping these enabled permanently is bad" - - Please toggle ld2412 Bluetooth on, configure your sensor, then turn ld2412 Bluetooth back off. Otherwise, your Wi-Fi and database could become overwhelmed with excessive traffic. - - **g0 Move Threshold** - - * Configures the movement sensitivity threshold for gate 0. - - **g0 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 0. - - **g1 Move Threshold** - - * Configures the movement sensitivity threshold for gate 1. - - **g1 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 1. - - **g2 Move Threshold** - - * Configures the movement sensitivity threshold for gate 2. - - **g2 Still Threshold** - - * Configures the stillness sensitivity threshold for for gate 2. - - **g3 Move Threshold** - - * Configures the movement sensitivity threshold for gate 3. - - **g3 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 3. - - **g4 Move Threshold** - - * Configures the movement sensitivity threshold for gate 4. - - **g4 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 4. - - **g5 Move Threshold** - - * Configures the movement sensitivity threshold for gate 5. - - **g5 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 5. - - **g6 Move Threshold** - - * Configures the movement sensitivity threshold for gate 6. - - **g6 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 6. - - **g7 Move Threshold** - - * Configures the movement sensitivity threshold for gate 7. - - **g7 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 7. - - **g8 Move Threshold** - - * Configures the movement sensitivity threshold for gate 8. - - **g8 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 8. - - **g9 Move Threshold** - - * Configures the movement sensitivity threshold for gate 8. - - **g9 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 8. - - **g10 Move Threshold** - - * Configures the movement sensitivity threshold for gate 8. - - **g10 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 8. - - **g11 Move Threshold** - - * Configures the movement sensitivity threshold for gate 8. - - **g11 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 8. - - **g12 Move Threshold** - - * Configures the movement sensitivity threshold for gate 8. - - **g12 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 8. - - **g13 Move Threshold** - - * Configures the movement sensitivity threshold for gate 8. - - **g13 Still Threshold** - - * Configures the stillness sensitivity threshold for gate 8. - -??? info "Diagnostic" - - **ESP Temperature** - - * Displays the current temperature of the ESP32 chip. (Disabled by Default) - - **LD2412 g0 move energy to g13 move energy** - - * Displays the move energy levels for gates g0 through g13 - - **LD2412 g0 move energy to g13 still energy** - - * Displays the still energy levels for gates g0 through g13 - - **Online** - - * Shows the connection status. - - **LD2412 Query Params** - - * Button to query parameters for debugging or advanced configurations. - - **LD2412 BT MAC** - - * Displays the Bluetooth MAC Address for the LD2412. (Disabled by Default) - - **LD2412 Firmware** - - * Displays the current firmware version for the LD2412 radar. (Disabled by Default) - - **LD2450 BT MAC** - - * Displays the Bluetooth MAC Address for the LD2450. (Disabled by Default) - - **LD2450 Firmware** - - * Displays the current firmware version for the LD2450 radar. (Disabled by Default) - - **LD2412 Restart Radar** - - * Button to restart the radar sensor. - - **RSSI** - - * Displays the Wi-Fi signal strength. - - **Uptime** - - * Shows the time since last reboot. - -[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } \ No newline at end of file +Once added to Home Assistant you can configure different settings for your R-PRO-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +The R-PRO-1 pairs two radars: an **LD2450** that tracks the position of up to three targets and reports zone occupancy, and an **LD2412** that handles presence and per-gate sensitivity tuning. It also carries an LTR390 light sensor and an optional SCD40 CO₂ module. + +!!! note "How often readings update" + + The **Default Update** column is how often each entity refreshes. Radar entities update in real time as targets move. The SCD40 and LTR390 sensors report every 60s. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | Four RGB Neopixel LEDs. Click the light bulb or color wheel to change the color. Use the toggle to turn them on or off. | + | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the outdoor baseline (about 420 ppm). Run it outdoors or next to an open window. | + +=== "Sensors" + + #### Air quality & light + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **CO2** | 60s | True NDIR reading from the SCD40. Shows *Unknown* if you do not have the CO₂ module. You can re-calibrate it to the outdoor baseline. | + | **SCD40 Temperature** | 60s | Temperature from the optional SCD40 module. Disabled by default. Adjusted by the **SCD40 Temperature Offset**. | + | **SCD40 Humidity** | 60s | Humidity from the optional SCD40 module. Disabled by default. Adjusted by the **SCD40 Humidity Offset**. | + | **LTR390 Light** | 60s | Ambient light level in lux from the LTR390. | + | **LTR390 UV Index** | 60s | UV index measured by the LTR390. | + + #### Combined presence + + | 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. | + + #### Radar presence (LD2412 mmWave) + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **LD2412 Presence** | real-time | Whether the LD2412 detects any target, moving or still. | + | **LD2412 Moving Target** | real-time | Whether the LD2412 detects only a moving target. | + | **LD2412 Still Target** | real-time | Whether the LD2412 detects only a still target. | + | **LD2412 Detection Distance** | real-time | Distance of the target being tracked. Disabled by default. | + | **LD2412 Moving Distance** | real-time | Distance of the moving target being tracked. Disabled by default. | + | **LD2412 Still Distance** | real-time | Distance of the still target being tracked. Disabled by default. | + | **LD2412 Move Energy** | real-time | Energy level of the moving target being tracked. Disabled by default. | + | **LD2412 Still Energy** | real-time | Energy level of the still target being tracked. Disabled by default. | + | **LD2412 Light** | real-time | Light level reported by the LD2412. Disabled by default. | + + #### Radar tracking (LD2450 mmWave) + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **LD2450 Presence** | real-time | Whether the radar currently detects any target. Great for occupancy automations. | + | **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). | + | **LD2450 Moving Target Count** | real-time | Count of all moving targets (max 3). | + | **LD2450 Still Target Count** | real-time | Count of all still targets (max 3). | + | **LD2450 Target-1 / Target-2 / Target-3 X** | real-time | Distance in mm of the target from the sensor along the X-axis (negative = left, positive = right, range -3000 to 3000). | + | **LD2450 Target-1 / Target-2 / Target-3 Y** | real-time | Distance in mm of the target from the sensor in the Y direction (near/far, range 0 to 6000). | + | **LD2450 Target-1 / Target-2 / Target-3 Speed** | real-time | Speed of the moving target in mm/s. | + | **LD2450 Target-1 / Target-2 / Target-3 Angle** | real-time | Angle of the target in degrees relative to the sensor. | + | **LD2450 Target-1 / Target-2 / Target-3 Distance** | real-time | Straight-line distance of the target from the sensor. | + | **LD2450 Target-1 / Target-2 / Target-3 Resolution** | real-time | Target detection range resolution in mm. Disabled by default. | + | **LD2450 Target-1 / Target-2 / Target-3 Direction** | real-time | Direction of the target: `Stationary`, `Moving away`, `Approaching`, or `NA`. | + | **LD2450 Zone-1 / Zone-2 / Zone-3 All Target Count** | real-time | Total targets in the zone, stationary or moving. | + | **LD2450 Zone-1 / Zone-2 / Zone-3 Moving Target Count** | real-time | Count of moving targets in the zone. | + | **LD2450 Zone-1 / Zone-2 / Zone-3 Still Target Count** | real-time | Count of stationary targets in the zone. | + +=== "Configuration" + + #### General + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Firmware Type** | WiFi / Ethernet | Switches between the Wi-Fi and Ethernet firmware without re-flashing. After picking the firmware you want, press **Firmware Update** to apply it. | + | **Reduce DB Reporting** | Off | Filters several entities so they only report when a threshold is met, using less Wi-Fi airtime and less Home Assistant database space. | + | **SCD40 Temperature Offset** | 18.86 °C | Calibration offset for the SCD40 temperature reading. Disabled by default. | + | **SCD40 Humidity Offset** | 0 % | Calibration offset for the SCD40 humidity reading. Disabled by default. | + | **SCD40 Automatic Self Calibration** | On | Lets the SCD40 self-calibrate over time against the lowest CO₂ it sees. Disabled by default. | + + #### LD2412 radar + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **LD2412 Bluetooth** | — | Toggles the LD2412's Bluetooth so you can connect with the HLK Radartool phone app for tuning. Turn it back off when finished. | + | **LD2412 Engineering Mode** | — | Enables the g00 to g13 move and still energy readouts used for mmWave tuning. | + | **LD2412 Timeout** | — | Seconds the LD2412 presence stays detected after the target is lost. | + | **LD2412 min distance gate** | — | Minimum distance gate for detection. | + | **LD2412 max distance gate** | — | Maximum distance gate for detection. | + | **LD2412 g00 to g13 move threshold** | — | Movement sensitivity threshold for each 0.75 m gate, from gate 0 (nearest) to gate 13. Raise a gate's value to tune out false motion at that distance. | + | **LD2412 g00 to g13 still threshold** | — | Stillness sensitivity threshold for each 0.75 m gate, from gate 0 (nearest) to gate 13. | + | **LD2412 Factory Reset** | — | Restores the LD2412's move and still thresholds to the manufacturer defaults. | + | **LD2412 Light Threshold** | — | Light level threshold for the LD2412. Disabled by default. | + | **LD2412 Light Function** | — | Selects how the LD2412 uses its light reading. Disabled by default. | + | **LD2412 Hardware output pin level** | — | Output pin level for the LD2412. Disabled by default. | + | **LD2412 Distance resolution** | — | Distance resolution for the LD2412. Disabled by default. | + | **LD2412 baud rate** | from module | Serial baud rate the LD2412 uses to talk to the R-PRO-1 (default 115200). Disabled by default; no need to change. | + + #### LD2450 radar + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **LD2450 Bluetooth** | — | Toggles the LD2450's Bluetooth so you can connect with the HLK Radartool phone app for tuning. Turn it back off when finished. | + | **LD2450 Multi Target Tracking** | from module | Turns multi-target tracking on or off. Initial state is read from the LD2450 at boot. Disabled by default. | + | **LD2450 Timeout** | — | Seconds the LD2450 presence stays detected after the target is lost. | + | **LD2450 Zone Type** | Disabled | Zone detection mode: `Disabled`, `Detection` (only detect targets inside the zone), or `Filter` (exclude the zone from detection). | + | **LD2450 Zone-1 / Zone-2 / Zone-3 X1, X2** | — | Start and end X coordinates of the zone in mm (-3000 left to 3000 right). | + | **LD2450 Zone-1 / Zone-2 / Zone-3 Y1, Y2** | — | Start and end Y coordinates of the zone in mm (0 to 6000). | + | **LD2450 Factory Reset** | — | Resets the LD2450 radar module to its factory settings. | + | **LD2450 Baud rate** | from module | Serial baud rate the LD2450 uses to talk to the R-PRO-1 (default 256000). Disabled by default; no need to change. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. | + | **IP Address** | on connect | The device's IP address on your network (Wi-Fi firmware). | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. Disabled by default. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + | **LD2412 Dynamic Background Correction Status** | real-time | Whether the LD2412 is running dynamic background correction. | + | **LD2412 Out Pin** | real-time | State of the LD2412 hardware output pin. Disabled by default. | + | **LD2412 Firmware** | on boot | Firmware version installed on the LD2412 radar module. Disabled by default. | + | **LD2412 BT MAC** | on boot | Bluetooth MAC address of the LD2412 radar module. Disabled by default. | + | **LD2412 g00 to g13 move energy** | real-time | Live move energy for each gate (g00 to g13), used when tuning with Engineering Mode. | + | **LD2412 g00 to g13 still energy** | real-time | Live still energy for each gate (g00 to g13), used when tuning with Engineering Mode. | + | **LD2412 Query params** | — | Queries the LD2412's current parameters for debugging or advanced setup. | + | **LD2412 Restart** | — | Restarts the LD2412 radar module. | + | **LD2412 Start Dynamic Background Correction** | — | Kicks off a dynamic background correction pass on the LD2412. | + | **LD2450 Firmware** | on boot | Firmware version installed on the LD2450 radar module. Disabled by default. | + | **LD2450 BT MAC** | on boot | Bluetooth MAC address of the LD2450 radar module. Disabled by default. | + | **LD2450 Restart** | — | Restarts the LD2450 radar module. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From ccd402124532e34fdea2ef7645cbc70c92d469d9 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:47:23 -0500 Subject: [PATCH 10/11] docs(plt1): rebuild Sensor Definitions with tabbed layout and update intervals (#910) Convert to a Controls/Sensors/Configuration/Diagnostic tab strip with tables and a Default Update column sourced from firmware (v26.3.2.1). Drop the raw ESPHome component-config dump in favor of the HA entity definitions, document the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address), and correct the Sleep Duration / 100% Water Voltage defaults. Convert the Homey mirror to a snippet so it inherits the rebuilt page. --- .../plt1/setup/plt1-sensor-definitions.md | 121 +----------- .../plt1/setup/plt1-sensor-definitions.md | 175 ++++++------------ 2 files changed, 58 insertions(+), 238 deletions(-) diff --git a/docs/homey/products/plt1/setup/plt1-sensor-definitions.md b/docs/homey/products/plt1/setup/plt1-sensor-definitions.md index ac6c2ba871..ddc94f2efd 100755 --- a/docs/homey/products/plt1/setup/plt1-sensor-definitions.md +++ b/docs/homey/products/plt1/setup/plt1-sensor-definitions.md @@ -1,120 +1 @@ -# Sensors - -#### LTR390 UV - -* **uv\_index** (*Optional*): UV index (UVI). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **uv** (*Optional*): Sensor counts for the UV sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **light** (*Optional*): Lux of ambient light (lx). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **ambient\_light** (*Optional*): Sensor counts for the Ambient light sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. Default is `"X18"`, see table below for options. -* **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. Default is `20`, see table below for options. -* **window\_correction\_factor** (*Optional*, float): Window correction factor. Use larger values when using under tinted windows. Default is `1.0`, must be `>= 1.0`. -* **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is `0x53`. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. It is recommended that the update interval is at least 1 second since updates can take up to 800ms when using a high resolution value. - -#### AHT20-F - -* **variant** (*Optional*, enum): Set the variant of the device in use. Defaults to `AHT10`. - * `AHT10` - For AHT10 devices. - * `AHT20` - For AHT20 and AHT30 devices. -* **temperature** (**Required**): The information for the temperature sensor. - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **humidity** (**Required**): The information for the humidity sensor - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. - -#### DS18B20 - -* **address** (*Optional*, int): The address of the sensor. Required if there is more than one device on the bus. -* **resolution** (*Optional*, int): An optional resolution from 9 to 12. Higher means more accurate. Defaults to the maximum for most Dallas temperature sensors: 12. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval that the sensors should be checked. Defaults to 60 seconds. -* **one\_wire\_id** (*Optional*, [1-Wire Bus](https://esphome.io/components/one_wire#one-wire)): The ID of the 1-Wire bus to use. Required if there is more than one bus. -* All other options from [Sensor](https://esphome.io/components/sensor/#config-sensor). - -# Sensor Definitions - -![](/assets/screenshot-2024-10-03-at-4-10-25-pm.png) - -![](/assets/screenshot-2024-10-03-at-2-25-47-pm.png) - -#### Controls: - -##### Accessory Power: - -* This allows you to control the power delivery to the sensor. Toggled ON sends power to the entire device. Toggled OFF only sends power to the ESP chip. When in the OFF position you will be unable turn on the LED light. - -##### RGB Light: - -* This allows you to control the RGB LED on the PLT-1. You can toggle it on or off directly from the ESPHome dashboard, which can be useful for creating visual alerts or indications related to plant health (e.g., turning green if everything is fine, red if moisture is too low, etc.). - -#### Sensors: - -##### Air Humidity: 48.73% - -* This sensor measures the relative humidity of the air surrounding your plant. Ideal humidity levels are crucial for maintaining optimal growth conditions for indoor plants. The reading here shows 48.73%, which might be within a reasonable range depending on the plant type. Too low or too high humidity can stress the plant and affect its ability to absorb nutrients and water properly. - -##### Air Temperature: 80.58°F - -* This sensor monitors the air temperature around the plant. The temperature is critical to maintaining a suitable growing environment. This current reading of 80.58°F is quite warm, which might be suitable for tropical or heat-loving plants but could be a bit high for others. The ideal temperature range depends on the plant species, and you can set automations to trigger alerts if the temperature goes beyond a specified range. - -##### LTR390 Light: 3.4 lx - -* This is the light intensity sensor, measured in lux (lx). The light sensor helps you track how much light your plant is receiving. 3.4 lux indicates that the plant is currently in low light conditions, which could be fine for shade-loving plants or indicate that it’s not receiving enough light. For sun-loving plants, you may need to increase light exposure. - -##### LTR390 UV Index: 0.00043 UVI - -* This sensor measures ultraviolet light (UV Index). UV is another aspect of the light spectrum, important for photosynthesis and general plant health. The low UV Index here indicates very minimal UV radiation, which could be acceptable for most indoor plants since they usually do not require strong UV exposure. However, some plants may benefit from higher levels of UV for robust growth. - -##### Soil Moisture: 59% - -* The soil moisture sensor measures the water content in the soil as a percentage. A reading of 59% means the soil has a moderate amount of moisture, but depending on the plant species, you may need to adjust watering. The ideal moisture level varies by plant; for instance, succulents prefer drier soil, while tropical plants may require consistently moist soil. - -##### Soil Temperature: Unknown - -* This field represents the reading from the optional soil temperature probe. It currently shows as “Unknown” because the soil temperature probe may not be connected or is not currently returning data. Soil temperature is crucial for root health and affects the plant’s ability to take up water and nutrients. This optional feature can give deeper insights into the root zone environment. - -#### Configuration: - -##### 100% Water Voltage: 1.5 - -* This setting defines the voltage that corresponds to 100% soil saturation (completely wet soil). A voltage of 1.5V is being used as the threshold for completely moist soil. This parameter can be tuned based on your plant’s needs, and it’s helpful in creating accurate alerts or automations when soil moisture is low. - -##### Dry Voltage: 2.7 - -* This value represents the voltage at which the soil is considered completely dry. A dry voltage of 2.7V indicates the sensor has defined this threshold for when your plant needs watering. Automations can be created to alert you when the voltage rises to this point, signaling that the soil is too dry. - -##### Sleep Duration: 480-720 minutes - -* This setting specifies how long the PLT-1 will remain in sleep mode between connection intervals. A 480-720 minute sleep duration is a good balance between battery life and update frequency. You can adjust this depending on how often you want the sensor to wake up and report new data. - -##### Sleep After Connecting: Enabled - -* This configuration means the PLT-1 will enter sleep mode after it finishes sending data during each connection. Enabling sleep mode helps conserve battery life, making it ideal for a battery-powered setup. This will override the Run Duration setting. Toggling this off will default to the Run Duration setting. - -##### Prevent Sleep: Enabled - -* With this option enabled, the PLT-1 will not enter sleep mode under certain conditions, ensuring continuous operation. This is useful if you want the sensor to remain active for extended periods, perhaps for monitoring changes in real-time without interruptions. - -#### Diagnostic: - -##### ESP Temperature: 89.8°F - -* The ESP module’s internal temperature is displayed here. An ESP temperature of 89.8°F could be a result of the WiFi module being continuously active. While this might not directly impact plant health, it’s useful to monitor as it can affect the accuracy of nearby temperature sensors. - -##### Status: Online - -* This confirms that the PLT-1 is currently online and connected to the WiFi network, communicating with Home Assistant. - -##### RSSI: -56 dBm - -* The Received Signal Strength Indicator (RSSI) shows the strength of the WiFi signal. A reading of -56 dBm is fairly decent, indicating that the PLT-1 has a strong enough connection to the WiFi router. Lower RSSI values (closer to zero) represent better signal strength. - -##### Uptime: 13 hours 37 minutes - -* This shows how long the PLT-1 has been running continuously since its last reboot or power-up. An uptime of 13 hours and 37 minutes indicates that the device has been stable and working for a decent period without any issues. - -## Buttons - -When looking at the PLT-1 in the below orientation, the boot button is on the left and the reset is on the right by the USB-C port - -![](/assets/plt-1-buttons.png) \ No newline at end of file +--8<-- "products/plt1/setup/plt1-sensor-definitions.md:5:" diff --git a/docs/products/plt1/setup/plt1-sensor-definitions.md b/docs/products/plt1/setup/plt1-sensor-definitions.md index 496411781b..27bd806b3e 100755 --- a/docs/products/plt1/setup/plt1-sensor-definitions.md +++ b/docs/products/plt1/setup/plt1-sensor-definitions.md @@ -2,123 +2,62 @@ title: PLT-1 Sensor Definitions description: Full list of definitions for the PLT-1 and its various sensors. --- -# Sensors - -#### LTR390 UV - -* **uv\_index** (*Optional*): UV index (UVI). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **uv** (*Optional*): Sensor counts for the UV sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **light** (*Optional*): Lux of ambient light (lx). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **ambient\_light** (*Optional*): Sensor counts for the Ambient light sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. Default is `"X18"`, see table below for options. -* **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. Default is `20`, see table below for options. -* **window\_correction\_factor** (*Optional*, float): Window correction factor. Use larger values when using under tinted windows. Default is `1.0`, must be `>= 1.0`. -* **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is `0x53`. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. It is recommended that the update interval is at least 1 second since updates can take up to 800ms when using a high resolution value. - -#### AHT20-F - -* **variant** (*Optional*, enum): Set the variant of the device in use. Defaults to `AHT10`. - * `AHT10` - For AHT10 devices. - * `AHT20` - For AHT20 and AHT30 devices. -* **temperature** (**Required**): The information for the temperature sensor. - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **humidity** (**Required**): The information for the humidity sensor - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. - -#### DS18B20 - -* **address** (*Optional*, int): The address of the sensor. Required if there is more than one device on the bus. -* **resolution** (*Optional*, int): An optional resolution from 9 to 12. Higher means more accurate. Defaults to the maximum for most Dallas temperature sensors: 12. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval that the sensors should be checked. Defaults to 60 seconds. -* **one\_wire\_id** (*Optional*, [1-Wire Bus](https://esphome.io/components/one_wire#one-wire)): The ID of the 1-Wire bus to use. Required if there is more than one bus. -* All other options from [Sensor](https://esphome.io/components/sensor/#config-sensor). - # Sensor Definitions -![](/assets/screenshot-2024-10-03-at-4-10-25-pm.png) - -![](/assets/screenshot-2024-10-03-at-2-25-47-pm.png) - -#### Controls: - -##### Accessory Power: - -* This allows you to control the power delivery to the sensor. Toggled ON sends power to the entire device. Toggled OFF only sends power to the ESP chip. When in the OFF position you will be unable turn on the LED light. - -##### RGB Light: - -* This allows you to control the RGB LED on the PLT-1. You can toggle it on or off directly from the ESPHome dashboard, which can be useful for creating visual alerts or indications related to plant health (e.g., turning green if everything is fine, red if moisture is too low, etc.). - -#### Sensors: - -##### Air Humidity: 48.73% - -* This sensor measures the relative humidity of the air surrounding your plant. Ideal humidity levels are crucial for maintaining optimal growth conditions for indoor plants. The reading here shows 48.73%, which might be within a reasonable range depending on the plant type. Too low or too high humidity can stress the plant and affect its ability to absorb nutrients and water properly. - -##### Air Temperature: 80.58°F - -* This sensor monitors the air temperature around the plant. The temperature is critical to maintaining a suitable growing environment. This current reading of 80.58°F is quite warm, which might be suitable for tropical or heat-loving plants but could be a bit high for others. The ideal temperature range depends on the plant species, and you can set automations to trigger alerts if the temperature goes beyond a specified range. - -##### LTR390 Light: 3.4 lx - -* This is the light intensity sensor, measured in lux (lx). The light sensor helps you track how much light your plant is receiving. 3.4 lux indicates that the plant is currently in low light conditions, which could be fine for shade-loving plants or indicate that it’s not receiving enough light. For sun-loving plants, you may need to increase light exposure. - -##### LTR390 UV Index: 0.00043 UVI - -* This sensor measures ultraviolet light (UV Index). UV is another aspect of the light spectrum, important for photosynthesis and general plant health. The low UV Index here indicates very minimal UV radiation, which could be acceptable for most indoor plants since they usually do not require strong UV exposure. However, some plants may benefit from higher levels of UV for robust growth. - -##### Soil Moisture: 59% - -* The soil moisture sensor measures the water content in the soil as a percentage. A reading of 59% means the soil has a moderate amount of moisture, but depending on the plant species, you may need to adjust watering. The ideal moisture level varies by plant; for instance, succulents prefer drier soil, while tropical plants may require consistently moist soil. - -##### Soil Temperature: Unknown - -* This field represents the reading from the optional soil temperature probe. It currently shows as “Unknown” because the soil temperature probe may not be connected or is not currently returning data. Soil temperature is crucial for root health and affects the plant’s ability to take up water and nutrients. This optional feature can give deeper insights into the root zone environment. - -#### Configuration: - -##### 100% Water Voltage: 1.5 - -* This setting defines the voltage that corresponds to 100% soil saturation (completely wet soil). A voltage of 1.5V is being used as the threshold for completely moist soil. This parameter can be tuned based on your plant’s needs, and it’s helpful in creating accurate alerts or automations when soil moisture is low. - -##### Dry Voltage: 2.7 - -* This value represents the voltage at which the soil is considered completely dry. A dry voltage of 2.7V indicates the sensor has defined this threshold for when your plant needs watering. Automations can be created to alert you when the voltage rises to this point, signaling that the soil is too dry. - -##### Sleep Duration: 480-720 minutes - -* This setting specifies how long the PLT-1 will remain in sleep mode between connection intervals. A 480-720 minute sleep duration is a good balance between battery life and update frequency. You can adjust this depending on how often you want the sensor to wake up and report new data. - -##### Sleep After Connecting: Enabled - -* This configuration means the PLT-1 will enter sleep mode after it finishes sending data during each connection. Enabling sleep mode helps conserve battery life, making it ideal for a battery-powered setup. This will override the Run Duration setting. Toggling this off will default to the Run Duration setting. - -##### Prevent Sleep: Enabled - -* With this option enabled, the PLT-1 will not enter sleep mode under certain conditions, ensuring continuous operation. This is useful if you want the sensor to remain active for extended periods, perhaps for monitoring changes in real-time without interruptions. - -#### Diagnostic: - -##### ESP Temperature: 89.8°F - -* The ESP module’s internal temperature is displayed here. An ESP temperature of 89.8°F could be a result of the WiFi module being continuously active. While this might not directly impact plant health, it’s useful to monitor as it can affect the accuracy of nearby temperature sensors. - -##### Status: Online - -* This confirms that the PLT-1 is currently online and connected to the WiFi network, communicating with Home Assistant. - -##### RSSI: -56 dBm - -* The Received Signal Strength Indicator (RSSI) shows the strength of the WiFi signal. A reading of -56 dBm is fairly decent, indicating that the PLT-1 has a strong enough connection to the WiFi router. Lower RSSI values (closer to zero) represent better signal strength. - -##### Uptime: 13 hours 37 minutes - -* This shows how long the PLT-1 has been running continuously since its last reboot or power-up. An uptime of 13 hours and 37 minutes indicates that the device has been stable and working for a decent period without any issues. - -## Buttons - -When looking at the PLT-1 in the below orientation, the boot button is on the left and the reset is on the right by the USB-C port - -![](/assets/plt-1-buttons.png) \ No newline at end of file +Once added to Home Assistant you can configure different settings for your PLT-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +![PLT-1 Sensor Data](/assets/screenshot-2024-10-03-at-4-10-25-pm.png) + +!!! note "How the PLT-1 sleeps" + + The PLT-1 is a battery-powered deep-sleep sensor. By default it wakes, reports its readings, then deep-sleeps for the **Sleep Duration**. When it connects to Home Assistant it waits a few seconds, sends one full set of readings, then sleeps again, unless **Prevent Sleep** is on or the device is in OTA mode. Turn **Prevent Sleep** on to keep the device awake for live readings and OTA updates (this uses much more battery). The **Default Update** column is how often each entity refreshes while the PLT-1 is awake. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | One RGB Neopixel LED. Click the light bulb or color wheel to change the color. Use the toggle to turn it on or off. Useful for visual plant-health alerts (for example, green when fine, red when soil is too dry). | + | **Accessory Power** | Controls power delivery to the sensor board. On sends power to the whole device. Off powers only the ESP chip, which also disables the RGB Light. Battery models only. | + +=== "Sensors" + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Soil Moisture** | 60s | Water content of the soil as a percentage, calculated from the soil voltage against the **100% Water Voltage** and **Dry Voltage** calibration values. Ideal range depends on the plant. | + | **Soil Temperature** | 60s | Reading from the optional DS18B20 soil temperature probe. Shows *Unknown* if no probe is connected. | + | **Air Temperature** | 60s | Air temperature around the plant from the AHT20 sensor. Adjusted by the **Air Temperature Offset**. | + | **Air Humidity** | 60s | Relative humidity of the air around the plant from the AHT20 sensor. Adjusted by the **Air Humidity Offset**. | + | **LTR390 Light** | 60s* | Ambient light level in lux. *Polls at the **LTR390 Update Interval** (60s by default). | + | **LTR390 UV Index** | 60s* | UV index measured by the LTR390. *Polls at the **LTR390 Update Interval**. | + | **Battery level** | 60s | Battery charge as a percentage, from the MAX17048 fuel gauge. Battery models only. | + | **Battery voltage** | 60s | Battery voltage from the MAX17048 fuel gauge. Battery models only. | + | **Soil ADC** | 5s | Raw soil voltage from the ADC, used to calculate **Soil Moisture**. Diagnostic, disabled by default. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **100% Water Voltage** | 1.55 | Soil voltage that corresponds to fully saturated (wet) soil. Lowers the **Soil Moisture** scale. Tune this for your plant and probe. | + | **Dry Voltage** | 2.7 | Soil voltage that corresponds to completely dry soil. Sets the point where **Soil Moisture** reads 0%. | + | **Air Temperature Offset** | 0.0 °C | Calibration offset applied to the **Air Temperature** reading. | + | **Air Humidity Offset** | 0 % | Calibration offset applied to the **Air Humidity** reading. | + | **LTR390 Update Interval** | 60 s | How often the LTR390 light and UV sensors poll (1 to 300 seconds). | + | **Sleep Duration** | 12 h (battery) / 5 min (USB) | How long the PLT-1 deep-sleeps between wake cycles. Battery models default to 12 hours; USB-powered models default to 5 minutes. | + | **Prevent Sleep** | On | Keeps the device awake instead of deep-sleeping, so it reports continuously. Required for OTA updates and live readings. Turn it off to save battery. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } From 44e2fd82b673a2fcc527d74d748794592d0cf445 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:47:27 -0500 Subject: [PATCH 11/11] docs(plt1b): rebuild Sensor Definitions with tabbed layout and update intervals (#911) Convert to a Controls/Sensors/Configuration/Diagnostic tab strip with tables and a Default Update column sourced from firmware (v26.3.2.1). Drop the raw ESPHome component-config dump in favor of the HA entity definitions, document the new firmware-version entities (Apollo Firmware Version, ESPHome Version, IP Address) and the 18650 battery sensors, and correct the Sleep Duration / 100% Water Voltage defaults. Convert the Homey mirror to a snippet so it inherits the rebuilt page. --- .../plt1b/setup/plt1b-sensor-definitions.md | 121 +----------- .../plt1b/setup/plt1b-sensor-definitions.md | 176 ++++++------------ 2 files changed, 59 insertions(+), 238 deletions(-) diff --git a/docs/homey/products/plt1b/setup/plt1b-sensor-definitions.md b/docs/homey/products/plt1b/setup/plt1b-sensor-definitions.md index ac6c2ba871..bbb783b040 100755 --- a/docs/homey/products/plt1b/setup/plt1b-sensor-definitions.md +++ b/docs/homey/products/plt1b/setup/plt1b-sensor-definitions.md @@ -1,120 +1 @@ -# Sensors - -#### LTR390 UV - -* **uv\_index** (*Optional*): UV index (UVI). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **uv** (*Optional*): Sensor counts for the UV sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **light** (*Optional*): Lux of ambient light (lx). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **ambient\_light** (*Optional*): Sensor counts for the Ambient light sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. Default is `"X18"`, see table below for options. -* **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. Default is `20`, see table below for options. -* **window\_correction\_factor** (*Optional*, float): Window correction factor. Use larger values when using under tinted windows. Default is `1.0`, must be `>= 1.0`. -* **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is `0x53`. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. It is recommended that the update interval is at least 1 second since updates can take up to 800ms when using a high resolution value. - -#### AHT20-F - -* **variant** (*Optional*, enum): Set the variant of the device in use. Defaults to `AHT10`. - * `AHT10` - For AHT10 devices. - * `AHT20` - For AHT20 and AHT30 devices. -* **temperature** (**Required**): The information for the temperature sensor. - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **humidity** (**Required**): The information for the humidity sensor - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. - -#### DS18B20 - -* **address** (*Optional*, int): The address of the sensor. Required if there is more than one device on the bus. -* **resolution** (*Optional*, int): An optional resolution from 9 to 12. Higher means more accurate. Defaults to the maximum for most Dallas temperature sensors: 12. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval that the sensors should be checked. Defaults to 60 seconds. -* **one\_wire\_id** (*Optional*, [1-Wire Bus](https://esphome.io/components/one_wire#one-wire)): The ID of the 1-Wire bus to use. Required if there is more than one bus. -* All other options from [Sensor](https://esphome.io/components/sensor/#config-sensor). - -# Sensor Definitions - -![](/assets/screenshot-2024-10-03-at-4-10-25-pm.png) - -![](/assets/screenshot-2024-10-03-at-2-25-47-pm.png) - -#### Controls: - -##### Accessory Power: - -* This allows you to control the power delivery to the sensor. Toggled ON sends power to the entire device. Toggled OFF only sends power to the ESP chip. When in the OFF position you will be unable turn on the LED light. - -##### RGB Light: - -* This allows you to control the RGB LED on the PLT-1. You can toggle it on or off directly from the ESPHome dashboard, which can be useful for creating visual alerts or indications related to plant health (e.g., turning green if everything is fine, red if moisture is too low, etc.). - -#### Sensors: - -##### Air Humidity: 48.73% - -* This sensor measures the relative humidity of the air surrounding your plant. Ideal humidity levels are crucial for maintaining optimal growth conditions for indoor plants. The reading here shows 48.73%, which might be within a reasonable range depending on the plant type. Too low or too high humidity can stress the plant and affect its ability to absorb nutrients and water properly. - -##### Air Temperature: 80.58°F - -* This sensor monitors the air temperature around the plant. The temperature is critical to maintaining a suitable growing environment. This current reading of 80.58°F is quite warm, which might be suitable for tropical or heat-loving plants but could be a bit high for others. The ideal temperature range depends on the plant species, and you can set automations to trigger alerts if the temperature goes beyond a specified range. - -##### LTR390 Light: 3.4 lx - -* This is the light intensity sensor, measured in lux (lx). The light sensor helps you track how much light your plant is receiving. 3.4 lux indicates that the plant is currently in low light conditions, which could be fine for shade-loving plants or indicate that it’s not receiving enough light. For sun-loving plants, you may need to increase light exposure. - -##### LTR390 UV Index: 0.00043 UVI - -* This sensor measures ultraviolet light (UV Index). UV is another aspect of the light spectrum, important for photosynthesis and general plant health. The low UV Index here indicates very minimal UV radiation, which could be acceptable for most indoor plants since they usually do not require strong UV exposure. However, some plants may benefit from higher levels of UV for robust growth. - -##### Soil Moisture: 59% - -* The soil moisture sensor measures the water content in the soil as a percentage. A reading of 59% means the soil has a moderate amount of moisture, but depending on the plant species, you may need to adjust watering. The ideal moisture level varies by plant; for instance, succulents prefer drier soil, while tropical plants may require consistently moist soil. - -##### Soil Temperature: Unknown - -* This field represents the reading from the optional soil temperature probe. It currently shows as “Unknown” because the soil temperature probe may not be connected or is not currently returning data. Soil temperature is crucial for root health and affects the plant’s ability to take up water and nutrients. This optional feature can give deeper insights into the root zone environment. - -#### Configuration: - -##### 100% Water Voltage: 1.5 - -* This setting defines the voltage that corresponds to 100% soil saturation (completely wet soil). A voltage of 1.5V is being used as the threshold for completely moist soil. This parameter can be tuned based on your plant’s needs, and it’s helpful in creating accurate alerts or automations when soil moisture is low. - -##### Dry Voltage: 2.7 - -* This value represents the voltage at which the soil is considered completely dry. A dry voltage of 2.7V indicates the sensor has defined this threshold for when your plant needs watering. Automations can be created to alert you when the voltage rises to this point, signaling that the soil is too dry. - -##### Sleep Duration: 480-720 minutes - -* This setting specifies how long the PLT-1 will remain in sleep mode between connection intervals. A 480-720 minute sleep duration is a good balance between battery life and update frequency. You can adjust this depending on how often you want the sensor to wake up and report new data. - -##### Sleep After Connecting: Enabled - -* This configuration means the PLT-1 will enter sleep mode after it finishes sending data during each connection. Enabling sleep mode helps conserve battery life, making it ideal for a battery-powered setup. This will override the Run Duration setting. Toggling this off will default to the Run Duration setting. - -##### Prevent Sleep: Enabled - -* With this option enabled, the PLT-1 will not enter sleep mode under certain conditions, ensuring continuous operation. This is useful if you want the sensor to remain active for extended periods, perhaps for monitoring changes in real-time without interruptions. - -#### Diagnostic: - -##### ESP Temperature: 89.8°F - -* The ESP module’s internal temperature is displayed here. An ESP temperature of 89.8°F could be a result of the WiFi module being continuously active. While this might not directly impact plant health, it’s useful to monitor as it can affect the accuracy of nearby temperature sensors. - -##### Status: Online - -* This confirms that the PLT-1 is currently online and connected to the WiFi network, communicating with Home Assistant. - -##### RSSI: -56 dBm - -* The Received Signal Strength Indicator (RSSI) shows the strength of the WiFi signal. A reading of -56 dBm is fairly decent, indicating that the PLT-1 has a strong enough connection to the WiFi router. Lower RSSI values (closer to zero) represent better signal strength. - -##### Uptime: 13 hours 37 minutes - -* This shows how long the PLT-1 has been running continuously since its last reboot or power-up. An uptime of 13 hours and 37 minutes indicates that the device has been stable and working for a decent period without any issues. - -## Buttons - -When looking at the PLT-1 in the below orientation, the boot button is on the left and the reset is on the right by the USB-C port - -![](/assets/plt-1-buttons.png) \ No newline at end of file +--8<-- "products/plt1b/setup/plt1b-sensor-definitions.md:5:" diff --git a/docs/products/plt1b/setup/plt1b-sensor-definitions.md b/docs/products/plt1b/setup/plt1b-sensor-definitions.md index 4f7952ece1..7cf035427c 100755 --- a/docs/products/plt1b/setup/plt1b-sensor-definitions.md +++ b/docs/products/plt1b/setup/plt1b-sensor-definitions.md @@ -2,123 +2,63 @@ title: PLT-1B Sensor Definitions description: Full list of definitions for the PLT-1B and its various sensors. --- -# Sensors - -#### LTR390 UV - -* **uv\_index** (*Optional*): UV index (UVI). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **uv** (*Optional*): Sensor counts for the UV sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **light** (*Optional*): Lux of ambient light (lx). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **ambient\_light** (*Optional*): Sensor counts for the Ambient light sensor (#). All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. Default is `"X18"`, see table below for options. -* **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. Default is `20`, see table below for options. -* **window\_correction\_factor** (*Optional*, float): Window correction factor. Use larger values when using under tinted windows. Default is `1.0`, must be `>= 1.0`. -* **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is `0x53`. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. It is recommended that the update interval is at least 1 second since updates can take up to 800ms when using a high resolution value. - -#### AHT20-F - -* **variant** (*Optional*, enum): Set the variant of the device in use. Defaults to `AHT10`. - * `AHT10` - For AHT10 devices. - * `AHT20` - For AHT20 and AHT30 devices. -* **temperature** (**Required**): The information for the temperature sensor. - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **humidity** (**Required**): The information for the humidity sensor - * All options from [Sensor](https://esphome.io/components/sensor/#config-sensor). -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `60s`. - -#### DS18B20 - -* **address** (*Optional*, int): The address of the sensor. Required if there is more than one device on the bus. -* **resolution** (*Optional*, int): An optional resolution from 9 to 12. Higher means more accurate. Defaults to the maximum for most Dallas temperature sensors: 12. -* **update\_interval** (*Optional*, [Time](https://esphome.io/guides/configuration-types#config-time)): The interval that the sensors should be checked. Defaults to 60 seconds. -* **one\_wire\_id** (*Optional*, [1-Wire Bus](https://esphome.io/components/one_wire#one-wire)): The ID of the 1-Wire bus to use. Required if there is more than one bus. -* All other options from [Sensor](https://esphome.io/components/sensor/#config-sensor). - # Sensor Definitions -![](/assets/screenshot-2024-10-03-at-4-10-25-pm.png) - -![](/assets/screenshot-2024-10-03-at-2-25-47-pm.png) - -#### Controls: - -##### Accessory Power: - -* This allows you to control the power delivery to the sensor. Toggled ON sends power to the entire device. Toggled OFF only sends power to the ESP chip. When in the OFF position you will be unable turn on the LED light. - -##### RGB Light: - -* This allows you to control the RGB LED on the PLT-1. You can toggle it on or off directly from the ESPHome dashboard, which can be useful for creating visual alerts or indications related to plant health (e.g., turning green if everything is fine, red if moisture is too low, etc.). - -#### Sensors: - -##### Air Humidity: 48.73% - -* This sensor measures the relative humidity of the air surrounding your plant. Ideal humidity levels are crucial for maintaining optimal growth conditions for indoor plants. The reading here shows 48.73%, which might be within a reasonable range depending on the plant type. Too low or too high humidity can stress the plant and affect its ability to absorb nutrients and water properly. - -##### Air Temperature: 80.58°F - -* This sensor monitors the air temperature around the plant. The temperature is critical to maintaining a suitable growing environment. This current reading of 80.58°F is quite warm, which might be suitable for tropical or heat-loving plants but could be a bit high for others. The ideal temperature range depends on the plant species, and you can set automations to trigger alerts if the temperature goes beyond a specified range. - -##### LTR390 Light: 3.4 lx - -* This is the light intensity sensor, measured in lux (lx). The light sensor helps you track how much light your plant is receiving. 3.4 lux indicates that the plant is currently in low light conditions, which could be fine for shade-loving plants or indicate that it’s not receiving enough light. For sun-loving plants, you may need to increase light exposure. - -##### LTR390 UV Index: 0.00043 UVI - -* This sensor measures ultraviolet light (UV Index). UV is another aspect of the light spectrum, important for photosynthesis and general plant health. The low UV Index here indicates very minimal UV radiation, which could be acceptable for most indoor plants since they usually do not require strong UV exposure. However, some plants may benefit from higher levels of UV for robust growth. - -##### Soil Moisture: 59% - -* The soil moisture sensor measures the water content in the soil as a percentage. A reading of 59% means the soil has a moderate amount of moisture, but depending on the plant species, you may need to adjust watering. The ideal moisture level varies by plant; for instance, succulents prefer drier soil, while tropical plants may require consistently moist soil. - -##### Soil Temperature: Unknown - -* This field represents the reading from the optional soil temperature probe. It currently shows as “Unknown” because the soil temperature probe may not be connected or is not currently returning data. Soil temperature is crucial for root health and affects the plant’s ability to take up water and nutrients. This optional feature can give deeper insights into the root zone environment. - -#### Configuration: - -##### 100% Water Voltage: 1.5 - -* This setting defines the voltage that corresponds to 100% soil saturation (completely wet soil). A voltage of 1.5V is being used as the threshold for completely moist soil. This parameter can be tuned based on your plant’s needs, and it’s helpful in creating accurate alerts or automations when soil moisture is low. - -##### Dry Voltage: 2.7 - -* This value represents the voltage at which the soil is considered completely dry. A dry voltage of 2.7V indicates the sensor has defined this threshold for when your plant needs watering. Automations can be created to alert you when the voltage rises to this point, signaling that the soil is too dry. - -##### Sleep Duration: 480-720 minutes - -* This setting specifies how long the PLT-1 will remain in sleep mode between connection intervals. A 480-720 minute sleep duration is a good balance between battery life and update frequency. You can adjust this depending on how often you want the sensor to wake up and report new data. - -##### Sleep After Connecting: Enabled - -* This configuration means the PLT-1 will enter sleep mode after it finishes sending data during each connection. Enabling sleep mode helps conserve battery life, making it ideal for a battery-powered setup. This will override the Run Duration setting. Toggling this off will default to the Run Duration setting. - -##### Prevent Sleep: Enabled - -* With this option enabled, the PLT-1 will not enter sleep mode under certain conditions, ensuring continuous operation. This is useful if you want the sensor to remain active for extended periods, perhaps for monitoring changes in real-time without interruptions. - -#### Diagnostic: - -##### ESP Temperature: 89.8°F - -* The ESP module’s internal temperature is displayed here. An ESP temperature of 89.8°F could be a result of the WiFi module being continuously active. While this might not directly impact plant health, it’s useful to monitor as it can affect the accuracy of nearby temperature sensors. - -##### Status: Online - -* This confirms that the PLT-1 is currently online and connected to the WiFi network, communicating with Home Assistant. - -##### RSSI: -56 dBm - -* The Received Signal Strength Indicator (RSSI) shows the strength of the WiFi signal. A reading of -56 dBm is fairly decent, indicating that the PLT-1 has a strong enough connection to the WiFi router. Lower RSSI values (closer to zero) represent better signal strength. - -##### Uptime: 13 hours 37 minutes - -* This shows how long the PLT-1 has been running continuously since its last reboot or power-up. An uptime of 13 hours and 37 minutes indicates that the device has been stable and working for a decent period without any issues. - -## Buttons - -When looking at the PLT-1 in the below orientation, the boot button is on the left and the reset is on the right by the USB-C port - -![](/assets/plt-1-buttons.png) \ No newline at end of file +Once added to Home Assistant you can configure different settings for your PLT-1B. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +![PLT-1B Sensor Data](/assets/screenshot-2024-10-03-at-4-10-25-pm.png) + +!!! note "How often readings update" + + The **Default Update** column is how often each sensor refreshes while the PLT-1B is awake. The PLT-1B is the 18650-battery variant, so by default it deep-sleeps to save power. By default **Prevent Sleep** is on, which keeps the device awake and reporting continuously at these intervals. If you turn **Prevent Sleep** off, the PLT-1B wakes for about 90 seconds, reports its readings, then deep-sleeps for the **Sleep Duration** before waking again. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **RGB Light** | One RGB Neopixel LED. Click the light bulb or color wheel to change the color. Use the toggle to turn it on or off. Useful for visual alerts tied to plant health, such as green when readings are fine and red when moisture is low. | + | **Accessory Power** | Controls power delivery to the sensors. On sends power to the whole device. Off powers only the ESP chip, and while off you cannot turn on the RGB Light. | + +=== "Sensors" + + | Sensor | Default Update | Details | + |--------|:--------------:|---------| + | **Air Temperature** | 60s | Air temperature around the plant, from the AHT20. Adjusted by the **Air Temperature Offset**. | + | **Air Humidity** | 60s | Relative humidity of the air around the plant, from the AHT20. Adjusted by the **Air Humidity Offset**. | + | **Soil Moisture** | 60s | Water content of the soil as a percentage, calculated from the soil probe voltage using the **100% Water Voltage** and **Dry Voltage** calibration values. | + | **Soil Temperature** | 60s | Reading from the optional DS18B20 soil temperature probe. Shows *Unknown* if the probe is not connected. | + | **LTR390 Light** | 60s* | Ambient light level in lux. *Polls at the interval set by the **LTR390 Update Interval** number (60s by default). | + | **LTR390 UV Index** | 60s* | UV index measured by the LTR390. *Polls at the **LTR390 Update Interval**. | + | **Battery level** | on wake | Remaining 18650 battery charge as a percentage, from the MAX17048 fuel gauge. | + | **Battery voltage** | on wake | Current 18650 battery voltage, from the MAX17048 fuel gauge. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **ESP Reboot** | — | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Air Temperature Offset** | 0.0 °C | Calibrates the AHT20 air temperature reading to a known value. Range is -70 to 70 °C in 0.1 steps. | + | **Air Humidity Offset** | 0 % | Calibrates the AHT20 air humidity reading to a known value. Range is -70 to 70 % in 0.1 steps. | + | **100% Water Voltage** | 1.55 | Soil probe voltage that corresponds to fully saturated (100% wet) soil. Tune this to calibrate the **Soil Moisture** reading. Range is 0 to 5 V in 0.01 steps. | + | **Dry Voltage** | 2.7 | Soil probe voltage that corresponds to completely dry soil. Tune this to calibrate the **Soil Moisture** reading and to trigger low-moisture automations. Range is 0 to 5 V in 0.01 steps. | + | **LTR390 Update Interval** | 60 s | How often the LTR390 light and UV sensors poll (1 to 300 seconds). | + | **Sleep Duration** | 12 h | How long the PLT-1B stays in deep sleep between wake cycles (only used when **Prevent Sleep** is off). Range is 0 to 800 hours. | + | **Prevent Sleep** | On | Keeps the device awake instead of deep-sleeping, so it reports continuously. Required for OTA updates and live readings; turn it off to save battery. | + | **Accessory Power** | On | Powers the sensors. Turn off to power only the ESP chip. | + | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. | + +=== "Diagnostic" + + | Entity | Default Update | What it shows | + |--------|:--------------:|---------------| + | **Apollo Firmware Version** | on boot | The Apollo firmware build installed on the device (for example, `26.3.2.1`). | + | **ESPHome Version** | on boot | The ESPHome version the firmware was compiled with. | + | **Firmware Update** | — | Shows whether a firmware update is available and lets you update from inside Home Assistant. | + | **IP Address** | on connect | The device's IP address on your network. | + | **Online** | on change | Connection status of the device to Home Assistant. | + | **RSSI** | 60s | Wi-Fi signal strength in dBm. Values closer to 0 are stronger; a weak signal can affect reliability. | + | **ESP Temperature** | 60s | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. | + | **Uptime** | 60s | How long the device has been running since its last reboot. | + | **Soil ADC** | 5s | Raw soil probe voltage used to calculate **Soil Moisture**. Disabled by default. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button }