Add documentation for AT581x Radar component (#3646)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
parent
7263d0b157
commit
9af1575411
|
@ -0,0 +1,194 @@
|
|||
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`
|
Binary file not shown.
After Width: | Height: | Size: 17 KiB |
|
@ -517,6 +517,7 @@ Presence Detection
|
|||
.. imgtable::
|
||||
|
||||
DFRobot mmWave Radar, components/dfrobot_sen0395, dfrobot_sen0395.jpg
|
||||
AT581X, components/at581x, at581x.png
|
||||
LD2410, components/sensor/ld2410, ld2410.jpg
|
||||
LD2420, components/sensor/ld2420, ld2420.jpg
|
||||
Seeed Studio MR24HPC1 mmWave, components/seeed_mr24hpc1, seeed-mr24hpc1.jpg
|
||||
|
|
Loading…
Reference in New Issue