tmc51x0_comm_interface.hpp

Go to the documentation of this file.

 
#pragma once
#include <algorithm>
#include <array>
#include <cstdarg>
#include <cstdint>
#include <cstdio>
 
#include "tmc51x0_result.hpp"
 
namespace tmc51x0 {
 
enum class LogLevel : uint8_t {
  Error = 0,
  Warn = 1,
  Info = 2,
  Debug = 3,
  Verbose = 4
};
 
#ifndef TMC51X0_DISABLE_DEBUG_LOGGING
// Optional compile-time log level filter:
// 0=Error, 1=Warn, 2=Info, 3=Debug, 4=Verbose.
// If not defined, everything up to Verbose is compiled in.
#ifndef TMC51X0_LOG_LEVEL
#define TMC51X0_LOG_LEVEL 4
#endif
 
// Level-specific macros provide best compile-time dead-stripping.
#if TMC51X0_LOG_LEVEL >= 0
#define TMC51X0_LOGE(comm_obj, tag, ...) (comm_obj).LogDebug(::tmc51x0::LogLevel::Error, tag, __VA_ARGS__)
#else
#define TMC51X0_LOGE(comm_obj, tag, ...) ((void)0)
#endif
 
#if TMC51X0_LOG_LEVEL >= 1
#define TMC51X0_LOGW(comm_obj, tag, ...) (comm_obj).LogDebug(::tmc51x0::LogLevel::Warn, tag, __VA_ARGS__)
#else
#define TMC51X0_LOGW(comm_obj, tag, ...) ((void)0)
#endif
 
#if TMC51X0_LOG_LEVEL >= 2
#define TMC51X0_LOGI(comm_obj, tag, ...) (comm_obj).LogDebug(::tmc51x0::LogLevel::Info, tag, __VA_ARGS__)
#else
#define TMC51X0_LOGI(comm_obj, tag, ...) ((void)0)
#endif
 
#if TMC51X0_LOG_LEVEL >= 3
#define TMC51X0_LOGD(comm_obj, tag, ...) (comm_obj).LogDebug(::tmc51x0::LogLevel::Debug, tag, __VA_ARGS__)
#else
#define TMC51X0_LOGD(comm_obj, tag, ...) ((void)0)
#endif
 
#if TMC51X0_LOG_LEVEL >= 4
#define TMC51X0_LOGV(comm_obj, tag, ...) (comm_obj).LogDebug(::tmc51x0::LogLevel::Verbose, tag, __VA_ARGS__)
#else
#define TMC51X0_LOGV(comm_obj, tag, ...) ((void)0)
#endif
 
// Backwards-compatible macro: routes to the level-specific macros when possible.
// If `level` is a constant `LogLevel` (recommended), the compiler will fold the branch.
// NOLINTNEXTLINE(cppcoreguidelines-macro-usage) - Intentional: compile-time logging control
#define TMC51X0_LOG_DEBUG(comm_obj, level, tag, ...)                           \
  do {                                                                         \
    const int _lvl = static_cast<int>(level);                                  \
    if (_lvl <= 0) {                                                           \
      TMC51X0_LOGE(comm_obj, tag, __VA_ARGS__);                                \
    } else if (_lvl == 1) {                                                    \
      TMC51X0_LOGW(comm_obj, tag, __VA_ARGS__);                                \
    } else if (_lvl == 2) {                                                    \
      TMC51X0_LOGI(comm_obj, tag, __VA_ARGS__);                                \
    } else if (_lvl == 3) {                                                    \
      TMC51X0_LOGD(comm_obj, tag, __VA_ARGS__);                                \
    } else {                                                                   \
      TMC51X0_LOGV(comm_obj, tag, __VA_ARGS__);                                \
    }                                                                          \
  } while (0)
#else
// Debug logging disabled - optimize out completely (arguments not evaluated)
// NOLINTNEXTLINE(cppcoreguidelines-macro-usage) - Intentional: compile-time
// logging control
#define TMC51X0_LOGE(comm_obj, tag, ...) ((void)0)
#define TMC51X0_LOGW(comm_obj, tag, ...) ((void)0)
#define TMC51X0_LOGI(comm_obj, tag, ...) ((void)0)
#define TMC51X0_LOGD(comm_obj, tag, ...) ((void)0)
#define TMC51X0_LOGV(comm_obj, tag, ...) ((void)0)
#define TMC51X0_LOG_DEBUG(comm_obj, level, tag, ...) ((void)0)
#endif
 
enum class CommMode : uint8_t {
  SPI, 
  UART 
};
 
enum class TMC51x0CtrlPin : uint8_t {
  // Basic control pins (always available)
  EN,   
  DIR,  
  STEP, 
 
  // Reference switch pins (when SD_MODE=0, internal ramp generator mode)
  // Same physical pins as STEP/DIR but used as reference switches
  REFL_STEP, 
  REFR_DIR,  
 
  // Diagnostic output pins / UART pins (mode-dependent)
  DIAG0, 
  DIAG1, 
 
  // Encoder input pins (when SD_MODE=0, internal ramp generator mode)
  // Same physical pins as DC Step pins but used as encoder inputs
  ENCA, 
  ENCB, 
  ENCN, 
 
  // DC Step control pins (when SD_MODE=1, SPI_MODE=1, external step/dir mode)
  // Same physical pins as encoder pins but used for DC Step control
  DCEN, 
  DCIN, 
  DCO,  
 
  // Clock pin (optional external clock)
  CLK, 
 
  // Mode configuration pins (if made available as control pins)
  // WARNING: These pins are typically hardwired and read at startup.
  // Only use these if you have connected these pins to GPIO outputs for dynamic
  // control.
  // Changing these pins requires a chip reset to take effect.
  SPI_MODE, 
  SD_MODE   
};
 
enum class GpioSignal : uint8_t {
  INACTIVE = 0, 
  ACTIVE = 1    
};
 
struct PinActiveLevels {
  // Basic control pins (per TMC51x0 datasheet)
  bool en{false};  
  bool dir{true};  
  bool step{true}; 
 
  // Reference switch pins (when SD_MODE=0)
  bool ref_left{
      false}; 
  bool ref_right{
      false}; 
 
  // Diagnostic pins (read-only outputs from TMC51x0 - not typically configured)
  bool diag0{true}; 
  bool diag1{true}; 
 
  // Encoder pins (when SD_MODE=0, read-only inputs)
  bool enca{true}; 
  bool encb{true}; 
  bool encn{true}; 
 
  // DC Step pins (when SD_MODE=1, SPI_MODE=1)
  bool dcen{true}; 
  bool dcin{true}; 
  bool dco{true};  
 
  // Clock pin
  bool clk{
      true}; 
 
  // Mode configuration pins (if available as control pins)
  bool spi_mode{true}; 
  bool sd_mode{
      true}; 
 
  [[nodiscard]] bool GetActiveLevel(TMC51x0CtrlPin pin) const noexcept {
    switch (pin) {
    case TMC51x0CtrlPin::EN:
      return en;
    case TMC51x0CtrlPin::DIR:
      return dir;
    case TMC51x0CtrlPin::STEP:
      return step;
    case TMC51x0CtrlPin::REFL_STEP:
      return ref_left;
    case TMC51x0CtrlPin::REFR_DIR:
      return ref_right;
    case TMC51x0CtrlPin::DIAG0:
      return diag0;
    case TMC51x0CtrlPin::DIAG1:
      return diag1;
    case TMC51x0CtrlPin::ENCA:
      return enca;
    case TMC51x0CtrlPin::ENCB:
      return encb;
    case TMC51x0CtrlPin::ENCN:
      return encn;
    case TMC51x0CtrlPin::DCEN:
      return dcen;
    case TMC51x0CtrlPin::DCIN:
      return dcin;
    case TMC51x0CtrlPin::DCO:
      return dco;
    case TMC51x0CtrlPin::CLK:
      return clk;
    case TMC51x0CtrlPin::SPI_MODE:
      return spi_mode;
    case TMC51x0CtrlPin::SD_MODE:
      return sd_mode;
    default:
      return true; // Default to HIGH
    }
  }
 
  void SetActiveLevel(TMC51x0CtrlPin pin, bool active_level) noexcept {
    switch (pin) {
    case TMC51x0CtrlPin::EN:
      en = active_level;
      break;
    case TMC51x0CtrlPin::DIR:
      dir = active_level;
      break;
    case TMC51x0CtrlPin::STEP:
      step = active_level;
      break;
    case TMC51x0CtrlPin::REFL_STEP:
      ref_left = active_level;
      break;
    case TMC51x0CtrlPin::REFR_DIR:
      ref_right = active_level;
      break;
    case TMC51x0CtrlPin::DIAG0:
      diag0 = active_level;
      break;
    case TMC51x0CtrlPin::DIAG1:
      diag1 = active_level;
      break;
    case TMC51x0CtrlPin::ENCA:
      enca = active_level;
      break;
    case TMC51x0CtrlPin::ENCB:
      encb = active_level;
      break;
    case TMC51x0CtrlPin::ENCN:
      encn = active_level;
      break;
    case TMC51x0CtrlPin::DCEN:
      dcen = active_level;
      break;
    case TMC51x0CtrlPin::DCIN:
      dcin = active_level;
      break;
    case TMC51x0CtrlPin::DCO:
      dco = active_level;
      break;
    case TMC51x0CtrlPin::CLK:
      clk = active_level;
      break;
    case TMC51x0CtrlPin::SPI_MODE:
      spi_mode = active_level;
      break;
    case TMC51x0CtrlPin::SD_MODE:
      sd_mode = active_level;
      break;
    default:
      break;
    }
  }
};
 
struct TMC51x0PinConfig {
  // Basic control pins
  int en_pin{-1}; 
  int dir_pin{
      -1}; 
  int step_pin{
      -1}; 
 
  // Reference switch pins (when SD_MODE=0)
  int ref_left_pin{
      -1}; 
  int ref_right_pin{
      -1}; 
 
  // Diagnostic pins (read-only outputs from TMC51x0)
  int diag0_pin{-1}; 
  int diag1_pin{-1}; 
 
  // Encoder pins (when SD_MODE=0)
  int enc_a_pin{-1}; 
  int enc_b_pin{-1}; 
  int enc_n_pin{-1}; 
 
  // DC Step pins (when SD_MODE=1, SPI_MODE=1)
  int dc_in_pin{-1}; 
  int dc_en_pin{-1}; 
  int dc_out_pin{
      -1}; 
 
  // Clock pin
  int clk_pin{-1}; 
 
  // Mode configuration pins (if made available as control pins)
  // WARNING: These pins are typically hardwired and read at startup.
  // Only configure these if you have connected SPI_MODE (pin 22) and SD_MODE
  // (pin 21) to GPIO outputs for dynamic mode control. Changing these requires
  // a chip reset.
  int spi_mode_pin{-1}; 
  int sd_mode_pin{-1};  
 
  TMC51x0PinConfig() = default;
 
  TMC51x0PinConfig(int en, int dir = -1, int step = -1) noexcept
      : en_pin(en), dir_pin(dir), step_pin(step) {}
};
 
struct SpiStatus {
  uint8_t value; 
 
  static SpiStatus FromByte(uint8_t status_byte) noexcept {
    SpiStatus status{};
    status.value = status_byte;
    return status;
  }
 
  [[nodiscard]] bool HasError() const noexcept {
    return DriverError(); // Only bit 1 (driver_error) is an error; bit 0
                          // (reset) is informational
  }
 
  [[nodiscard]] bool ResetFlag() const noexcept { return (value & 0x01) != 0; }
 
  [[nodiscard]] bool DriverError() const noexcept {
    return (value & 0x02) != 0;
  }
 
  [[nodiscard]] bool StallGuard2() const noexcept {
    return (value & 0x04) != 0;
  }
 
  [[nodiscard]] bool Standstill() const noexcept { return (value & 0x08) != 0; }
 
  [[nodiscard]] bool VelocityReached() const noexcept {
    return (value & 0x10) != 0;
  }
 
  [[nodiscard]] bool PositionReached() const noexcept {
    return (value & 0x20) != 0;
  }
 
  [[nodiscard]] bool StopLeft() const noexcept { return (value & 0x40) != 0; }
 
  [[nodiscard]] bool StopRight() const noexcept { return (value & 0x80) != 0; }
 
  void FormatStatusBits(char *out, size_t cap) const noexcept {
    if (out == nullptr || cap == 0) return;
    std::snprintf(
        out, cap,
        "RST:%d STST:%d VEL:%d POS:%d STOP_L:%d STOP_R:%d SG2:%d DRV_ERR:%d",
        ResetFlag() ? 1 : 0, Standstill() ? 1 : 0, VelocityReached() ? 1 : 0,
        PositionReached() ? 1 : 0, StopLeft() ? 1 : 0, StopRight() ? 1 : 0,
        StallGuard2() ? 1 : 0, DriverError() ? 1 : 0);
  }
 
  [[nodiscard]] const char *ToString() const noexcept {
    // This is a simplified version - in practice, you'd want a buffer
    // For now, return a static description of key flags
    if (HasError()) {
      return "DRV_ERR"; // Only driver_error is an error
    }
    if (ResetFlag()) {
      return "RST"; // Reset is informational
    }
    return "OK";
  }
};
 
struct SpiCommand {
  union Frame {
    uint8_t bytes[5]; 
    struct {
      uint8_t
          address_byte; 
      uint8_t data_bytes[4]; 
    } fields;                
    uint64_t raw; 
  } frame;        
 
  [[nodiscard]] uint8_t GetAddress() const noexcept {
    return frame.fields.address_byte & 0x7F;
  }
 
  [[nodiscard]] bool IsWrite() const noexcept {
    return (frame.fields.address_byte & 0x80) != 0;
  }
 
  [[nodiscard]] uint32_t GetValue() const noexcept {
    return (static_cast<uint32_t>(frame.fields.data_bytes[0]) << 24) |
           (static_cast<uint32_t>(frame.fields.data_bytes[1]) << 16) |
           (static_cast<uint32_t>(frame.fields.data_bytes[2]) << 8) |
           static_cast<uint32_t>(frame.fields.data_bytes[3]);
  }
 
  void SetFrame(const uint8_t *bytes) noexcept {
    for (size_t i = 0; i < 5; ++i) {
      frame.bytes[i] = bytes[i];
    }
  }
 
  void GetFrame(uint8_t *bytes) const noexcept {
    for (size_t i = 0; i < 5; ++i) {
      bytes[i] = frame.bytes[i];
    }
  }
 
  static SpiCommand Read(uint8_t addr) noexcept {
    SpiCommand cmd{};
    cmd.frame.raw = 0;                           // Initialize to zero
    cmd.frame.fields.address_byte = addr & 0x7F; // Clear write bit (bit 7 = 0)
    // Data bytes are already zero (dummy data for read)
    return cmd;
  }
 
  static SpiCommand Write(uint8_t addr, uint32_t val) noexcept {
    SpiCommand cmd{};
    cmd.frame.fields.address_byte =
        (addr & 0x7F) | 0x80; // Set write bit (bit 7 = 1)
    cmd.frame.fields.data_bytes[0] =
        static_cast<uint8_t>((val >> 24) & 0xFF); // MSB
    cmd.frame.fields.data_bytes[1] = static_cast<uint8_t>((val >> 16) & 0xFF);
    cmd.frame.fields.data_bytes[2] = static_cast<uint8_t>((val >> 8) & 0xFF);
    cmd.frame.fields.data_bytes[3] = static_cast<uint8_t>(val & 0xFF); // LSB
    return cmd;
  }
};
 
struct SpiResponse {
  SpiStatus status; 
  uint32_t value; 
  bool success;   
};
 
static constexpr uint8_t calculateCrc8(const uint8_t *data,
                                       size_t length) noexcept {
  uint8_t crc = 0; // Initial value is zero per datasheet
 
  // Process each byte LSB to MSB
  for (size_t i = 0; i < length; ++i) {
    uint8_t current_byte = data[i];
 
    // Process each bit LSB to MSB (j=0 is LSB, j=7 is MSB)
    for (uint8_t j = 0; j < 8; ++j) {
      // Check: (CRC >> 7) XOR (current_byte & 0x01)
      // This XORs the MSB of CRC with the LSB of current_byte
      if (((crc >> 7) ^ (current_byte & 0x01)) != 0) {
        crc = (crc << 1) ^ 0x07; // Polynomial 0x07 (CRC8-ATM)
      } else {
        crc = (crc << 1);
      }
      current_byte = current_byte >> 1; // Shift to next bit (LSB to MSB)
    }
  }
 
  return crc;
}
 
enum class UartFrameType : uint8_t {
  WriteAccess, 
  ReadRequest, 
  ReadReply    
};
 
struct UartFrame {
  union Frame {
    uint8_t bytes[8]; 
 
    // Write Access Structure (8 bytes)
    struct {
      uint8_t sync_reserved; 
      uint8_t node_addr;     
      uint8_t rw_address;    
      uint8_t data_bytes[4]; 
      uint8_t crc;           
    } write_fields;
 
    // Read Request Structure (4 bytes)
    struct {
      uint8_t sync_reserved; 
      uint8_t node_addr;     
      uint8_t rw_address;    
      uint8_t crc;           
    } read_request_fields;
 
    // Read Reply Structure (8 bytes)
    struct {
      uint8_t sync_reserved; 
      uint8_t master_addr;   
      uint8_t reg_addr;      
      uint8_t data_bytes[4]; 
      uint8_t crc;           
    } read_reply_fields;
 
  } frame;
 
  UartFrameType type; 
 
  [[nodiscard]] size_t GetSize() const noexcept {
    return (type == UartFrameType::ReadRequest) ? 4 : 8;
  }
 
  [[nodiscard]] uint8_t GetAddress() const noexcept {
    if (type == UartFrameType::ReadReply) {
      return frame.read_reply_fields.reg_addr;
    }
    // For ReadRequest and WriteAccess, address is in the same byte (Byte 2)
    // Need to mask off RW bit (bit 7)
    return frame.write_fields.rw_address & 0x7F;
  }
 
  [[nodiscard]] bool IsWrite() const noexcept {
    return type == UartFrameType::WriteAccess;
  }
 
  [[nodiscard]] uint32_t GetValue() const noexcept {
    if (type == UartFrameType::ReadRequest) {
      return 0;
    }
    // Both WriteAccess and ReadReply have data at offset 3
    return (static_cast<uint32_t>(frame.write_fields.data_bytes[0]) << 24) |
           (static_cast<uint32_t>(frame.write_fields.data_bytes[1]) << 16) |
           (static_cast<uint32_t>(frame.write_fields.data_bytes[2]) << 8) |
           static_cast<uint32_t>(frame.write_fields.data_bytes[3]);
  }
 
  void CalculateCrc() noexcept {
    size_t frame_size = GetSize();
    size_t crc_length = frame_size - 1; // All bytes except CRC byte
 
    // Calculate CRC over bytes 0 to (frame_size-2)
    uint8_t calculated_crc = calculateCrc8(frame.bytes, crc_length);
 
    // Set CRC in the last byte
    frame.bytes[frame_size - 1] = calculated_crc;
  }
 
  [[nodiscard]] bool VerifyCrc() const noexcept {
    size_t frame_size = GetSize();
    size_t crc_length = frame_size - 1; // All bytes except CRC byte
 
    uint8_t calculated_crc = calculateCrc8(frame.bytes, crc_length);
 
    // Compare with received CRC (last byte)
    return calculated_crc == frame.bytes[frame_size - 1];
  }
 
  void SetFrame(const uint8_t *bytes, UartFrameType frame_type) noexcept {
    type = frame_type;
    size_t frame_size = GetSize();
    for (size_t i = 0; i < frame_size; ++i) {
      frame.bytes[i] = bytes[i];
    }
    // Zero out unused bytes for safety (if any)
    if (frame_size < 8) {
      for (size_t i = frame_size; i < 8; ++i) {
        frame.bytes[i] = 0;
      }
    }
  }
 
  void GetFrame(uint8_t *bytes) const noexcept {
    size_t frame_size = GetSize();
    for (size_t i = 0; i < frame_size; ++i) {
      bytes[i] = frame.bytes[i];
    }
  }
 
  static UartFrame Write(uint8_t node_addr, uint8_t reg_addr,
                         uint32_t value) noexcept {
    UartFrame uart_frame{};
    uart_frame.type = UartFrameType::WriteAccess;
 
    // Byte 0: Sync nibble (0x05)
    uart_frame.frame.write_fields.sync_reserved = 0x05;
 
    // Byte 1: Node Address
    uart_frame.frame.write_fields.node_addr = node_addr;
 
    // Byte 2: RW bit (1) + Register Address
    uart_frame.frame.write_fields.rw_address = (reg_addr & 0x7F) | 0x80;
 
    // Bytes 3-6: Data (MSB-first)
    uart_frame.frame.write_fields.data_bytes[0] =
        static_cast<uint8_t>((value >> 24) & 0xFF);
    uart_frame.frame.write_fields.data_bytes[1] =
        static_cast<uint8_t>((value >> 16) & 0xFF);
    uart_frame.frame.write_fields.data_bytes[2] =
        static_cast<uint8_t>((value >> 8) & 0xFF);
    uart_frame.frame.write_fields.data_bytes[3] =
        static_cast<uint8_t>(value & 0xFF);
 
    // Byte 7: CRC (calculated)
    uart_frame.CalculateCrc();
 
    return uart_frame;
  }
 
  static UartFrame ReadRequest(uint8_t node_addr, uint8_t reg_addr) noexcept {
    UartFrame uart_frame{};
    uart_frame.type = UartFrameType::ReadRequest;
 
    // Byte 0: Sync nibble (0x05)
    uart_frame.frame.read_request_fields.sync_reserved = 0x05;
 
    // Byte 1: Node Address
    uart_frame.frame.read_request_fields.node_addr = node_addr;
 
    // Byte 2: RW bit (0) + Register Address
    uart_frame.frame.read_request_fields.rw_address = reg_addr & 0x7F;
 
    // Byte 3: CRC (calculated)
    uart_frame.CalculateCrc();
 
    return uart_frame;
  }
 
  static UartFrame ReadReply(const uint8_t *bytes) noexcept {
    UartFrame uart_frame{};
    uart_frame.type = UartFrameType::ReadReply;
    uart_frame.SetFrame(bytes, UartFrameType::ReadReply);
    return uart_frame;
  }
 
  [[nodiscard]] bool IsValid() const noexcept {
    if (!VerifyCrc()) {
      return false;
    }
    if (type == UartFrameType::ReadReply) {
      // Verify Master Address (Byte 1) is 0xFF
      return frame.read_reply_fields.master_addr == 0xFF;
    }
    return true;
  }
};
 
template <typename Derived> class CommInterface {
public:
  CommInterface() noexcept = default;
 
  [[nodiscard]] CommMode GetMode() const noexcept {
    return static_cast<const Derived *>(this)->GetMode();
  }
 
  Result<uint32_t> ReadRegister(uint8_t address,
                                uint8_t address_param = 0) noexcept {
    uint32_t value = 0;
    return static_cast<Derived *>(this)->ReadRegister(address,
                                                      address_param);
  }
 
  Result<void> WriteRegister(uint8_t address, uint32_t value,
                             uint8_t address_param = 0) noexcept {
    return static_cast<Derived *>(this)->WriteRegister(address, value,
                                                       address_param);
  }
 
  Result<void> GpioSet(TMC51x0CtrlPin pin, GpioSignal signal) noexcept {
    return static_cast<Derived *>(this)->GpioSet(pin, signal);
  }
 
  Result<GpioSignal> GpioRead(TMC51x0CtrlPin pin) noexcept {
    return static_cast<Derived *>(this)->GpioRead(pin);
  }
 
  Result<void> GpioSetActive(TMC51x0CtrlPin pin) noexcept {
    return GpioSet(pin, GpioSignal::ACTIVE);
  }
 
  Result<void> GpioSetInactive(TMC51x0CtrlPin pin) noexcept {
    return GpioSet(pin, GpioSignal::INACTIVE);
  }
 
protected:
  void DebugLog(int level, const char *tag, const char *format,
                va_list args) noexcept {
    static_cast<Derived *>(this)->DebugLog(level, tag, format, args);
  }
 
public:
  void DelayMs(uint32_t ms) noexcept {
    static_cast<Derived *>(this)->DelayMs(ms);
  }
 
  void DelayUs(uint32_t us) noexcept {
    static_cast<Derived *>(this)->DelayUs(us);
  }
 
  Result<void> SetPowerEnabled(bool enabled) noexcept {
    (void)enabled;
    return Result<void>(ErrorCode::UNSUPPORTED);
  }
 
  Result<void> PowerCycle(uint32_t power_off_ms = 20,
                          uint32_t power_on_settle_ms = 20) noexcept {
    auto r_off = SetPowerEnabled(false);
    if (!r_off) {
      return r_off;
    }
    DelayMs(power_off_ms);
 
    auto r_on = SetPowerEnabled(true);
    if (!r_on) {
      return r_on;
    }
    DelayMs(power_on_settle_ms);
    return Result<void>();
  }
 
  Result<void> SetClkFreq(uint32_t frequency_hz) noexcept {
    // Default implementation returns UNSUPPORTED (not supported / using
    // internal clock) Derived classes can override this if they support
    // external clock generation When frequency_hz = 0, this means "use internal
    // clock" (set CLK pin to GND)
    (void)frequency_hz; // Suppress unused parameter warning
    return Result<void>(ErrorCode::UNSUPPORTED);
  }
 
protected:
  ~CommInterface() = default;
 
  // Allow moving
  CommInterface(CommInterface &&) = default;
  CommInterface &operator=(CommInterface &&) = default;
 
public:
  // Prevent copying
  CommInterface(const CommInterface &) = delete;
  CommInterface &operator=(const CommInterface &) = delete;
#ifndef TMC51X0_DISABLE_DEBUG_LOGGING
  void LogDebug(int level, const char *tag, const char *format, ...) noexcept {
    va_list args{}; // va_start will properly initialize this
    va_start(args, format);
    // Do not allocate (no std::string) just to enforce a newline.
    // Platform log backends (ESP-IDF, etc.) typically add their own newline.
    DebugLog(level, tag, format, args);
    va_end(args);
  }
 
  void LogDebug(LogLevel level, const char *tag, const char *format, ...) noexcept {
    va_list args{}; // va_start will properly initialize this
    va_start(args, format);
    DebugLog(static_cast<int>(level), tag, format, args);
    va_end(args);
  }
#else
  // Debug logging disabled - function optimized out completely
  inline void LogDebug(int /*level*/, const char * /*tag*/,
                       const char * /*format*/, ...) noexcept {
    // Empty function body - all logging optimized out
  }
 
  // Debug logging disabled - overload also optimized out completely
  inline void LogDebug(LogLevel /*level*/, const char * /*tag*/,
                       const char * /*format*/, ...) noexcept {
    // Empty function body - all logging optimized out
  }
#endif
};
 
template <typename Derived>
class SpiCommInterface : public CommInterface<Derived> {
public:
  //--------------------------------------------------------------------------------
  // Configuration
  //--------------------------------------------------------------------------------
  // Maximum supported daisy-chain size for static SPI scratch buffers.
  // Default keeps RAM small while supporting common chains.
  // Override at compile time if you have longer chains:
  //   #define TMC51X0_SPI_MAX_CHAIN_DEVICES 255
  // Note: scratch buffers are sized for (max_devices+2)*5 bytes to support
  // AutoDetectChainLength() and the "beyond last device" probe.
#ifndef TMC51X0_SPI_MAX_CHAIN_DEVICES
#define TMC51X0_SPI_MAX_CHAIN_DEVICES 8
#endif
 
  static_assert(TMC51X0_SPI_MAX_CHAIN_DEVICES >= 1,
                "TMC51X0_SPI_MAX_CHAIN_DEVICES must be >= 1");
  static_assert(TMC51X0_SPI_MAX_CHAIN_DEVICES <= 255,
                "TMC51X0_SPI_MAX_CHAIN_DEVICES must be <= 255");
 
  static constexpr size_t kSpiScratchBytes =
      static_cast<size_t>(TMC51X0_SPI_MAX_CHAIN_DEVICES + 2U) * 5U;
 
  SpiCommInterface() noexcept : CommInterface<Derived>() {}
 
  void SetDaisyChainLength(uint8_t total_length) noexcept {
    total_chain_length_ = total_length;
    user_specified_chain_length_ = total_length; // Track user-specified value
    chain_length_verified_ = false;              // Reset verification flag
  }
 
  [[nodiscard]] uint8_t GetDaisyChainLength() const noexcept {
    return total_chain_length_;
  }
 
  uint8_t AutoDetectChainLength(uint8_t max_devices = 8) noexcept {
    if (max_devices == 0) {
      max_devices = 8; // Default to 8 devices
    }
    if (max_devices > TMC51X0_SPI_MAX_CHAIN_DEVICES) {
      max_devices = TMC51X0_SPI_MAX_CHAIN_DEVICES;
    }
 
    // Create a unique command pattern that we can reliably identify when it
    // loops back Use a read command to a register that's safe to read (GSTAT =
    // 0x00) But we'll use a unique address pattern to make it more distinctive
    // Actually, let's use a write command with a unique value that we can
    // recognize But writes modify state... better to use read with a unique
    // address
 
    // Best approach: Use a read command with a distinctive address
    // We'll use address 0x73 (last register) which is safe to read
    // The command pattern will be: [0x73] [0x00] [0x00] [0x00] [0x00]
    // This is distinctive enough to identify
 
    // Actually, even better: Use a read to an address that's unlikely to appear
    // in device responses Let's use 0x73 (last register address) - this is
    // distinctive
    SpiCommand cmd = SpiCommand::Read(0x73); // Read last register (0x73)
 
    // Get the command frame bytes so we can search for it
    uint8_t cmd_bytes[5];
    cmd.GetFrame(cmd_bytes);
 
    // Send command to position (max_devices+1) - beyond the last device
    // Total transfer: (max_devices+2)*40 bits to ensure we capture loopback
    size_t transfer_bytes = static_cast<size_t>(max_devices + 2) * 5;
    if (transfer_bytes > kSpiScratchBytes) {
      // Should not happen due to clamping, but keep it safe.
      return 0;
    }
 
    // No heap: use static scratch buffers sized by TMC51X0_SPI_MAX_CHAIN_DEVICES.
    std::fill(tx_scratch_.begin(), tx_scratch_.end(), 0);
    std::fill(rx_scratch_.begin(), rx_scratch_.end(), 0);
    uint8_t *tx_buf = tx_scratch_.data();
    uint8_t *rx_buf = rx_scratch_.data();
 
    // Place command at the beginning (bytes 0-4)
    cmd.GetFrame(tx_buf);
    // Rest is padding (zeros) - already initialized to 0
 
    TMC51X0_LOG_DEBUG(
        *static_cast<Derived *>(this), 2, "SPI",
        "AutoDetectChainLength: Probing up to %u devices, transfer_bytes=%zu, "
        "cmd_pattern=%02X %02X %02X %02X %02X",
        max_devices, transfer_bytes, cmd_bytes[0], cmd_bytes[1], cmd_bytes[2],
        cmd_bytes[3], cmd_bytes[4]);
 
    // Perform SPI transfer
    if (!SpiTransfer(tx_buf, rx_buf, transfer_bytes)) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "AutoDetectChainLength: SPI transfer failed");
      return 0;
    }
 
    // Search for our exact command pattern in the received data
    // The command loops back after n*40 bits, appearing at offset n*5 bytes
    // Since each device delays data by 40 clocks, our command should appear
    // unmodified at the loopback point
 
    uint8_t detected_length = 0;
 
    // Search backwards from max_devices to find where our command appears
    // For n devices, our command appears at offset n*5 after looping back
    // We require an EXACT match of all 5 bytes to confirm loopback
    for (uint8_t n = max_devices; n >= 1; --n) {
      size_t loopback_offset = static_cast<size_t>(n) * 5;
 
      if (loopback_offset + 4 < transfer_bytes) {
        // Check if the 5-byte chunk at loopback_offset matches our command
        // pattern EXACTLY This is the only reliable way to confirm the command
        // looped back correctly
        bool exact_match = true;
 
        for (uint8_t i = 0; i < 5; ++i) {
          if (rx_buf[loopback_offset + i] != cmd_bytes[i]) {
            exact_match = false;
            break;
          }
        }
 
        if (exact_match) {
          // Found our exact command pattern! This confirms it looped back after
          // n devices
          detected_length = n;
          TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 2, "SPI",
                            "AutoDetectChainLength: Found EXACT command "
                            "pattern match at offset "
                            "%zu (expected for n=%u), chain length = %u",
                            loopback_offset, n, detected_length);
          break;
        }
      }
    }
 
    // If exact match failed, log debug info to help diagnose
    if (detected_length == 0) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "AutoDetectChainLength: Exact command pattern not "
                        "found in received data");
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 3, "SPI",
          "AutoDetectChainLength: Expected pattern: %02X %02X %02X %02X %02X",
          cmd_bytes[0], cmd_bytes[1], cmd_bytes[2], cmd_bytes[3], cmd_bytes[4]);
 
      // Log first few potential loopback positions for debugging
      for (uint8_t n = 1; n <= 3 && n <= max_devices; ++n) {
        size_t loopback_offset = static_cast<size_t>(n) * 5;
        if (loopback_offset + 4 < transfer_bytes) {
          TMC51X0_LOG_DEBUG(
              *static_cast<Derived *>(this), 3, "SPI",
              "AutoDetectChainLength: At offset %zu (n=%u): %02X %02X %02X "
              "%02X %02X",
              loopback_offset, n, rx_buf[loopback_offset],
              rx_buf[loopback_offset + 1], rx_buf[loopback_offset + 2],
              rx_buf[loopback_offset + 3], rx_buf[loopback_offset + 4]);
        }
      }
    }
 
    // If we detected a length, set it (but don't overwrite user-specified value
    // yet) The caller will handle verification and update
    if (detected_length > 0) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 2, "SPI",
                        "AutoDetectChainLength: Detected chain length = %u",
                        detected_length);
      // Only update if not user-specified, or if user-specified value matches
      if (user_specified_chain_length_ == 0 ||
          user_specified_chain_length_ == detected_length) {
        total_chain_length_ = detected_length;
      }
    } else {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "AutoDetectChainLength: Command pattern not found, "
                        "assuming single chip");
      // Don't reset total_chain_length_ if it was already set (e.g., to 1 for
      // single-chip mode) Only reset if it was 0 and user hasn't specified a
      // length
      if (user_specified_chain_length_ == 0 && total_chain_length_ == 0) {
        // Keep it at 0 - caller will handle single-chip case
      }
    }
 
    return detected_length;
  }
 
  [[nodiscard]] CommMode GetMode() const noexcept { return CommMode::SPI; }
 
  Result<void> SpiTransfer(const uint8_t *tx, uint8_t *rx,
                           size_t length) noexcept {
    return static_cast<Derived *>(this)->SpiTransfer(tx, rx, length);
  }
 
  Result<uint32_t> ReadRegister(uint8_t address,
                                uint8_t daisy_chain_position = 0) noexcept {
    uint32_t value = 0;
    // Log function call with arguments (level 3 = DEBUG, only shows at DEBUG
    // log level)
    if (daisy_chain_position > 0) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                        "ReadRegister(0x%02X, daisy_chain=%u)", address,
                        daisy_chain_position);
    } else {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                        "ReadRegister(0x%02X)", address);
    }
 
    // CRITICAL: Chain length MUST be known for correct response extraction
    // Ensure chain length is known and verified (auto-detects if needed)
    if (!EnsureChainLengthKnown(daisy_chain_position, "ReadRegister")) {
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Build command using SpiCommand structure (union-based frame)
    SpiCommand cmd = SpiCommand::Read(address);
 
    // CRITICAL: Chain length MUST be known at this point
    // If daisy_chain_position > 0, total_chain_length_ must be > 0 (detected or
    // set) If daisy_chain_position == 0, total_chain_length_ should be 1
    // (single chip)
    if (daisy_chain_position > 0 && total_chain_length_ == 0) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "ReadRegister: Chain length unknown for daisy_chain_position=%u. "
          "Cannot proceed without chain length.",
          daisy_chain_position);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Calculate transfer size and response offset using datasheet formula
    // Transfer size: max((k+1)*5, (n-k)*5) bytes
    //   - Sending: (k+1)*5 bytes needed to address device k
    //   - Receiving: (n-k)*5 bytes needed to shift response back (datasheet
    //   formula)
    //   - Use max() to ensure both requirements are met
    // Response offset: (n-k-1)*5 bytes (reverse order: last device first)
    uint8_t n = total_chain_length_;
    uint8_t k = daisy_chain_position;
    if (n == 0) {
      // Single-chip mode should effectively be 1 device.
      n = 1;
    }
    if (n > TMC51X0_SPI_MAX_CHAIN_DEVICES) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "ReadRegister: Chain length %u exceeds TMC51X0_SPI_MAX_CHAIN_DEVICES=%u",
          n, static_cast<unsigned>(TMC51X0_SPI_MAX_CHAIN_DEVICES));
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Validate: k must be < n (device position must be less than total chain
    // length)
    if (k >= n) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "ReadRegister: Invalid daisy_chain_position=%u for chain length=%u. "
          "Position must be < chain length.",
          k, n);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Calculate transfer size: max of sending and receiving requirements
    size_t sending_bytes =
        static_cast<size_t>(k + 1) * 5; // Command must reach device k
    size_t receiving_bytes = static_cast<size_t>(n - k) *
                             5; // Response extraction (datasheet formula)
    size_t transfer_bytes = std::max(sending_bytes, receiving_bytes);
 
    // Response offset: (n-k-1)*5 bytes (based on reverse order of devices)
    size_t response_byte_offset = static_cast<size_t>(n - k - 1) * 5;
 
    // Validate transfer size meets receiving requirement
    if (transfer_bytes < receiving_bytes) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "ReadRegister: Transfer size %zu bytes < receiving "
                        "requirement %zu bytes. "
                        "Response extraction may fail.",
                        transfer_bytes, receiving_bytes);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Validate response offset is within buffer bounds
    if (response_byte_offset + 4 >= transfer_bytes) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "ReadRegister: Response offset %zu + 4 >= transfer size %zu. "
          "Cannot read full 5-byte response.",
          response_byte_offset, transfer_bytes);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    if (transfer_bytes > kSpiScratchBytes) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "ReadRegister: transfer_bytes=%zu exceeds scratch cap=%zu",
                        transfer_bytes, kSpiScratchBytes);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    std::fill(tx_scratch_.begin(), tx_scratch_.end(), 0);
    std::fill(rx_scratch_.begin(), rx_scratch_.end(), 0);
    uint8_t *tx_buf = tx_scratch_.data();
    uint8_t *rx_buf = rx_scratch_.data();
 
    // Place command at the beginning (bytes 0-4)
    // For daisy-chain position k, the command is placed first, then padding
    // (zeros) Padding structure:
    //   - Bytes 5 to (k+1)*5-1: Padding to shift command to device k
    //   - Bytes (k+1)*5 to transfer_bytes-1: Additional padding for full-duplex
    //   response extraction
    //     (only present if transfer_bytes > (k+1)*5, i.e., when (n-k)*5 >
    //     (k+1)*5)
    cmd.GetFrame(tx_buf);
    // Bytes 5 onwards are padding (zeros) - already initialized to 0 by vector
    // constructor
 
    // First transaction: Send read command (TX1), receive status (RX1)
    if (!SpiTransfer(tx_buf, rx_buf, transfer_bytes)) {
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Log [TX1]/RX1 after first transfer
    // Show "=0x00000000" for reads to align with Write format (read command has
    // no data, all zeros)
    TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                      "Read 0x%02X=0x00000000: [TX1] %02X %02X %02X %02X %02X "
                      "/ RX1 %02X %02X %02X %02X %02X",
                      address, tx_buf[0], tx_buf[1], tx_buf[2], tx_buf[3],
                      tx_buf[4], rx_buf[response_byte_offset],
                      (response_byte_offset + 1 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 1]
                          : 0,
                      (response_byte_offset + 2 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 2]
                          : 0,
                      (response_byte_offset + 3 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 3]
                          : 0,
                      (response_byte_offset + 4 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 4]
                          : 0);
 
    // Minimum CSN high time: 2*tclk + 10ns (typically ~176ns with 12MHz clock)
    // Per datasheet: CSN must go high between pipelined read transfers
    // Use 10us delay to ensure TMC5160 has time to prepare pipelined data
    // Some registers (like GLOBAL_SCALER, X_COMPARE) may require longer delay
    // Note: ESP32 spi_device_transmit automatically handles CSN (pulls high
    // after transfer)
    this->DelayUs(10);
 
    // Second transaction: Send address again (TX2), receive actual data (RX2 -
    // pipelined read) Per datasheet: Read data is transferred back with the
    // subsequent access Use same transfer size for daisy-chaining consistency
    if (!SpiTransfer(tx_buf, rx_buf, transfer_bytes)) {
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Log TX2/[RX2] after second transfer (RX2 contains the actual read data)
    // Align TX2 line with TX1 line by padding address field
    SpiStatus status = SpiStatus::FromByte(rx_buf[response_byte_offset]);
    char status_bits[128];
    status.FormatStatusBits(status_bits, sizeof(status_bits));
 
    // Align TX2 bytes with TX1 bytes: "Read 0xXX=0x00000000: " (25) + "[TX1] "
    // (6) = 31 chars to first byte For TX2: "Read 0xXX=0x00000000: " (25) + "
    // " (6 spaces) + "TX2 " (4) = 35, but bytes should be at 31 Actually: align
    // "TX2" label with "[TX1]" label, then bytes naturally align "Read
    // 0xXX=0x00000000: [TX1] " = 31, bytes at 31 "Read 0xXX=0x00000000: TX2 " =
    // 31 (25 + 6), bytes at 31 ✓
    TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                      "Read 0x%02X:             TX2 %02X %02X %02X %02X %02X / "
                      "[RX2] %02X %02X %02X %02X %02X (STATUS=0x%02X)",
                      address, tx_buf[0], tx_buf[1], tx_buf[2], tx_buf[3],
                      tx_buf[4], rx_buf[response_byte_offset],
                      (response_byte_offset + 1 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 1]
                          : 0,
                      (response_byte_offset + 2 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 2]
                          : 0,
                      (response_byte_offset + 3 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 3]
                          : 0,
                      (response_byte_offset + 4 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 4]
                          : 0,
                      rx_buf[response_byte_offset]);
 
    // Log status bit breakdown with arrow pointing to STATUS byte
    // Calculate position: "Read 0xXX:            TX2 XX XX XX XX XX / [RX2] " =
    // ~60 chars, then STATUS byte at ~68
    TMC51X0_LOG_DEBUG(
        *static_cast<Derived *>(this), 3, "SPI",
        "                                                   └─> %s",
        status_bits);
 
    // Extract response data based on daisy-chain position
    // IMPORTANT: Responses come back in REVERSE order (last device first, first
    // device last) Response offset is calculated above based on whether
    // total_chain_length_ is known
    // - If total_chain_length_ > 0: Use datasheet formula, response at
    // (n-k-1)*5 bytes
    // - If total_chain_length_ == 0: Use simplified approach, response at k*5
    // bytes (end of transfer)
 
    // Extract SPI_STATUS from response byte 0 (bits 39-32 per datasheet
    // section 4.1.2) For daisy-chaining, this is at the calculated offset
    // (status was already extracted above for logging)
    if (response_byte_offset >= transfer_bytes) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "Read register 0x%02X: Response offset %zu exceeds buffer size %zu",
          address, response_byte_offset, transfer_bytes);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Log SPI_STATUS with detailed flag information.
    // Note: RESET (bit 0) is informational (normal on power-up). DRV_ERR (bit
    // 1) indicates a driver-side fault (e.g., OT/short) but does NOT imply a
    // transport failure, so we do not return COMM_ERROR for it.
    if (status.HasError()) {
      // Rate-limit DRV_ERR logs to avoid spamming at high read rates.
      const bool should_log = (drv_err_log_count_ < 5U) ||
                              ((drv_err_log_count_ % 50U) == 0U);
      ++drv_err_log_count_;
 
      if (should_log) {
        // Build informational flags string (reset + status flags)
        char info_flags[64] = "";
        if (status.ResetFlag() || status.StallGuard2() || status.Standstill() ||
            status.VelocityReached() || status.PositionReached() ||
            status.StopLeft() || status.StopRight()) {
          snprintf(info_flags, sizeof(info_flags), " [%s%s%s%s%s%s%s]",
                   status.ResetFlag() ? "RST " : "",
                   status.StallGuard2() ? "SG2 " : "",
                   status.Standstill() ? "STST " : "",
                   status.VelocityReached() ? "VEL " : "",
                   status.PositionReached() ? "POS " : "",
                   status.StopLeft() ? "STOP_L " : "",
                   status.StopRight() ? "STOP_R " : "");
        }
 
        TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                          "Read 0x%02X: STATUS=0x%02X DRV_ERR%s", address,
                          status.value, info_flags);
      }
    } else {
      // Log response bytes (first 8 or all if less)
      size_t log_rx_bytes = (transfer_bytes < 8) ? transfer_bytes : 8;
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                        "Read register 0x%02X: RX[0..%zu] %02X %02X %02X %02X "
                        "%02X %02X %02X %02X "
                        "| SPI_STATUS=0x%02X [%s%s%s%s%s%s%s%s]",
                        address, log_rx_bytes - 1, rx_buf[0],
                        (log_rx_bytes > 1) ? rx_buf[1] : 0,
                        (log_rx_bytes > 2) ? rx_buf[2] : 0,
                        (log_rx_bytes > 3) ? rx_buf[3] : 0,
                        (log_rx_bytes > 4) ? rx_buf[4] : 0,
                        (log_rx_bytes > 5) ? rx_buf[5] : 0,
                        (log_rx_bytes > 6) ? rx_buf[6] : 0,
                        (log_rx_bytes > 7) ? rx_buf[7] : 0, status.value,
                        status.ResetFlag() ? "RST " : "",
                        status.DriverError() ? "DRV_ERR " : "",
                        status.StallGuard2() ? "SG2 " : "",
                        status.Standstill() ? "STST " : "",
                        status.VelocityReached() ? "VEL " : "",
                        status.PositionReached() ? "POS " : "",
                        status.StopLeft() ? "STOP_L " : "",
                        status.StopRight() ? "STOP_R " : "");
    }
 
    // Extract 32-bit value from bytes (response_byte_offset+1) to
    // (response_byte_offset+4) Byte (response_byte_offset+0) contains
    // SPI_STATUS (bits 39-32) Bytes (response_byte_offset+1) to
    // (response_byte_offset+4) contain data (bits 31-0)
    if (response_byte_offset + 4 >= transfer_bytes) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "Read register 0x%02X: Data offset %zu+4 exceeds buffer size %zu",
          address, response_byte_offset, transfer_bytes);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Extract 32-bit value from RX2 (bytes response_byte_offset+1 to
    // response_byte_offset+4)
    value = (static_cast<uint32_t>(rx_buf[response_byte_offset + 1]) << 24) |
            (static_cast<uint32_t>(rx_buf[response_byte_offset + 2]) << 16) |
            (static_cast<uint32_t>(rx_buf[response_byte_offset + 3]) << 8) |
            static_cast<uint32_t>(rx_buf[response_byte_offset + 4]);
 
    // Do not treat DRV_ERR as a transport failure. Caller may query GSTAT /
    // DRV_STATUS to diagnose the underlying cause.
    return Result<uint32_t>(value);
  }
 
  Result<void> WriteRegister(uint8_t address, uint32_t value,
                             uint8_t daisy_chain_position = 0) noexcept {
    // Log function call with arguments (level 3 = DEBUG, only shows at DEBUG
    // log level)
    if (daisy_chain_position > 0) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                        "WriteRegister(0x%02X=0x%08X, daisy_chain=%u)", address,
                        value, daisy_chain_position);
    } else {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                        "WriteRegister(0x%02X=0x%08X)", address, value);
    }
 
    // CRITICAL: Chain length MUST be known for correct response extraction
    // Ensure chain length is known and verified (auto-detects if needed)
    if (!EnsureChainLengthKnown(daisy_chain_position, "WriteRegister")) {
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Build command using SpiCommand structure (union-based frame)
    SpiCommand cmd = SpiCommand::Write(address, value);
 
    // CRITICAL: Chain length MUST be known at this point
    // If daisy_chain_position > 0, total_chain_length_ must be > 0 (detected or
    // set) If daisy_chain_position == 0, total_chain_length_ should be 1
    // (single chip)
    if (daisy_chain_position > 0 && total_chain_length_ == 0) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "WriteRegister: Chain length unknown for daisy_chain_position=%u. "
          "Cannot proceed without chain length.",
          daisy_chain_position);
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Calculate transfer size and response offset using datasheet formula
    // Transfer size: max((k+1)*5, (n-k)*5) bytes
    //   - Sending: (k+1)*5 bytes needed to address device k
    //   - Receiving: (n-k)*5 bytes needed to shift response back (datasheet
    //   formula)
    //   - Use max() to ensure both requirements are met
    //   - Extra bytes beyond (k+1)*5 are padding (zeros) for full-duplex
    //   behavior
    // Response offset: (n-k-1)*5 bytes (reverse order: last device first)
    uint8_t n = total_chain_length_;
    uint8_t k = daisy_chain_position;
    if (n == 0) {
      n = 1;
    }
    if (n > TMC51X0_SPI_MAX_CHAIN_DEVICES) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "WriteRegister: Chain length %u exceeds TMC51X0_SPI_MAX_CHAIN_DEVICES=%u",
          n, static_cast<unsigned>(TMC51X0_SPI_MAX_CHAIN_DEVICES));
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Validate: k must be < n (device position must be less than total chain
    // length)
    if (k >= n) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "WriteRegister: Invalid daisy_chain_position=%u for chain length=%u. "
          "Position must be < chain length.",
          k, n);
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Calculate transfer size: max of sending and receiving requirements
    size_t sending_bytes =
        static_cast<size_t>(k + 1) * 5; // Command must reach device k
    size_t receiving_bytes = static_cast<size_t>(n - k) *
                             5; // Response extraction (datasheet formula)
    size_t transfer_bytes = std::max(sending_bytes, receiving_bytes);
 
    // Response offset: (n-k-1)*5 bytes (based on reverse order of devices)
    size_t response_byte_offset = static_cast<size_t>(n - k - 1) * 5;
 
    // Validate transfer size meets receiving requirement
    if (transfer_bytes < receiving_bytes) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "WriteRegister: Transfer size %zu bytes < receiving "
                        "requirement %zu bytes. "
                        "Response extraction may fail.",
                        transfer_bytes, receiving_bytes);
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Validate response offset is within buffer bounds
    if (response_byte_offset + 4 >= transfer_bytes) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "WriteRegister: Response offset %zu + 4 >= transfer size %zu. "
          "Cannot read full 5-byte response.",
          response_byte_offset, transfer_bytes);
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    if (transfer_bytes > kSpiScratchBytes) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "WriteRegister: transfer_bytes=%zu exceeds scratch cap=%zu",
                        transfer_bytes, kSpiScratchBytes);
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    std::fill(tx_scratch_.begin(), tx_scratch_.end(), 0);
    std::fill(rx_scratch_.begin(), rx_scratch_.end(), 0);
    uint8_t *tx_buf = tx_scratch_.data();
    uint8_t *rx_buf = rx_scratch_.data();
 
    // Place command at the beginning (bytes 0-4)
    // For daisy-chain position k, the command is placed first, then padding
    // (zeros) Padding structure:
    //   - Bytes 5 to (k+1)*5-1: Padding to shift command to device k
    //   - Bytes (k+1)*5 to transfer_bytes-1: Additional padding for full-duplex
    //   response extraction
    //     (only present if transfer_bytes > (k+1)*5, i.e., when (n-k)*5 >
    //     (k+1)*5)
    cmd.GetFrame(tx_buf);
    // Bytes 5 onwards are padding (zeros) - already initialized to 0 by vector
    // constructor
 
    // First transaction: Send write command (TX1), receive status (RX1)
    if (!SpiTransfer(tx_buf, rx_buf, transfer_bytes)) {
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Log [TX1]/RX1 after first transfer
    TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                      "Write 0x%02X=0x%08X: [TX1] %02X %02X %02X %02X %02X / "
                      "RX1 %02X %02X %02X %02X %02X",
                      address, value, tx_buf[0], tx_buf[1], tx_buf[2],
                      tx_buf[3], tx_buf[4], rx_buf[response_byte_offset],
                      (response_byte_offset + 1 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 1]
                          : 0,
                      (response_byte_offset + 2 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 2]
                          : 0,
                      (response_byte_offset + 3 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 3]
                          : 0,
                      (response_byte_offset + 4 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 4]
                          : 0);
 
    // Extract response data based on daisy-chain position
    // IMPORTANT: Responses come back in REVERSE order (last device first, first
    // device last) Response offset is calculated above based on whether
    // total_chain_length_ is known
    // - If total_chain_length_ > 0: Use datasheet formula, response at
    // (n-k-1)*5 bytes
    // - If total_chain_length_ == 0: Use simplified approach, response at k*5
    // bytes (end of transfer)
    if (response_byte_offset >= transfer_bytes) {
      TMC51X0_LOG_DEBUG(
          *static_cast<Derived *>(this), 1, "SPI",
          "Write register 0x%02X: Response offset %zu exceeds buffer size %zu",
          address, response_byte_offset, transfer_bytes);
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Extract SPI_STATUS from first transaction response
    // Per datasheet: First write response contains SPI_STATUS + dummy/previous
    // data
    SpiStatus status1 = SpiStatus::FromByte(rx_buf[response_byte_offset]);
 
    // Note: RESET is informational. DRV_ERR is a driver-side fault; we log it
    // (rate-limited) but do not treat it as a transport error.
    if (status1.HasError()) {
      const bool should_log = (drv_err_log_count_ < 5U) ||
                              ((drv_err_log_count_ % 50U) == 0U);
      ++drv_err_log_count_;
 
      if (should_log) {
        // Build informational flags string (reset + status flags)
        char info_flags[64] = "";
        if (status1.ResetFlag() || status1.StallGuard2() ||
            status1.Standstill() || status1.VelocityReached() ||
            status1.PositionReached() || status1.StopLeft() ||
            status1.StopRight()) {
          snprintf(info_flags, sizeof(info_flags), " [%s%s%s%s%s%s%s]",
                   status1.ResetFlag() ? "RST " : "",
                   status1.StallGuard2() ? "SG2 " : "",
                   status1.Standstill() ? "STST " : "",
                   status1.VelocityReached() ? "VEL " : "",
                   status1.PositionReached() ? "POS " : "",
                   status1.StopLeft() ? "STOP_L " : "",
                   status1.StopRight() ? "STOP_R " : "");
        }
 
        TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                          "Write 0x%02X (TX1): STATUS=0x%02X DRV_ERR%s",
                          address, status1.value, info_flags);
      }
    } else {
      // Log response bytes (first 8 or all if less)
      size_t log_rx1_bytes = (transfer_bytes < 8) ? transfer_bytes : 8;
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                        "Write register 0x%02X (TX1): RX[0..%zu] %02X %02X "
                        "%02X %02X %02X %02X %02X %02X | "
                        "SPI_STATUS=0x%02X [%s%s%s%s%s%s%s%s]",
                        address, log_rx1_bytes - 1, rx_buf[0],
                        (log_rx1_bytes > 1) ? rx_buf[1] : 0,
                        (log_rx1_bytes > 2) ? rx_buf[2] : 0,
                        (log_rx1_bytes > 3) ? rx_buf[3] : 0,
                        (log_rx1_bytes > 4) ? rx_buf[4] : 0,
                        (log_rx1_bytes > 5) ? rx_buf[5] : 0,
                        (log_rx1_bytes > 6) ? rx_buf[6] : 0,
                        (log_rx1_bytes > 7) ? rx_buf[7] : 0, status1.value,
                        status1.ResetFlag() ? "RST " : "",
                        status1.DriverError() ? "DRV_ERR " : "",
                        status1.StallGuard2() ? "SG2 " : "",
                        status1.Standstill() ? "STST " : "",
                        status1.VelocityReached() ? "VEL " : "",
                        status1.PositionReached() ? "POS " : "",
                        status1.StopLeft() ? "STOP_L " : "",
                        status1.StopRight() ? "STOP_R " : "");
    }
 
    // Minimum CSN high time: 2*tclk + 10ns (typically ~176ns with 12MHz clock)
    // Use 1us delay for safety
    this->DelayUs(1);
 
    // Second transaction: Send dummy read to receive write confirmation/status
    // The response from the second transaction contains the status/confirmation
    // for the write command sent in the first transaction
    // Clear tx_buf and place read command at the beginning (same position as
    // write command)
    std::fill(tx_scratch_.begin(), tx_scratch_.end(), 0);
    SpiCommand read_cmd = SpiCommand::Read(address);
    read_cmd.GetFrame(tx_buf);
    // Padding (zeros) after byte 4 will shift this command to the target device
 
    if (!SpiTransfer(tx_buf, rx_buf, transfer_bytes)) {
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Log TX2/[RX2] after second transfer (RX2 contains the write confirmation)
    // Align TX2 line with TX1 line by padding address field
    SpiStatus status2 = SpiStatus::FromByte(rx_buf[response_byte_offset]);
    char status2_bits[128];
    status2.FormatStatusBits(status2_bits, sizeof(status2_bits));
 
    // Align TX2 bytes with TX1 bytes: "Write 0xXX=0xXXXXXXXX: " (25) + "[TX1] "
    // (6) = 31 chars to first byte For TX2: "Write 0xXX: " (13) + padding to
    // reach 31 = 18 spaces needed But we want "TX2 " to align with "[TX1] ",
    // so: "Write 0xXX: " (13) + 6 spaces + "TX2 " (4) = 23 To align bytes:
    // "Write 0xXX: " (13) + 18 spaces = 31, then bytes start Actually simpler:
    // align "TX2" label with "[TX1]" label, then bytes naturally align "Write
    // 0xXX=0xXXXXXXXX: [TX1] " = 31, bytes at 31 "Write 0xXX:            TX2 "
    // = 31 (13 + 18), bytes at 31 ✓
    TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                      "Write 0x%02X:             TX2 %02X %02X %02X %02X %02X "
                      "/ [RX2] %02X %02X %02X %02X %02X (STATUS=0x%02X)",
                      address, tx_buf[0], tx_buf[1], tx_buf[2], tx_buf[3],
                      tx_buf[4], rx_buf[response_byte_offset],
                      (response_byte_offset + 1 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 1]
                          : 0,
                      (response_byte_offset + 2 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 2]
                          : 0,
                      (response_byte_offset + 3 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 3]
                          : 0,
                      (response_byte_offset + 4 < transfer_bytes)
                          ? rx_buf[response_byte_offset + 4]
                          : 0,
                      rx_buf[response_byte_offset]);
 
    // Log status bit breakdown with arrow pointing to STATUS byte
    TMC51X0_LOG_DEBUG(
        *static_cast<Derived *>(this), 3, "SPI",
        "                                                   └─> %s",
        status2_bits);
 
    // Validate response offset (status2 was already extracted above for
    // logging)
    if (response_byte_offset >= transfer_bytes) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                        "Write register 0x%02X (TX2): Response offset %zu "
                        "exceeds buffer size %zu",
                        address, response_byte_offset, transfer_bytes);
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Note: RESET is informational. DRV_ERR is a driver-side fault; we log it
    // (rate-limited) but do not treat it as a transport error.
    if (status2.HasError()) {
      const bool should_log = (drv_err_log_count_ < 5U) ||
                              ((drv_err_log_count_ % 50U) == 0U);
      ++drv_err_log_count_;
 
      if (should_log) {
        // Build informational flags string (reset + status flags)
        char info_flags[64] = "";
        if (status2.ResetFlag() || status2.StallGuard2() ||
            status2.Standstill() || status2.VelocityReached() ||
            status2.PositionReached() || status2.StopLeft() ||
            status2.StopRight()) {
          snprintf(info_flags, sizeof(info_flags), " [%s%s%s%s%s%s%s]",
                   status2.ResetFlag() ? "RST " : "",
                   status2.StallGuard2() ? "SG2 " : "",
                   status2.Standstill() ? "STST " : "",
                   status2.VelocityReached() ? "VEL " : "",
                   status2.PositionReached() ? "POS " : "",
                   status2.StopLeft() ? "STOP_L " : "",
                   status2.StopRight() ? "STOP_R " : "");
        }
 
        TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                          "Write 0x%02X (TX2): STATUS=0x%02X DRV_ERR%s",
                          address, status2.value, info_flags);
      }
    } else {
      // Log response bytes (first 8 or all if less)
      size_t log_rx2_bytes = (transfer_bytes < 8) ? transfer_bytes : 8;
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                        "Write register 0x%02X (TX2): RX[0..%zu] %02X %02X "
                        "%02X %02X %02X %02X %02X %02X | "
                        "SPI_STATUS=0x%02X [%s%s%s%s%s%s%s%s]",
                        address, log_rx2_bytes - 1, rx_buf[0],
                        (log_rx2_bytes > 1) ? rx_buf[1] : 0,
                        (log_rx2_bytes > 2) ? rx_buf[2] : 0,
                        (log_rx2_bytes > 3) ? rx_buf[3] : 0,
                        (log_rx2_bytes > 4) ? rx_buf[4] : 0,
                        (log_rx2_bytes > 5) ? rx_buf[5] : 0,
                        (log_rx2_bytes > 6) ? rx_buf[6] : 0,
                        (log_rx2_bytes > 7) ? rx_buf[7] : 0, status2.value,
                        status2.ResetFlag() ? "RST " : "",
                        status2.DriverError() ? "DRV_ERR " : "",
                        status2.StallGuard2() ? "SG2 " : "",
                        status2.Standstill() ? "STST " : "",
                        status2.VelocityReached() ? "VEL " : "",
                        status2.PositionReached() ? "POS " : "",
                        status2.StopLeft() ? "STOP_L " : "",
                        status2.StopRight() ? "STOP_R " : "");
    }
 
    // Per datasheet: Write access returns SPI_STATUS (byte 0) + previously
    // written data (bytes 1-4) "If the previous access was a write access, then
    // the data read back mirrors the previously received write data." Verify
    // that the returned data matches what we wrote
    if (response_byte_offset + 4 < transfer_bytes) {
      uint32_t returned_value =
          (static_cast<uint32_t>(rx_buf[response_byte_offset + 1]) << 24) |
          (static_cast<uint32_t>(rx_buf[response_byte_offset + 2]) << 16) |
          (static_cast<uint32_t>(rx_buf[response_byte_offset + 3]) << 8) |
          static_cast<uint32_t>(rx_buf[response_byte_offset + 4]);
 
      if (returned_value != value) {
        TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                          "WriteRegister(0x%02X): Write verification failed - "
                          "wrote 0x%08X, got back 0x%08X",
                          address, value, returned_value);
        // Don't fail the write operation, but log the mismatch for debugging
      } else {
        TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "SPI",
                          "WriteRegister(0x%02X): Write verification passed - "
                          "wrote 0x%08X, got back 0x%08X",
                          address, value, returned_value);
      }
    }
 
    return Result<void>();
  }
 
protected:
  uint8_t total_chain_length_{
      0}; 
  uint8_t user_specified_chain_length_{0}; 
  bool chain_length_verified_{false}; 
 
  ~SpiCommInterface() = default;
 
  // Allow moving
  SpiCommInterface(SpiCommInterface &&) = default;
  SpiCommInterface &operator=(SpiCommInterface &&) = default;
 
public:
  // Prevent copying
  SpiCommInterface(const SpiCommInterface &) = delete;
  SpiCommInterface &operator=(const SpiCommInterface &) = delete;
 
private:
  // Static scratch buffers used for SPI transfers to avoid heap allocation.
  // Sized by TMC51X0_SPI_MAX_CHAIN_DEVICES (+2 for auto-detect probe).
  std::array<uint8_t, kSpiScratchBytes> tx_scratch_{};
  std::array<uint8_t, kSpiScratchBytes> rx_scratch_{};
 
  // Counts how many times we've seen SPI_STATUS.DRV_ERR so we can rate-limit
  // logs without relying on platform-specific time functions.
  uint32_t drv_err_log_count_{0};
 
  Result<void> EnsureChainLengthKnown(uint8_t daisy_chain_position,
                                      const char *context) noexcept {
    // Auto-detect chain length on first access if needed
    if (daisy_chain_position > 0 && total_chain_length_ == 0) {
      uint8_t detected_length =
          AutoDetectChainLength(TMC51X0_SPI_MAX_CHAIN_DEVICES); // Probe up to configured max
      if (detected_length == 0) {
        // Detection failed - cannot proceed without chain length
        TMC51X0_LOG_DEBUG(
            *static_cast<Derived *>(this), 1, "SPI",
            "%s: Auto-detection failed, but daisy_chain_position=%u > 0. "
            "Chain length is required for correct response extraction. "
            "Operation failed.",
            context, daisy_chain_position);
        return Result<void>(ErrorCode::COMM_ERROR);
      }
    }
 
    // For single chip (daisy_chain_position == 0), chain length is not needed
    // But if it's set, ensure it's at least 1
    if (daisy_chain_position == 0 && total_chain_length_ == 0) {
      // Single chip mode - this is valid
      total_chain_length_ = 1; // Set to 1 for single chip (n=1, k=0)
      chain_length_verified_ =
          true; // Single-chip mode doesn't need verification
    }
 
    // Verify chain length if user specified one
    if (!chain_length_verified_ && user_specified_chain_length_ > 0) {
      // User specified a chain length, verify it matches detected length
      uint8_t detected_length = AutoDetectChainLength(8);
      if (detected_length > 0 &&
          detected_length != user_specified_chain_length_) {
        TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                          "%s: DAISY CHAIN LENGTH MISMATCH! "
                          "User specified: %u, Auto-detected: %u. "
                          "Response extraction will be incorrect. "
                          "Call SetDaisyChainLength(%u) to fix.",
                          context, user_specified_chain_length_,
                          detected_length, detected_length);
        // Update to detected length and mark as verified (use detected value)
        total_chain_length_ = detected_length;
        chain_length_verified_ = true;
        // Continue with detected length (don't fail, but log error)
      } else if (detected_length > 0) {
        // Match confirmed
        chain_length_verified_ = true;
        TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 2, "SPI",
                          "%s: Chain length verified: %u devices", context,
                          detected_length);
      }
    } else if (!chain_length_verified_ && total_chain_length_ > 0) {
      // Chain length was set but not verified yet, verify it now
      // Skip verification for single-chip mode (daisy_chain_position == 0,
      // total_chain_length_ == 1) Auto-detection can fail for single-chip
      // setups, so we trust the set value
      if (daisy_chain_position == 0 && total_chain_length_ == 1) {
        // Single-chip mode - no verification needed
        chain_length_verified_ = true;
      } else {
        // Multi-chip mode - verify chain length
        uint8_t detected_length = AutoDetectChainLength(8);
        if (detected_length > 0 && detected_length != total_chain_length_) {
          TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "SPI",
                            "%s: DAISY CHAIN LENGTH MISMATCH! "
                            "Specified: %u, Auto-detected: %u. "
                            "Updating to detected length.",
                            context, total_chain_length_, detected_length);
          total_chain_length_ = detected_length;
        }
        chain_length_verified_ = true;
      }
    }
 
    return Result<void>();
  }
};
 
template <typename Derived>
class UartCommInterface : public CommInterface<Derived> {
public:
  UartCommInterface() noexcept : CommInterface<Derived>() {}
 
  [[nodiscard]] CommMode GetMode() const noexcept { return CommMode::UART; }
 
  Result<void> SetNaiPin(bool active) noexcept {
    return static_cast<Derived *>(this)->SetNaiPin(active);
  }
 
  Result<bool> GetNaoPin() noexcept {
    bool active = false;
    return static_cast<Derived *>(this)->GetNaoPin(active);
  }
 
  Result<void> UartSend(const uint8_t *data, size_t length) noexcept {
    return static_cast<Derived *>(this)->UartSend(data, length);
  }
 
  Result<void> UartReceive(uint8_t *data, size_t length) noexcept {
    return static_cast<Derived *>(this)->UartReceive(data, length);
  }
 
  Result<uint32_t> ReadRegister(uint8_t address,
                                uint8_t node_address = 0) noexcept {
    uint32_t value = 0;
    // Build read request frame (4 bytes)
    uint8_t node_addr = node_address & 0x7F;
    UartFrame read_request = UartFrame::ReadRequest(node_addr, address);
 
    // Get frame bytes (4 bytes)
    std::array<uint8_t, 8> tx_buf{}; // Max size for any frame is 8
    read_request.GetFrame(tx_buf.data());
    size_t tx_size = read_request.GetSize(); // 4 bytes
 
    TMC51X0_LOG_DEBUG(
        *static_cast<Derived *>(this), 3, "UART",
        "Read register 0x%02X (NodeAddr=0x%02X): TX %02X %02X %02X %02X",
        address, node_addr, tx_buf[0], tx_buf[1], tx_buf[2], tx_buf[3]);
 
    if (!UartSend(tx_buf.data(), tx_size)) {
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Receive read reply (8 bytes)
    std::array<uint8_t, 8> rx_buf{};
    if (!UartReceive(rx_buf.data(), 8)) {
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Parse read reply using UartFrame structure
    UartFrame read_reply = UartFrame::ReadReply(rx_buf.data());
 
    TMC51X0_LOG_DEBUG(
        *static_cast<Derived *>(this), 3, "UART",
        "Read register 0x%02X: RX %02X %02X %02X %02X %02X %02X %02X %02X",
        address, rx_buf[0], rx_buf[1], rx_buf[2], rx_buf[3], rx_buf[4],
        rx_buf[5], rx_buf[6], rx_buf[7]);
 
    // Verify CRC8 and frame validity
    if (!read_reply.VerifyCrc()) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "UART",
                        "Read register 0x%02X: CRC8 verification failed",
                        address);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    if (!read_reply.IsValid()) {
      TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 1, "UART",
                        "Read register 0x%02X: Invalid frame structure",
                        address);
      return Result<uint32_t>(ErrorCode::COMM_ERROR);
    }
 
    // Extract 32-bit value
    value = read_reply.GetValue();
 
    return Result<uint32_t>(value);
  }
 
  Result<void> WriteRegister(uint8_t address, uint32_t value,
                             uint8_t node_address = 0) noexcept {
    // Build write access frame (8 bytes)
    uint8_t node_addr = node_address & 0x7F;
    UartFrame write_frame = UartFrame::Write(node_addr, address, value);
 
    // Get frame bytes (8 bytes)
    std::array<uint8_t, 8> tx_buf{};
    write_frame.GetFrame(tx_buf.data());
    size_t tx_size = write_frame.GetSize(); // 8 bytes
 
    TMC51X0_LOG_DEBUG(*static_cast<Derived *>(this), 3, "UART",
                      "Write register 0x%02X = 0x%08X (NodeAddr=0x%02X): TX "
                      "%02X %02X %02X %02X "
                      "%02X %02X %02X %02X",
                      address, node_addr, tx_buf[0], tx_buf[1], tx_buf[2],
                      tx_buf[3], tx_buf[4], tx_buf[5], tx_buf[6], tx_buf[7]);
 
    if (!UartSend(tx_buf.data(), tx_size)) {
      return Result<void>(ErrorCode::COMM_ERROR);
    }
 
    // Write does NOT have a reply packet from the device (only updates internal
    // counter). We return true if send was successful. Note: Some single-wire
    // implementations receive their own TX (echo). If so, the derived class or
    // HAL should handle flushing the echo. This interface assumes UartSend
    // handles the transmission.
 
    return Result<void>();
  }
 
protected:
  ~UartCommInterface() = default;
 
  // Allow moving
  UartCommInterface(UartCommInterface &&) = default;
  UartCommInterface &operator=(UartCommInterface &&) = default;
 
public:
  // Prevent copying
  UartCommInterface(const UartCommInterface &) = delete;
  UartCommInterface &operator=(const UartCommInterface &) = delete;
};
 
} // namespace tmc51x0