feat: X3 gyroscope-based tilt page turning via QMI8658 IMU (#1636)

Co-authored-by: justinian <juicecutlus@gmail.com> Co-authored-by: Vincent Politzer <vincent@skipwithjoy.com>
2026-04-29 15:29:33 -04:00
parent bc9651b664
commit 5d2e5596b4
31 changed files with 524 additions and 134 deletions
@@ -0,0 +1,234 @@
+#include "HalTiltSensor.h"
+
+#include <Logging.h>
+
+HalTiltSensor halTiltSensor;  // Singleton instance
+
+bool HalTiltSensor::writeReg(uint8_t reg, uint8_t val) const {
+  Wire.beginTransmission(_i2cAddr);
+  Wire.write(reg);
+  Wire.write(val);
+  return Wire.endTransmission() == 0;
+}
+
+bool HalTiltSensor::readReg(uint8_t reg, uint8_t* val) const {
+  Wire.beginTransmission(_i2cAddr);
+  Wire.write(reg);
+  if (Wire.endTransmission(false) != 0) {
+    return false;
+  }
+  Wire.requestFrom(_i2cAddr, (uint8_t)1);
+  if (Wire.available() < 1) {
+    return false;
+  }
+  *val = Wire.read();
+  return true;
+}
+
+bool HalTiltSensor::readGyro(float& gx, float& gy, float& gz) const {
+  Wire.beginTransmission(_i2cAddr);
+  Wire.write(REG_GX_L);  // Start reading at Gyro X Low
+  if (Wire.endTransmission(false) != 0) {
+    return false;
+  }
+
+  Wire.requestFrom(_i2cAddr, (uint8_t)6);
+  if (Wire.available() < 6) {
+    return false;
+  }
+
+  auto readInt16 = [&]() -> int16_t {
+    const uint8_t lo = Wire.read();
+    const uint8_t hi = Wire.read();
+    return static_cast<int16_t>((hi << 8) | lo);
+  };
+
+  // If Full Scale is ±512 dps, the scale factor is 32768 / 512 = 64 LSB/dps
+  constexpr float SCALE = 1.0f / 64.0f;
+  gx = readInt16() * SCALE;
+  gy = readInt16() * SCALE;
+  gz = readInt16() * SCALE;
+  return true;
+}
+
+void HalTiltSensor::begin() {
+  if (!gpio.deviceIsX3()) {
+    _available = false;
+    return;
+  }
+
+  // Try primary address, then alternate
+  uint8_t whoami = 0;
+  _i2cAddr = I2C_ADDR_QMI8658;
+  if (!readReg(QMI8658_WHO_AM_I_REG, &whoami) || whoami != QMI8658_WHO_AM_I_VALUE) {
+    _i2cAddr = I2C_ADDR_QMI8658_ALT;
+    if (!readReg(QMI8658_WHO_AM_I_REG, &whoami) || whoami != QMI8658_WHO_AM_I_VALUE) {
+      LOG_ERR("GYR", "QMI8658 IMU not found");
+      _available = false;
+      return;
+    }
+  }
+
+  LOG_INF("GYR", "QMI8658 IMU found at 0x%02X", _i2cAddr);
+
+  if (!writeReg(REG_CTRL7, CTRL7_DISABLE_ALL) || !writeReg(REG_CTRL3, CTRL3_FS_512DPS | CTRL3_ODR_28HZ) ||
+      !writeReg(REG_CTRL1, CTRL1_BASE | CTRL1_SENSOR_DISABLE)) {
+    LOG_ERR("GYR", "QMI8658 register configuration failed");
+    _available = false;
+    return;
+  }
+
+  _available = true;
+  _initMs = millis();
+  _lastPollMs = millis();
+  LOG_INF("GYR", "QMI8658 gyro initialized and put to sleep");
+}
+
+bool HalTiltSensor::wake() {
+  if (!_available) {
+    return false;
+  }
+
+  // Wait for init to complete before waking
+  if ((millis() - _initMs) < SLEEP_STABILIZE_MS) {
+    return false;
+  }
+
+  if (writeReg(REG_CTRL1, CTRL1_BASE) && writeReg(REG_CTRL7, CTRL7_GYRO_ENABLE)) {
+    _lastPollMs = millis();
+    _lastTiltMs = millis();
+    _wakeMs = millis();
+    LOG_INF("GYR", "QMI8658 woke up");
+    return true;
+  } else {
+    LOG_ERR("GYR", "Failed to wake QMI8658");
+    return false;
+  }
+}
+
+bool HalTiltSensor::deepSleep() {
+  if (!_available) {
+    return false;
+  }
+
+  if ((millis() - _wakeMs) < SLEEP_STABILIZE_MS) {
+    return false;
+  }
+
+  if (writeReg(REG_CTRL7, CTRL7_DISABLE_ALL) && writeReg(REG_CTRL1, CTRL1_BASE | CTRL1_SENSOR_DISABLE)) {
+    // Clear any residual state so it doesn't immediately trigger upon waking
+    clearPendingEvents();
+    _inTilt = false;
+    LOG_INF("GYR", "QMI8658 entered sleep mode");
+    return true;
+  } else {
+    LOG_ERR("GYR", "Failed to put QMI8658 to sleep");
+    return false;
+  }
+}
+
+void HalTiltSensor::update(const uint8_t mode, const uint8_t orientation, const bool inReader) {
+  if (!_available) {
+    return;
+  }
+
+  // State machine: wake up or sleep based on the enabled flag
+  if ((mode != CrossPointTiltPageTurn::TILT_OFF) && !_isAwake) {
+    _isAwake = wake();
+    return;
+  } else if ((mode == CrossPointTiltPageTurn::TILT_OFF) && _isAwake) {
+    _isAwake = !deepSleep();
+    return;
+  }
+
+  // If disabled, skip the rest of the polling logic and avoid unnecessary I2C traffic in non-reader activities
+  if ((mode == CrossPointTiltPageTurn::TILT_OFF) || !inReader) {
+    return;
+  }
+
+  const unsigned long now = millis();
+  // Stabilization: discard readings during gyro startup transient
+  if ((now - _wakeMs) < WAKE_STABILIZE_MS) {
+    return;
+  }
+
+  if ((now - _lastPollMs) < POLL_INTERVAL_MS) {
+    return;
+  }
+  _lastPollMs = now;
+
+  float gx, gy, gz;
+  if (!readGyro(gx, gy, gz)) {
+    return;
+  }
+
+  // Map the gyro axis to left/right tilt based on reader orientation.
+  // On the X3 PCB: X axis = left/right in portrait, Y axis = left/right in landscape.
+  float tiltAxis;
+  switch (orientation) {
+    case CrossPointOrientation::PORTRAIT:
+      tiltAxis = mode == CrossPointTiltPageTurn::TILT_INVERTED ? -gx : gx;
+      break;
+    case CrossPointOrientation::INVERTED:
+      tiltAxis = mode == CrossPointTiltPageTurn::TILT_INVERTED ? gx : -gx;
+      break;
+    case CrossPointOrientation::LANDSCAPE_CW:
+      tiltAxis = mode == CrossPointTiltPageTurn::TILT_INVERTED ? gy : -gy;
+      break;
+    case CrossPointOrientation::LANDSCAPE_CCW:
+      tiltAxis = mode == CrossPointTiltPageTurn::TILT_INVERTED ? -gy : gy;
+      break;
+    default:
+      tiltAxis = gx;
+      break;
+  }
+
+  if (_inTilt) {
+    // Wait for device to return to neutral before allowing next trigger
+    if (fabsf(tiltAxis) < NEUTRAL_RATE_DPS) {
+      _inTilt = false;
+    }
+  } else {
+    // Check for new tilt gesture (with cooldown)
+    if ((now - _lastTiltMs) >= COOLDOWN_MS) {
+      if (tiltAxis > RATE_THRESHOLD_DPS) {
+        _tiltForwardEvent = true;
+        _hadActivity = true;
+        _inTilt = true;
+        _lastTiltMs = now;
+        LOG_INF("GYR", "Forward Trigger=(%.1f) dps", tiltAxis);
+      } else if (tiltAxis < -RATE_THRESHOLD_DPS) {
+        _tiltBackEvent = true;
+        _hadActivity = true;
+        _inTilt = true;
+        _lastTiltMs = now;
+        LOG_INF("GYR", "Backward Trigger=(%.1f) dps", tiltAxis);
+      }
+    }
+  }
+}
+
+bool HalTiltSensor::wasTiltedForward() {
+  const bool val = _tiltForwardEvent;
+  _tiltForwardEvent = false;
+  return val;
+}
+
+bool HalTiltSensor::wasTiltedBack() {
+  const bool val = _tiltBackEvent;
+  _tiltBackEvent = false;
+  return val;
+}
+
+bool HalTiltSensor::hadActivity() {
+  const bool val = _hadActivity;
+  _hadActivity = false;
+  return val;
+}
+
+void HalTiltSensor::clearPendingEvents() {
+  _tiltForwardEvent = false;
+  _tiltBackEvent = false;
+  _hadActivity = false;
+  // Intentionally preserve _inTilt so a held tilt doesn't retrigger on next poll
+}
@@ -0,0 +1,100 @@
+#pragma once
+
+#include <Arduino.h>
+#include <Wire.h>
+
+#include "HalGPIO.h"
+
+// TODO: Move enums into new header and share with CrossPointSettings.h
+namespace CrossPointOrientation {
+enum Value : uint8_t { PORTRAIT = 0, LANDSCAPE_CW = 1, INVERTED = 2, LANDSCAPE_CCW = 3 };
+}
+
+namespace CrossPointTiltPageTurn {
+enum Value : uint8_t { TILT_OFF = 0, TILT_NORMAL = 1, TILT_INVERTED = 2 };
+}
+
+class HalTiltSensor;
+extern HalTiltSensor halTiltSensor;  // Singleton
+
+class HalTiltSensor {
+  bool _available = false;
+  uint8_t _i2cAddr = 0;
+
+  // Tilt gesture state machine
+  bool _tiltForwardEvent = false;  // Consumed by wasTiltedForward()
+  bool _tiltBackEvent = false;     // Consumed by wasTiltedBack()
+  bool _hadActivity = false;       // Non-consuming flag for sleep timer
+  bool _inTilt = false;            // Currently tilted past threshold
+  bool _isAwake = false;           // Tracks power state
+  unsigned long _initMs = 0;       // Timestamp of sensor init
+  unsigned long _lastTiltMs = 0;   // Debounce / cooldown
+  unsigned long _wakeMs = 0;       // Timestamp of last wake() for stabilization
+
+  // Tuning constants
+  static constexpr float RATE_THRESHOLD_DPS = 270.0f;      // Deg/sec speed to trigger flick
+  static constexpr float NEUTRAL_RATE_DPS = 50.0f;         // Must stop moving below this rate before next trigger
+  static constexpr unsigned long COOLDOWN_MS = 600;        // Minimum ms between triggers
+  static constexpr unsigned long POLL_INTERVAL_MS = 50;    // 20 Hz polling
+  static constexpr unsigned long WAKE_STABILIZE_MS = 300;  // Ignore readings after wake
+  static constexpr unsigned long SLEEP_STABILIZE_MS = 15;  // Sleep turn on/off delay
+
+  mutable unsigned long _lastPollMs = 0;
+
+  // --- QMI8658 registers ---
+  static constexpr uint8_t REG_CTRL1 = 0x02;
+  static constexpr uint8_t REG_CTRL3 = 0x04;
+  static constexpr uint8_t REG_CTRL7 = 0x08;
+  static constexpr uint8_t REG_GX_L = 0x3B;
+
+  // --- Register Bit Flags ---
+
+  // REG_CTRL1 (0x02)
+  static constexpr uint8_t CTRL1_BIG_ENDIAN = (1 << 5);                     // 0x20: Default state (1 = Big Endian)
+  static constexpr uint8_t CTRL1_AUTO_INC = (1 << 6);                       // 0x40: Enable address auto-increment
+  static constexpr uint8_t CTRL1_SENSOR_DISABLE = (1 << 0);                 // 0x01: Power down sensor engine
+  static constexpr uint8_t CTRL1_BASE = CTRL1_AUTO_INC | CTRL1_BIG_ENDIAN;  // 0x60
+
+  // REG_CTRL3 (0x04) - Gyro Config
+  static constexpr uint8_t CTRL3_FS_512DPS = (0b101 << 4);  // Bits 6:4 = 101
+  static constexpr uint8_t CTRL3_ODR_28HZ = 0b1000;         // Bits 3:0 = 1000 (28.025 Hz)
+
+  // REG_CTRL7 (0x08) - Enable
+  static constexpr uint8_t CTRL7_DISABLE_ALL = 0x00;
+  static constexpr uint8_t CTRL7_GYRO_ENABLE = (1 << 1);  // Bit 1 = 1
+
+  bool writeReg(uint8_t reg, uint8_t val) const;
+  bool readReg(uint8_t reg, uint8_t* val) const;
+  bool readGyro(float& gx, float& gy, float& gz) const;
+
+ public:
+  // Call after gpio.begin() and powerManager.begin() (I2C already initialised for X3)
+  void begin();
+
+  // Enables the QMI8658 internal sensor engine
+  bool wake();
+
+  // Puts the QMI8658 into a low-power standby state
+  bool deepSleep();
+
+  // True if the QMI8658 IMU is present on this device
+  bool isAvailable() const { return _available; }
+
+  // Poll the accelerometer and update tilt gesture state.
+  void update(const uint8_t mode, const uint8_t orientation, const bool inReader);
+
+  // Returns true once per tilt-forward gesture (next page direction).
+  // Consumed on read — subsequent calls return false until next gesture.
+  bool wasTiltedForward();
+
+  // Returns true once per tilt-back gesture (previous page direction).
+  // Consumed on read.
+  bool wasTiltedBack();
+
+  // Non-consuming: true if any tilt activity occurred since last call.
+  // Used to reset the auto-sleep inactivity timer.
+  bool hadActivity();
+
+  // Discard any pending tilt events (call when leaving reader or disabling tilt).
+  void clearPendingEvents();
+};