[lis2dh12] [PR 2/3] Event detection and automation triggers documentation

src/content/docs/components/index.mdx

@@ -529,6 +529,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
   ["LD2420", "/components/sensor/ld2420/", "ld2420.jpg", "Motion & Presence"],
   ["LD2450", "/components/sensor/ld2450/", "ld2450.png", "Motion & Presence"],
   ["RD-03D", "/components/sensor/rd03d/", "rd03d.webp", "Motion & Presence"],
+  ["LIS2DH12", "/components/sensor/lis2dh12/", "lis2dh12.jpg", "Accelerometer"],
   ["MPU6050", "/components/sensor/mpu6050/", "mpu6050.jpg", "Accelerometer & Gyroscope"],
   ["MPU6886", "/components/sensor/mpu6886/", "mpu6886.jpg", "Accelerometer & Gyroscope"],
   ["MSA301", "/components/sensor/msa3xx/", "msa301.jpg", "Accelerometer"],

src/content/docs/components/sensor/lis2dh12.mdx

@@ -0,0 +1,187 @@
+---
+description: "Instructions for setting up the LIS2DH12 digital tri-axial accelerometer."
+title: "LIS2DH12 Sensor"
+---
+
+import APIRef from '@components/APIRef.astro';
+
+<span id="lis2dh12-component"></span>
+
+## Component/Hub
+
+The `lis2dh12` sensor platform allows you to use your ST LIS2DH12 ultra-low-power tri-axial
+accelerometer ([datasheet](https://www.st.com/resource/en/datasheet/lis2dh12.pdf))
+with ESPHome via the [I²C](/components/i2c) bus.
+
+LIS2DH12 is a high-performance accelerometer with selectable resolution (12-bit, 10-bit, or 8-bit),
+tap/double-tap (click) detection, free-fall detection, activity/inactivity detection,
+and 6D orientation recognition.
+
+This component provides acceleration data in m/s², orientation information, and event detection. XYZ axes can be
+calibrated and transformed to match the physical orientation of the sensor.
+
+```yaml
+# Example I2C configuration
+lis2dh12_i2c:
+  range: 4G
+  resolution: high
+  output_data_rate: 100Hz
+  update_interval: 10s
+```
+
+### Configuration variables
+
+- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval for updating acceleration sensors.
+  Defaults to `10s`.
+
+- **range** (*Optional*, string): The range of the sensor measurements. One of `2G`, `4G`, `8G`, `16G`.
+  Defaults to `2G` which means it picks up accelerations between `-2g` and `2g`.
+
+- **resolution** (*Optional*, string): ADC resolution mode. One of `high` (12-bit), `medium` (10-bit), `low` (8-bit).
+  Defaults to `high`.
+
+- **output_data_rate** (*Optional*, string): Output data rate. One of `1Hz`, `10Hz`, `25Hz`, `50Hz`, `100Hz`,
+  `200Hz`, `400Hz`, `1620Hz`, `5376Hz`. Defaults to `100Hz`.
+
+- **calibration** (*Optional*):
+
+  - **offset_x** (*Optional*, float): X-axis zero position calibration, in m/s². From -4.5 to 4.5. Defaults to `0`.
+  - **offset_y** (*Optional*, float): Y-axis zero position calibration, in m/s². From -4.5 to 4.5. Defaults to `0`.
+  - **offset_z** (*Optional*, float): Z-axis zero position calibration, in m/s². From -4.5 to 4.5. Defaults to `0`.
+
+- **transform** (*Optional*):
+
+  - **mirror_x** (*Optional*, boolean): Mirror X-axis. Defaults to `false`.
+  - **mirror_y** (*Optional*, boolean): Mirror Y-axis. Defaults to `false`.
+  - **mirror_z** (*Optional*, boolean): Mirror Z-axis. Defaults to `false`.
+  - **swap_xy** (*Optional*, boolean): Swap X and Y axis. Defaults to `false`.
+
+- All options from [I²C Device](/components/i2c#i2c-device). Default address is `0x19`.
+
+## Sensor
+
+Acceleration data is available through sensors configuration.
+You can use shorthand notation like `acceleration_x: "Acceleration X"` or use regular notation. For
+regular notation only the **name** is required. All options from [Sensor](/components/sensor).
+
+```yaml
+sensor:
+  - platform: lis2dh12_base
+    acceleration_x: Accel X
+    acceleration_y: Accel Y
+    acceleration_z: Accel Z
+```
+
+### Configuration variables
+
+- **acceleration_x** (*Optional*): X-axis acceleration, m/s².
+- **acceleration_y** (*Optional*): Y-axis acceleration, m/s².
+- **acceleration_z** (*Optional*): Z-axis acceleration, m/s².
+
+## Binary Sensor
+
+Four binary sensors available for use. Internal 500 ms debounce is applied for all sensors.
+For every sensor **name** is required. All other options from [Binary Sensor](/components/binary_sensor#config-binary_sensor).
+Shorthand notation also can be used.
+
+```yaml
+binary_sensor:
+  - platform: lis2dh12_base
+    tap: Single tap          # shorthand notation for the sensor
+    double_tap: Double tap   # -- "" --
+    freefall: Freefall       # -- "" --
+    active:                  # regular notation for the sensor to be able
+      name: Active           # to use filters and other options
+      filters:
+        - delayed_off: 5000ms # example of prolongation of movement detection signal
+```
+
+### Configuration variables
+
+- **tap** (*Optional*): Single tap (click) detection.
+- **double_tap** (*Optional*): Double tap (double-click) detection.
+- **freefall** (*Optional*): Free-fall detection.
+- **active** (*Optional*): Movement detection.
+
+## Text Sensor
+
+Text sensor provides 6D orientation information based on the dominant gravity axis.
+Uses 6D position recognition mode with ~60° threshold per ST DT0097 application note.
+
+```yaml
+text_sensor:
+  - platform: lis2dh12_base
+    orientation: Orientation
+```
+
+### Configuration variables
+
+- **orientation** (*Optional*): 6D orientation. Can be one of `Face Up`, `Face Down`,
+  `Portrait Up`, `Portrait Down`, `Landscape Left`, `Landscape Right`.
+
+## Automations
+
+### `on_tap` trigger
+
+This automation will be triggered when single tap is detected.
+
+```yaml
+lis2dh12_i2c:
+  # ...
+  on_tap:
+    - then:
+        - logger.log: "Tapped"
+```
+
+### `on_double_tap` trigger
+
+This automation will be triggered when double tap is detected.
+
+```yaml
+lis2dh12_i2c:
+  # ...
+  on_double_tap:
+    - then:
+        - logger.log: "Double tapped"
+```
+
+### `on_freefall` trigger
+
+This automation will be triggered when free-fall is detected.
+
+```yaml
+lis2dh12_i2c:
+  # ...
+  on_freefall:
+    - then:
+        - logger.log: "Freefall detected"
+```
+
+### `on_active` trigger
+
+This automation will be triggered when device detects changes in motion.
+
+```yaml
+lis2dh12_i2c:
+  # ...
+  on_active:
+    - then:
+        - logger.log: "Activity detected"
+```
+
+### `on_orientation` trigger
+
+This automation will be triggered when device orientation is changed with respect to the gravitation field vector `g`.
+
+```yaml
+lis2dh12_i2c:
+  # ...
+  on_orientation:
+    - then:
+        - logger.log: "Orientation change detected"
+```
+
+## See Also
+
+- [Sensor Filters](/components/sensor#sensor-filters)
+- <APIRef text="lis2dh12_base.h" path="lis2dh12_base/lis2dh12_base.h" />