unit_ExtIO2.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_EXTIO_UNIT_EXTIO2_HPP
#define M5_UNIT_EXTIO_UNIT_EXTIO2_HPP
 
#include <M5UnitComponent.hpp>
#include <m5_utility/container/circular_buffer.hpp>
#include <array>
#include <algorithm>
 
namespace m5 {
namespace unit {
 
namespace extio2 {
 
enum class Mode : int8_t {
    Invalid = -1,
    DigitalInput,   
    DigitalOutput,  
    ADCInput,       
    ServoControl,   
    LEDControl,     
    //    PWMControl,     //!< PWM Control (Firmware V3 or later)
};
static_assert(sizeof(Mode) == sizeof(uint8_t), "Mode and uint8_t size must match");
 
enum AnalogMode : uint8_t {
    Bits8,   
    Bits12,  
};
 
}  // namespace extio2
 
class UnitExtIO2 : public Component {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitExtIO2, 0x45);
 
public:
    static constexpr uint8_t NUMBER_OF_PINS{8};  
 
    static constexpr uint8_t MIN_ANALOG_8{0};         
    static constexpr uint8_t MAX_ANALOG_8{255};       
    static constexpr uint16_t MIN_ANALOG_12{0};       
    static constexpr uint16_t MAX_ANALOG_12{4095};    
    static constexpr uint8_t MIN_SERVO_ANGLE{0};      
    static constexpr uint8_t MAX_SERVO_ANGLE{180};    
    static constexpr uint16_t MIN_SERVO_PULSE{500};   
    static constexpr uint16_t MAX_SERVO_PULSE{2500};  
 
    struct config_t {
        bool apply_mode{true};
        extio2::Mode mode[NUMBER_OF_PINS] = {extio2::Mode::DigitalInput, extio2::Mode::DigitalInput,
                                             extio2::Mode::DigitalInput, extio2::Mode::DigitalInput,
                                             extio2::Mode::DigitalInput, extio2::Mode::DigitalInput,
                                             extio2::Mode::DigitalInput, extio2::Mode::DigitalInput};
    };
 
    explicit UnitExtIO2(const uint8_t addr = DEFAULT_ADDRESS) : Component(addr)
    {
        auto ccfg  = component_config();
        ccfg.clock = 100 * 1000U;
        component_config(ccfg);
        std::fill(_mode.begin(), _mode.end(), extio2::Mode::Invalid);
    }
    virtual ~UnitExtIO2()
    {
    }
 
    virtual bool begin() override;
 
 
    inline config_t config()
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
 
    uint8_t firmwareVersion() const
    {
        return _fw_version;
    }
    bool readFirmwareVersion(uint8_t& version);
 
 
    inline extio2::Mode mode(const uint8_t pin)
    {
        return (pin < NUMBER_OF_PINS) ? _mode[pin] : extio2::Mode::Invalid;
    }
    bool readMode(extio2::Mode& mode, const uint8_t pin);
    bool readAllMode(extio2::Mode mode[NUMBER_OF_PINS]);
    bool writeMode(const uint8_t pin, const extio2::Mode mode);
    bool writePinBitsMode(const uint8_t pin_bits, const extio2::Mode mode);
    bool writeAllMode(const extio2::Mode mode);
    bool writeAllMode(const extio2::Mode mode[NUMBER_OF_PINS]);
 
 
    bool readDigitalInput(bool& high, const uint8_t pin);
    bool readPinBitsDigitalInput(uint8_t& high_bits, const uint8_t pin_bits);
    bool readAllDigitalInput(uint8_t& high_bits);
 
 
    bool writeDigitalOutput(const uint8_t pin, const bool high);
    inline bool writeDigitalOutputHigh(const uint8_t pin)
    {
        return writeDigitalOutput(pin, true);
    }
    inline bool writeDigitalOutputLow(const uint8_t pin)
    {
        return writeDigitalOutput(pin, false);
    }
    template <typename T, typename std::enable_if<std::is_same<T, bool>::value, std::nullptr_t>::type = nullptr>
    inline bool writePinBitsDigitalOutput(const uint8_t pin_bits, const T high)
    {
        return write_pin_bits_digital_output(pin_bits, high);
    }
    template <typename T, typename std::enable_if<!std::is_same<T, bool>::value && std::is_integral<T>::value,
                                                  std::nullptr_t>::type = nullptr>
    inline bool writePinBitsDigitalOutput(const uint8_t pin_bits, const T high_bits)
    {
        return write_pin_bits_digital_output(pin_bits, static_cast<uint8_t>(high_bits));
    }
    inline bool writePinBitsDigitalOutputHigh(const uint8_t pin_bits)
    {
        return writePinBitsDigitalOutput(pin_bits, true);
    }
    inline bool writePinBitsDigitalOutputLow(const uint8_t pin_bits)
    {
        return writePinBitsDigitalOutput(pin_bits, false);
    }
    inline bool writeAllDigitalOutput(const bool high)
    {
        return writePinBitsDigitalOutput(0xFF, high);
    }
    inline bool writeAllDigitalOutputHigh()
    {
        return writeAllDigitalOutput(true);
    }
    inline bool writeAllDigitalOutputLow()
    {
        return writeAllDigitalOutput(false);
    }
 
 
    bool readAnalogInput(uint16_t& value, const uint8_t pin, const extio2::AnalogMode amode);
    inline bool readAnalogInput8(uint16_t& value, const uint8_t pin)
    {
        return readAnalogInput(value, pin, extio2::AnalogMode::Bits8);
    }
    inline bool readAnalogInput12(uint16_t& value, const uint8_t pin)
    {
        return readAnalogInput(value, pin, extio2::AnalogMode::Bits12);
    }
    bool readPinBitsAnalogInput(uint16_t values[NUMBER_OF_PINS], const uint8_t pin_bits,
                                const extio2::AnalogMode amode);
    inline bool readPinBitsAnalogInput8(uint16_t values[NUMBER_OF_PINS], const uint8_t pin_bits)
    {
        return readPinBitsAnalogInput(values, pin_bits, extio2::AnalogMode::Bits8);
    }
    inline bool readPinBitsAnalogInput12(uint16_t values[NUMBER_OF_PINS], const uint8_t pin_bits)
    {
        return readPinBitsAnalogInput(values, pin_bits, extio2::AnalogMode::Bits12);
    }
    inline bool readAllAnalogInput(uint16_t values[NUMBER_OF_PINS], const extio2::AnalogMode amode)
    {
        return readPinBitsAnalogInput(values, 0xFF, amode);
    }
    bool readAllAnalogInput8(uint16_t values[NUMBER_OF_PINS])
    {
        return readAllAnalogInput(values, extio2::AnalogMode::Bits8);
    }
    bool readAllAnalogInput12(uint16_t values[NUMBER_OF_PINS])
    {
        return readAllAnalogInput(values, extio2::AnalogMode::Bits12);
    }
 
 
    bool readServoAngle(uint8_t& degree, const uint8_t pin);
    bool readPinBitsServoAngle(uint8_t degrees[NUMBER_OF_PINS], const uint8_t pin_bits);
    inline bool readAllServoAngle(uint8_t degrees[NUMBER_OF_PINS])
    {
        return readPinBitsServoAngle(degrees, 0xFF);
    }
    bool writeServoAngle(const uint8_t pin, const uint8_t degree);
    bool writePinBitsServoAngle(const uint8_t pin_bits, const uint8_t degree);
    inline bool writeAllServoAngle(const uint8_t degree)
    {
        return writePinBitsServoAngle(0xFF, degree);
    }
    bool readServoPulse(uint16_t& pulse, const uint8_t pin);
    bool readPinBitsServoPulse(uint16_t pulses[NUMBER_OF_PINS], const uint8_t pin_bits);
    inline bool readAllServoPulse(uint16_t pulses[NUMBER_OF_PINS])
    {
        return readPinBitsServoPulse(pulses, 0xFF);
    }
    bool writeServoPulse(const uint8_t pin, const uint16_t pulse);
    bool writePinBitsServoPulse(const uint8_t pin_bits, const uint16_t pulse);
    inline bool writeAllServoPulse(const uint16_t pulse)
    {
        return writePinBitsServoPulse(0xFF, pulse);
    }
 
 
    bool readLEDColor(uint32_t& rgb888, const uint8_t pin);
    bool readPinBitsLEDColor(uint32_t rgb888[NUMBER_OF_PINS], const uint8_t pin_bits);
    inline bool readAllLEDColor(uint32_t rgb888[NUMBER_OF_PINS])
    {
        return readPinBitsLEDColor(rgb888, 0xFF);
    }
    inline bool writeLEDColor(const uint8_t pin, const uint32_t rgb888)
    {
        return writeLEDColor(pin, (rgb888 >> 16) & 0xFF, (rgb888 >> 8) & 0xFF, rgb888 & 0xFF);
    }
    bool writeLEDColor(const uint8_t pin, const uint8_t r, const uint8_t g, const uint8_t b);
    inline bool writePinBitsLEDColor(const uint8_t pin_bits, const uint32_t rgb888)
    {
        return writePinBitsLEDColor(pin_bits, (rgb888 >> 16) & 0xFF, (rgb888 >> 8) & 0xFF, rgb888 & 0xFF);
    }
    bool writePinBitsLEDColor(const uint8_t pin_bits, const uint8_t r, const uint8_t g, const uint8_t b);
    inline bool writeAllLEDColor(const uint32_t rgb888)
    {
        return writePinBitsLEDColor(0xFF, rgb888);
    }
    inline bool writeAllLEDColor(const uint8_t r, const uint8_t g, const uint8_t b)
    {
        return writePinBitsLEDColor(0xFF, r, g, b);
    }
 
 
    bool changeI2CAddress(const uint8_t i2c_address);
    bool readI2CAddress(uint8_t& i2c_address);
 
protected:
    bool write_pin_bits_digital_output(const uint8_t pin_bits, const bool high);
    bool write_pin_bits_digital_output(const uint8_t pin_bits, const uint8_t high_bits);
 
    static constexpr uint8_t FIRMWARE_VERSION_CAN_PWM_CONTROL{0x03};
    inline bool canPWMControl() const
    {
        return _fw_version >= FIRMWARE_VERSION_CAN_PWM_CONTROL;
    }
 
private:
    std::array<extio2::Mode, NUMBER_OF_PINS> _mode{};
    config_t _cfg{};
    uint8_t _fw_version{};
};
 
namespace extio2 {
namespace command {
constexpr uint8_t MODE_REG{0x00};
constexpr uint8_t OUTPUT_CTL_REG{0x10};
// constexpr uint8_t OUTPUTS_CTL_REG{0x18};
constexpr uint8_t DIGITAL_INPUT_REG{0x20};
// constexpr uint8_t DIGITAL_INPUTS_REG{0x28};
constexpr uint8_t ANALOG_INPUT_8BITS_REG{0x30};
constexpr uint8_t ANALOG_INPUT_12BITS_REG{0x40};
constexpr uint8_t SERVO_ANGLE_8BITS_REG{0x50};
constexpr uint8_t SERVO_PULSE_16BITS_REG{0x60};
constexpr uint8_t RGB_24BITS_REG{0x70};
constexpr uint8_t FW_VERSION_REG{0xFE};
constexpr uint8_t ADDRESS_REG{0xFF};
constexpr uint8_t PWM_DUTY_REG{0x90};  // Firmware V3 or later
constexpr uint8_t PWM_FREQ_REG{0xA0};  // Firmware V3 or later
 
}  // namespace command
}  // namespace extio2
 
}  // namespace unit
}  // namespace m5
#endif