SBK_BarDrive.h

Go to the documentation of this file.

 
#pragma once

#ifndef SBK_BARDRIVE_WITH_ANIM
#pragma message(" ⚠️ SBK_BARDRIVE_WITH_ANIM is not defined. SBK BarDrive Built-in animations are disabled and cannot be accessed, saving memory if they are not needed. If you do need the animations library, define SBK_BARDRIVE_WITH_ANIM before including SBK_BarDrive.h.")
#endif
 
// IMPORTANT: Include the appropriate driver before SBK_BarDrive.h
// e.g., #include <SBK_MAX72xxSoft.h>, <SBK_MAX72xxHard.h> or <SBK_HT16K33.h>
#if !defined(SBK_MAX72xx_IS_DEFINED) && !defined(SBK_HT16K33_IS_DEFINED)
#pragma message(" ⚠️ SBK BarDrive library note: Include an SBK_MAX72xx or SBK_HT16K33 driver header and declare a driver before creating a bar meter instance.")
#endif
 
#include <Arduino.h>
#ifdef SBK_BARDRIVE_WITH_ANIM
#include "SBK_BarMeterAnimations.h"
#endif

enum class MatrixPreset
{
    NONE,              
    SBK_BarMeter_SK28, 
    SBK_BarMeter_SA28, 
    BL28_3005SK,       
    BL28_3005SA        
};

enum class BarDirection : uint8_t
{
    FORWARD = 0, 
    REVERSE = 1  
};

template <typename DriverT>
class SBK_BarMeter
{
public:
    SBK_BarMeter(DriverT *driver,
                 uint8_t devIdx,
                 MatrixPreset matrixPreset = MatrixPreset::BL28_3005SK,
                 BarDirection direction = BarDirection::FORWARD,
                 uint8_t rowOffset = 0,
                 uint8_t colOffset = 0)
        : _driver(driver),
          _devIdx(constrain(devIdx, 0, 7)),
          _matrixPreset(matrixPreset),
          _direction(direction)
    {
        _isMatrixMapped = true;
        if (_devIdx > (driver->devsNum() - 1))
        {
            _initializePresetMapping(MatrixPreset::NONE);
            _segsNum = 0;
            _rowsNum = 0;
            _colsNum = 0;
            _rowOffset = 0;
            _colOffset = 0;
        }
        else
        {
            _initializePresetMapping(matrixPreset);
            _rowOffset = constrain(rowOffset, 0, _driver->maxRows(_devIdx) - 1);
            _colOffset = constrain(colOffset, 0, _driver->maxColumns() - 1);
        }
    }

    SBK_BarMeter(DriverT *driver,
                 uint8_t devIdx,
                 uint8_t rowsNum,
                 uint8_t colsNum,
                 BarDirection direction = BarDirection::FORWARD,
                 uint8_t rowOffset = 0,
                 uint8_t colOffset = 0)
        : _driver(driver),
          _devIdx(constrain(devIdx, 0, 7)),
          _direction(direction)
    {
        _isMatrixMapped = true;
        if (_devIdx > (driver->devsNum() - 1))
        {
            _segsNum = 0;
            _rowsNum = 0;
            _colsNum = 0;
            _rowOffset = 0;
            _colOffset = 0;
        }
        else
        {
            _rowsNum = constrain(rowsNum, 1, 255);
            _colsNum = constrain(colsNum, 1, driver->maxColumns());
            _rowOffset = constrain(rowOffset, 0, _driver->maxRows(_devIdx) - 1);
            _colOffset = constrain(colOffset, 0, _driver->maxColumns() - 1);
        }
    }

    SBK_BarMeter(DriverT *driver,
                 uint8_t devIdx,
                 uint8_t segsNum,
                 BarDirection direction = BarDirection::FORWARD,
                 uint8_t segOffset = 0)
        : _driver(driver),
          _devIdx(constrain(devIdx, 0, 7)),
          _direction(direction),
          _segsNum(segsNum)
    {
        _isMatrixMapped = false;
        if (_devIdx > (driver->devsNum() - 1))
        {
            _segsNum = 0;
            _rowsNum = 0;
            _colsNum = 0;
            _segOffset = 0;
        }
        else
        {
            _rowsNum = _driver->maxRows(_devIdx);
            _colsNum = _driver->maxColumns();
            _segOffset = constrain(segOffset, 0, _driver->maxSegments(_devIdx) - 1);
        }
    }

    template <size_t N>
    SBK_BarMeter(DriverT *driver,
                 uint8_t devIdx,
                 const uint8_t (&mapping)[N][3],
                 BarDirection direction = BarDirection::FORWARD,
                 bool progmem = false,
                 uint8_t rowOffset = 0,
                 uint8_t colOffset = 0)
        : _driver(driver),
          _devIdx(constrain(devIdx, 0, 7)),
          _customMapping(mapping),
          _direction(direction),
          _userMappingIsProgmem(progmem)
    {
        _isMatrixMapped = true;
        if (_devIdx > (driver->devsNum() - 1))
        {
            _segsNum = 0;
            _rowsNum = 0;
            _colsNum = 0;
            _rowOffset = 0;
            _colOffset = 0;
        }
        else
        {
            _segsNum = N;
            _rowsNum = _driver->maxRows(_devIdx);
            _colsNum = _driver->maxColumns();
            _rowOffset = constrain(rowOffset, 0, _driver->maxRows(_devIdx) - 1);
            _colOffset = constrain(colOffset, 0, _driver->maxColumns() - 1);
        }
    }
 
    ~SBK_BarMeter() { /* Nothing to clean up for now*/ }

    void show() { _driver->show(); }

    void clear()
    {
        for (uint8_t i = 0; i < _segsNum; ++i)
            setPixel(i, false);
    }

    void setDirection(BarDirection dir) { _direction = dir; }

    BarDirection getDirection() const { return _direction; }

    uint8_t getSegsNum() const { return _segsNum; }

    void debugSegmentMapping(Stream &stream = Serial)
    {
        for (uint8_t i = 0; i < _segsNum; ++i)
        {
            uint8_t devIdx = _devIdx;
            uint8_t rowIdx, colIdx;
            _getMappedDevRowCol(i, &devIdx, &rowIdx, &colIdx);
            stream.print(F("Segment "));
            stream.print(i);
            stream.print(F(" → Device "));
            stream.print(devIdx);
            stream.print(F(", Row "));
            stream.print(rowIdx);
            stream.print(F(", Col "));
            stream.println(colIdx);
        }
    }

 
    void setPixel(uint8_t segment, uint8_t state)
    {
        if (segment >= _segsNum || !_driver)
            return;
 
        uint8_t devIdx = _devIdx;
        uint8_t rowIdx, colIdx;
        _getMappedDevRowCol(segment, &devIdx, &rowIdx, &colIdx);
        _driver->setLed(devIdx, rowIdx, colIdx, state != 0);
    }

    uint8_t getPixelState(uint8_t segment) const
    {
        if (segment >= _segsNum || !_driver)
            return false;
 
        uint8_t devIdx = _devIdx;
        uint8_t rowIdx, colIdx;
 
        _getMappedDevRowCol(segment, &devIdx, &rowIdx, &colIdx);
        return _driver->getLed(devIdx, rowIdx, colIdx);
    }

    SBK_BarMeter &setSegmentOffset(uint8_t offset)
    {
        _segOffset = offset;
        return *this;
    }

    SBK_BarMeter &setMatrixOffset(uint8_t rowOffset, uint8_t colOffset)
    {
        _rowOffset = rowOffset;
        _colOffset = colOffset;
        return *this;
    }
 
private:
    void _initializePresetMapping(MatrixPreset matrixPreset)
    {
 
        if (matrixPreset == MatrixPreset::SBK_BarMeter_SK28)
            matrixPreset = MatrixPreset::BL28_3005SK;
        if (matrixPreset == MatrixPreset::SBK_BarMeter_SA28)
            matrixPreset = MatrixPreset::BL28_3005SA;
 
        switch (matrixPreset)
        {
        case MatrixPreset::NONE:
            _rowsNum = _driver->maxRows(_devIdx);
            _colsNum = _driver->maxColumns();
            _segsNum = _rowsNum * _colsNum;
            _isMatrixMapped = false;
            break;
        case MatrixPreset::BL28_3005SK:
            _segsNum = 28;
            _rowsNum = 4;
            _colsNum = 7;
            _isMatrixMapped = true;
            break;
        case MatrixPreset::BL28_3005SA:
            _segsNum = 28;
            _rowsNum = 7;
            _colsNum = 4;
            _isMatrixMapped = true;
            break;
        default:
            _rowsNum = _driver->maxRows(_devIdx);
            _colsNum = _driver->maxColumns();
            _segsNum = _rowsNum * _colsNum;
            _isMatrixMapped = false;
            break;
        }
    }
 
    void _getMappedDevRowCol(uint8_t seg, uint8_t *devIdx, uint8_t *rowIdx, uint8_t *colIdx) const
    {
        // Apply direction correction
        uint8_t mappedSeg = (_direction == BarDirection::REVERSE)
                                ? (_segsNum - 1 - seg)
                                : seg;
 
        // Add segment offset only in segment-based mode
        mappedSeg += (_isMatrixMapped ? 0 : _segOffset);
 
        if (_customMapping)
        {
            // Handle custom mappings
            if (_userMappingIsProgmem)
            {
                *devIdx = pgm_read_byte(&_customMapping[mappedSeg][0]);
                *rowIdx = pgm_read_byte(&_customMapping[mappedSeg][1]);
                *colIdx = pgm_read_byte(&_customMapping[mappedSeg][2]);
            }
            else
            {
                *devIdx = _customMapping[mappedSeg][0];
                *rowIdx = _customMapping[mappedSeg][1] + _rowOffset;
                *colIdx = _customMapping[mappedSeg][2] + _colOffset;
            }
            return;
        }
 
        // Auto mapping
 
        const uint8_t segPerDev = _driver->maxRows(*devIdx) * _driver->maxColumns();
        const uint8_t baseDevIdx = *devIdx + (mappedSeg / segPerDev);
        const uint8_t localIdx = mappedSeg % segPerDev;
 
        if (_isMatrixMapped)
        {
            // Matrix-style layout: column-major mapping
            uint8_t baseRowIdx = localIdx % _rowsNum;
            uint8_t baseColIdx = localIdx / _rowsNum;
 
            *devIdx = baseDevIdx;
            *rowIdx = baseRowIdx + _rowOffset;
            *colIdx = baseColIdx + _colOffset;
        }
        else
        {
            // Segment-style layout: row-major linear index
            uint8_t baseRowIdx = localIdx / _driver->maxColumns();
            uint8_t baseColIdx = localIdx % _driver->maxColumns();
 
            *devIdx = baseDevIdx;
            *rowIdx = baseRowIdx;
            *colIdx = baseColIdx;
        }
    }
 
    DriverT *_driver;
    const uint8_t _devIdx;
    MatrixPreset _matrixPreset = MatrixPreset::NONE;
    const uint8_t (*_customMapping)[3] = nullptr;
    BarDirection _direction;
    uint8_t _segOffset = 0;       // existing logic
    uint8_t _rowOffset = 0;       // for matrix displays
    uint8_t _colOffset = 0;       // for matrix displays
    bool _isMatrixMapped = false; // whether to apply row/col offset
    uint8_t _segsNum;
    uint8_t _rowsNum = 0;
    uint8_t _colsNum = 0;
    bool _userMappingIsProgmem = false;
};
 
// -----------------------------
// SBK_BarDrive wrapper
// -----------------------------
template <typename DriverT>
class SBK_BarDrive
{
public:
    SBK_BarDrive(DriverT *driver,
                 uint8_t devIdx,
                 MatrixPreset matrixPreset,
                 BarDirection direction = BarDirection::FORWARD,
                 uint8_t rowOffset = 0,
                 uint8_t colOffset = 0)
        : _barMeter(driver, devIdx, matrixPreset, direction, rowOffset, colOffset)
#ifdef SBK_BARDRIVE_WITH_ANIM
          ,
          _barAnimations(_barMeter)
#endif
    {
#ifdef SBK_BARDRIVE_WITH_ANIM
        _barAnimations.setSegsNum(_barMeter.getSegsNum());
#endif
    }

    SBK_BarDrive(DriverT *driver,
                 uint8_t devIdx,
                 uint8_t rowsNum,
                 uint8_t colsNum,
                 BarDirection direction = BarDirection::FORWARD,
                 uint8_t rowOffset = 0,
                 uint8_t colOffset = 0)
        : _barMeter(driver, devIdx, rowsNum, colsNum, direction, rowOffset, colOffset)
#ifdef SBK_BARDRIVE_WITH_ANIM
          ,
          _barAnimations(_barMeter)
#endif
    {
#ifdef SBK_BARDRIVE_WITH_ANIM
        _barAnimations.setSegsNum(_barMeter.getSegsNum());
#endif
    }

    SBK_BarDrive(DriverT *driver,
                 uint8_t devIdx,
                 uint8_t segsNum,
                 BarDirection direction = BarDirection::FORWARD,
                 uint8_t segOffset = 0)
        : _barMeter(driver, devIdx, segsNum, direction, segOffset)
#ifdef SBK_BARDRIVE_WITH_ANIM
          ,
          _barAnimations(_barMeter)
#endif
    {
#ifdef SBK_BARDRIVE_WITH_ANIM
        _barAnimations.setSegsNum(_barMeter.getSegsNum());
#endif
    }

    template <size_t N>
    SBK_BarDrive(DriverT *driver,
                 uint8_t devIdx,
                 const uint8_t (&mapping)[N][3],
                 BarDirection direction = BarDirection::FORWARD,
                 bool progmem = false,
                 uint8_t rowOffset = 0,
                 uint8_t colOffset = 0)
        : _barMeter(driver, devIdx, mapping, direction, progmem, rowOffset, colOffset)
#ifdef SBK_BARDRIVE_WITH_ANIM
          ,
          _barAnimations(_barMeter)
#endif
    {
#ifdef SBK_BARDRIVE_WITH_ANIM
        _barAnimations.setSegsNum(_barMeter.getSegsNum());
#endif
    }
 
    ~SBK_BarDrive() { /* Nothing to clean up for now*/ }

    SBK_BarMeter<DriverT> &barmeter() { return _barMeter; }
#ifdef SBK_BARDRIVE_WITH_ANIM
    SBK_BarMeterAnimations<SBK_BarMeter<DriverT>> &animations() { return _barAnimations; }
#endif

    void show() { _barMeter.show(); }

    void clear() { _barMeter.clear(); }

    void setDirection(BarDirection dir) { _barMeter.setDirection(dir); }

    BarDirection getDirection() { return _barMeter.getDirection(); }

    uint8_t getSegsNum() { return _barMeter.getSegsNum(); }

    void debugSegmentMapping(Stream &stream = Serial) { _barMeter.debugSegmentMapping(stream); }

    void setPixel(uint8_t segment, uint8_t state) { _barMeter.setPixel(segment, state); }

    uint8_t getPixelState(uint8_t segment) { return _barMeter.getPixelState(segment); }

    SBK_BarDrive &setSegmentOffset(uint8_t offset)
    {
        _barMeter.setSegmentOffset(offset);
        return *this;
    }

    SBK_BarDrive &setMatrixOffset(uint8_t rowOffset, uint8_t colOffset)
    {
        _barMeter.setMatrixOffset(rowOffset, colOffset);
        return *this;
    }
 
private:
    SBK_BarMeter<DriverT> _barMeter;
#ifdef SBK_BARDRIVE_WITH_ANIM
    SBK_BarMeterAnimations<SBK_BarMeter<DriverT>> _barAnimations;
#endif
};