-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation for new Qwiic PIR binary sensor component (#3106)
- Loading branch information
Showing
4 changed files
with
73 additions
and
0 deletions.
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,72 @@ | ||
Qwiic PIR Motion Binary Sensor | ||
============================== | ||
|
||
.. seo:: | ||
:description: Instructions for setting up the Qwiic PIR Motion binary sensor. | ||
:image: qwiic_pir.jpg | ||
|
||
The Qwiic PIR Motion binary sensor allows you to use your Qwiic PIR (`EKMC4607112K based <https://www.sparkfun.com/products/17374>`__, `EKMB1107112 based <https://www.sparkfun.com/products/17375>`__, `firmware documentation <https://github.com/sparkfun/Qwiic_PIR>`__) | ||
sensors from SparkFun with ESPHome. | ||
|
||
.. figure:: images/qwiic_pir.jpg | ||
:align: center | ||
:width: 30.0% | ||
|
||
SparkFun Qwiic PIR sensor. | ||
(Credit: `Sparkfun <https://www.sparkfun.com/products/17374>`__, image cropped and compressed) | ||
|
||
.. _Sparkfun: https://www.sparkfun.com/products/17374 | ||
|
||
The SparkFun Qwiic PIR Motion binary sensor uses PIR sensors to detect motion. It communicates over I²C. There are two models currently available. One uses the `Panasonic EKMC4607112K sensor <https://cdn.sparkfun.com/assets/7/2/a/4/3/EKMC460711xK_Spec.pdf>`__, and the other uses the `Panasonic EKMB1107112 sensor <https://cdn.sparkfun.com/assets/c/e/8/7/5/EKMB110711x_Spec.pdf>`__. | ||
|
||
You can configure a debounce mode to reduce noise and false detections. See :ref:`debounce-modes` for the available options. | ||
|
||
To use the sensor, first set up an :ref:`I²C Bus <i2c>` and connect the sensor to the specified pins. | ||
|
||
.. code-block:: yaml | ||
# Example configuration entry | ||
binary_sensor: | ||
- platform: qwiic_pir | ||
name: "Qwiic PIR Motion Sensor" | ||
Configuration variables: | ||
------------------------ | ||
|
||
- **debounce_mode** (*Optional*, enum): How the component debounces the motion sensor's signal. Must be one of ``HYBRID``, ``NATIVE``, or ``RAW``. See :ref:`debounce-modes` for details. Defaults to ``HYBRID``. | ||
- **debounce** (*Optional*, :ref:`config-time`): Only valid when using ``NATIVE`` debounce mode. Configures the debounce time on the sensor to reduce noise and false detections. Defaults to ``1ms``. | ||
|
||
- All other options from :ref:`Binary Sensor <config-binary_sensor>`. | ||
|
||
.. _debounce-modes: | ||
|
||
Debounce Modes | ||
************** | ||
|
||
There are three options for ``debounce_mode``. | ||
|
||
- ``HYBRID``: | ||
|
||
- Use a combination of the raw sensor reading and the sensor's native event detection to determine state. | ||
- Very reliable for detecting both object's being detected and no longer detected. | ||
- Use binary sensor filters to reduce noise and false detections. | ||
|
||
- ``NATIVE``: | ||
|
||
- Use the sensor's native event detection to debounce the signal. | ||
- Logic follows `SparkFun's reference example implementation <https://github.com/sparkfun/SparkFun_Qwiic_PIR_Arduino_Library/blob/master/examples/Example2_PrintPIRStatus/Example2_PrintPIRStatus.ino>`__. | ||
- May be unreliable at detecting when an object is removed, especially at high debounce rates. | ||
- Binary sensor filters are not necessary to reduce noise and false detections. | ||
|
||
- ``RAW``: | ||
|
||
- Use the raw state of the PIR sensor as reported by the firmware. | ||
- May miss a very short motion detection events if ESPHome's loop time is slow. | ||
- Use binary sensor filters to reduce noise and false detections. | ||
|
||
See Also | ||
-------- | ||
- :doc:`/components/binary_sensor/index` | ||
- :apiref:`qwiic_pir/qwiic_pir.h` | ||
- `SparkFun Qwiic PIR Library <https://github.com/sparkfun/SparkFun_Qwiic_PIR_Arduino_Library>`__ by `SparkFun <https://www.sparkfun.com/>`__ | ||
- :ghedit:`Edit` |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters