pca9685.hpp

Go to the documentation of this file.

 
#pragma once
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
#include "pca9685_i2c_interface.hpp"
#include "pca9685_version.h"
 
namespace pca9685 {
 
template <typename I2cType>
class PCA9685 {
public:
  enum class Error : uint16_t {
    None = 0,
    I2cWrite = 1 << 0,       
    I2cRead = 1 << 1,        
    InvalidParam = 1 << 2,   
    DeviceNotFound = 1 << 3, 
    NotInitialized = 1 << 4, 
    OutOfRange = 1 << 5      
  };
 
  enum class Register : uint8_t {
    MODE1 = 0x00,      
    MODE2 = 0x01,      
    SUBADR1 = 0x02,    
    SUBADR2 = 0x03,    
    SUBADR3 = 0x04,    
    ALLCALLADR = 0x05, 
    LED0_ON_L = 0x06,  
    LED0_ON_H = 0x07,  
    LED0_OFF_L = 0x08, 
    LED0_OFF_H =
        0x09, 
    /* LED1–LED15: registers 0x0A–0x45 (four bytes per channel, same layout as LED0) */
    ALL_LED_ON_L = 0xFA,  
    ALL_LED_ON_H = 0xFB,  
    ALL_LED_OFF_L = 0xFC, 
    ALL_LED_OFF_H = 0xFD, 
    PRE_SCALE = 0xFE,     
    TESTMODE = 0xFF       
  };
 
  static constexpr uint8_t MAX_CHANNELS_ = 16;    
  static constexpr uint16_t MAX_PWM_ = 4095;      
  static constexpr uint32_t OSC_FREQ_ = 25000000; 
  static constexpr uint32_t OSC_STARTUP_US_ = 500;
 
  PCA9685(I2cType* bus, uint8_t address);
 
  bool EnsureInitialized() noexcept;
 
  bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  bool Reset() noexcept;
 
  bool SetPwmFreq(float freq_hz) noexcept;
 
  bool SetPwm(uint8_t channel, uint16_t on_time, uint16_t off_time) noexcept;
 
  bool SetDuty(uint8_t channel, float duty) noexcept;
 
  bool SetAllPwm(uint16_t on_time, uint16_t off_time) noexcept;
 
  [[nodiscard]] uint16_t GetErrorFlags() const noexcept {
    return error_flags_;
  }
 
  [[nodiscard]] bool HasError(Error e) const noexcept {
    return (error_flags_ & static_cast<uint16_t>(e)) != 0;
  }
 
  [[nodiscard]] bool HasAnyError() const noexcept {
    return error_flags_ != 0;
  }
 
  void ClearError(Error e) noexcept {
    error_flags_ &= ~static_cast<uint16_t>(e);
  }
 
  void ClearErrorFlags(uint16_t mask = 0xFFFF) noexcept {
    error_flags_ &= ~mask;
  }
 
  [[nodiscard]] Error GetLastError() const noexcept {
    return last_error_;
  }
 
  [[nodiscard]] bool GetPrescale(uint8_t& prescale) noexcept;
 
  void SetRetries(int retries) noexcept {
    retries_ = retries;
  }
 
  using RetryDelayFn = void (*)();
 
  void SetRetryDelay(RetryDelayFn fn) noexcept {
    retry_delay_ = fn;
  }
 
  // ---- Power Management ----
 
  bool Sleep() noexcept;
 
  bool Wake() noexcept;
 
  // ---- Output Configuration ----
 
  bool SetOutputInvert(bool invert) noexcept;
 
  bool SetOutputDriverMode(bool totem_pole) noexcept;
 
  bool SetOutputEnable(bool enable) noexcept;
 
  // ---- Channel On/Off ----
 
  bool SetChannelFullOn(uint8_t channel) noexcept;
 
  bool SetChannelFullOff(uint8_t channel) noexcept;
 
  // ===========================================================================
  // Driver Version
  // ===========================================================================
 
  static constexpr const char* GetDriverVersion() noexcept {
    return HF_PCA9685_VERSION_STRING;
  }
 
  static constexpr uint8_t GetDriverVersionMajor() noexcept {
    return HF_PCA9685_VERSION_MAJOR;
  }
 
  static constexpr uint8_t GetDriverVersionMinor() noexcept {
    return HF_PCA9685_VERSION_MINOR;
  }
 
  static constexpr uint8_t GetDriverVersionPatch() noexcept {
    return HF_PCA9685_VERSION_PATCH;
  }
 
private:
  static constexpr uint8_t MODE1_RESTART_ = 0x80; 
  static constexpr uint8_t MODE1_AI_ = 0x20;      
  static constexpr uint8_t MODE1_SLEEP_ = 0x10;   
  static constexpr uint32_t OSC_STARTUP_FALLBACK_READS_ = 13;
 
  I2cType* i2c_;
  uint8_t addr_;
  Error last_error_{Error::None};
  uint16_t error_flags_{0};
  int retries_{3};
  RetryDelayFn retry_delay_{nullptr};
  bool initialized_{false};
 
  void setError(Error e) noexcept {
    last_error_ = e;
    error_flags_ |= static_cast<uint16_t>(e);
  }
 
  bool writeReg(uint8_t reg, uint8_t value) noexcept;
  bool readReg(uint8_t reg, uint8_t& value) noexcept;
  bool writeRegBlock(uint8_t reg, const uint8_t* data, size_t len) noexcept;
  bool readRegBlock(uint8_t reg, uint8_t* data, size_t len) noexcept;
  [[nodiscard]] uint8_t calcPrescale(float freq_hz) const noexcept;
 
  bool writeMode1(uint8_t value) noexcept;
 
  bool restartAfterSleep(uint8_t mode1, bool restart) noexcept;
 
  void waitOscillatorStartup() noexcept;
 
  [[nodiscard]] static ::std::array<uint8_t, 4> pwmFrame(uint16_t on_time,
                                                         uint16_t off_time) noexcept;
 
  bool modifyReg(uint8_t reg, uint8_t mask, uint8_t value) noexcept;
};
 
// Include template implementation
#define PCA9685_HEADER_INCLUDED
// NOLINTNEXTLINE(bugprone-suspicious-include) - Intentional: template
// implementation file
#include "../src/pca9685.ipp"
#undef PCA9685_HEADER_INCLUDED
 
// Public API: Get driver version string
inline const char* GetDriverVersion() noexcept {
  return HF_PCA9685_VERSION_STRING;
}
 
} // namespace pca9685