diff --git a/public/images/lis2dh12.jpg b/public/images/lis2dh12.jpg new file mode 100644 index 0000000000..dedb6bb275 Binary files /dev/null and b/public/images/lis2dh12.jpg differ diff --git a/src/content/docs/components/index.mdx b/src/content/docs/components/index.mdx index 5c2ed01a57..9e8d5246da 100644 --- a/src/content/docs/components/index.mdx +++ b/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"], diff --git a/src/content/docs/components/sensor/lis2dh12.mdx b/src/content/docs/components/sensor/lis2dh12.mdx new file mode 100644 index 0000000000..5f2bccc51e --- /dev/null +++ b/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'; + + + +## 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) +-