diff --git a/esphome/components/mcp4461/mcp4461.h b/esphome/components/mcp4461/mcp4461.h index 6e53aa4a66..0e40ec6cab 100644 --- a/esphome/components/mcp4461/mcp4461.h +++ b/esphome/components/mcp4461/mcp4461.h @@ -7,6 +7,7 @@ namespace esphome { namespace mcp4461 { +/// @brief Struct representing current wiper details/state struct WiperState { bool enabled = true; uint16_t state = 0; @@ -20,9 +21,10 @@ struct WiperState { bool update_terminal = false; }; -// default wiper state is 128 / 0x80h +/// @brief Class containing i2c commands supported by the device enum class Mcp4461Commands : uint8_t { WRITE = 0x00, INCREMENT = 0x04, DECREMENT = 0x08, READ = 0x0C }; +/// @brief Class containing register addresses of the device enum class Mcp4461Addresses : uint8_t { MCP4461_VW0 = 0x00, MCP4461_VW1 = 0x10, @@ -34,6 +36,7 @@ enum class Mcp4461Addresses : uint8_t { MCP4461_EEPROM_1 = 0xB0 }; +// @brief enumerate allowed channels/wipers enum Mcp4461WiperIdx : uint8_t { MCP4461_WIPER_0 = 0, MCP4461_WIPER_1 = 1, @@ -45,6 +48,7 @@ enum Mcp4461WiperIdx : uint8_t { MCP4461_WIPER_7 = 7 }; +/// @brief Class containing valid EEProm user data locations enum class Mcp4461EepromLocation : uint8_t { MCP4461_EEPROM_0 = 0, MCP4461_EEPROM_1 = 1, @@ -53,6 +57,7 @@ enum class Mcp4461EepromLocation : uint8_t { MCP4461_EEPROM_4 = 4 }; +/// @brief Class containing valid terminal register params for terminal functions enum class Mcp4461TerminalIdx : uint8_t { MCP4461_TERMINAL_0 = 0, MCP4461_TERMINAL_1 = 1 }; class Mcp4461Wiper; @@ -70,16 +75,29 @@ class Mcp4461Component : public Component, public i2c::I2CDevice { this->reg_[2].enabled = !wiper_2_disabled_; this->reg_[3].enabled = !wiper_3_disabled_; } - + /// @brief perform initialisation of component void setup() override; + /// @brief dump component config on boot void dump_config() override; + /// @brief set hardware priority for component float get_setup_priority() const override { return setup_priority::HARDWARE; } void loop() override; + /// @brief get user-data value from eeprom location + /// @param[location] location to fetch data from, valid is uint8_t in range of 0-4 for 5x 9 bits of user-data uint16_t get_eeprom_value(Mcp4461EepromLocation location); + /// @brief set user-data value from eeprom location + /// @param[location] location to write data to, valid is uint8_t in range of 0-4 for 5x 9 bits of user-data bool set_eeprom_value(Mcp4461EepromLocation location, uint16_t value); + /// @brief set initial value for wiper + /// @param[wiper] wiper for which initial_value shall be set + /// @param[initial_value] the float value in range 0 to 1.0 the wiper shall be set to void set_initial_value(Mcp4461WiperIdx wiper, float initial_value); + /// @brief initialize terminal of wiper with state disabled + /// @param[wiper] wiper for which terminal shall be initialized disabled + /// @param[terminal] terminal to disable, one of { 'a', 'b', 'w', 'h' } void initialize_terminal_disabled(Mcp4461WiperIdx wiper, char terminal); + /// @brief enumerate required status codes enum ErrorCode { MCP4461_STATUS_OK = 0, // CMD completed successfully MCP4461_FAILED, // component failed @@ -97,26 +115,55 @@ class Mcp4461Component : public Component, public i2c::I2CDevice { protected: friend class Mcp4461Wiper; + /// @brief update write protection status of device void update_write_protection_status_(); + /// @brief fetch wiper address for given wiper uint8_t get_wiper_address_(uint8_t wiper); uint16_t read_wiper_level_(uint8_t wiper); + /// @brief fetch device status register values uint8_t get_status_register_(); + /// @brief read current level/state of given wiper uint16_t get_wiper_level_(Mcp4461WiperIdx wiper); + /// @brief set level/state of given wiper bool set_wiper_level_(Mcp4461WiperIdx wiper, uint16_t value); + /// @brief update current level/state of given wiper bool update_wiper_level_(Mcp4461WiperIdx wiper); + /// @brief enable given wiper + /// @param[wiper] wiper to enable void enable_wiper_(Mcp4461WiperIdx wiper); + /// @brief disable given wiper + /// @param[wiper] wiper to disable void disable_wiper_(Mcp4461WiperIdx wiper); + /// @brief increase given wiper + /// @param[wiper] wiper to increase bool increase_wiper_(Mcp4461WiperIdx wiper); + /// @brief increase given wiper + /// @param[wiper] wiper to increase bool decrease_wiper_(Mcp4461WiperIdx wiper); + /// @brief enable terminal of wiper + /// @param[wiper] desired wiper for which the terminal shall be enabled void enable_terminal_(Mcp4461WiperIdx wiper, char terminal); + /// @brief disable terminal of wiper + /// @param[wiper] desired wiper for which the terminal shall be disabled void disable_terminal_(Mcp4461WiperIdx, char terminal); + /// @brief check if device is still busy writing to eeprom bool is_writing_(); + /// @brief wait until timeout if device is busy + /// @param[wait_if_not_ready] set to true to wait until timeout again, if previous write timed out already bool is_eeprom_ready_for_writing_(bool wait_if_not_ready); + /// @brief set wiper level + /// @param[wiper] wiper for which the new state shall be set + /// @param[value] the int value in range 0-256 the wiper shall be set to void write_wiper_level_(uint8_t wiper, uint16_t value); + /// @brief internal i2c write function bool mcp4461_write_(uint8_t addr, uint16_t data, bool nonvolatile = false); + /// @brief calculate correct terminal register values uint8_t calc_terminal_connector_byte_(Mcp4461TerminalIdx terminal_connector); + /// @brief internal function to update terminal registers void update_terminal_register_(Mcp4461TerminalIdx terminal_connector); + /// @brief internal function to get terminal register values uint8_t get_terminal_register_(Mcp4461TerminalIdx terminal_connector); + /// @brief internal function to set terminal registers bool set_terminal_register_(Mcp4461TerminalIdx terminal_connector, uint8_t data); WiperState reg_[8];