esphome-docs/components/at581x.rst

AirTouch AT581x Radar
=====================

.. seo::
    :description: Instructions for setting up AirTouch AT581x Radar
    :image: at581x.png
    :keywords: radar

The `AirTouch AT581x radar <https://en.airtouching.com/product/32.html>`__
(aka ``AT581x``) is a familly of 5.8GHz radar which can be used for human presence detection. It can detect tiny movements
and compared to a PIR sensor **it can detect presence continuously**. This can be useful, for example, to turn
the lights on when you enter a room, keep them on as long as you are there (without waving your hands at the
sensor) and turn them off almost immediately after you leave the room.

They are ultra-low power (as low as 40µA of current consumption) and are extremely simple to use, yet can be setup by I2C.
It's installed in many low cost appliance, like the ESP32S3-BOX-3, and can be found by many different manufacturer or reference,
like the MoreSense MS58-3909S68U4.

It is possible to use this sensor with only a single GPIO pin; however, if you wish to change its settings,
a :doc:`/components/i2c` component (and its requisite GPIO pins) is required in your device's configuration.

.. figure:: ../images/at581x.png
    :align: center
    :width: 75%

    AirTouch AT581x Radar / presence detection sensor

.. code-block:: yaml

    # Example configuration entry
    at581x:
      id: "Radar"
      i2c_id: bus_a

.. _at581x-component:

Component/Hub
-------------

You need to have the hub component (``at581x:`` entry) defined to be able to change the sensor's
settings, get it listed as an motion entity or being able to turn on/off the radio frequency emmission.
A :doc:`/components/binary_sensor/gpio` alone could be sufficient if you only want
to determine presence/occupancy. When you define ``at581x:`` you'll need to have a ``i2c:`` entry in
your configuration with both the SDA and SCL pins defined.

Multiple instances of this component may be defined if multiple :doc:`/components/i2c` components are available:

.. code-block:: yaml

    at581x:
      - id: mmWave_1
        i2c_id: bus_a
        address: 0x28
      - id: mmWave_2
        i2c_id: bus_a
        address: 0x29
      ...

Configuration variables:
************************

- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Necessary if you want
  to define multiple instances of this component.
- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :doc:`/components/i2c` if you want
  to use multiple I2C buses.

.. _at581x-binary_sensor:

Binary Sensor
-------------

The state of the radar detection is available via its GPIO pin. It's required to use a GPIO binary sensor to monitor the motion status

.. code-block:: yaml

    binary_sensor:
      - platform: gpio
        name: "Human in front"
        pin: GPIOXX

Configuration variables:
************************

- Refer to other options from :ref:`Binary Sensor <config-binary_sensor>` and :doc:`GPIO Binary Sensor </components/binary_sensor/gpio>`.

.. _at581x-switch:

Switch
------

:ref:`Switch components <config-switch>` are used to enable/disable radio frequency hardware.

.. code-block:: yaml

    switch:
      - platform: at581x
        at581x_id: Radar
        name: "Enable Radar"

Configuration variables:
************************

- **at581x_id** (*Optional*, :ref:`config-id`): The ID of the AT581x component defined above.
  Required when multiple instances of the ``at581x`` component are defined.
- All other options from :ref:`Switch <config-switch>`.

.. _at581x-actions:

Actions
-------

.. _at581x-action_settings:

``at581x.settings`` Action
**************************

.. warning::

    The hardware frontend reset option is only required to reset the frontend in case it is struck, before sending the
    new configuration. However, a frontend reset is always performed after changing the settings.

The radar has several settings which can be changed. These settings are not saved in non-volatile memory
and need to be set on each boot.

The settings action allows changing of any number of the radar's internal parameters/settings. With this
action, any unspecified parameters will remain unchanged.

.. code-block:: yaml

    on_...:
      - at581x.settings:
          id: "Waveradar"
          hw_frontend_reset: false
          frequency: 5800MHz
          sensing_distance: 200 # 0-1023
          poweron_selfcheck_time: 2000ms
          protect_time: 1s
          trigger_base: 500ms
          trigger_keep: 10s
          stage_gain: 3 # 0-12 the higher the value the smaller the gain
          power_consumption: 70µA


Configuration variables:
````````````````````````

- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the sensor on which settings should be
  changed. If only one radar is defined, this is optional.
- **hw_frontend_reset** (*Optional*, boolean): If set to true, a reset of the analog frontend will be performed before
  changing other options. Ignored if not set or set to ``false``. Upon applying the settings a frontend reset
  will be performed anyway, this is only useful if the sensor is not answering or locked up.
- **frequency** (*Optional*, int): Any of the possible frequencies (5696, 5715, 5730, 5748, 5765, 5784, 5800, 5819, 5836, 5851, 5869, 5888) in MHz.
- **sensing_distance** (*Optional*, int): A unitless number, in range 0-1023, specifying the maximum distance to detect motion
- **poweron_selfcheck_time** (*Optional*, int): The delay to perform self check and calibration on power on. Recommanded not to change this
- **protect_time** (*Optional*, int): The delay after an end-of-trigger event where the detection will not trigger anymore. Max 65535ms
- **trigger_base** (*Optional*, int): The delay while a detection must be active to change the state of the sensor. Max 65535ms
- **trigger_keep** (*Optional*, int): The delay that the output will stay high after a detection event. This is usually what you want to change.
- **stage_gain** (*Optional*, int): The analog gain to use for threshold test. Any value in range 0-12, with 12 being the lowest gain and 0 the highest
- **power_consumption** (*Optional*, int): Any of the possible power profile (48, 56, 63, 70, 77, 91, 105, 115, 40, 44, 47, 51, 54, 61, 68, 78) in µA


``at581x.reset`` Action
***********************

Restart the sensor.

.. code-block:: yaml

    on_...:
      at581x.reset:

Configuration variables:
````````````````````````

- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the AT581x component. Useful when multiple instances of this component are defined.

See Also
--------
- :ref:`I2C bus <i2c>`
- :ref:`Binary Sensor <config-binary_sensor>`
- :doc:`GPIO Binary Sensor </components/binary_sensor/gpio>`
- :ref:`config-id`
- :ghedit:`Edit`