mirror of
https://github.com/letscontrolit/ESPEasy.git
synced 2026-07-28 04:07:47 +00:00
[P125] Add documentation (also mostly shared with P120 I2C plugin)
This commit is contained in:
Ton Huisman
@@ -45,98 +45,8 @@ The available settings here depend on the build used. At least the **Force Slow
|
||||
|
||||
**I2C Address**: The address the device is using. Some boards holding this chip offer an extra connection SD0 that can be used to select the address. The available addresses are ``0x53`` and ``0x1D`` (secondary).
|
||||
|
||||
Device Settings
|
||||
^^^^^^^^^^^^^^^^
|
||||
.. include:: P120_P125_common.repl
|
||||
|
||||
* **Range**: The range determines the sensitivity and accuracy of the sensor, and the default is set to 16G as then the measuring resolution is 13 bit, while in lower ranges the resolution is 10 bit.
|
||||
|
||||
.. image:: P120_RangeOptions.png
|
||||
:alt: Range options
|
||||
|
||||
* **X/Y/Z-axis activity sensing**: These 3 settings determine if sensing for that axis is to be used or not. If an axis is disabled, then the resulting Value will be 0.
|
||||
|
||||
* **Activity treshold**: The minimum of movement required to include the activity in measurement. When setting too low, the sensor will be very instable, and cause many events. The treshold is configurable in steps of 62.5 milligram.
|
||||
|
||||
* **In-activity treshold**: If the movement goes below this treshold, then measuring is stopped, and an In-activity event will be generated (if enabled).
|
||||
|
||||
* **Enable (in)activity events**: When enabled will generate an event for each enabled axis if activity or in-activity state changes.
|
||||
|
||||
.. .. comment
|
||||
|
||||
* **Log sensor activity (INFO)**: When enabled will log any activity or in-activity that is detected. The log is output at INFO level, so that level, or a more detailed level like DEBUG, must be enabled to be visible.
|
||||
|
||||
* **Events with raw measurements**: When enabled wil, instead of a corrected, calculated and averaged measurement, output the raw measured value from the sensor. This is normally only used for debugging or testing purposes.
|
||||
|
||||
Tap detection
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
* **X/Y/Z-axis**: When enabled will detect single-tap activity for the axis enabled. Be aware that even if the sensor is tapped in a clean X, Y or Z direction, still the other directions will most likely also be triggered. Enabling one of these axis will enable generation of a ``taskname#Tapped`` event, with 3 arguments for all 3 axis, providing the last measured X/Y/Z activity, or 0 when that axis activity is disabled.
|
||||
|
||||
* **Tap treshold**: The minimum acceleration required to cause a tap detected. Again this is measured in 62.5 milligram increments.
|
||||
|
||||
* **Tap duration**: The minimum duration of a tap to be recognized as such. Configurable in 625 microsecond increments.
|
||||
|
||||
* **Enable double-tap detection**: If Single-tap detection is enabled for any of the axis, then Double-tap can be detected as well. This will be generated as a ``taskname#DoubleTap`` event. Once a Double-tap is detected, no single-tap event will be generated for the same movement.
|
||||
|
||||
* **Double-tap latency**: The amount of time that has to pass between the 2 taps of a double-tap action. Configurable in 1.25 millisecond steps.
|
||||
|
||||
* **Double-tap window**: The maximum time that may pass before the second of taps is to be registered as a double-tap. Configurable in 1.25 millisecond steps.
|
||||
|
||||
Free-fall detection
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* **Enable free-fall detection**: The sensor is able to detect if it is falling (free-fall), and can generate an event ``taskname#FreeFall`` if it does. To enable that feature this checkbox should be checked.
|
||||
|
||||
* **Free-fall treshold**: To avoid false triggers, the treshold can be set before a movement is detected as free-fall. This can be set in 62.5 milligram increments.
|
||||
|
||||
* **Free-fall duration**: The minimum time the sensor is falling before a free-fall event is generated can be configured in 625 microsecond increments.
|
||||
|
||||
Axis calibration
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
* **X/Y/Z-axis offset**: Corrective values can be set to calibrate the sensor once it is mounted in its intended location. These values are similar to the measured values as presented. Available calibration range is -127 to 127.
|
||||
|
||||
Calibration procedure
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To calibrate the sensor in its intended position follow these steps:
|
||||
|
||||
* Reset all calibration settings to 0.
|
||||
* Enable all axis that need to be calibrated in the **Device settings** section.
|
||||
* Set the **Averaging buffer size** to 10, and the **Measuring frequency** to 10x per second.
|
||||
* Uncheck **Events with raw measurements**. This setting should be left unchecked when expecting calibrated measurements using the sensor.
|
||||
* Set the **Interval** to 5 seconds.
|
||||
* Save the settings using the Submit button.
|
||||
* Place the sensor in its intended position.
|
||||
* Enable the sensor, if that wasn't already set (can be done using the settings page or by sending a ``TaskEnable,taskname`` command).
|
||||
* Wait for at least 30 seconds to stabilize the measurements.
|
||||
* Take note of the values for the X, Y and Z axis values, as presented on the **Devices** overview page.
|
||||
* For each axis to be calibrated, enter the X, or Y value(s) *multiplied by* **-1** into the X- and Y-axis calibration fields.
|
||||
|
||||
* The Z-axis value has a default deviation of -256 so that has to be used as the reference point. Add 256 to the noted Z-axis value to get the required Z-axis calibration value.
|
||||
|
||||
* Restore any of the settings changed above to their original state.
|
||||
* Save the settings using the Submit button.
|
||||
* Validate that the measured values are now 0 with the sensor in its intended position.
|
||||
|
||||
NB: Instead of calibrating to 0 it is also possible to calibrate a defined offset, if that better fits the intended solution.
|
||||
|
||||
Data retrieval
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
* **Averaging buffer size**: The number of measurements that will be averaged before presenting it as **Values**. When set to 1, there is effectively no averaging.
|
||||
|
||||
* **Measuring frequency**: The plugin supports 2 measuring frequencies, 10x per second or 50x per second. When using 50x per second, it will stabilize the measurements if the **Averaging buffer size** is also increased, f.e. to 50 or 100. This may increase the load on the ESP unit somewhat.
|
||||
|
||||
Data Acquisition
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
This group of settings, **Single event with all values**, **Send to Controller** and **Interval** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
|
||||
|
||||
Values
|
||||
^^^^^^
|
||||
|
||||
There are 3 values available for this sensor, with default names as provided. The number of decimals is by default set to 0, as no decimals are provided from the measurement.
|
||||
|
||||
.. Commands available
|
||||
.. ^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
Device Settings
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
* **Range**: The range determines the sensitivity and accuracy of the sensor, and the default is set to 16G as then the measuring resolution is 13 bit, while in lower ranges the resolution is 10 bit.
|
||||
|
||||
.. image:: P120_RangeOptions.png
|
||||
:alt: Range options
|
||||
|
||||
* **X/Y/Z-axis activity sensing**: These 3 settings determine if sensing for that axis is to be used or not. If an axis is disabled, then the resulting Value will be 0.
|
||||
|
||||
* **Activity treshold**: The minimum of movement required to include the activity in measurement. When setting too low, the sensor will be very instable, and cause many events. The treshold is configurable in steps of 62.5 milligram.
|
||||
|
||||
* **In-activity treshold**: If the movement goes below this treshold, then measuring is stopped, and an In-activity event will be generated (if enabled).
|
||||
|
||||
* **Enable (in)activity events**: When enabled will generate an event for each enabled axis if activity or in-activity state changes.
|
||||
|
||||
.. .. comment
|
||||
|
||||
* **Log sensor activity (INFO)**: When enabled will log any activity or in-activity that is detected. The log is output at INFO level, so that level, or a more detailed level like DEBUG, must be enabled to be visible.
|
||||
|
||||
* **Events with raw measurements**: When enabled wil, instead of a corrected, calculated and averaged measurement, output the raw measured value from the sensor. This is normally only used for debugging or testing purposes.
|
||||
|
||||
Tap detection
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
* **X/Y/Z-axis**: When enabled will detect single-tap activity for the axis enabled. Be aware that even if the sensor is tapped in a clean X, Y or Z direction, still the other directions will most likely also be triggered. Enabling one of these axis will enable generation of a ``taskname#Tapped`` event, with 3 arguments for all 3 axis, providing the last measured X/Y/Z activity, or 0 when that axis activity is disabled.
|
||||
|
||||
* **Tap treshold**: The minimum acceleration required to cause a tap detected. Again this is measured in 62.5 milligram increments.
|
||||
|
||||
* **Tap duration**: The minimum duration of a tap to be recognized as such. Configurable in 625 microsecond increments.
|
||||
|
||||
* **Enable double-tap detection**: If Single-tap detection is enabled for any of the axis, then Double-tap can be detected as well. This will be generated as a ``taskname#DoubleTap`` event. Once a Double-tap is detected, no single-tap event will be generated for the same movement.
|
||||
|
||||
* **Double-tap latency**: The amount of time that has to pass between the 2 taps of a double-tap action. Configurable in 1.25 millisecond steps.
|
||||
|
||||
* **Double-tap window**: The maximum time that may pass before the second of taps is to be registered as a double-tap. Configurable in 1.25 millisecond steps.
|
||||
|
||||
Free-fall detection
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* **Enable free-fall detection**: The sensor is able to detect if it is falling (free-fall), and can generate an event ``taskname#FreeFall`` if it does. To enable that feature this checkbox should be checked.
|
||||
|
||||
* **Free-fall treshold**: To avoid false triggers, the treshold can be set before a movement is detected as free-fall. This can be set in 62.5 milligram increments.
|
||||
|
||||
* **Free-fall duration**: The minimum time the sensor is falling before a free-fall event is generated can be configured in 625 microsecond increments.
|
||||
|
||||
Axis calibration
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
* **X/Y/Z-axis offset**: Corrective values can be set to calibrate the sensor once it is mounted in its intended location. These values are similar to the measured values as presented. Available calibration range is -127 to 127.
|
||||
|
||||
Calibration procedure
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To calibrate the sensor in its intended position follow these steps:
|
||||
|
||||
* Reset all calibration settings to 0.
|
||||
* Enable all axis that need to be calibrated in the **Device settings** section.
|
||||
* Set the **Averaging buffer size** to 10, and the **Measuring frequency** to 10x per second.
|
||||
* Uncheck **Events with raw measurements**. This setting should be left unchecked when expecting calibrated measurements using the sensor.
|
||||
* Set the **Interval** to 5 seconds.
|
||||
* Save the settings using the Submit button.
|
||||
* Place the sensor in its intended position.
|
||||
* Enable the sensor, if that wasn't already set (can be done using the settings page or by sending a ``TaskEnable,taskname`` command).
|
||||
* Wait for at least 30 seconds to stabilize the measurements.
|
||||
* Take note of the values for the X, Y and Z axis values, as presented on the **Devices** overview page.
|
||||
* For each axis to be calibrated, enter the X, or Y value(s) *multiplied by* **-1** into the X- and Y-axis calibration fields.
|
||||
|
||||
* The Z-axis value has a default deviation of -256 so that has to be used as the reference point. Add 256 to the noted Z-axis value to get the required Z-axis calibration value.
|
||||
|
||||
* Restore any of the settings changed above to their original state.
|
||||
* Save the settings using the Submit button.
|
||||
* Validate that the measured values are now 0 with the sensor in its intended position.
|
||||
|
||||
NB: Instead of calibrating to 0 it is also possible to calibrate a defined offset, if that better fits the intended solution.
|
||||
|
||||
Data retrieval
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
* **Averaging buffer size**: The number of measurements that will be averaged before presenting it as **Values**. When set to 1, there is effectively no averaging.
|
||||
|
||||
* **Measuring frequency**: The plugin supports 2 measuring frequencies, 10x per second or 50x per second. When using 50x per second, it will stabilize the measurements if the **Averaging buffer size** is also increased, f.e. to 50 or 100. This may increase the load on the ESP unit somewhat.
|
||||
|
||||
Data Acquisition
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
This group of settings, **Single event with all values**, **Send to Controller** and **Interval** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
|
||||
|
||||
Values
|
||||
^^^^^^
|
||||
|
||||
There are 3 values available for this sensor, with default names as provided. The number of decimals is by default set to 0, as no decimals are provided from the measurement.
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
.. include:: ../Plugin/_plugin_substitutions_p12x.repl
|
||||
.. _P125_page:
|
||||
|
||||
|P125_typename|
|
||||
==================================================
|
||||
|
||||
|P125_shortinfo|
|
||||
|
||||
Plugin details
|
||||
--------------
|
||||
|
||||
Type: |P125_type|
|
||||
|
||||
Name: |P125_name|
|
||||
|
||||
Status: |P125_status|
|
||||
|
||||
GitHub: |P125_github|_
|
||||
|
||||
Maintainer: |P125_maintainer|
|
||||
|
||||
Used libraries: |P125_usedlibraries|
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
The ADXL345 Acceleration sensor can be used to detect movement of the sensor in X, Y and Z direction, also supports detection of single and double taps, and free falling detection.
|
||||
|
||||
This sensor is sometimes combined with an ITG3205 Gyro sensor and a HMC5883L magneto position sensor on a single board, as these sensors are often used together because of their accompanying features.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
.. image:: P125_DeviceConfiguration.png
|
||||
:alt: Device Configuration
|
||||
|
||||
**Name** A unique name should be entered here.
|
||||
|
||||
**Enabled** The device can be disabled or enabled. When not enabled the device should not use any resources.
|
||||
|
||||
Sensor
|
||||
^^^^^^
|
||||
|
||||
**GPIO -> CS**: The GPIO pin that is to be used for controlling the ``CS`` signal of the board. Each SPI device should have its own CS pin, the other SPI signals can be shared among devices.
|
||||
|
||||
.. note:: Not all boards that claim to support SPI connections actually do. This may be caused by substandard production methods, or by ommitting parts to reduce cost. Usually, the same board also supports being connected via I2C, and that has worked reliably on all tests.
|
||||
|
||||
.. include:: P120_P125_common.repl
|
||||
|
||||
|
||||
.. Commands available
|
||||
.. ^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. .. include:: P125_commands.repl
|
||||
|
||||
.. Events
|
||||
.. ~~~~~~
|
||||
|
||||
.. .. include:: P125_events.repl
|
||||
|
||||
Change log
|
||||
----------
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
...
|
||||
|
||||
|added|
|
||||
2021-12-14 Initial release version.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 95 KiB |
@@ -143,6 +143,7 @@ There are different released versions of ESP Easy:
|
||||
":ref:`P117_page`","|P117_status|","P117"
|
||||
":ref:`P120_page`","|P120_status|","P120"
|
||||
":ref:`P124_page`","|P124_status|","P124"
|
||||
":ref:`P125_page`","|P125_status|","P125"
|
||||
|
||||
|
||||
Internal GPIO handling
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
.. |Plugin_Analog_input| replace:: :ref:`P002_page`, :ref:`P007_page`, :ref:`P025_page`, :ref:`P060_page`, :ref:`P097_page`
|
||||
.. |Plugin_Acceleration| replace:: :ref:`P120_page`
|
||||
.. |Plugin_Acceleration| replace:: :ref:`P120_page`, :ref:`P125_page`
|
||||
.. |Plugin_Communication| replace:: :ref:`P016_page`, :ref:`P020_page`, :ref:`P035_page`, :ref:`P044_page`, :ref:`P054_page`, :ref:`P071_page`, :ref:`P087_page`, :ref:`P089_page`, :ref:`P094_page`, :ref:`P101_page`
|
||||
.. |Plugin_Display| replace:: :ref:`P012_page`, :ref:`P023_page`, :ref:`P036_page`, :ref:`P057_page`, :ref:`P073_page`, :ref:`P075_page`, :ref:`P095_page`, :ref:`P104_page`
|
||||
.. |Plugin_Distance| replace:: :ref:`P110_page`, :ref:`P113_page`
|
||||
|
||||
@@ -23,3 +23,17 @@
|
||||
.. |P124_maintainer| replace:: `tonhuisman`
|
||||
.. |P124_compileinfo| replace:: `.`
|
||||
.. |P124_usedlibraries| replace:: `https://github.com/Seeed-Studio/Multi_Channel_Relay_Arduino_Library (modified local copy)`
|
||||
|
||||
.. |P125_name| replace:: :cyan:`ADXL345 SPI`
|
||||
.. |P125_type| replace:: :cyan:`Acceleration`
|
||||
.. |P125_typename| replace:: :cyan:`Acceleration - ADXL345 (SPI)`
|
||||
.. |P125_porttype| replace:: `.`
|
||||
.. |P125_status| replace:: :yellow:`TESTING E`
|
||||
.. |P125_github| replace:: P125_ADXL345_SPI.ino
|
||||
.. _P125_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P125_ADXL345_SPI.ino
|
||||
.. |P125_usedby| replace:: `.`
|
||||
.. |P125_shortinfo| replace:: `Acceleration X/Y/X sensor`
|
||||
.. |P125_maintainer| replace:: `tonhuisman`
|
||||
.. |P125_compileinfo| replace:: `.`
|
||||
.. |P125_usedlibraries| replace:: `https://github.com/sparkfun/SparkFun_ADXL345_Arduino_Library (local copy)`
|
||||
|
||||
|
||||
@@ -421,6 +421,10 @@ void P120_data_struct::send_task_event(struct EventStruct *event,
|
||||
// Load the configuration interface
|
||||
// *******************************************************************
|
||||
bool P120_data_struct::plugin_webform_load(struct EventStruct *event) {
|
||||
if (!i2c_mode) {
|
||||
addFormSubHeader(F("Device Settings"));
|
||||
}
|
||||
|
||||
// Range
|
||||
{
|
||||
const __FlashStringHelper *rangeOptions[] = {
|
||||
|
||||
Reference in New Issue
Block a user