Skip to content
ESPHome - Smart Home Made Simple 2026.5.2

Motion Component (IMU)

The motion hub component allows you to define sensors that read data from inertial measurement units (IMUs) such as accelerometers and gyroscopes. Not all IMU chips support all types of measurements, see the individual platform documentation for details.

# Example configuration entry
motion:
  - platform: ...
    accelerometer_range: 4G # Platform dependent options here


sensor:
  - platform: motion
    type: acceleration_x
    name: "Accel X"
  - platform: motion
    type: angular_rate_x
    name: "Gyro X"
  - platform: motion
    type: pitch
    name: "Pitch Angle"

Configuration variables

Section titled “Configuration variables”

Base configuration

Section titled “Base configuration”

  • axis_map (Optional, mapping): Remap or invert the physical axes of the sensor to match your board orientation. Each key (x, y, z) maps to the physical axis it should read from, optionally prefixed with - to invert. All three axes must be present and each physical axis may only appear once. Mutually exclusive with transform_matrix.

    # Example: swap X and Y, invert Z
    motion:
      - platform: ...
        axis_map:
          x: y
          y: x
          z: "-z"

  • transform_matrix (Optional, list of floats): A 3×3 transformation matrix applied to raw accelerometer and gyroscope readings. This allows arbitrary calibration beyond simple axis remapping. Can be specified as a flat list of 9 values (row-major order) or as a 3×3 nested list. Mutually exclusive with axis_map.

    # Example: 3x3 nested format
    motion:
      - platform: ...
        transform_matrix:
          - [0.998, 0.010, -0.050]
          - [-0.010, 0.999, 0.020]
          - [0.050, -0.020, 0.998]
    # Example: flat format
    motion:
      - platform: ...
        transform_matrix: [0.998, 0.010, -0.050, -0.010, 0.999, 0.020, 0.050, -0.020, 0.998]

    The matrix can be obtained from the runtime calibration actions described below — after calibration the computed matrix is logged in a format that can be copied directly into your configuration for persistent use.

  • update_interval (Optional, Time): The interval at which sensor data is read. Defaults to 250ms.

  • id (Optional, ID): Manually specify the ID used for code generation.

Sensor configuration

Section titled “Sensor configuration”
  • type (Required, string): The type of measurement to expose. One of:
    • acceleration_x: X-axis acceleration in g.
    • acceleration_y: Y-axis acceleration in g.
    • acceleration_z: Z-axis acceleration in g.
    • angular_rate_x: X-axis angular velocity in °/s.
    • angular_rate_y: Y-axis angular velocity in °/s.
    • angular_rate_z: Z-axis angular velocity in °/s.
    • gyroscope_x: Synonym for angular_rate_x.
    • gyroscope_y: Synonym for angular_rate_y.
    • gyroscope_z: Synonym for angular_rate_z.
    • pitch: Pitch angle in °.
    • roll: Roll angle in °.
    • orientation: Discrete in-plane rotation derived from gravity, reported as 0, 90, 180 or 270°. While the device lies flat (face up or face down) no value is published.
  • flat_threshold (Optional, float): Only used by the orientation type. The minimum tilt angle from horizontal, in degrees, before an orientation is reported. While the device is more level than this it is treated as flat and the sensor publishes no value. Defaults to 30.
  • All other options from Sensor.

Binary Sensor

Section titled “Binary Sensor”

The motion binary sensor platform reports orientation and movement states derived from the IMU data. Each binary sensor selects a type and reads from a motion hub.

# Example configuration entry
binary_sensor:
  - platform: motion
    type: face_up
    name: "Face Up"
  - platform: motion
    type: free_fall
    name: "Free Fall"

Configuration variables

Section titled “Configuration variables”
  • type (Required, string): The state to detect. One of:
    • face_up: ON while the device lies roughly horizontal with its Z axis pointing up.
    • face_down: ON while the device lies roughly horizontal with its Z axis pointing down.
    • free_fall: ON while the device is in free fall (total acceleration near zero).
    • moving: ON while the device is being moved or rotated.
  • threshold (Optional, float): Detection threshold; its meaning and default depend on type:
    • face_up / face_down: the maximum tilt from horizontal, in degrees (0–90). Smaller values require the device to be more level. Defaults to 30. These two states are only evaluated while the device is at rest; during movement the last reported state is held.
    • free_fall: the total acceleration in g below which free fall is detected. Defaults to 0.15.
    • moving: the change in acceleration in g (or a proportional change in angular rate) above which motion is detected. Defaults to 0.05.
  • duration (Optional, Time): Only used by free_fall and moving. For free_fall, the device must be falling for at least this long before the sensor turns ON; defaults to 100ms. For moving, the sensor stays ON for at least this long after the last detected motion; defaults to 2s.
  • motion_id (Optional, ID): The ID of the motion hub to read from. Only required when more than one motion hub is configured.
  • All other options from Binary Sensor.

Event

Section titled “Event”

The motion event platform fires events for gesture-like motions. It exposes a single event type, shake, triggered by a sharp change in acceleration.

# Example configuration entry
event:
  - platform: motion
    name: "Shake"

Configuration variables

Section titled “Configuration variables”
  • threshold (Optional, float): The change in acceleration between successive readings, in g, above which a shake is detected. Lower values make detection more sensitive. Defaults to 0.5.
  • cooldown (Optional, Time): The minimum time between consecutive shake events. Defaults to 500ms.
  • motion_id (Optional, ID): The ID of the motion hub to read from. Only required when more than one motion hub is configured.
  • All other options from Event.

Actions

Section titled “Actions”

motion.calibrate_level Action

Section titled “motion.calibrate_level Action”

This action computes a calibration matrix so that the current accelerometer reading maps to [0, 0, 1] (device flat, Z pointing up). Place the device on a level surface and trigger this action. It replaces the current transform_matrix.

  • save (Optional, boolean): Save the resulting matrix to NVS flash so it is automatically restored on the next boot. Defaults to false.
  • on_success (Optional, Automation): Actions to run when calibration succeeds.
  • on_error (Optional, Automation): Actions to run when calibration fails (e.g. sensor read failure or insufficient tilt).
on_...:
  then:
    - motion.calibrate_level:
        id: my_motion
        save: true
        on_success:
          - logger.log: "Level calibration succeeded"
        on_error:
          - logger.log: "Level calibration failed"

After execution the resulting matrix is logged at INFO level in a format that can be copied into the transform_matrix configuration for persistent calibration.

motion.calibrate_heading Action

Section titled “motion.calibrate_heading Action”

This action corrects the heading (rotation around Z) after a prior level calibration. Tilt the device around its Y axis only (pitch forward or backward) and trigger this action. It composes a Z-rotation correction with the existing matrix so that the horizontal acceleration component falls entirely on the X axis, with its sign preserved.

  • save (Optional, boolean): Save the resulting matrix to NVS flash. Defaults to false.
  • on_success (Optional, Automation): Actions to run when calibration succeeds.
  • on_error (Optional, Automation): Actions to run when calibration fails.
on_...:
  then:
    - motion.calibrate_heading:
        id: my_motion
        save: true
        on_success:
          - logger.log: "Heading calibration succeeded"

motion.clear_calibration Action

Section titled “motion.clear_calibration Action”

This action discards any runtime calibration and restores the build-time matrix defined by axis_map or transform_matrix (or the identity matrix if neither is configured). Use it to undo a motion.calibrate_level / motion.calibrate_heading sequence without re-flashing.

  • save (Optional, boolean): Also clear the saved calibration in NVS flash so the reset persists across reboots. Defaults to false. When false, the in-memory matrix is reset but a previously saved calibration will be restored again on the next boot.
on_...:
  then:
    - motion.clear_calibration:
        id: my_motion
        save: true

Calibration persistence

Section titled “Calibration persistence”

When a calibration action is run with save: true, the resulting matrix is stored in NVS flash and automatically restored on the next boot, taking precedence over the axis_map / transform_matrix configuration. The saved calibration is tied to the configured base matrix: if you change axis_map or transform_matrix and re-flash, the stale saved calibration is automatically discarded and the new configuration is used. To explicitly return to the configured base at runtime, use motion.clear_calibration.

Calibration procedure

Section titled “Calibration procedure”
  1. Place the device on a flat, level surface.
  2. Trigger motion.calibrate_level. This aligns Z with gravity.
  3. Tilt the device around the Y axis only (e.g. prop one edge up along the X direction).
  4. Trigger motion.calibrate_heading. This fixes the X/Y heading.

The new calibration matrix is now active and can be saved to flash if desired. If you have a way to monitor the logs, you can verify that the calibration succeeded by checking for an INFO log entry with the resulting matrix in a format suitable for copy-pasting into your configuration.

Device being calibrated
Device Calibration

See Also

Section titled “See Also”