feat: add documentation for AS5600 (#3304)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
Branden Cash 2023-12-20 17:07:49 -07:00 committed by GitHub
parent 863a9388c9
commit 1b497bfa82
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 304 additions and 0 deletions

View File

@ -0,0 +1,303 @@
AS5600 12-Bit Magnetic Position Sensor
======================================
.. seo::
:description: Instructions for setting up AS5600 magnetic position sensor / encoder.
:image: as5600.jpg
:keywords: AS5600 AS5600L
.. _as5600-component:
Component/Hub
-------------
The ``as5600`` sensor platform you to use your AS5600 (`datasheet <https://ams.com/documents/20143/36005/AS5600_DS000365_5-00.pdf/649ee61c-8f9a-20df-9e10-43173a3eb323>`__,
`AMS <https://ams.com/en/as5600>`__) or AS5600L (`datasheet <https://ams.com/documents/20143/36005/AS5600L_DS000545_3-00.pdf/7ade6878-7a32-2294-b88d-479d50fab6de>`__,
`AMS <https://ams.com/en/as5600l>`__) 12-bit magnetic position sensor with ESPHome. Individual sensors will be added
using the :ref:`AS5600 Sensor Platform <as5600-sensor>`. To use this hub, first setup
the :ref:`I²C Bus <i2c>` and connect the sensor to the pins specified there.
.. figure:: images/as5600-full.jpg
:align: center
:width: 50.0%
AS5600 12-Bit Magnetic Position Sensor.
.. _AMS_AS5600: https://ams.com/en/as5600
.. _AMS_AS5600L: https://ams.com/en/as5600l
.. code-block:: yaml
as5600:
dir_pin: 22
start_position: 0deg
range: 180deg
Configuration variables:
************************
- **dir_pin** (*Optional*, int): The pin connected to the AS5600's direction pin.
See :ref:`Direction <as5600_direction>` for more information.
- **direction** (*Optional*, string): The direction that the magnet should rotate to increase values.
Used in combination with the **dir_pin**.
- ``clockwise`` (default)
- ``counterclockwise``
- **start_position** (*Optional*, int): The raw position that should be considered the start (i.e. ``0``).
See :ref:`Position / Range <as5600_position_range>`.
- **end_position** (*Optional*, int): The raw position that should be considered the end (e.g. 180deg)
of the allowable rotation range. Mutually exclusive with **range**. See :ref:`Position / Range <as5600_position_range>`.
- **range** (*Optional*, int): The allowable rotation range from the **start_position**. Mutually
exclusive with **end_position**. See :ref:`Position / Range <as5600_position_range>`.
- **hysteresis** (*Optional*, string): See datasheet.
- ``none`` (default)
- ``lsb1``
- ``lsb2``
- ``lsb3``
- **power_mode** (*Optional*, string): The power mode to run the sensor. Note: When **watchdog** is enabled,
it will switch the device to ``low3`` when there is not much change in position.
- ``nominal`` (default)
- ``low1``
- ``low2``
- ``low3``
- **watchdog** (*Optional*, boolean): Whether to enable the watchdog that puts the the chip in to
low power mode 3. Check the datasheet for more information.
Defaults to ``off``.
- **slow_filter** (*Optional*, string): See datasheet.
- ``16x`` (default)
- ``8x``
- ``4x``
- ``2x``
- **fast_filter** (*Optional*, string): See datasheet.
- ``none`` (default)
- ``lsb6``
- ``lsb7``
- ``lsb9``
- ``lsb18``
- ``lsb21``
- ``lsb24``
- ``lsb10``
- **address** (*Optional*, int): The i²c address of the sensor.
See :ref:`I²C Addresses <as5600_i2c_addresses>` for more information.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this AS5600 Hub.
- All other options for I²C devices described at :ref:`I²C Bus <i2c>`.
.. _as5600_direction:
Direction
---------
The AS5600 has ``direction`` pin that controls which rotation direction will cause the position value to **increase**.
This pin should be pulled low for clockwise, and pulled high for counterclockwise. If left floating, you are likely
to encounter erratic behavior.
If you would like the ESP controller to pull that pin high or low, you may configure the ``dir_pin`` and optionally, the
``direction`` option to have the ESP controller pull the pin high or low.
.. _as5600_position_range:
Position / Range
----------------
.. figure:: images/as5600-magnet-position.png
:align: center
:width: 80.0%
Position and range may be configured as one of the following:
- a value between ``-4095`` and ``4095``
- an angle between ``-360deg`` and ``360deg``
- a percentage between ``-100%`` and ``100%``
.. note::
Negative position values will be normalized to their respective positive position (e.g. -90deg would translate to 270deg).
The AS5600 reports 2 position values. The value for both types of position values will always be a whole number between 0 and 4095.
A "raw" position value is not filtered, scaled, etc. So a value of `0` is always when the north end of the magnet is at the top of
the chip, 2048 is always when the north end of the magnet is as the bottom of the chip, etc.
The regular/scaled position is filtered and scaled based on the sensor configuration (e.g. ``start_position``, ``end_position``, ``range``, etc).
For example, let's say we have the following component config:
.. code-block:: yaml
as5600:
start_position: 90deg
range: 180deg
direction: clockwise
dir_pin: 22
- If the magnet north was at the right side of the chip (i.e. 1024 / 90deg raw position), the scaled position would report a value of ``0``.
- If the magnet north was at the bottom of the chip (i.e. 2048 / 180deg raw position), the scaled position would report a value of ``2048``.
- If the magnet north was at the left of the chip (i.e. 3096 / 270deg raw position), the scaled position would report a value of ``4095``.
- If the magnet north was at the top of the chipe (i.e. 0 / 0deg raw position), the scaled position would be out of range (which also has
it's own caveats discussed below).
.. note::
You may specify an ``end_position`` that is less than the ``start_position``. When doing so, the allowable range will start at the
``start_position`` and continue through to the highest position value (i.e. ``4095``) and then continue from ``0`` until it reaches
the ``end_position``.
.. warning::
The datasheet calls out that the minimum angle that can be configured (start and end position, or start and range) it 18 degrees.
Configuring anything less than that may yield un-expected results.
.. _as5600_i2c_addresses:
I²C Addresses
-------------
The AS5600 address is not configurable and must be ``0x36``. However, if using an AS5600L,
the default address should be ``0x40`` and it is configurable.
.. _as5600-sensor:
Sensor
------
The ``as5600`` sensor allows you to publish the angle/position measurement from your AS5600 with ESPHome.
First, setup an :ref:`AS5600 Hub <as5600-component>` for your AS5600 sensor and then use this
sensor platform to create individual sensors that will report the position to Home Assistant.
.. figure:: images/as5600-ui.jpg
:align: center
:width: 80.0%
.. code-block:: yaml
as5600:
dir_pin: 22
sensor:
- platform: as5600
name: Position
raw_position:
name: Raw Position
gain:
name: Gain
magnitude:
name: Magnitude
status:
name: Status
.. _as5600-sensor-config:
Configuration variables:
************************
- **out_of_range_mode** (*Optional*, string): How to treat out of range values. Only applicable if configured
for a range less than 360 degrees. Defaults to ``min_max``. See :ref:`Out of Range Mode <as5600-out-of-range-mode>`.
- **as5600_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the
:ref:`AS5600 Hub <as5600-component>` you want to use this sensor.
- **update_interval** (*Optional*, :ref:`config-time`): The interval
to check the sensor. Defaults to ``60s``.
- **raw_position** (*Optional*): Reports the raw (un-scaled, un-filtered) position of the magnet.
- All other options from :ref:`Sensor <config-sensor>`.
- **gain** (*Optional*): Information about the automatic gain control. Typically for diagnostic purposes.
The datasheet says this will be between 0-255 when powered by 5v and between 0-128 when powered by 3.3v.
Ideally the value should be close to the middle of the respective range.
- All other options from :ref:`Sensor <config-sensor>`.
- **magnitude** (*Optional*): Information about the detected magnitude. Typically for diagnostic purposes.
The expected scale does not appear to be defined in the datasheet, however, AMS provides a
`user guide <https://ams.com/documents/20143/36005/Position%20Sensors_UG000359_1-00.pdf/65a99825-c115-f2f0-9167-6efad8e27c20>`__
which contains pictures that show it as a scale between ``0`` and ``3000``. Typically this value is seen somewhere
in the neighborhood of ``2100`` for a well positioned magnet.
- All other options from :ref:`Sensor <config-sensor>`.
- **status** (*Optional*): Information about the magnet status. Typically for diagnostic purposes.
See :ref:`Magnet Status <as5600-magnet-status>`
- All other options from :ref:`Sensor <config-sensor>`.
- All other options from :ref:`Sensor <config-sensor>`.
.. _as5600-out-of-range-mode:
Out of Range Mode
*****************
- ``min_max`` (default)
- ``nan``
When using a range less that 360deg, there would be a range of raw values that would be considered "out of range". By default (``min_max`` mode), the AS5600
splits that range in half and reports ``0`` while in the half of the "out-of-range" range closest to the ``start_position`` and it reports
``4095`` while in the half of the "out-of-range" range closest to the ``end_position`` / end of the ``range``. Alternatively, you may set to ``nan``
mode where the sensor will publish ``NAN`` (i.e. "Unknown") when the position falls outside the narrowed range.
.. _as5600-magnet-status:
Magnet Status
*************
The magnet status should report one of the following values:
- ``2`` indicates that no magnet was detected.
- ``4`` indicates that the magnet was detected and has good reading.
- ``5`` indicates that the magnet was detected, but is too strong. Measurements may appear to be stuck if the magnet is too strong.
- ``6`` indicates that the magnet was detected, but is too weak. Measurements may still be possible in this state.
.. _as5600-converting-position:
Converting Position
*******************
You may desire the position to be converted from the native ``0`` thru ``4095`` to degrees, or perhaps a percentage of the allowable range.
Here are some examples to make that happen:
.. figure:: images/as5600-ui-derived.jpg
:align: center
:width: 80.0%
.. code-block:: yaml
as5600:
id: my_as5600
sensor:
- platform: as5600
update_interval: 1s
name: Angle
unit_of_measurement: '°'
accuracy_decimals: 2
icon: mdi:rotate-right
filters:
- delta: 1
- lambda: 'return x * as5600::RAW_TO_DEGREES * id(my_as5600).get_range_scale();'
.. code-block:: yaml
as5600:
id: my_as5600
sensor:
- platform: as5600
update_interval: 1s
name: Percent
unit_of_measurement: '%'
accuracy_decimals: 2
icon: mdi:rotate-right
filters:
- delta: 1
- lambda: 'return (x / as5600::POSITION_COUNT) * 100;'
See Also
--------
- :ref:`i2c`
- :ref:`sensor-filters`
- :apiref:`as5600/as5600.h`
- :ghedit:`Edit`

Binary file not shown.

After

Width:  |  Height:  |  Size: 52 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 114 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 35 KiB

BIN
images/as5600.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

View File

@ -368,6 +368,7 @@ Magnetic
.. imgtable::
ESP32 Hall Sensor, components/sensor/esp32_hall, magnet.svg, ESP internal, dark-invert
AS5600, components/sensor/as5600, as5600.jpg, 12-Bit Magnetic Position Sensor
HMC5883L, components/sensor/hmc5883l, hmc5883l.jpg, 3-Axis magnetometer
MMC5603, components/sensor/mmc5603, mmc5603.jpg, 3-Axis magnetometer
MMC5983, components/sensor/mmc5983, mmc5983.jpg, 3-Axis magnetometer