mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-11-05 09:20:08 +01:00
195 lines
6.9 KiB
ReStructuredText
195 lines
6.9 KiB
ReStructuredText
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
|
|
|
|
binary_sensor:
|
|
- platform: gpio
|
|
pin: GPIO21
|
|
name: "Radar motion"
|
|
|
|
switch:
|
|
# Switch to turn on/off RF emission
|
|
- platform: at581x
|
|
at581x_id: "Radar"
|
|
name: "Enable Radar"
|
|
|
|
.. _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: GPIO21
|
|
|
|
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`
|