ESPHome LIS2DH12 (Valar fork)

Standalone ESPHome external_components fork of latonita's draft LIS2DH12 PR (esphome#14788) with four targeted fixes applied on top.

1. Stale-sample guard in update() — the upstream draft burst-reads OUT_X_L on every polled tick regardless of whether a fresh sample is ready, so when ESPHome's update_interval runs faster than the chip's effective ODR you get duplicate samples re-published as if they were new. This fork reads STATUS_REG first and bails out early if ZYXDA isn't set — only fresh data reaches the sensor publishes. Mirrors the in-tree lis3dh pattern.
2. Throttled loop() status reads (Fix 1b) — the upstream draft reads CLICK_SRC + INT1_SRC on every main-loop tick (~60-200 Hz), generating constant I²C traffic that can cluster into watchdog-tripping spikes (took a long time for an operation (174 ms), max is 30 ms). This fork throttles those reads to once per 50 ms, which still catches taps (event cooldown is 500 ms) and orientation transitions while cutting bus utilization ~10x. This is the actual fix for the "took a long time" warning.
3. Optional interrupt_pin: for data-ready (Fix 2) — wire the LIS2DH12 INT1 line to a GPIO and acceleration samples are pulled in an ISR-driven loop() instead of polled. When interrupt_pin: is configured, polled update() is a no-op to avoid a double-read race on OUT_* registers.
4. High-pass filter (HPF) support (Fix 3) — enable the chip's on-die HPF on the output data path via CTRL_REG2.FDS, with full control over HPM (mode) and HPCF (cutoff) bits. Removes the need to subtract gravity in user lambdas.

Why a fork?

Latonita's PR has been open in draft for a while and we need these fixes in production now. Forking lets us ship without waiting for upstream review and merge. The component is otherwise a near-verbatim copy of his work.

Usage

Add the external component to your ESPHome YAML:

external_components:
  - source: github://Valar-Systems/esphome-lis2dh12
    components: [lis2dh12_base, lis2dh12_i2c]

Example: all four new options

i2c:
  sda: GPIO8
  scl: GPIO9

lis2dh12_i2c:
  id: accel
  address: 0x19
  range: 2G
  resolution: high
  output_data_rate: 100Hz
  update_interval: 1s

  # Fix 2: route INT1 (data-ready) to a GPIO; loop() drains on the ISR flag.
  interrupt_pin:
    number: GPIO5
    mode:
      input: true
      pullup: false

  # Fix 3: enable the on-chip high-pass filter on the output data path.
  high_pass_filter: true
  hpf_mode: NORMAL      # NORMAL | REFERENCE | NORMAL2 | AUTORESET
  hpf_cutoff: 0          # 0..3 (higher = lower cutoff frequency; depends on ODR)

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

Fixes 1 and 1b apply automatically — no YAML knobs.

Roadmap (still missing)

These are present in the ST datasheet and partially implemented in the underlying register writes, but not yet exposed as ESPHome entities / config knobs:

• FIFO mode (stream / FIFO / bypass) and watermark interrupt
• Interrupt sources for 6D orientation (face up/down, portrait, landscape) wired as text sensor / binary sensors
• Single-tap and double-tap binary sensors / triggers exposed at the YAML level
• Activity / inactivity (sleep-to-wake) configuration
• Free-fall detection threshold / duration as YAML options

Contributions welcome.

When to switch back to upstream

When esphome#14788 merges into the ESPHome mainline (and the four fixes here either landed upstream or are no longer needed), drop the external_components: block and use the built-in lis2dh12_* component instead.

Attribution

Original LIS2DH12 ESPHome component authored by @latonita in esphome#14788. This fork keeps CODEOWNERS pointing to the original author for the unmodified base, adds the fixes listed above, and is otherwise a near-verbatim copy of his work. Released under the same MIT license as ESPHome itself.