Skip to content

[lis2dh12_base][lis2dh12_i2c] (PR 2/3) Add event detection, orientation, and automation triggers#14804

Draft
latonita wants to merge 7 commits intoesphome:devfrom
latonita:lis2dh12-events
Draft

[lis2dh12_base][lis2dh12_i2c] (PR 2/3) Add event detection, orientation, and automation triggers#14804
latonita wants to merge 7 commits intoesphome:devfrom
latonita:lis2dh12-events

Conversation

@latonita
Copy link
Contributor

@latonita latonita commented Mar 14, 2026

PR1: Base I2C #14788
PR2: Triggers #14804
PR3: SPI #14805

What does this implement/fix?

Add event detection and orientation features to the LIS2DH12 accelerometer component (introduced in #14788):

  • Binary sensors: tap, double-tap, freefall, activity detection with 500ms debounce
  • Text sensor: 6D orientation (X/Y/Z Up/Down)
  • Automation triggers: on_tap, on_double_tap, on_freefall, on_active, on_orientation

Note: This PR depends on #14788 and should be merged after it.

Types of changes

  • Bugfix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected) — policy
  • Developer breaking change (an API change that could break external components) — policy
  • Undocumented C++ API change (removal or change of undocumented public methods that lambda users may depend on) — policy
  • Code quality improvements to existing code or addition of tests
  • Other

Related issue or feature (if applicable):

Pull request in esphome-docs with documentation (if applicable):

Test Environment

  • ESP32
  • ESP32 IDF
  • ESP8266
  • RP2040/RP2350
  • BK72xx
  • RTL87xx
  • LN882x
  • nRF52840

Example entry for config.yaml:

i2c:
  sda: GPIO21
  scl: GPIO22

lis2dh12_i2c:
  id: lis2dh12_accel
  range: 4G
  resolution: high
  output_data_rate: 100Hz
  update_interval: 10s
  on_tap:
    - logger.log: "Tapped"
  on_double_tap:
    - logger.log: "Double tapped"
  on_freefall:
    - logger.log: "Freefall detected"
  on_active:
    - logger.log: "Activity detected"
  on_orientation:
    - logger.log: "Orientation changed"

sensor:
  - platform: lis2dh12_base
    lis2dh12_id: lis2dh12_accel
    acceleration_x: "Accel X"
    acceleration_y: "Accel Y"
    acceleration_z: "Accel Z"

text_sensor:
  - platform: lis2dh12_base
    lis2dh12_id: lis2dh12_accel
    orientation: "Orientation"

binary_sensor:
  - platform: lis2dh12_base
    lis2dh12_id: lis2dh12_accel
    tap: "Single tap"
    double_tap: "Double tap"
    freefall: "Freefall"
    active:
      name: "Active"
      filters:
        - delayed_off: 5000ms

Checklist:

  • The code change is tested and works locally.
  • Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

Copilot AI review requested due to automatic review settings March 14, 2026 12:29
@github-actions
Copy link
Contributor

To use the changes from this PR as an external component, add the following to your ESPHome configuration YAML file:

external_components:
  - source: github://pr#14804
    components: [lis2dh12_base, lis2dh12_i2c]
    refresh: 1h

(Added by the PR bot)

@codecov-commenter
Copy link

codecov-commenter commented Mar 14, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.34%. Comparing base (33f9ad9) to head (13fb02b).
⚠️ Report is 60 commits behind head on dev.

Additional details and impacted files
@@           Coverage Diff           @@
##              dev   #14804   +/-   ##
=======================================
  Coverage   75.34%   75.34%           
=======================================
  Files          55       55           
  Lines       12038    12038           
  Branches     1665     1665           
=======================================
  Hits         9070     9070           
  Misses       2543     2543           
  Partials      425      425           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new LIS2DH12 accelerometer implementation split into a reusable lis2dh12_base core plus an lis2dh12_i2c bus variant, along with YAML build fixtures to exercise the new configuration on multiple targets. This enables exposing acceleration, event-style binary sensors, orientation text sensor, and automation triggers through the shared base.

Changes:

  • Introduce lis2dh12_base core (C++ + Python schemas) with acceleration reading, event processing, and automation triggers.
  • Add lis2dh12_i2c component wiring the base to ESPHome’s I2C device API (incl. multi-byte auto-increment behavior).
  • Add component build-test YAMLs for ESP32 (Arduino/IDF), ESP8266, and RP2040 + update CODEOWNERS.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
tests/components/lis2dh12_i2c/test.rp2040-ard.yaml Adds RP2040 Arduino build fixture including shared config.
tests/components/lis2dh12_i2c/test.esp8266-ard.yaml Adds ESP8266 Arduino build fixture including shared config.
tests/components/lis2dh12_i2c/test.esp32-idf.yaml Adds ESP32 IDF build fixture including shared config.
tests/components/lis2dh12_i2c/test.esp32-ard.yaml Adds ESP32 Arduino build fixture including shared config.
tests/components/lis2dh12_i2c/common.yaml Shared configuration covering component setup, sensors, text sensor, binary sensors, and automations.
esphome/components/lis2dh12_i2c/lis2dh12_i2c.h Declares I2C variant implementing the base bus abstraction.
esphome/components/lis2dh12_i2c/lis2dh12_i2c.cpp Implements dump_config() for the I2C variant.
esphome/components/lis2dh12_i2c/init.py Python config schema + codegen for the I2C component.
esphome/components/lis2dh12_base/text_sensor.py Adds orientation text sensor platform wiring into the base hub.
esphome/components/lis2dh12_base/sensor.py Adds acceleration sensor platform wiring into the base hub.
esphome/components/lis2dh12_base/binary_sensor.py Adds event binary sensor platform wiring (tap/double/freefall/active).
esphome/components/lis2dh12_base/init.py Defines shared schema, enums, and builds automations for triggers.
esphome/components/lis2dh12_base/lis2dh12_base.h Declares the base component, register map, state, and triggers.
esphome/components/lis2dh12_base/lis2dh12_base.cpp Implements setup, register configuration, acceleration reads, and event/orientation processing.
CODEOWNERS Adds ownership entries for the new LIS2DH12 component directories.

@latonita latonita marked this pull request as draft March 14, 2026 15:37
@latonita latonita changed the title [lis2dh12] Add event detection, orientation, and automation triggers [lis2dh12] [PR 2/3] Add event detection, orientation, and automation triggers Mar 14, 2026
- PROGMEM_STRING_TABLE for range/resolution/data rate strings
- PROGMEM sensitivity arrays
- Consolidate 4 cooldown constants into single EVENT_COOLDOWN_MS (uint16_t)
- mark_failed(LOG_STR(...)) with reason strings
- Remove redundant ESP_LOGE in dump_config (mark_failed handles it)
- Use encode_uint16() from helpers.h
- ESP_LOGV for setup message
- Fix 6D orientation: threshold 0x36 (~60°) and duration 0x06 (240ms) per ST DT0097
- Orientation strings: Face Up/Down, Portrait Up/Down, Landscape Left/Right
@latonita latonita changed the title [lis2dh12] [PR 2/3] Add event detection, orientation, and automation triggers [lis2dh12_base, lis2dh12_i2c] [PR 2/3] Add event detection, orientation, and automation triggers Mar 15, 2026
INT1_CFG 0x7F→0xFF (AOI=1, 6D=1) so INT1_SRC reflects current
orientation continuously instead of pulsing on change.
@latonita latonita changed the title [lis2dh12_base, lis2dh12_i2c] [PR 2/3] Add event detection, orientation, and automation triggers [lis2dh12] (PR 2/3) Add event detection, orientation, and automation triggers Mar 15, 2026
@esphome esphome bot removed the needs-docs label Mar 15, 2026
@latonita latonita changed the title [lis2dh12] (PR 2/3) Add event detection, orientation, and automation triggers [lis2dh12_base][lis2dh12_i2c] (PR 2/3) Add event detection, orientation, and automation triggers Mar 15, 2026
…ation to loop

- INT2 configured for freefall: INT2_CFG=0x95 (AOI=1, low bits),
  INT2_THS=0x16 (350mg), INT2_DURATION=0x03 (30ms) per AN5005
- CTRL_REG5: latch both INT1+INT2 (0x0A)
- CTRL_REG6: route IA2 to INT2 pin (0x20)
- Freefall now uses INT2_SRC.ia instead of misusing INT1 orientation bits
- Activity detects clicks or orientation changes
- Orientation text sensor publishes from process_events_() on change
- Add <utility> include for std::swap
- Rename RegInt1Src to RegIntSrc (shared by INT1/INT2)
@latonita latonita marked this pull request as ready for review March 15, 2026 21:51
@latonita latonita marked this pull request as draft March 16, 2026 10:00
…and binary sensor

Trigger with cooldown is now a simple function without binary sensor coupling.
Binary sensors publish state directly via publish_state() which deduplicates.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants