From 85b554c048f2f597a78b8e7bec620b9e1cdd3676 Mon Sep 17 00:00:00 2001
From: Toby <mr2web@hotmail.com>
Date: Sun, 20 Sep 2026 22:54:01 +0200
Subject: [PATCH] docs: add upstream LSM6DS status bit bug report

---
 docs/lsm6ds-upstream-bug-report.md | 156 +++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 docs/lsm6ds-upstream-bug-report.md

diff --git a/docs/lsm6ds-upstream-bug-report.md b/docs/lsm6ds-upstream-bug-report.md
new file mode 100644
index 000000000..dbf661644
--- /dev/null
+++ b/docs/lsm6ds-upstream-bug-report.md
@@ -0,0 +1,156 @@
+# Bug: LSM6DS STATUS_REG XLDA/GDA masks are reversed
+
+## Summary
+
+The LSM6DS base component has the accelerometer and gyroscope data-ready
+bits of `STATUS_REG` (`0x1E`) reversed.
+
+The affected implementation treats:
+
+``` cpp
+status & 0x01  // GDA - gyroscope data available
+status & 0x02  // XLDA - accelerometer data available
+```
+
+The correct mapping is:
+
+  Bit       Mask Meaning
+  ----- -------- ---------------------------------------
+  0       `0x01` XLDA --- accelerometer data available
+  1       `0x02` GDA --- gyroscope data available
+  2       `0x04` TDA --- temperature data available
+
+## Test environment
+
+-   LSM6DSOXTR
+-   Seeed Studio XIAO ESP32-C6
+-   ESPHome 2026.8.2
+-   ESP-IDF
+-   I2C
+-   Accelerometer ODR: 104 Hz
+-   Gyroscope ODR: OFF
+-   Polling interval: 10 ms
+
+Relevant configuration:
+
+``` yaml
+lsm6ds_i2c:
+  id: imu
+  i2c_id: i2c_bus
+  address: 0x6A
+  accel_range: 2G
+  gyro_range: 250DPS
+  accel_odr: 104HZ
+  gyro_odr: "OFF"
+  update_interval: 10ms
+```
+
+## Reproduction and diagnostic evidence
+
+To determine which data-ready bits were actually being asserted,
+temporary logging was added immediately after reading `STATUS_REG`:
+
+``` cpp
+uint8_t status;
+if (!this->read_register(0x1E, &status, 1))
+  return;
+
+ESP_LOGW(TAG, "STATUS=0x%02X accel_odr=0x%02X gyro_odr=0x%02X",
+         status,
+         static_cast<uint8_t>(this->accel_odr_),
+         static_cast<uint8_t>(this->gyro_odr_));
+```
+
+With:
+
+``` text
+accel_odr=0x04
+gyro_odr=0x00
+```
+
+the device repeatedly reported:
+
+``` text
+STATUS=0x01 accel_odr=0x04 gyro_odr=0x00
+STATUS=0x05 accel_odr=0x04 gyro_odr=0x00
+```
+
+`0x02` was not observed.
+
+`0x05` is `0x01 | 0x04`, corresponding to accelerometer data plus
+temperature data being available.
+
+This behavior is consistent with:
+
+``` text
+0x01 = XLDA
+0x02 = GDA
+0x04 = TDA
+```
+
+rather than the mapping used by the component.
+
+## Fix
+
+The data-ready tests should be:
+
+``` cpp
+if (this->gyro_odr_ != LSM6DS_ODR_OFF && (status & 0x02)) {  // GDA
+    // read gyroscope
+}
+
+if (this->accel_odr_ != LSM6DS_ODR_OFF && (status & 0x01)) {  // XLDA
+    // read accelerometer
+}
+```
+
+Temperature handling remains unchanged:
+
+``` cpp
+if (status & 0x04) {  // TDA
+    // read temperature
+}
+```
+
+## Validation
+
+After correcting the masks, with the accelerometer configured at 104 Hz
+and the gyroscope disabled:
+
+-   accelerometer X/Y/Z values update normally;
+-   no gyroscope values are read/published;
+-   temperature continues to update normally;
+-   downstream pitch/roll calculations operate normally.
+
+The correction is present in:
+
+``` text
+7adb22de2 lsm6ds: fix swapped accel and gyro status bits
+```
+
+## Related changes
+
+During the investigation two related improvements were also made:
+
+``` text
+41cb715d6 lsm6ds: expose OFF output data rate
+3b86faa44 lsm6ds: skip reads for disabled sensors
+```
+
+Diagnostic commits used to establish the register behavior were:
+
+``` text
+e2d4b947e lsm6ds: add temporary status diagnostics
+53218bd4d lsm6ds: raise temporary status diagnostic to warning
+```
+
+These changes are separable from the XLDA/GDA mask correction itself.
+
+## Scope
+
+This bug was discovered while investigating a separate ESP32-C6
+interrupt-watchdog issue.
+
+No claim is currently made that the reversed XLDA/GDA masks caused those
+watchdog resets. The status-register mapping error is independently
+reproducible and confirmed by the data-ready behavior described above.