M5UnitComponent.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2024 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_COMPONENT_HPP
#define M5_UNIT_COMPONENT_HPP
 
#include "m5_unit_component/types.hpp"
#include "m5_unit_component/adapter.hpp"
#include <cstdint>
#include <vector>
#include <algorithm>
#include <iterator>
#include <type_traits>
#include <memory>
 
class TwoWire;
class HardwareSerial;
class SPIClass;
struct SPISettings;
 
namespace m5 {
class I2C_Class;
namespace unit {
 
class UnitUnified;
class Adapter;
 
class Component {
public:
    struct component_config_t {
        uint32_t clock{100000};
        uint32_t stored_size{1};
        bool self_update{false};
        uint8_t max_children{0};
    };
 
    static const types::uid_t uid;    
    static const types::attr_t attr;  
    static const char name[];         
 
    explicit Component(const uint8_t addr = 0x00);  // I2C address
 
    Component(const Component&) = delete;
 
    Component(Component&&) noexcept = default;
 
    Component& operator=(const Component&) = delete;
 
    Component& operator=(Component&&) noexcept = default;
 
    virtual ~Component() = default;
 
 
    inline component_config_t component_config() const
    {
        return _component_cfg;
    }
    inline void component_config(const component_config_t& cfg)
    {
        _component_cfg = cfg;
    }
 
 
    virtual bool begin()
    {
        return true;
    }
    virtual void update(const bool force = false)
    {
        (void)force;
    }
 
 
    inline const char* deviceName() const
    {
        return unit_device_name();
    }
    inline types::uid_t identifier() const
    {
        return unit_identifier();
    }
    inline types::attr_t attribute() const
    {
        return unit_attribute();
    }
    inline types::category_t category() const
    {
        return unit_category();
    }
    inline uint32_t order() const
    {
        return _order;
    }
    inline int16_t channel() const
    {
        return _channel;
    }
    inline bool isRegistered() const
    {
        return _manager != nullptr;
    }
    inline uint8_t address() const
    {
        return _addr;
    }
    inline Adapter* adapter() const
    {
        return _adapter.get();
    }
    template <class T>
    inline auto asAdapter(const Adapter::Type t) ->
        typename std::remove_cv<typename std::remove_pointer<T>::type>::type*
    {
        using U = typename std::remove_cv<typename std::remove_pointer<T>::type>::type;
        static_assert(std::is_base_of<Adapter, U>::value, "T must be derived from Adapter");
        return (_adapter->type() == t) ? static_cast<U*>(_adapter.get()) : nullptr;
    }
    template <class T>
    inline auto asAdapter(const Adapter::Type t) const -> const
        typename std::remove_cv<typename std::remove_pointer<T>::type>::type*
    {
        using U = typename std::remove_cv<typename std::remove_pointer<T>::type>::type;
        static_assert(std::is_base_of<Adapter, U>::value, "T must be derived from Adapter");
        return (_adapter->type() == t) ? static_cast<const U*>(_adapter.get()) : nullptr;
    }
 
    bool canAccessI2C() const;
    bool canAccessGPIO() const;
    bool canAccessUART() const;
    bool canAccessSPI() const;
 
 
    inline bool inPeriodic() const
    {
        return in_periodic();
    }
    inline bool updated() const
    {
        return _updated;
    }
    inline types::elapsed_time_t updatedMillis() const
    {
        return _latest;
    }
    inline types::elapsed_time_t interval() const
    {
        return _interval;
    }
 
 
    virtual bool assign(m5::hal::bus::Bus* bus);
    virtual bool assign(TwoWire& wire);
    virtual bool assign(m5::I2C_Class& i2c);
    virtual bool assign(const int8_t rx_pin, const int8_t tx_pin);
    virtual bool assign(HardwareSerial& serial);
    virtual bool assign(SPIClass& spi, const SPISettings& settings);
 
 
    inline bool hasParent() const
    {
        return _parent != nullptr;
    }
    inline bool hasSiblings() const
    {
        return (_prev != nullptr) || (_next != nullptr);
    }
    inline bool hasChildren() const
    {
        return _child;
    }
    size_t childrenSize() const;
    bool existsChild(const uint8_t ch) const;
    inline Component* parent()
    {
        return _parent;
    }
    Component* child(const uint8_t channel) const;
    bool add(Component& c, const int16_t channel);
    bool selectChannel(const uint8_t ch = 8);
 
    template <typename T>
    class iterator {
    public:
        using iterator_category = std::forward_iterator_tag;
        using difference_type   = std::ptrdiff_t;
        using value_type        = T;
        using pointer           = T*;
        using reference         = T&;
 
        explicit iterator(Component* c = nullptr) : _ptr(c)
        {
        }
 
        reference operator*() const
        {
            return *_ptr;
        }
        pointer operator->() const
        {
            return _ptr;
        }
        iterator& operator++()
        {
            _ptr = _ptr ? _ptr->_next : nullptr;
            return *this;
        }
        iterator operator++(int)
        {
            auto tmp = *this;
            ++(*this);
            return tmp;
        }
        friend bool operator==(const iterator& a, const iterator& b)
        {
            return a._ptr == b._ptr;
        }
        friend bool operator!=(const iterator& a, const iterator& b)
        {
            return a._ptr != b._ptr;
        }
 
    private:
        Component* _ptr;
    };
 
    using child_iterator       = iterator<Component>;
    using const_child_iterator = iterator<const Component>;
    inline child_iterator childBegin() noexcept
    {
        return child_iterator(_child);
    }
    inline child_iterator childEnd() noexcept
    {
        return child_iterator();
    }
    inline const_child_iterator childBegin() const noexcept
    {
        return const_child_iterator(_child);
    }
    inline const_child_iterator childEnd() const noexcept
    {
        return const_child_iterator();
    }
 
    bool generalCall(const uint8_t* data, const size_t len);
 
    virtual std::string debugInfo() const;
 
 
    // I2C R/W
    m5::hal::error::error_t readWithTransaction(uint8_t* data, const size_t len);
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool readRegister(const Reg reg, uint8_t* rbuf, const size_t len, const uint32_t delayMillis,
                      const bool stop = true);
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool readRegister8(const Reg reg, uint8_t& result, const uint32_t delayMillis, const bool stop = true);
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool readRegister16BE(const Reg reg, uint16_t& result, const uint32_t delayMillis, const bool stop = true)
    {
        return read_register16E(reg, result, delayMillis, stop, true);
    }
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool readRegister16LE(const Reg reg, uint16_t& result, const uint32_t delayMillis, const bool stop = true)
    {
        return read_register16E(reg, result, delayMillis, stop, false);
    }
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool readRegister32BE(const Reg reg, uint32_t& result, const uint32_t delayMillis, const bool stop = true)
    {
        return read_register32E(reg, result, delayMillis, stop, true);
    }
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool readRegister32LE(const Reg reg, uint32_t& result, const uint32_t delayMillis, const bool stop = true)
    {
        return read_register32E(reg, result, delayMillis, stop, false);
    }
 
    m5::hal::error::error_t writeWithTransaction(const uint8_t* data, const size_t len, const uint32_t exparam = 1);
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    m5::hal::error::error_t writeWithTransaction(const Reg reg, const uint8_t* data, const size_t len,
                                                 const bool stop = true);
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool writeRegister(const Reg reg, const uint8_t* buf = nullptr, const size_t len = 0U, const bool stop = true);
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool writeRegister8(const Reg reg, const uint8_t value, const bool stop = true);
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool writeRegister16BE(const Reg reg, const uint16_t value, const bool stop = true)
    {
        return write_register16E(reg, value, stop, true);
    }
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool writeRegister16LE(const Reg reg, const uint16_t value, const bool stop = true)
    {
        return write_register16E(reg, value, stop, false);
    }
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool writeRegister32BE(const Reg reg, const uint32_t value, const bool stop = true)
    {
        return write_register32E(reg, value, stop, true);
    }
 
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    inline bool writeRegister32LE(const Reg reg, const uint32_t value, const bool stop = true)
    {
        return write_register32E(reg, value, stop, false);
    }
 
    // GPIO
    bool pinModeRX(const gpio::Mode m);
    bool writeDigitalRX(const bool high);
    bool readDigitalRX(bool& high);
    bool writeAnalogRX(const uint16_t v);
    bool readAnalogRX(uint16_t& v);
    bool readAnalogMilliVoltsRX(uint32_t& mv);
    bool pulseInRX(uint32_t& duration, const int state, const uint32_t timeout_us = 1000000);
 
    bool pinModeTX(const gpio::Mode m);
    bool writeDigitalTX(const bool high);
    bool readDigitalTX(bool& high);
    bool writeAnalogTX(const uint16_t v);
    bool readAnalogTX(uint16_t& v);
    bool readAnalogMilliVoltsTX(uint32_t& mv);
    bool pulseInTX(uint32_t& duration, const int state, const uint32_t timeout_us = 1000000);
 
#if defined(DOXYGEN_PROCESS)
    // There is a problem with the Doxygen output of templates containing std::enable_if,
    // so we need a section for Doxygen output
    m5::hal::error::error_t readWithTransaction(uint8_t* data, const size_t len);
    template <typename Reg>
    bool readRegister(const Reg reg, uint8_t* rbuf, const size_t len, const uint32_t delayMillis,
                      const bool stop = true);
    template <typename Reg>
    bool readRegister8(const Reg reg, uint8_t& result, const uint32_t delayMillis, const bool stop = true);
    template <typename Reg>
    bool readRegister16BE(const Reg reg, uint16_t& result, const uint32_t delayMillis, const bool stop = true);
    template <typename Reg>
    bool readRegister16LE(const Reg reg, uint16_t& result, const uint32_t delayMillis, const bool stop = true);
    template <typename Reg>
    bool readRegister32BE(const Reg reg, uint32_t& result, const uint32_t delayMillis, const bool stop = true);
    template <typename Reg>
    bool readRegister32LE(const Reg reg, uint32_t& result, const uint32_t delayMillis, const bool stop = true);
 
    m5::hal::error::error_t writeWithTransaction(const uint8_t* data, const size_t len, const bool stop = true);
    template <typename Reg>
    m5::hal::error::error_t writeWithTransaction(const Reg reg, const uint8_t* data, const size_t len,
                                                 const bool stop = true);
    template <typename Reg>
    bool writeRegister(const Reg reg, const uint8_t* buf = nullptr, const size_t len = 0U, const bool stop = true);
    template <typename Reg>
    bool writeRegister8(const Reg reg, const uint8_t value, const bool stop = true);
    template <typename Reg>
    bool writeRegister16BE(const Reg reg, const uint16_t value, const bool stop = true);
    template <typename Reg>
    bool writeRegister16LE(const Reg reg, const uint16_t value, const bool stop = true);
    template <typename Reg>
    bool writeRegister32BE(const Reg reg, const uint32_t value, const bool stop = true);
    template <typename Reg>
    bool writeRegister32LE(const Reg reg, const uint32_t value, const bool stop = true);
#endif
 
protected:
    // Proper implementation in derived classes is required
    virtual const char* unit_device_name() const = 0;
    virtual types::uid_t unit_identifier() const = 0;
    virtual types::attr_t unit_attribute() const = 0;
    inline virtual types::category_t unit_category() const
    {
        return types::category_t::None;
    }
    inline virtual bool in_periodic() const
    {
        return _periodic;
    }
 
    inline virtual std::shared_ptr<Adapter> ensure_adapter(const uint8_t /*ch*/)
    {
        return _adapter;  // By default, offer my adapter for sharing
    }
 
    // Select valid channel if exists(PaHub etc...)
    inline virtual m5::hal::error::error_t select_channel(const uint8_t)
    {
        return m5::hal::error::error_t::OK;
    }
 
    inline size_t stored_size() const
    {
        return _component_cfg.stored_size;
    }
 
    bool add_child(Component* c);
 
    // I2C
    bool changeAddress(const uint8_t addr);  // Functions for dynamically addressable devices
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool read_register16E(const Reg reg, uint16_t& result, const uint32_t delayMillis, const bool stop,
                          const bool endian);
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool write_register16E(const Reg reg, const uint16_t value, const bool stop, const bool endian);
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool read_register32E(const Reg reg, uint32_t& result, const uint32_t delayMillis, const bool stop,
                          const bool endian);
    template <typename Reg,
              typename std::enable_if<std::is_integral<Reg>::value && std::is_unsigned<Reg>::value && sizeof(Reg) <= 2,
                                      std::nullptr_t>::type = nullptr>
    bool write_register32E(const Reg reg, const uint32_t value, const bool stop, const bool endian);
 
protected:
    // For periodic measurement
    types::elapsed_time_t _latest{}, _interval{};
    bool _periodic{};  // During periodic measurement?
    bool _updated{};
 
private:
    UnitUnified* _manager{};
    std::shared_ptr<m5::unit::Adapter> _adapter{};
 
    uint32_t _order{};
    component_config_t _component_cfg{};
    int16_t _channel{-1};  // valid [0...]
    uint8_t _addr{};
    bool _begun{};
 
    // for chain
    Component* _parent{};
    Component* _next{};
    Component* _prev{};
    Component* _child{};
 
    friend class UnitUnified;
};
 
template <class Derived, typename MD>
class PeriodicMeasurementAdapter {
public:
 
    template <typename... Args>
    inline bool startPeriodicMeasurement(Args&&... args)
    {
        // Prepare for future common initiation preprocessing needs
        return static_cast<Derived*>(this)->start_periodic_measurement(std::forward<Args>(args)...);
    }
    template <typename... Args>
    inline bool stopPeriodicMeasurement(Args&&... args)
    {
        // Prepare for future common stopping preprocessing needs
        return static_cast<Derived*>(this)->stop_periodic_measurement(std::forward<Args>(args)...);
    }
 
    inline size_t available() const
    {
        return available_periodic_measurement_data();
    }
    inline bool empty() const
    {
        return empty_periodic_measurement_data();
    }
    inline bool full() const
    {
        return full_periodic_measurement_data();
    }
    inline MD oldest() const
    {
        return static_cast<const Derived*>(this)->oldest_periodic_data();
    }
    inline MD latest() const
    {
        return static_cast<const Derived*>(this)->latest_periodic_data();
    }
    inline void discard()
    {
        discard_periodic_measurement_data();
    }
    inline void flush()
    {
        flush_periodic_measurement_data();
    }
 
protected:
    virtual size_t available_periodic_measurement_data() const = 0;
    virtual bool empty_periodic_measurement_data() const       = 0;
    virtual bool full_periodic_measurement_data() const        = 0;
    virtual void discard_periodic_measurement_data()           = 0;
    virtual void flush_periodic_measurement_data()             = 0;
};
 
}  // namespace unit
}  // namespace m5
 
// Helper for creating derived classes from Component
#define M5_UNIT_COMPONENT_HPP_BUILDER(cls, reg)                  \
public:                                                          \
    constexpr static uint8_t DEFAULT_ADDRESS{(reg)};             \
    static const types::uid_t uid;                               \
    static const types::attr_t attr;                             \
    static const char name[];                                    \
                                                                 \
    cls(const cls&) = delete;                                    \
                                                                 \
    cls& operator=(const cls&) = delete;                         \
                                                                 \
    cls(cls&&) noexcept = default;                               \
                                                                 \
    cls& operator=(cls&&) noexcept = default;                    \
                                                                 \
protected:                                                       \
    inline virtual const char* unit_device_name() const override \
    {                                                            \
        return name;                                             \
    }                                                            \
    inline virtual types::uid_t unit_identifier() const override \
    {                                                            \
        return uid;                                              \
    }                                                            \
    inline virtual types::attr_t unit_attribute() const override \
    {                                                            \
        return attr;                                             \
    }
 
// Helper for creating derived class from PeriodicMeasurementAdapter
#define M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(cls, md)    \
protected:                                                                     \
    friend class PeriodicMeasurementAdapter<cls, md>;                          \
                                                                               \
    inline md oldest_periodic_data() const                                     \
    {                                                                          \
        return !_data->empty() ? _data->front().value() : md{};                \
    }                                                                          \
    inline md latest_periodic_data() const                                     \
    {                                                                          \
        return !_data->empty() ? _data->back().value() : md{};                 \
    }                                                                          \
    inline virtual size_t available_periodic_measurement_data() const override \
    {                                                                          \
        return _data->size();                                                  \
    }                                                                          \
    inline virtual bool empty_periodic_measurement_data() const override       \
    {                                                                          \
        return _data->empty();                                                 \
    }                                                                          \
    inline virtual bool full_periodic_measurement_data() const override        \
    {                                                                          \
        return _data->full();                                                  \
    }                                                                          \
    inline virtual void discard_periodic_measurement_data() override           \
    {                                                                          \
        _data->pop_front();                                                    \
    }                                                                          \
    inline virtual void flush_periodic_measurement_data() override             \
    {                                                                          \
        _data->clear();                                                        \
    }
 
#endif