unit_LED.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_RGB_UNIT_LED_HPP
#define M5_UNIT_RGB_UNIT_LED_HPP
 
#include "unit_LED_data.hpp"
#include <M5UnitComponent.hpp>
#include <vector>
 
namespace m5 {
namespace unit {
 
namespace rgb {
 
enum class Order : int8_t {
    unknown = -1,  
    // 24 bits (no white channel)
    rgb24,
    rbg24,
    grb24,
    gbr24,
    brg24,
    bgr24,
    // 32 bits (with white channel)
    hasWhite,  
    //
    wrgb32 = hasWhite,  
    wrbg32,
    wgrb32,
    wgbr32,
    wbrg32,
    wbgr32,
    //
    rwgb32,
    rwbg32,
    rgwb32,
    rgbw32,
    rbwg32,
    rbgw32,
    //
    gwrb32,
    gwbr32,
    grwb32,
    grbw32,
    gbwr32,
    gbrw32,
    //
    bwrg32,
    bwgr32,
    brwg32,
    brgw32,
    bgwr32,
    bgrw32,
};
 
int8_t offsetR(const Order f);
int8_t offsetG(const Order f);
int8_t offsetB(const Order f);
int8_t offsetW(const Order f);
}  // namespace rgb
 
class UnitLED : public Component {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitLED, 0x00);
 
    class PixelProxy {
    public:
        PixelProxy(UnitLED& u, const uint32_t i) : _u(u), _i(i), _c{u.color(i)}
        {
        }
 
        inline operator rgb::Color() const
        {
            return _c;
        }
 
        PixelProxy& operator=(const rgb::Color& c)
        {
            _c = c;
            _u.setPixelColor(_i, _c);
            return *this;
        }
        PixelProxy& operator=(const PixelProxy& o)
        {
            _c = static_cast<rgb::Color>(o);
            _u.setPixelColor(_i, _c);
            return *this;
        }
 
    private:
        UnitLED& _u;
        uint32_t _i;
        rgb::Color _c;  // Color at the time of Proxy creation
    };
 
public:
    using container_type      = std::vector<uint8_t>;              
    using item_container_type = std::vector<gpio::m5_rmt_item_t>;  
 
    struct config_t {
        uint8_t brightness{10};  
        uint8_t mem_blocks{0};
        bool with_dma{false};
    };
 
 
    inline config_t config() const
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
    virtual ~UnitLED()
    {
    }
 
    bool add(UnitLED& c, const int16_t channel);
 
    virtual bool begin() override;
 
 
    inline uint16_t numPixels() const
    {
        return _numPixels;
    }
    inline uint8_t brightness() const
    {
        return _brightness;
    }
 
    inline virtual uint16_t width() const
    {
        return numPixels();
    }
    inline virtual uint16_t height() const
    {
        return 1;
    }
 
    inline bool hasWhite() const
    {
        return (_order >= rgb::Order::hasWhite);
    }
    inline rgb::Order order() const
    {
        return _order;
    }
    inline int8_t offsetR() const
    {
        return _offsetR;
    }
    inline int8_t offsetG() const
    {
        return _offsetG;
    }
    inline int8_t offsetB() const
    {
        return _offsetB;
    }
    inline int8_t offsetW() const
    {
        return _offsetW;
    }
 
    const container_type& pixels() const
    {
        return _pixels;
    }
    inline rgb::Color color(const uint16_t n) const
    {
        return (n < _numPixels) ? get_pixel_color(index_of(n)) : rgb::Color();
    }
    inline rgb::Color absoluteColor(const uint16_t n) const
    {
        return (n < _numPixels) ? get_pixel_color(n) : rgb::Color();
    }
 
 
    bool writePixels();
    inline bool show()
    {
        return writePixels();
    }
 
 
    inline void setBrightness(const uint8_t b)
    {
        _brightness = b;
    }
    bool setPixelColor(const uint16_t n, const uint8_t r, const uint8_t g, const uint8_t b);
    inline bool setPixelColor(const uint16_t n, const uint8_t r, const uint8_t g, const uint8_t b, const uint8_t w)
    {
        return setPixelColor(n, rgb::Color(r, g, b, w));
    }
    inline bool setPixelColor(const uint16_t n, const rgb::wrgb32_color_t c)
    {
        return setPixelColor(n, rgb::Color(c));
    }
    inline bool setPixelColor(const uint16_t n, const rgb::Color& c)
    {
        if (n >= _numPixels) {
            return false;
        }
        return set_pixel_color(index_of(n), c);
    }
    bool fill(const rgb::Color& c, const uint16_t first = 0, const uint16_t count = 0);
    inline void clear(void)
    {
        fill(rgb::Color());
    }
    bool fillRainbow(const uint16_t first = 0, const uint16_t count = 0, const uint8_t firstHue = 0);
    bool fillGradation(const rgb::Color& firstClr, const rgb::Color& lastClr, const uint16_t first = 0,
                       const uint16_t count = 0);
    bool fillRandom(const uint16_t first = 0, const uint16_t count = 0);
    inline void shiftLeft(const uint16_t count = 1)
    {
        shift_left(count, false);
    }
    inline void shiftRight(const uint16_t count = 1)
    {
        shift_right(count, false);
    }
    inline void rotateLeft(const uint16_t count = 1)
    {
        shift_left(count, true);
    }
    inline void rotateRight(const uint16_t count = 1)
    {
        shift_right(count, true);
    }
 
 
    inline virtual uint8_t maxRotation() const
    {
        return 2;  // 0,180 deg
    }
    inline float rotationDegree() const
    {
        return 360.f / maxRotation();
    }
    inline int8_t rotation() const
    {
        return _rot;
    }
    void setRotation(const int8_t rot);
 
 
    rgb::Color operator[](const uint16_t i) const
    {
        return color(i);
    }
    PixelProxy operator[](const uint16_t i)
    {
        return PixelProxy(*this, i);
    }
 
    // Class that abstracts the interaction between classes and adapters
    class Interface {
    public:
        explicit Interface(UnitLED& u) : _unit{u}
        {
        }
        virtual ~Interface()
        {
        }
        virtual bool write(const uint8_t*, const uint32_t) = 0;
        // For RGB888
        virtual UnitLED::container_type rgb888_items()
        {
            return {};
        }
        virtual UnitLED::container_type rgb888_items_from_root()
        {
            return {};
        }
 
        // Write pixels directly via the protocol-specific method
        virtual bool writePixelsDirect()
        {
            return false;
        }
 
    protected:
        UnitLED& _unit;
    };
 
protected:
    inline virtual types::category_t unit_category() const override
    {
        return types::category_t::UnitLED;
    }
    inline virtual gpio::adapter_config_t rmt_config()
    {
        return gpio::adapter_config_t{};
    }
    inline virtual gpio::m5_rmt_item_t rmt_item_one()
    {
        return gpio::m5_rmt_item_t{};
    }
    inline virtual gpio::m5_rmt_item_t rmt_item_zero()
    {
        return gpio::m5_rmt_item_t{};
    }
    inline virtual gpio::m5_rmt_item_t rmt_item_reset()
    {
        return gpio::m5_rmt_item_t{};
    }
    // RMT TX resolution (Hz) used to convert durations to ticks.
    // The actual one from M5UnitUnified 0.6.4 or later, otherwise the one requested by rmt_config().tx.tick_ns
    uint32_t rmt_resolution_hz();
    // RMT item of a data bit: high for high_ns, then low for low_ns
    gpio::m5_rmt_item_t rmt_item_from_ns(const uint32_t high_ns, const uint32_t low_ns);
    // RMT item that holds the line low for low_ns (reset / latch)
    gpio::m5_rmt_item_t rmt_item_low_from_ns(const uint32_t low_ns);
    inline container_type& pixels()
    {
        return _pixels;
    }
 
    // Not affected by rotation
    rgb::Color get_pixel_color(const uint16_t n) const;
    bool set_pixel_color(const uint16_t n, const rgb::Color& c);
 
    inline uint8_t rotation_of(const int8_t r) const
    {
        return (r % maxRotation() + maxRotation()) % maxRotation();
    }
 
    inline virtual uint16_t index_of(const uint16_t n) const
    {
        // 0 or 180 deg
        return _rot ? _numPixels - (n % _numPixels) - 1 : n;
    }
 
    container_type rgb888_items();
 
    void shift_left(const uint16_t count, const bool wrap);
    void shift_right(const uint16_t count, const bool wrap);
 
protected:
    // Protected so only derived types with hardcoded Order (UnitRGB / UnitPuzzle / ...) can construct.
    explicit UnitLED(const uint16_t num_of_pixels, const rgb::Order order)
        : Component(0x00), _order{order}, _numPixels{num_of_pixels}
    {
        _offsetR = rgb::offsetR(_order);
        _offsetG = rgb::offsetG(_order);
        _offsetB = rgb::offsetB(_order);
        _offsetW = rgb::offsetW(_order);
        _pixels.resize(_numPixels * (3 + hasWhite()));
    }
 
private:
    rgb::Order _order{rgb::Order::unknown};
    uint8_t _brightness{10};
    int8_t _rot{};
    int8_t _offsetR{-1}, _offsetG{-1}, _offsetB{-1}, _offsetW{-1};
    uint16_t _numPixels{};
    bool _ready{false};
    container_type _pixels{};  // Order by rgb::Order
    std::unique_ptr<Interface> _interface{};
    config_t _cfg{};
    uint32_t _rmt_resolution_hz{};  // 0 = unknown, see rmt_resolution_hz()
 
    friend class InterfaceGPIO;
    friend class InterfacePbHub;
};
 
}  // namespace unit
}  // namespace m5
#endif