diff --git a/components/binary_sensor/images/qwiic_pir.jpg b/components/binary_sensor/images/qwiic_pir.jpg new file mode 100644 index 000000000..866fe14e0 Binary files /dev/null and b/components/binary_sensor/images/qwiic_pir.jpg differ diff --git a/components/binary_sensor/qwiic_pir.rst b/components/binary_sensor/qwiic_pir.rst new file mode 100644 index 000000000..6980c65a9 --- /dev/null +++ b/components/binary_sensor/qwiic_pir.rst @@ -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 `__, `EKMB1107112 based `__, `firmware documentation `__) +sensors from SparkFun with ESPHome. + +.. figure:: images/qwiic_pir.jpg + :align: center + :width: 30.0% + + SparkFun Qwiic PIR sensor. + (Credit: `Sparkfun `__, 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 `__, and the other uses the `Panasonic EKMB1107112 sensor `__. + +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 ` 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 `. + +.. _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 `__. + - 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 `__ by `SparkFun `__ +- :ghedit:`Edit` diff --git a/images/qwiic_pir.jpg b/images/qwiic_pir.jpg new file mode 100644 index 000000000..f35eb3069 Binary files /dev/null and b/images/qwiic_pir.jpg differ diff --git a/index.rst b/index.rst index c9e02d42a..0399f4675 100644 --- a/index.rst +++ b/index.rst @@ -499,6 +499,7 @@ Miscellaneous LD2410, components/sensor/ld2410, ld2410.jpg Modbus Binary Sensor, components/binary_sensor/modbus_controller, modbus.png PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg + Qwiic PIR Motion, components/binary_sensor/qwiic_pir, qwiic_pir.jpg Remote Receiver, components/remote_receiver, remote.svg, dark-invert Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg Tuya Binary Sensor, components/binary_sensor/tuya, tuya.png