is31fl3733.hpp

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Cal Abel. All rights reserved.
 *  Author: Cal Abel (async rewrite and ongoing maintenance)
 *  Author: Neil Enns (original C++ library)
 *  Licensed under the MIT License. See LICENSE in the project root for license information.
 *
 *  Based on the original IS31FL3733 C++ library by Neil Enns
 *  (https://github.com/neilenns/is31fl3733).
 *  This is a nearly complete rewrite for asynchronous DMA-driven operation on
 *  Arduino SAMD.
 *
 *  Asynchronous DMA-driven IS31FL3733 driver for Arduino SAMD (SimIO framework).
 *
 *  Architecture:
 *  - Non-blocking I2C via SERCOM transaction descriptors with DMA
 *  - Lock-free ring buffer for PWM row updates (12 rows, bitfield-tracked)
 *  - Single in-flight PWM transaction (_pwmTxn) with shadow buffer (_pwmTxPtr[17])
 *  - Separate command transaction chain (_cmdTxn[4]) for page select / fault handling
 *  - Default Page 1 (PWM) - no page switching for normal writes
 *  - IRQ-driven fault detection (open/short) with async transaction chain
 *  - Color order support (RGB, GRB, BRG, RBG, GBR, BGR)
 *
 *  See /docs/ASYNC_DMA_ARCHITECTURE.md for full design details.
 *--------------------------------------------------------------------------------------------*/
#pragma once
 
#include <Arduino.h>
#include <Wire.h> // TwoWire I2C interface
#include <functional>
 
namespace IS31FL3733 {
// -----------------------------------------------------------------------------------------
// Constants
// -----------------------------------------------------------------------------------------
 
constexpr uint8_t kHardwareRows = 12; 
constexpr uint8_t kHardwareCols = 16; 
constexpr uint8_t kLedCount = kHardwareRows * kHardwareCols; 
 
constexpr uint8_t kLogicalRows = 4; 
 
// -----------------------------------------------------------------------------------------
// Register Addresses (Common + Paged)
// -----------------------------------------------------------------------------------------
 
enum CommonRegister : uint8_t {
    PSR = 0xFD,  
    PSWL = 0xFE, 
    IMR = 0xF0,  
    ISR = 0xF1,  
};
 
enum PagedRegister : uint16_t {
    LEDONOFF = 0x0000, 
    LEDOPEN = 0x0018,  
    LEDSHORT = 0x0030, 
    LEDPWM = 0x0100,   
    LEDABM = 0x0200,   
    CR = 0x0300,       
    GCC = 0x0301,      
    ABM1CR = 0x0302,   
    ABM2CR = 0x0306,   
    ABM3CR = 0x030A,   
    TUR = 0x030E,      
    SWPUR = 0x030F,    
    CSPDR = 0x0310,    
    RESET = 0x0311,    
};
 
// -----------------------------------------------------------------------------------------
// Register Configuration Options
// -----------------------------------------------------------------------------------------
 
enum PswlOptions : uint8_t {
    PSWL_DISABLE = 0x00,
    PSWL_ENABLE = 0xC5,
};
 
enum ImrOptions : uint8_t {
    IMR_IAC = 0x08, 
    IMR_IAB = 0x04, 
    IMR_IS = 0x02,  
    IMR_IO = 0x01,  
};
 
enum IsrOptions : uint8_t {
    ISR_ABM3 = 0x10, 
    ISR_ABM2 = 0x08, 
    ISR_ABM1 = 0x04, 
    ISR_SB = 0x02,   
    ISR_OB = 0x01,   
};
 
enum CrOptions : uint8_t {
    CR_SYNC_MASTER = 0x40,
    CR_SYNC_SLAVE = 0x80,
    CR_OSD = 0x04, 
    CR_BEN = 0x02, 
    CR_SSD = 0x01, 
};
 
inline uint8_t CR_PFS(uint8_t page) {
    return (page & 0x03) << 5;
} // PSR bits are [6:5] for page select
 
// -----------------------------------------------------------------------------------------
// Color Order Enum
// -----------------------------------------------------------------------------------------
 
enum class ColorOrder : uint8_t {
    RGB = 0,
    GRB = 1,
    BRG = 2,
    RBG = 3,
    GBR = 4,
    BGR = 5,
};
 
enum class ABMMode : uint8_t {
    PWM_MODE = 0x00, // Renamed from PWM to avoid Arduino Due macro conflict
    ABM1 = 0x01,
    ABM2 = 0x02,
    ABM3 = 0x03,
};
 
enum AbmT1 : uint8_t {
    T1_210MS = 0x00,   
    T1_420MS = 0x20,   
    T1_840MS = 0x40,   
    T1_1680MS = 0x60,  
    T1_3360MS = 0x80,  
    T1_6720MS = 0xA0,  
    T1_13440MS = 0xC0, 
    T1_26880MS = 0xE0, 
};
 
enum AbmT2 : uint8_t {
    T2_0MS = 0x00,     
    T2_210MS = 0x02,   
    T2_420MS = 0x04,   
    T2_840MS = 0x06,   
    T2_1680MS = 0x08,  
    T2_3360MS = 0x0A,  
    T2_6720MS = 0x0C,  
    T2_13440MS = 0x0E, 
    T2_26880MS = 0x10, 
};
 
enum AbmT3 : uint8_t {
    T3_210MS = 0x00,   
    T3_420MS = 0x20,   
    T3_840MS = 0x40,   
    T3_1680MS = 0x60,  
    T3_3360MS = 0x80,  
    T3_6720MS = 0xA0,  
    T3_13440MS = 0xC0, 
    T3_26880MS = 0xE0, 
};
 
enum AbmT4 : uint8_t {
    T4_0MS = 0x00,      
    T4_210MS = 0x02,    
    T4_420MS = 0x04,    
    T4_840MS = 0x06,    
    T4_1680MS = 0x08,   
    T4_3360MS = 0x0A,   
    T4_6720MS = 0x0C,   
    T4_13440MS = 0x0E,  
    T4_26880MS = 0x10,  
    T4_53760MS = 0x12,  
    T4_107520MS = 0x14, 
};
 
enum AbmLoopBegin : uint8_t {
    LOOP_BEGIN_T1 = 0x00, 
    LOOP_BEGIN_T2 = 0x10, 
    LOOP_BEGIN_T3 = 0x20, 
    LOOP_BEGIN_T4 = 0x30, 
};
 
enum AbmLoopEnd : uint8_t {
    LOOP_END_T3 = 0x00, 
    LOOP_END_T1 = 0x40, 
};
 
constexpr int kAbmLoopTimesMax = 0x0FFF;
constexpr int kAbmLoopForever = 0x0000;
 
struct ABMConfig {
    AbmT1 T1;            
    AbmT2 T2;            
    AbmT3 T3;            
    AbmT4 T4;            
    AbmLoopBegin Tbegin; 
    AbmLoopEnd Tend;     
    uint16_t Times;      
};
 
// -----------------------------------------------------------------------------------------
// IS31FL3733 Async Driver Class
// -----------------------------------------------------------------------------------------
 
class IS31FL3733 {
  public:
    // ---------------------------------------------------------------------------------------
    // Constructor / Destructor
    // ---------------------------------------------------------------------------------------
 
    IS31FL3733(TwoWire *wire, uint8_t addr = 0x50, uint8_t sdbPin = 0xFF, uint8_t irqPin = 0xFF);
 
    ~IS31FL3733();
    // ---------------------------------------------------------------------------------------
    // Initialization
    // ---------------------------------------------------------------------------------------
 
    bool begin(uint8_t pfs = 0, uint8_t pur = 0b111, uint8_t pdr = 0b111);
 
    void end();
    // ---------------------------------------------------------------------------------------
    // Device Control
    // ---------------------------------------------------------------------------------------
 
    void DeviceOn();
 
    void DeviceOff();
    // ---------------------------------------------------------------------------------------
    // Runtime Configuration (Page 3/Common)
    // ---------------------------------------------------------------------------------------
 
    void SetGCC(uint8_t gcc);
 
    void SetSWPUR(uint8_t pur);
 
    void SetCSPDR(uint8_t pdr);
 
    void SetPFS(uint8_t pfs);
 
    void SetIMR(uint8_t imrMask);
 
    void SetShortFaultMaskEnabled(bool enable) {
        _maskShortFaults = enable;
    }
 
    bool GetShortFaultMaskEnabled() const {
        return _maskShortFaults;
    }
 
    bool IsPwmUpdatePending() const {
        return _pwmTxn.txPtr != nullptr || _pwmEnqueued != 0u || _pwmLocked || _pwmBatchActive;
    }
    // ---------------------------------------------------------------------------------------
    // PWM & ABM Control (Raw Hardware Interface)
    // ---------------------------------------------------------------------------------------
 
    void SetPixelPWM(uint8_t row, uint8_t col, uint8_t pwm);
 
    void SetRowPWM(uint8_t row, const uint8_t *pwmValues);
 
    void BeginPwmBatch();
 
    void EndPwmBatch(bool flush = true);
 
    void SetPixelMode(uint8_t row, uint8_t col, ABMMode mode);
 
    void SetRowMode(uint8_t row, ABMMode mode);
 
    ABMMode GetPixelMode(uint8_t row, uint8_t col) const;
    // ---------------------------------------------------------------------------------------
    // RGB Pixel Control (Logical Coordinates with Color Order)
    // ---------------------------------------------------------------------------------------
 
    void SetPixelColor(uint8_t row, uint8_t col, uint8_t r, uint8_t g, uint8_t b);
 
    void SetPixelColorMode(uint8_t row, uint8_t col, ABMMode mode);
 
    void SetColorOrder(ColorOrder order) {
        _colorOrder = order;
    }
 
    ColorOrder GetColorOrder() const {
        return _colorOrder;
    }
    // ---------------------------------------------------------------------------------------
    // Bulk Operations
    // ---------------------------------------------------------------------------------------
 
    void Fill(uint8_t pwm = 0);
 
    void SetMatrixMode(ABMMode mode);
 
    void SetABMCallback(uint8_t abmNum, std::function<void()> callback);
    // ---------------------------------------------------------------------------------------
    // ABM Page 3 Control
    // ---------------------------------------------------------------------------------------
 
    void ConfigureABM(uint8_t abmNumber, const ABMConfig &config);
 
    void ConfigureABM1(const ABMConfig &config);
 
    void ConfigureABM2(const ABMConfig &config);
 
    void ConfigureABM3(const ABMConfig &config);
 
    void EnableABM(bool enable = true);
 
    void TriggerABM();
    // ---------------------------------------------------------------------------------------
    // Fault Detection (Read-Only)
    // ---------------------------------------------------------------------------------------
 
    const uint8_t *GetLEDOpen() const {
        return _ledOpen;
    }
 
    const uint8_t *GetLEDShort() const {
        return _ledShort;
    }
 
    const uint8_t *GetLEDOn() const {
        return _ledOn;
    }
#ifndef TEST_NATIVE
  private:
#endif // TEST_NATIVE
    // ---------------------------------------------------------------------------------------
    // Hardware Handles
    // ---------------------------------------------------------------------------------------
    SERCOM *_hw;          
    uint8_t _addr;        
    uint8_t _sdbPin;      
    uint8_t _irqPin;      
    uint8_t _currentPage; 
 
    static IS31FL3733 *_instance; 
    // ---------------------------------------------------------------------------------------
    // PWM Matrix and Transaction State (Page 1)
    // ---------------------------------------------------------------------------------------
    uint8_t _pwm_matrix[kHardwareRows]
                       [kHardwareCols + 1]; 
    SercomTxn _pwmTxn;                      
    uint8_t _pwmTxPtr[kHardwareCols + 1];   
 
    RingBufferN<kHardwareRows + 1> _pwmPendingRows; 
    uint16_t _pwmEnqueued; 
 
    bool _pwmLocked;      
    bool _pwmBatchActive; 
    // ---------------------------------------------------------------------------------------
    // Mode Matrix and Transaction State (Page 2)
    // ---------------------------------------------------------------------------------------
    uint8_t _abm_matrix[kHardwareRows]
                       [kHardwareCols + 1]; 
    SercomTxn _abmTxn;                      
    uint8_t _abmTxPtr[kHardwareCols + 1];   
 
    RingBufferN<kHardwareRows + 1> _abmPendingRows; 
    uint16_t _abmEnqueued; 
 
    bool _abmLocked; 
 
    std::function<void()> _abmCallbacks[3]; 
    // ---------------------------------------------------------------------------------------
    // Command Transaction Chain (Non-PWM Operations)
    // ---------------------------------------------------------------------------------------
    SercomTxn _cmdTxn[4]; 
 
    struct CmdTxnContext {
        IS31FL3733 *self;                  
        uint8_t index;                     
        void (*userCallback)(void *, int); 
        void *user;                        
        bool isFinal;                      
        int initialStatus;                 
    };
 
    CmdTxnContext _cmdCtx[4]; 
    uint8_t _crwlTx[2];       
    uint8_t _pgSelTx[2];      
    uint8_t _cmdTx[25];       
    uint8_t _cmdRx[24];       
 
    volatile uint8_t _cmdReturn; 
    volatile uint8_t _cmdError;  
 
    volatile bool _syncComplete;    
    volatile int _syncStatus;       
    volatile int8_t _syncTargetCmd; 
    bool _begun; 
 
    // ---------------------------------------------------------------------------------------
    // Fault Detection and ISR Cache
    // ---------------------------------------------------------------------------------------
    uint8_t _ledOpen[24];  
    uint8_t _ledShort[24]; 
    uint8_t _ledOn[24];    
    uint8_t _lastISR;      
    // ---------------------------------------------------------------------------------------
    // Configuration
    // ---------------------------------------------------------------------------------------
    uint8_t _crValue;       
    ColorOrder _colorOrder; 
    bool _maskShortFaults;  
    // ---------------------------------------------------------------------------------------
    // Private Methods (Transaction Management)
    // ---------------------------------------------------------------------------------------
 
    inline void _sendRowPWM();
 
    inline void _sendRowMode();
 
    void _ensurePage(uint8_t page);
 
    void _resumeDataTransfers();
 
    inline void _asyncWrite(uint16_t pagereg, const uint8_t *data, uint8_t len,
                            void (*callback)(void *, int) = nullptr, void *user = nullptr);
 
    inline void _asyncRead(uint16_t pagereg, uint8_t *dest, uint8_t len,
                           void (*callback)(void *, int) = nullptr, void *user = nullptr);
 
    bool _syncWrite(uint16_t pagereg, const uint8_t *data, uint8_t len);
 
    bool _syncRead(uint16_t pagereg, uint8_t *dest, uint8_t len);
    // ---------------------------------------------------------------------------------------
    // Static Callbacks
    // ---------------------------------------------------------------------------------------
 
    static inline void _txnCallback(void *user, int status);
 
    static inline void _txnModeCallback(void *user, int status);
 
    static inline void _irqCallback();
 
    static inline void _onServiceCallback(void *user, int status);
 
    static void _cmdCallback(void *user, int status);
 
    static void _osbCallback(void *user, int status);
 
    static void _abm1CallbackWrapper();
    static void _abm2CallbackWrapper();
    static void _abm3CallbackWrapper();
};
 
// =========================================================================================
// Inline Method Implementations
// =========================================================================================
 
inline void IS31FL3733::_sendRowPWM() {
    // Don't send if PWM is locked, batch staging is active, or if transaction is in-flight
    if (_pwmLocked || _pwmBatchActive || _pwmTxn.txPtr)
        return;
 
    // Dequeue next row
    int row = _pwmPendingRows.read_char();
    if (row < 0) {
        // Queue can be full with one row represented only in _pwmEnqueued.
        for (uint8_t candidate = 0; candidate < kHardwareRows; candidate++) {
            if (_pwmEnqueued & (1u << candidate)) {
                row = candidate;
                break;
            }
        }
    }
 
    if (row < 0)
        return; // Nothing pending
 
    // Clear enqueued bit
    _pwmEnqueued &= ~(1 << row);
 
    // Copy row data to transmit buffer
    memcpy(_pwmTxPtr, _pwm_matrix[row], 17);
 
    // Point transaction at prepared PWM row buffer
    _pwmTxn.txPtr = _pwmTxPtr;
    _pwmTxn.chainNext = false;
 
    _ensurePage(1);
 
    // Enqueue transaction
    _hw->enqueueWIRE(&_pwmTxn);
}
 
inline void IS31FL3733::_sendRowMode() {
    // Don't send if ABM is locked by command chain or if transaction already in-flight
    if (_abmLocked || _abmTxn.txPtr)
        return;
 
    // Dequeue next row
    int row = _abmPendingRows.read_char();
    if (row < 0) {
        // Queue can be full with one row represented only in _abmEnqueued.
        for (uint8_t candidate = 0; candidate < kHardwareRows; candidate++) {
            if (_abmEnqueued & (1u << candidate)) {
                row = candidate;
                break;
            }
        }
    }
 
    if (row < 0)
        return; // Nothing pending
 
    // Clear enqueued bit
    _abmEnqueued &= ~(1 << row);
 
    // Copy row data to transmit buffer
    // [row][0] is the page 2 row address (0x00..0x0B)
    memcpy(_abmTxPtr, _abm_matrix[row], 17);
 
    // Point transaction at prepared ABM row buffer
    _abmTxn.txPtr = _abmTxPtr;
    _abmTxn.chainNext = false;
 
    _ensurePage(2);
 
    // Enqueue transaction
    _hw->enqueueWIRE(&_abmTxn);
}
 
inline void IS31FL3733::_asyncWrite(uint16_t pagereg, const uint8_t *data, uint8_t len,
                                    void (*callback)(void *, int), void *user) {
    uint8_t page = pagereg >> 8;
 
    // Ensure page if needed (pages 0-3)
    if (page < 4) {
        _ensurePage(page);
        _cmdTx[0] = pagereg & 0xFF;
    } else if (page >= IMR)
        _cmdTx[0] = page;
    else
        return;
 
    // Copy data to TX buffer
    memcpy(_cmdTx + 1, data, len);
 
    // Configure and enqueue write transaction
    _cmdTxn[2].length = 1 + len;
    _cmdCtx[2].userCallback = callback;
    _cmdCtx[2].user = user;
    _cmdCtx[2].isFinal = true; // This is the only transaction
    _cmdCtx[2].initialStatus = 0;
    _cmdTxn[2].onComplete = _cmdCallback;
    _cmdTxn[2].user = &_cmdCtx[2];
    _cmdTxn[2].chainNext = false;
    _hw->enqueueWIRE(&_cmdTxn[2]);
}
 
inline void IS31FL3733::_asyncRead(uint16_t pagereg, uint8_t *dest, uint8_t len,
                                   void (*callback)(void *, int), void *user) {
    uint8_t page = pagereg >> 8;
 
    // Ensure page if needed
    if (page < 4) {
        _ensurePage(page);
        _cmdTx[0] = pagereg & 0xFF;
    } else if (page >= IMR)
        _cmdTx[0] = page;
    else
        return;
 
    // Configure write transaction (send register address) - NOT final
    _cmdTxn[2].length = 1;
    _cmdCtx[2].userCallback = nullptr;
    _cmdCtx[2].user = nullptr;
    _cmdCtx[2].isFinal = false; // Address phase doesn't trigger callback
    _cmdCtx[2].initialStatus = 0;
    _cmdTxn[2].onComplete = _cmdCallback;
    _cmdTxn[2].user = &_cmdCtx[2];
    _cmdTxn[2].chainNext = false;
 
    // Configure read transaction - IS final (will invoke user callback)
    _cmdTxn[3].rxPtr = dest;
    _cmdTxn[3].length = len;
    _cmdCtx[3].userCallback = callback;
    _cmdCtx[3].user = user;
    _cmdCtx[3].isFinal = true;    // Data phase is final, triggers callback
    _cmdCtx[3].initialStatus = 0; // Can be populated by write phase if needed
    _cmdTxn[3].onComplete = _cmdCallback;
    _cmdTxn[3].user = &_cmdCtx[3];
    _cmdTxn[3].chainNext = false;
 
    // Enqueue both transactions
    _hw->enqueueWIRE(&_cmdTxn[2]);
    _hw->enqueueWIRE(&_cmdTxn[3]);
}
 
// ---------------------------------------------------------------------------------------
// Inline Callbacks
// ---------------------------------------------------------------------------------------
 
inline void IS31FL3733::_txnCallback(void *user, int status) {
    IS31FL3733 *self = (IS31FL3733 *)user;
    (void)status;
 
    // Clear PWM transaction in-progress flag
    self->_pwmTxn.txPtr = nullptr;
 
    // Transaction complete - send next PWM row if available
    self->_sendRowPWM();
}
 
inline void IS31FL3733::_txnModeCallback(void *user, int status) {
    IS31FL3733 *self = (IS31FL3733 *)user;
    (void)status;
 
    // Clear ABM transaction in-progress flag
    self->_abmTxn.txPtr = nullptr;
 
    // Transaction complete - send next ABM row if available
    self->_sendRowMode();
}
 
inline void IS31FL3733::_irqCallback() {
    // Hardware ISR: Read F1h (ISR register) into _lastISR, with _onServiceCallback as completion
    // No page select needed for common register F1h
    if (_instance)
        _instance->_asyncRead((uint16_t)ISR << 8, &_instance->_lastISR, 1, _onServiceCallback,
                              _instance);
}
 
inline void IS31FL3733::_onServiceCallback(void *user, int status) {
    // Static callback after ISR read completes - dispatch to instance method
    IS31FL3733 *self = (IS31FL3733 *)user;
    (void)status;
    // Process _lastISR value (already read by _irqCallback)
    // Lock PWM writes during fault handling
    self->_pwmLocked = true;
    self->_abmLocked = true;
 
    uint8_t isr = self->_lastISR;
 
    if (isr & 0x1C) { // ABM1 (0x04), ABM2 (0x08), ABM3 (0x10)
        // Dispatch ABM completion to registered callback(s)
        if (isr & ISR_ABM1)
            _abm1CallbackWrapper();
        if (isr & ISR_ABM2)
            _abm2CallbackWrapper();
        if (isr & ISR_ABM3)
            _abm3CallbackWrapper();
    }
 
    const bool hasOpenFault = (isr & ISR_OB) != 0;
    const bool hasShortFault = ((isr & ISR_SB) != 0) && self->_maskShortFaults;
 
    // Service open faults always; service short faults only when short masking is enabled.
    if (hasOpenFault || hasShortFault) {
        // Determine which fault register to read
        uint16_t pagereg = hasOpenFault ? LEDOPEN : LEDSHORT;
        uint8_t *dest = hasOpenFault ? self->_ledOpen : self->_ledShort;
 
        // Read fault register asynchronously
        self->_asyncRead(pagereg, dest, 24, _osbCallback, self);
 
        return;
    }
 
    // No recognized interrupts - just unlock PWM/ABM
    self->_resumeDataTransfers();
}
 
} // namespace IS31FL3733