IS31FL3733::IS31FL3733 Class Reference

Asynchronous DMA-driven IS31FL3733 LED driver for SAMD SERCOM I2C. More...

#include <is31fl3733.hpp>

Inheritance diagram for IS31FL3733::IS31FL3733:

Collaboration diagram for IS31FL3733::IS31FL3733:

Classes
struct	CmdTxnContext
	Context passed to SERCOM ISR callback for command-chain transactions. More...

Public Member Functions
Constructor / Destructor
	IS31FL3733 (TwoWire *wire, uint8_t addr=0x50, uint8_t sdbPin=0xFF, uint8_t irqPin=0xFF)
	Construct a new IS31FL3733 driver instance.
	~IS31FL3733 ()
	Destroy the driver; calls end() if begin() succeeded.
Initialization
bool	begin (uint8_t pfs=0, uint8_t pur=0b111, uint8_t pdr=0b111)
	Initialize the device (blocking for initial config).
void	end ()
	RESET device and disable (hardware shutdown). Reads RESET register to trigger software reset, then disables device. Useful for cleanup and testing.
Device Control
void	DeviceOn ()
	Enable the device (hardware and software startup).
void	DeviceOff ()
	Disable the device (hardware and software shutdown).
Runtime Configuration (Page 3/Common)
void	SetGCC (uint8_t gcc)
	Set global current control register (Page 3 GCC).
void	SetSWPUR (uint8_t pur)
	Set SW pull-up resistor control (Page 3 SWPUR).
void	SetCSPDR (uint8_t pdr)
	Set CS pull-down resistor control (Page 3 CSPDR).
void	SetPFS (uint8_t pfs)
	Set PWM frequency selection bits in CR (PFS[6:5]). Preserves other tracked CR bits (e.g., ABM enable).
void	SetIMR (uint8_t imrMask)
	Set interrupt mask register (Common IMR).
void	SetShortFaultMaskEnabled (bool enable)
	Control whether LEDSHORT bits are applied when computing LEDONOFF mask.
bool	GetShortFaultMaskEnabled () const
	Returns true when LEDSHORT contributes to LEDONOFF masking.
bool	IsPwmUpdatePending () const
	Returns true while PWM row writes are in flight or queued.
PWM & ABM Control (Raw Hardware Interface)
void	SetPixelPWM (uint8_t row, uint8_t col, uint8_t pwm)
	Set PWM duty cycle for a single LED (hardware coordinates).
void	SetRowPWM (uint8_t row, const uint8_t *pwmValues)
	Set PWM values for an entire row (hardware coordinates).
void	BeginPwmBatch ()
	Begin a batched PWM update.
void	EndPwmBatch (bool flush=true)
	End a batched PWM update and optionally flush queued rows.
void	SetPixelMode (uint8_t row, uint8_t col, ABMMode mode)
	Set mode for a single LED (hardware coordinates, Page 2).
void	SetRowMode (uint8_t row, ABMMode mode)
	Set mode for an entire row (hardware coordinates, Page 2).
ABMMode	GetPixelMode (uint8_t row, uint8_t col) const
	Get mode for a single LED (hardware coordinates, Page 2).
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)
	Set RGB color for a logical pixel (with color order mapping).
void	SetPixelColorMode (uint8_t row, uint8_t col, ABMMode mode)
	Set mode for a logical RGB pixel (with color order mapping).
void	SetColorOrder (ColorOrder order)
	Set the color order for RGB pixel mapping.
ColorOrder	GetColorOrder () const
	Get the current color order.
Bulk Operations
void	Fill (uint8_t pwm=0)
	Fill the entire matrix with a PWM value.
void	SetMatrixMode (ABMMode mode)
	Set mode for the entire matrix (Page 2).
void	SetABMCallback (uint8_t abmNum, std::function< void()> callback)
	Register callback for ABM1/2/3 completion.
ABM Page 3 Control
void	ConfigureABM (uint8_t abmNumber, const ABMConfig &config)
	Configure ABM timing/loop registers for ABM1/2/3 on Page 3.
void	ConfigureABM1 (const ABMConfig &config)
	Configure ABM-1 control registers (Page 3 ABM1CR..ABM1CR+4).
void	ConfigureABM2 (const ABMConfig &config)
	Configure ABM-2 control registers (Page 3 ABM2CR..ABM2CR+4).
void	ConfigureABM3 (const ABMConfig &config)
	Configure ABM-3 control registers (Page 3 ABM3CR..ABM3CR+4).
void	EnableABM (bool enable=true)
	Enable or disable ABM engine in CR (Page 3).
void	TriggerABM ()
	Latch ABM timing updates by writing TUR on Page 3.
Fault Detection (Read-Only)
const uint8_t *	GetLEDOpen () const
	Get the cached LED open status (from last fault detection).
const uint8_t *	GetLEDShort () const
	Get the cached LED short status (from last fault detection).
const uint8_t *	GetLEDOn () const
	Get the cached LED on/off mask (last value written to LEDONOFF).

Private Member Functions
Private Methods (Transaction Management)
void	_sendRowPWM ()
	Dequeue and transmit next pending PWM row.
void	_sendRowMode ()
	Dequeue and transmit next pending ABM row.
void	_ensurePage (uint8_t page)
	Ensure we're on the target page (skips if already there, enqueues unlock + page-select if needed).
void	_resumeDataTransfers ()
	Restore Page 1, clear _pwmLocked, resume PWM writes.
void	_asyncWrite (uint16_t pagereg, const uint8_t *data, uint8_t len, void(*callback)(void *, int)=nullptr, void *user=nullptr)
	Generic async write helper (inline for performance).
void	_asyncRead (uint16_t pagereg, uint8_t *dest, uint8_t len, void(*callback)(void *, int)=nullptr, void *user=nullptr)
	Generic async read helper (inline for performance).
bool	_syncWrite (uint16_t pagereg, const uint8_t *data, uint8_t len)
	Blocking write helper used by begin() setup flow.
bool	_syncRead (uint16_t pagereg, uint8_t *dest, uint8_t len)
	Blocking read helper used by begin() setup flow.

Static Private Member Functions
Static Callbacks
static void	_txnCallback (void *user, int status)
	PWM row transaction callback, enqueues the next pending row if any.
static void	_txnModeCallback (void *user, int status)
	ABM row transaction callback, enqueues the next pending mode row if any.
static void	_irqCallback ()
	GPIO IRQ callback (triggered by IRQ pin edge).
static void	_onServiceCallback (void *user, int status)
	ISR completion callback (processes _lastISR after F1h read).
static void	_cmdCallback (void *user, int status)
	Command transaction callback (triggered by SERCOM ISR).
static void	_osbCallback (void *user, int status)
	Open/Short detection callback (updates LED On/Off mask).
static void	_abm1CallbackWrapper ()
	Static wrappers for ABM completion callback dispatch (PendSV-safe entry points).
static void	_abm2CallbackWrapper ()
	Dispatch ABM2 completion callback on a safe context.
static void	_abm3CallbackWrapper ()
	Dispatch ABM3 completion callback on a safe context.

Private Attributes
bool	_begun
	True after successful begin(); used for destructor auto-end safety.
PWM Matrix and Transaction State (Page 1)
uint8_t	_pwm_matrix [kHardwareRows][kHardwareCols+1]
	[row][0] = Page 1 row addr, [1..16] = PWM data
SercomTxn	_pwmTxn
	Single in-flight PWM transaction descriptor.
uint8_t	_pwmTxPtr [kHardwareCols+1]
	Shadow buffer for current transaction.
RingBufferN< kHardwareRows+1 >	_pwmPendingRows
	Effective capacity: kHardwareRows.
uint16_t	_pwmEnqueued
	Bitfield tracking enqueued rows (0x0001..0x0FFF)
bool	_pwmLocked
	True when command chain has preempted PWM.
bool	_pwmBatchActive
	True while staged PWM updates are being batched.
Mode Matrix and Transaction State (Page 2)
uint8_t	_abm_matrix [kHardwareRows][kHardwareCols+1]
	[row][0] = Page 2 row addr, [1..16] = ABM data
SercomTxn	_abmTxn
	Single in-flight ABM transaction descriptor.
uint8_t	_abmTxPtr [kHardwareCols+1]
	Shadow buffer for current transaction.
RingBufferN< kHardwareRows+1 >	_abmPendingRows
	Effective capacity: kHardwareRows.
uint16_t	_abmEnqueued
	Bitfield tracking enqueued rows (0x0001..0x0FFF)
bool	_abmLocked
	True when command chain has preempted ABM.
std::function< void()>	_abmCallbacks [3]
	Completion callbacks for ABM1/2/3.
Command Transaction Chain (Non-PWM Operations)
SercomTxn	_cmdTxn [4]
	[0]=unlock, [1]=page, [2]=write, [3]=read
CmdTxnContext	_cmdCtx [4]
	Context for each command transaction (for callbacks)
uint8_t	_crwlTx [2]
	Pre-staged unlock transaction {PSWL, PSWL_ENABLE}.
uint8_t	_pgSelTx [2]
	Page select transaction buffer {PSR, page}.
uint8_t	_cmdTx [25]
	TX buffer (max: 1 addr + 24 data for LED On/Off)
uint8_t	_cmdRx [24]
	RX buffer (max: 24 bytes for LED Open/Short)
volatile uint8_t	_cmdReturn
	Bitfield of completed command transactions (bits 0..3)
volatile uint8_t	_cmdError
	Bitfield of command transactions with nonzero status.
volatile bool	_syncComplete
	Blocking command completion flag.
volatile int	_syncStatus
	Blocking command final status.
volatile int8_t	_syncTargetCmd
	Index of command awaited by blocking API.
Fault Detection and ISR Cache
uint8_t	_ledOpen [24]
	Cached LED open status (Page 0, 0x18)
uint8_t	_ledShort [24]
	Cached LED short status (Page 0, 0x30)
uint8_t	_ledOn [24]
	Computed LED On/Off mask (Page 0, 0x00)
uint8_t	_lastISR
	Cached ISR value from last fault detection.
Configuration
uint8_t	_crValue
	Shadow of CR register state for runtime updates.
ColorOrder	_colorOrder
	RGB pixel color order.
bool	_maskShortFaults
	Include LEDSHORT bits in computed LEDONOFF mask.

Hardware Handles
SERCOM *	_hw
	SERCOM I2C hardware interface.
uint8_t	_addr
	7-bit I2C address
uint8_t	_sdbPin
	SDB (shutdown) pin (0xFF = not used)
uint8_t	_irqPin
	IRQ pin (0xFF = not used)
uint8_t	_currentPage
	Tracks current page (0-3, 0xFF=unknown) to minimize page selects.
static IS31FL3733 *	_instance = nullptr
	Static instance pointer for ISR access.

Detailed Description

Asynchronous DMA-driven IS31FL3733 LED driver for SAMD SERCOM I2C.

Provides non-blocking I2C operations, ABM control, and RGB pixel helpers.

Definition at line 271 of file is31fl3733.hpp.

Constructor & Destructor Documentation

IS31FL3733()

IS31FL3733::IS31FL3733::IS31FL3733	(	TwoWire *	wire,
		uint8_t	addr = 0x50,
		uint8_t	sdbPin = 0xFF,
		uint8_t	irqPin = 0xFF
	)

Construct a new IS31FL3733 driver instance.

Parameters

wire	Pointer to TwoWire I2C interface.
addr	7-bit I2C address (typically 0x50).
sdbPin	Optional SDB (shutdown) pin (active high). Use 0xFF to disable.
irqPin	Optional IRQ pin for open/short detection. Use 0xFF to disable.

Definition at line 33 of file is31fl3733.cpp.

    : _hw(wire ? wire->getSercom() : nullptr), _addr(addr), _sdbPin(sdbPin), _irqPin(irqPin),
      _currentPage(0xFF), _pwmEnqueued(0), _pwmLocked(false), _pwmBatchActive(false),
      _abmEnqueued(0), _abmLocked(false), _cmdReturn(0), _cmdError(0), _syncComplete(false),
      _syncStatus(0), _syncTargetCmd(-1), _begun(false), _lastISR(0), _crValue(CR_SSD),
      _colorOrder(ColorOrder::GRB), _maskShortFaults(false) {
 
    // Pre-stage unlock transaction and page buffers
    _crwlTx[0] = PSWL;
    _crwlTx[1] = PSWL_ENABLE;
    _pgSelTx[0] = PSR;
    // _pgSelTx[1] will be set dynamically based on target register page during transactions
 
    // CRWL Txn (unlock)
    _cmdTxn[0].config = I2C_CFG_STOP;
    _cmdTxn[0].address = _addr;
    _cmdTxn[0].txPtr = _crwlTx;
    _cmdTxn[0].length = 2;
    _cmdCtx[0] = {this, 0, nullptr, nullptr};
    _cmdTxn[0].onComplete = _cmdCallback;
    _cmdTxn[0].user = &_cmdCtx[0];
    _cmdTxn[0].chainNext = false;
 
    // Page Selection Txn
    _cmdTxn[1].config = I2C_CFG_STOP;
    _cmdTxn[1].address = _addr;
    _cmdTxn[1].txPtr = _pgSelTx;
    _cmdTxn[1].length = 2;
    _cmdCtx[1] = {this, 1, nullptr, nullptr};
    _cmdTxn[1].onComplete = _cmdCallback;
    _cmdTxn[1].user = &_cmdCtx[1];
    _cmdTxn[1].chainNext = false;
 
    // Command Write Txn
    _cmdTxn[2].config = I2C_CFG_STOP;
    _cmdTxn[2].address = _addr;
    _cmdTxn[2].txPtr = _cmdTx;
    _cmdCtx[2] = {this, 2, nullptr, nullptr};
    _cmdTxn[2].onComplete = _cmdCallback;
    _cmdTxn[2].user = &_cmdCtx[2];
    _cmdTxn[2].chainNext = false;
 
    // Command Read Txn
    _cmdTxn[3].config = I2C_CFG_READ | I2C_CFG_STOP;
    _cmdTxn[3].address = _addr;
    _cmdTxn[3].rxPtr = _cmdRx;
    _cmdCtx[3] = {this, 3, nullptr, nullptr};
    _cmdTxn[3].onComplete = _cmdCallback;
    _cmdTxn[3].user = &_cmdCtx[3];
    _cmdTxn[3].chainNext = false;
 
    // PWM Txn
    _pwmTxn.config = I2C_CFG_STOP;
    _pwmTxn.address = _addr;
    _pwmTxn.length = 17;
    _pwmTxn.txPtr = nullptr;
    _pwmTxn.onComplete = _txnCallback;
    _pwmTxn.user = this;
    _pwmTxn.chainNext = false;
 
    // ABM Txn
    _abmTxn.config = I2C_CFG_STOP;
    _abmTxn.address = _addr;
    _abmTxn.length = 17;
    _abmTxn.txPtr = nullptr;
    _abmTxn.onComplete = _txnModeCallback;
    _abmTxn.user = this;
    _abmTxn.chainNext = false;
 
    // set all LED's on by default (will be updated in begin()) after OSD reads if enabled
    memset(_ledOn, 0xFF, sizeof(_ledOn));
 
    // Initialize row start-register addresses with 16-byte row stride:
    // row0=0x00, row1=0x10, ... row11=0xB0
    for (uint8_t row = 0; row < kHardwareRows; row++)
        _pwm_matrix[row][0] = static_cast<uint8_t>(row * kHardwareCols);
 
    for (uint8_t row = 0; row < kHardwareRows; row++)
        _abm_matrix[row][0] = static_cast<uint8_t>(row * kHardwareCols);
}

~IS31FL3733()

IS31FL3733::IS31FL3733::~IS31FL3733

(

)

Destroy the driver; calls end() if begin() succeeded.

Definition at line 114 of file is31fl3733.cpp.

                        {
    if (_begun)
        end();
}

Member Function Documentation

_abm1CallbackWrapper()

void IS31FL3733::IS31FL3733::_abm1CallbackWrapper ( )

staticprivate

Static wrappers for ABM completion callback dispatch (PendSV-safe entry points).

Dispatch ABM1 completion callback on a safe context.

Definition at line 777 of file is31fl3733.cpp.

                                      {
    if (_instance && _instance->_abmCallbacks[0])
        _instance->_abmCallbacks[0]();
}

_abm2CallbackWrapper()

void IS31FL3733::IS31FL3733::_abm2CallbackWrapper ( )

staticprivate

Dispatch ABM2 completion callback on a safe context.

Definition at line 782 of file is31fl3733.cpp.

                                      {
    if (_instance && _instance->_abmCallbacks[1])
        _instance->_abmCallbacks[1]();
}

_abm3CallbackWrapper()

void IS31FL3733::IS31FL3733::_abm3CallbackWrapper ( )

staticprivate

Dispatch ABM3 completion callback on a safe context.

Definition at line 787 of file is31fl3733.cpp.

                                      {
    if (_instance && _instance->_abmCallbacks[2])
        _instance->_abmCallbacks[2]();
}

_asyncRead()

void IS31FL3733::IS31FL3733::_asyncRead ( uint16_t  pagereg, uint8_t *  dest, uint8_t  len, void(*)(void *, int)  callback = nullptr, void *  user = nullptr  )

inlineprivate

Generic async read helper (inline for performance).

Definition at line 800 of file is31fl3733.hpp.

                                                                              {
    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]);
}

References IS31FL3733::IS31FL3733::CmdTxnContext::initialStatus, IS31FL3733::IS31FL3733::CmdTxnContext::isFinal, IS31FL3733::IS31FL3733::CmdTxnContext::user, and IS31FL3733::IS31FL3733::CmdTxnContext::userCallback.

_asyncWrite()

void IS31FL3733::IS31FL3733::_asyncWrite ( uint16_t  pagereg, const uint8_t *  data, uint8_t  len, void(*)(void *, int)  callback = nullptr, void *  user = nullptr  )

inlineprivate

Generic async write helper (inline for performance).

Definition at line 772 of file is31fl3733.hpp.

                                                                               {
    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]);
}

References IS31FL3733::IS31FL3733::CmdTxnContext::initialStatus, IS31FL3733::IS31FL3733::CmdTxnContext::isFinal, IS31FL3733::IS31FL3733::CmdTxnContext::user, and IS31FL3733::IS31FL3733::CmdTxnContext::userCallback.

_cmdCallback()

void IS31FL3733::IS31FL3733::_cmdCallback ( void *  user, int  status  )

staticprivate

Command transaction callback (triggered by SERCOM ISR).

Parameters

user	Pointer to IS31FL3733 instance.
status	Transaction status (0 = success).

Definition at line 743 of file is31fl3733.cpp.

                                                    {
    auto *context = static_cast<CmdTxnContext *>(user);
    if (!context || !context->self)
        return;
 
    IS31FL3733 *self = context->self;
    const uint8_t bit = static_cast<uint8_t>(1u << context->index);
 
    self->_cmdReturn |= bit;
    if (status != 0)
        self->_cmdError |= bit;
 
    if (self->_syncTargetCmd == static_cast<int8_t>(context->index)) {
        self->_syncStatus = status;
        self->_syncComplete = true;
        self->_syncTargetCmd = -1;
    }
 
    // For non-final phases: accumulate status in next phase's context
    if (!context->isFinal && context->index < 3) {
        // Chain accumulated status forward: next phase sees all previous failures
        self->_cmdCtx[context->index + 1].initialStatus |= status;
        return; // Don't invoke user callback on intermediate phase
    }
 
    // Only invoke user callback on final transaction
    if (context->isFinal && context->userCallback)
        context->userCallback(context->user, status);
}

_ensurePage()

void IS31FL3733::IS31FL3733::_ensurePage ( uint8_t  page )

private

Ensure we're on the target page (skips if already there, enqueues unlock + page-select if needed).

Parameters

page	Page number (0..3).

Definition at line 568 of file is31fl3733.cpp.

                                         {
    // Skip page select if we're already on the target page
    if (_currentPage == page)
        return;
 
    // Enqueue unlock transaction (pre-staged in constructor)
    _cmdTxn[0].chainNext = false;
    _hw->enqueueWIRE(&_cmdTxn[0]);
 
    // Update and enqueue page select transaction
    _pgSelTx[0] = PSR;
    _pgSelTx[1] = page & 0b11; // Mask to 2 bits (0-3)
    _cmdTxn[1].chainNext = false;
    _hw->enqueueWIRE(&_cmdTxn[1]);
 
    // Update tracked page
    _currentPage = page;
}

_irqCallback()

void IS31FL3733::IS31FL3733::_irqCallback ( )

inlinestaticprivate

GPIO IRQ callback (triggered by IRQ pin edge).

Definition at line 865 of file is31fl3733.hpp.

                                     {
    // 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);
}

_onServiceCallback()

void IS31FL3733::IS31FL3733::_onServiceCallback ( void *  user, int  status  )

inlinestaticprivate

ISR completion callback (processes _lastISR after F1h read).

Parameters

user	Pointer to IS31FL3733 instance.
status	Transaction status (0 = success).

Definition at line 873 of file is31fl3733.hpp.

                                                                 {
    // 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();
}

_osbCallback()

void IS31FL3733::IS31FL3733::_osbCallback ( void *  user, int  status  )

staticprivate

Open/Short detection callback (updates LED On/Off mask).

Definition at line 727 of file is31fl3733.cpp.

                                                    {
    IS31FL3733 *self = (IS31FL3733 *)user;
 
    // Update LED On/Off mask from open faults only.  Short detection is not used for
    // masking because this hardware reports spurious shorts on active LED rows.
    for (size_t i = 0; i < 24; i++) {
        self->_ledOn[i] = static_cast<uint8_t>(self->_ledOn[i] & ~self->_ledOpen[i]);
    }
 
    // Write updated LED On/Off register
    self->_asyncWrite(LEDONOFF, self->_ledOn, 24, nullptr, nullptr);
 
    // Restore Page 1 and resume PWM/ABM
    self->_resumeDataTransfers();
}

_resumeDataTransfers()

void IS31FL3733::IS31FL3733::_resumeDataTransfers ( )

private

Restore Page 1, clear _pwmLocked, resume PWM writes.

Definition at line 587 of file is31fl3733.cpp.

                                      {
    _pwmLocked = false; // Clear PWM lock flag
    _abmLocked = false; // Clear ABM lock flag
    _sendRowPWM();      // Resume pending PWM writes
    _sendRowMode();     // Resume pending ABM writes
}

_sendRowMode()

void IS31FL3733::IS31FL3733::_sendRowMode ( )

inlineprivate

Dequeue and transmit next pending ABM row.

Definition at line 735 of file is31fl3733.hpp.

                                     {
    // 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);
}

_sendRowPWM()

void IS31FL3733::IS31FL3733::_sendRowPWM ( )

inlineprivate

Dequeue and transmit next pending PWM row.

Definition at line 699 of file is31fl3733.hpp.

                                    {
    // 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);
}

_syncRead()

bool IS31FL3733::IS31FL3733::_syncRead ( uint16_t  pagereg, uint8_t *  dest, uint8_t  len  )

private

Blocking read helper used by begin() setup flow.

Definition at line 620 of file is31fl3733.cpp.

                                                                       {
    _syncComplete = false;
    _syncStatus = 0;
    _syncTargetCmd = 3;
    _cmdError &= ~((1u << 0) | (1u << 1) | (1u << 2) | (1u << 3));
    _cmdCtx[3].initialStatus = 0;
 
    _asyncRead(pagereg, dest, len, nullptr, nullptr);
 
    constexpr uint32_t timeoutUs = 100000ul; // 100 ms
    const uint32_t start = micros();
    while (!_syncComplete && (static_cast<uint32_t>(micros() - start) < timeoutUs)) {
        yield();
    }
 
    if (!_syncComplete) {
        _syncStatus = -1;
        _syncTargetCmd = -1;
        _syncComplete = true;
        return false;
    }
 
    return (_syncStatus == 0) &&
           ((_cmdError & ((1u << 0) | (1u << 1) | (1u << 2) | (1u << 3))) == 0) &&
           (_cmdCtx[3].initialStatus == 0);
}

_syncWrite()

bool IS31FL3733::IS31FL3733::_syncWrite ( uint16_t  pagereg, const uint8_t *  data, uint8_t  len  )

private

Blocking write helper used by begin() setup flow.

Definition at line 594 of file is31fl3733.cpp.

                                                                              {
    _syncComplete = false;
    _syncStatus = 0;
    _syncTargetCmd = 2;
    _cmdError &= ~((1u << 0) | (1u << 1) | (1u << 2));
    _cmdCtx[2].initialStatus = 0;
 
    _asyncWrite(pagereg, data, len, nullptr, nullptr);
 
    constexpr uint32_t timeoutUs = 100000ul; // 100 ms
    const uint32_t start = micros();
    while (!_syncComplete && (static_cast<uint32_t>(micros() - start) < timeoutUs)) {
        yield();
    }
 
    if (!_syncComplete) {
        _syncStatus = -1;
        _syncTargetCmd = -1;
        _syncComplete = true;
        return false;
    }
 
    return (_syncStatus == 0) && ((_cmdError & ((1u << 0) | (1u << 1) | (1u << 2))) == 0) &&
           (_cmdCtx[2].initialStatus == 0);
}

_txnCallback()

void IS31FL3733::IS31FL3733::_txnCallback ( void *  user, int  status  )

inlinestaticprivate

PWM row transaction callback, enqueues the next pending row if any.

Parameters

user	Pointer to IS31FL3733 instance.
status	Transaction status (0 = success).

Definition at line 843 of file is31fl3733.hpp.

                                                           {
    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();
}

_txnModeCallback()

void IS31FL3733::IS31FL3733::_txnModeCallback ( void *  user, int  status  )

inlinestaticprivate

ABM row transaction callback, enqueues the next pending mode row if any.

Parameters

user	Pointer to IS31FL3733 instance.
status	Transaction status (0 = success).

Definition at line 854 of file is31fl3733.hpp.

                                                               {
    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();
}

begin()

bool IS31FL3733::IS31FL3733::begin	(	uint8_t	pfs = 0,
		uint8_t	pur = 0b111,
		uint8_t	pdr = 0b111
	)

Initialize the device (blocking for initial config).

Parameters

pfs	PWM Frequency Setting value (0..3) for initial configuration. See Table 13 for setting values. Default is 0 (slowest PWM frequency, 8.4 kHz).
pur	Pull-up resistor setting for de-ghosting (3 bits, 0..7). Default is 0b111 (32 kOhm pull-up). See Table 19 for resistor values.
pdr	Pull-down resistor setting for de-ghosting (3 bits, 0..7). Default is 0b111 (32 kOhm pull-down). See Table 20 for resistor values.

Returns

true if successful, false otherwise.

Definition at line 123 of file is31fl3733.cpp.

                                                            {
    // ---------------------------------------------------------------------------------
    // STEP 1: Configure pins
    // ---------------------------------------------------------------------------------
    // SDB pin (active high)
    if (_sdbPin != 0xFF) {
        pinMode(_sdbPin, OUTPUT);
        digitalWrite(_sdbPin, LOW); // Start disabled
        delay(1);
        digitalWrite(_sdbPin, HIGH); // Enable device
        delay(1);
    }
 
    // IRQ pin (if provided). Defer ISR attachment until initialization completes.
    if (_irqPin != 0xFF)
        pinMode(_irqPin, INPUT_PULLUP);
 
    // ---------------------------------------------------------------------------------
    // Force software RESET
    // ---------------------------------------------------------------------------------
 
    // Reading RESET triggers the IS31FL3733 software reset.
    uint8_t dummy;
    if (!_syncRead(RESET, &dummy, 1))
        return false;
    delay(1);
 
    // ---------------------------------------------------------------------------------
    // Configure Page 3 registers
    // ---------------------------------------------------------------------------------
 
    // CR: Normal operation (without OSD initially)
    _crValue = static_cast<uint8_t>(CR_SSD | CR_PFS(pfs & 0x03));
    if (!_syncWrite(CR, &_crValue, 1))
        return false;
 
    // ---------------------------------------------------------------------------------
    // Configure Page 0: LED On/Off and Open/Short Detection
    // ---------------------------------------------------------------------------------
    // Step 1: Enable all LEDs in LEDONOFF
    if (!_syncWrite(LEDONOFF, _ledOn, 24))
        return false;
 
    // Step 2: Set GCC to 0x01 for OSD
    uint8_t gcc_osd = 0x01;
    if (!_syncWrite(GCC, &gcc_osd, 1))
        return false;
 
    // Step 3: Trigger OSD strobe (CR with OSD bit set)
    uint8_t cr_osd = static_cast<uint8_t>(_crValue | CR_OSD);
    if (!_syncWrite(CR, &cr_osd, 1))
        return false;
 
    // Step 4: Wait for OSD to complete
    delay(10); // 10ms to ensure completion
 
    // Step 5: Read LEDOPEN and LEDSHORT registers
    if (!_syncRead(LEDOPEN, _ledOpen, 24))
        return false;
    if (!_syncRead(LEDSHORT, _ledShort, 24))
        return false;
 
    // Store ISR status read after OSD.
    uint8_t isr_status = 0;
    if (_syncRead((uint16_t)ISR << 8, &isr_status, 1))
        _lastISR = isr_status;
 
    // Compute LED On/Off mask based on configured fault policy.
    // NOTE: Short circuit detection disabled due to spurious shorts detected on
    // red LED rows during OSD sequence. Only OPEN detection is used to disable LEDs.
    for (size_t i = 0; i < 24; i++) {
        // Only disable LEDs if they are detected as open (not shorted)
        _ledOn[i] = static_cast<uint8_t>(_ledOn[i] & ~_ledOpen[i]);
    }
 
    // Write updated LEDONOFF mask (if faults detected)
    if (!_syncWrite(LEDONOFF, _ledOn, 24))
        return false;
 
    // Step 6: Restore GCC to normal operating value (0xFF)
    uint8_t gcc_normal = 0xFF;
    if (!_syncWrite(GCC, &gcc_normal, 1))
        return false;
 
    // Step 7: Clear CR OSD bit for normal operation
    if (!_syncWrite(CR, &_crValue, 1))
        return false;
 
    // Step 8: Force all LED mode registers to normal PWM mode.  RESET should leave
    // Page 2 at 0x00, but write it explicitly during begin so no previous ABM state
    // can survive a partial init or bus fault.
    uint8_t pwmMode[kHardwareCols];
    memset(pwmMode, static_cast<uint8_t>(ABMMode::PWM_MODE), sizeof(pwmMode));
    for (uint8_t row = 0u; row < kHardwareRows; ++row) {
        if (!_syncWrite(static_cast<uint16_t>(LEDABM + (row * kHardwareCols)), pwmMode,
                        sizeof(pwmMode)))
            return false;
        memset(_abm_matrix[row] + 1, static_cast<uint8_t>(ABMMode::PWM_MODE), kHardwareCols);
    }
 
    // Step 9: Minimal OSD sequence (if IRQ pin provided)
    if (_irqPin != 0xFF) {
        // Unmask interrupts for runtime fault detection.
        uint8_t imr_value = IMR_IO;
        if (_maskShortFaults)
            imr_value = static_cast<uint8_t>(imr_value | IMR_IS);
        if (!_syncWrite((uint16_t)IMR << 8, &imr_value, 1))
            return false;
    }
 
    // Step 10: Set pull-up/down for de-ghosting (default to all enabled)
    uint8_t purValue = pur & 0b111; // Mask to 3 bits
    uint8_t pdrValue = pdr & 0b111; // Mask to 3 bits
    if (!_syncWrite(SWPUR, &purValue, 1))
        return false;
    if (!_syncWrite(CSPDR, &pdrValue, 1))
        return false;
 
    // ---------------------------------------------------------------------------------
    // Clear command transaction pointers and set default page to Page 1 (PWM)
    // ---------------------------------------------------------------------------------
 
    _cmdCtx[2].userCallback = nullptr;
    _cmdCtx[2].user = nullptr;
    _cmdCtx[3].userCallback = nullptr;
    _cmdCtx[3].user = nullptr;
 
    _ensurePage(1);
 
    if (_irqPin != 0xFF) {
        _instance = this; // Set static instance for ISR access
        attachInterrupt(digitalPinToInterrupt(_irqPin), _irqCallback, FALLING);
    }
 
    _begun = true;
 
    return true;
}

BeginPwmBatch()

void IS31FL3733::IS31FL3733::BeginPwmBatch

(

)

Begin a batched PWM update.

While active, PWM row writes are staged in the internal matrix and queued, but transmission to the device is deferred until EndPwmBatch() is called.

Definition at line 378 of file is31fl3733.cpp.

                               {
    _pwmBatchActive = true;
}

ConfigureABM()

void IS31FL3733::IS31FL3733::ConfigureABM	(	uint8_t	abmNumber,
		const ABMConfig &	config
	)

Configure ABM timing/loop registers for ABM1/2/3 on Page 3.

Parameters

abmNumber	ABM selector (1..3).
config	ABM timing/loop configuration fields.

Definition at line 658 of file is31fl3733.cpp.

                                                                        {
    if (abmNumber < 1 || abmNumber > 3)
        return;
    uint16_t pagereg = 0;
    // Route to specific ABM configurator
    switch (abmNumber) {
    case 1:
        pagereg = ABM1CR;
        break;
    case 2:
        pagereg = ABM2CR;
        break;
    case 3:
        pagereg = ABM3CR;
        break;
    }
 
    const uint8_t cfg[4] = {
        static_cast<uint8_t>(static_cast<uint8_t>(config.T1) | static_cast<uint8_t>(config.T2)),
        static_cast<uint8_t>(static_cast<uint8_t>(config.T3) | static_cast<uint8_t>(config.T4)),
        static_cast<uint8_t>(static_cast<uint8_t>(config.Tend) |
                             static_cast<uint8_t>(config.Tbegin) |
                             static_cast<uint8_t>((config.Times >> 8) & 0x0F)),
        static_cast<uint8_t>(config.Times & 0xFF),
    };
    _asyncWrite(pagereg, cfg, 4, nullptr, nullptr);
 
    // Write 1 byte of zeros to TUR (0x0E) to complete latch (per datasheet: "Any write to
    // 0Eh will latch the ABM configuration")
    uint8_t turPadding[1] = {0};
    _asyncWrite(TUR, turPadding, 1, nullptr, nullptr);
}

References IS31FL3733::ABMConfig::T1, IS31FL3733::ABMConfig::T2, IS31FL3733::ABMConfig::T3, IS31FL3733::ABMConfig::T4, IS31FL3733::ABMConfig::Tbegin, IS31FL3733::ABMConfig::Tend, and IS31FL3733::ABMConfig::Times.

ConfigureABM1()

void IS31FL3733::IS31FL3733::ConfigureABM1

(

const ABMConfig &

config

)

Configure ABM-1 control registers (Page 3 ABM1CR..ABM1CR+4).

Definition at line 691 of file is31fl3733.cpp.

                                                      {
    ConfigureABM(1, config);
}

ConfigureABM2()

void IS31FL3733::IS31FL3733::ConfigureABM2

(

const ABMConfig &

config

)

Configure ABM-2 control registers (Page 3 ABM2CR..ABM2CR+4).

Definition at line 695 of file is31fl3733.cpp.

                                                      {
    ConfigureABM(2, config);
}

ConfigureABM3()

void IS31FL3733::IS31FL3733::ConfigureABM3

(

const ABMConfig &

config

)

Configure ABM-3 control registers (Page 3 ABM3CR..ABM3CR+4).

Definition at line 699 of file is31fl3733.cpp.

                                                      {
    ConfigureABM(3, config);
}

DeviceOff()

void IS31FL3733::IS31FL3733::DeviceOff

(

)

Disable the device (hardware and software shutdown).

Definition at line 293 of file is31fl3733.cpp.

                           {
    const uint8_t cr_off = 0x00;
    _syncWrite(CR, &cr_off, 1); // Ensure CR write completes before cutting power
 
    if (_sdbPin != 0xFF)
        digitalWrite(_sdbPin, LOW);
}

DeviceOn()

void IS31FL3733::IS31FL3733::DeviceOn

(

)

Enable the device (hardware and software startup).

Definition at line 283 of file is31fl3733.cpp.

                          {
    if (_sdbPin != 0xFF)
        digitalWrite(_sdbPin, HIGH);
 
    // Write cached CR register (SSD + runtime config bits)
    _asyncWrite(CR, &_crValue, 1, nullptr, nullptr);
 
    _resumeDataTransfers();
}

EnableABM()

void IS31FL3733::IS31FL3733::EnableABM

(

bool

enable = true

)

Enable or disable ABM engine in CR (Page 3).

Parameters

enable

True to set CR_BEN, false to clear it.

Definition at line 703 of file is31fl3733.cpp.

                                      {
    if (enable)
        _crValue |= CR_BEN;
    else
        _crValue &= static_cast<uint8_t>(~CR_BEN);
 
    _asyncWrite(CR, &_crValue, 1, nullptr, nullptr);
}

end()

void IS31FL3733::IS31FL3733::end

(

)

RESET device and disable (hardware shutdown). Reads RESET register to trigger software reset, then disables device. Useful for cleanup and testing.

Definition at line 262 of file is31fl3733.cpp.

                     {
    if (!_begun)
        return;
 
    _syncRead(CR, _cmdTx, 1); // RESET the device state
 
    DeviceOff();
 
    // Detach IRQ if configured
    if (_irqPin != 0xFF) {
        detachInterrupt(digitalPinToInterrupt(_irqPin));
        _instance = nullptr;
    }
 
    _begun = false;
}

EndPwmBatch()

void IS31FL3733::IS31FL3733::EndPwmBatch

(

bool

flush = true

)

End a batched PWM update and optionally flush queued rows.

Parameters

flush

If true, starts sending queued rows immediately (if bus is idle).

Definition at line 382 of file is31fl3733.cpp.

                                       {
    _pwmBatchActive = false;
 
    if (flush && !_pwmTxn.txPtr && !_pwmLocked)
        _sendRowPWM();
}

Fill()

void IS31FL3733::IS31FL3733::Fill

(

uint8_t

pwm = 0

)

Fill the entire matrix with a PWM value.

Parameters

pwm	PWM value (0..255).

Definition at line 444 of file is31fl3733.cpp.

                                 {
    // Fill all rows with the same PWM value
    for (uint8_t row = 0; row < kHardwareRows; row++) {
        memset(_pwm_matrix[row] + 1, pwm, kHardwareCols);
 
        // Enqueue row
        uint16_t rowBit = 1 << row;
        if (!(_pwmEnqueued & rowBit)) {
            _pwmEnqueued |= rowBit;
            _pwmPendingRows.store(row);
        }
    }
 
    // Kick transmission if not already in-flight
    if (!_pwmTxn.txPtr && !_pwmLocked)
        _sendRowPWM();
}

GetColorOrder()

ColorOrder IS31FL3733::IS31FL3733::GetColorOrder ( ) const

inline

Get the current color order.

Returns

Current color order.

Definition at line 439 of file is31fl3733.hpp.

                                     {
        return _colorOrder;
    }

GetLEDOn()

const uint8_t * IS31FL3733::IS31FL3733::GetLEDOn ( ) const

inline

Get the cached LED on/off mask (last value written to LEDONOFF).

Returns

Pointer to 24-byte array (Page 0, 0x00..0x17).

Definition at line 509 of file is31fl3733.hpp.

                                    {
        return _ledOn;
    }

GetLEDOpen()

const uint8_t * IS31FL3733::IS31FL3733::GetLEDOpen ( ) const

inline

Get the cached LED open status (from last fault detection).

Returns

Pointer to 24-byte array (Page 0, 0x18..0x2F).

Definition at line 497 of file is31fl3733.hpp.

                                      {
        return _ledOpen;
    }

GetLEDShort()

const uint8_t * IS31FL3733::IS31FL3733::GetLEDShort ( ) const

inline

Get the cached LED short status (from last fault detection).

Returns

Pointer to 24-byte array (Page 0, 0x30..0x47).

Definition at line 503 of file is31fl3733.hpp.

                                       {
        return _ledShort;
    }

GetPixelMode()

ABMMode IS31FL3733::IS31FL3733::GetPixelMode	(	uint8_t	row,
		uint8_t	col
	)		const

Get mode for a single LED (hardware coordinates, Page 2).

Parameters

row	Hardware row (1..12 = SW1..SW12).
col	Hardware column (1..16 = CS1..CS16).

Returns

Current cached LED mode.

Definition at line 534 of file is31fl3733.cpp.

                                                               {
    // guard against out-of-bounds and 0 (1-based indexing)
    if (row > kHardwareRows || col > kHardwareCols || !row || !col)
        return ABMMode::PWM_MODE;
 
    // Convert 1-based to 0-based index
    uint8_t idx = row - 1;
 
    // Read from cached ABM matrix
    return static_cast<ABMMode>(_abm_matrix[idx][col]);
}

GetShortFaultMaskEnabled()

bool IS31FL3733::IS31FL3733::GetShortFaultMaskEnabled ( ) const

inline

Returns true when LEDSHORT contributes to LEDONOFF masking.

Definition at line 358 of file is31fl3733.hpp.

                                          {
        return _maskShortFaults;
    }

IsPwmUpdatePending()

bool IS31FL3733::IS31FL3733::IsPwmUpdatePending ( ) const

inline

Returns true while PWM row writes are in flight or queued.

Definition at line 363 of file is31fl3733.hpp.

                                    {
        return _pwmTxn.txPtr != nullptr || _pwmEnqueued != 0u || _pwmLocked || _pwmBatchActive;
    }

SetABMCallback()

void IS31FL3733::IS31FL3733::SetABMCallback	(	uint8_t	abmNum,
		std::function< void()>	callback
	)

Register callback for ABM1/2/3 completion.

Parameters

abmNum	ABM selector (1..3).
callback	Invoked when selected ABM completes.

Definition at line 651 of file is31fl3733.cpp.

                                                                            {
    if (abmNum < 1 || abmNum > 3)
        return;
 
    _abmCallbacks[abmNum - 1] = callback;
}

SetColorOrder()

void IS31FL3733::IS31FL3733::SetColorOrder ( ColorOrder  order )

inline

Set the color order for RGB pixel mapping.

Parameters

order

Color order (RGB, GRB, BRG, RBG, GBR, BGR).

Definition at line 433 of file is31fl3733.hpp.

                                         {
        _colorOrder = order;
    }

SetCSPDR()

void IS31FL3733::IS31FL3733::SetCSPDR

(

uint8_t

pdr

)

Set CS pull-down resistor control (Page 3 CSPDR).

Parameters

pdr	Pull-down value (lower 3 bits are used).

Definition at line 310 of file is31fl3733.cpp.

                                     {
    uint8_t pdrValue = static_cast<uint8_t>(pdr & 0x07);
    _asyncWrite(CSPDR, &pdrValue, 1, nullptr, nullptr);
}

SetGCC()

void IS31FL3733::IS31FL3733::SetGCC

(

uint8_t

gcc

)

Set global current control register (Page 3 GCC).

Parameters

gcc	Global current value (0x00..0xFF).

Definition at line 301 of file is31fl3733.cpp.

                                   {
    _asyncWrite(GCC, &gcc, 1, nullptr, nullptr);
}

SetIMR()

void IS31FL3733::IS31FL3733::SetIMR

(

uint8_t

imrMask

)

Set interrupt mask register (Common IMR).

Parameters

imrMask

IMR bitmask (IMR_IO/IMR_IS/IMR_IAB/IMR_IAC).

Definition at line 320 of file is31fl3733.cpp.

                                       {
    uint8_t mask = static_cast<uint8_t>(imrMask & 0x0F);
    _asyncWrite((uint16_t)IMR << 8, &mask, 1, nullptr, nullptr);
}

SetMatrixMode()

void IS31FL3733::IS31FL3733::SetMatrixMode

(

ABMMode

mode

)

Set mode for the entire matrix (Page 2).

Parameters

mode	LED mode value (PWM/ABM1/ABM2/ABM3).

Definition at line 515 of file is31fl3733.cpp.

                                           {
    // Fill all rows with the same mode value (Page 2)
    for (uint8_t row = 0; row < kHardwareRows; row++) {
        memset(_abm_matrix[row] + 1, static_cast<uint8_t>(mode), kHardwareCols);
 
        // Enqueue row
        uint16_t rowBit = 1 << row;
        if (!(_abmEnqueued & rowBit)) {
            _abmEnqueued |= rowBit;
            _abmPendingRows.store(row);
        }
    }
 
    // Kick transmission if not already in-flight
    if (!_abmTxn.txPtr && !_abmLocked) {
        _sendRowMode();
    }
}

SetPFS()

void IS31FL3733::IS31FL3733::SetPFS

(

uint8_t

pfs

)

Set PWM frequency selection bits in CR (PFS[6:5]). Preserves other tracked CR bits (e.g., ABM enable).

Parameters

pfs	PWM frequency selector (0..3).

Definition at line 315 of file is31fl3733.cpp.

                                   {
    _crValue = static_cast<uint8_t>((_crValue & ~0x60u) | CR_PFS(pfs & 0x03));
    _asyncWrite(CR, &_crValue, 1, nullptr, nullptr);
}

SetPixelColor()

void IS31FL3733::IS31FL3733::SetPixelColor	(	uint8_t	row,
		uint8_t	col,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

Set RGB color for a logical pixel (with color order mapping).

Parameters

row	Logical pixel row (1..4).
col	Logical pixel column (1..16).
r	Red channel (0..255).
g	Green channel (0..255).
b	Blue channel (0..255).

Definition at line 393 of file is31fl3733.cpp.

                                                                                        {
    if (row > kLogicalRows || col > kHardwareCols || !row || !col)
        return;
 
    // Convert 1-based to 0-based index
    uint8_t idx = row - 1;
 
    // Map logical row to hardware rows based on color order
    // baseRow will be 0, 3, 6, or 9 for logical rows 0-3
    // Add 1 to convert to 1-based indexing for SetPixelPWM
    uint8_t baseRow = idx * 3 + 1;
 
    // Set PWM for each channel based on color order
    switch (_colorOrder) {
    case ColorOrder::RGB:
        SetPixelPWM(baseRow + 0, col, r); // R on first row
        SetPixelPWM(baseRow + 1, col, g); // G on second row
        SetPixelPWM(baseRow + 2, col, b); // B on third row
        break;
    case ColorOrder::GRB:
        SetPixelPWM(baseRow + 0, col, g); // G on first row
        SetPixelPWM(baseRow + 1, col, r); // R on second row
        SetPixelPWM(baseRow + 2, col, b); // B on third row
        break;
    case ColorOrder::BRG:
        SetPixelPWM(baseRow + 0, col, b); // B on first row
        SetPixelPWM(baseRow + 1, col, r); // R on second row
        SetPixelPWM(baseRow + 2, col, g); // G on third row
        break;
    case ColorOrder::RBG:
        SetPixelPWM(baseRow + 0, col, r); // R on first row
        SetPixelPWM(baseRow + 1, col, b); // B on second row
        SetPixelPWM(baseRow + 2, col, g); // G on third row
        break;
    case ColorOrder::GBR:
        SetPixelPWM(baseRow + 0, col, g); // G on first row
        SetPixelPWM(baseRow + 1, col, b); // B on second row
        SetPixelPWM(baseRow + 2, col, r); // R on third row
        break;
    case ColorOrder::BGR:
        SetPixelPWM(baseRow + 0, col, b); // B on first row
        SetPixelPWM(baseRow + 1, col, g); // G on second row
        SetPixelPWM(baseRow + 2, col, r); // R on third row
        break;
    }
}

Referenced by IS31FL3733::IS31FL3733RgbMatrix::SetPixelColor32().

SetPixelColorMode()

void IS31FL3733::IS31FL3733::SetPixelColorMode	(	uint8_t	row,
		uint8_t	col,
		ABMMode	mode
	)

Set mode for a logical RGB pixel (with color order mapping).

Parameters

row	Logical pixel row (1..4).
col	Logical pixel column (1..16).
mode	ABM mode.

Definition at line 546 of file is31fl3733.cpp.

                                                                         {
    if (row > kLogicalRows || col > kHardwareCols || !row || !col)
        return;
 
    // Convert 1-based to 0-based index
    uint8_t idx = row - 1;
 
    // Map logical row to hardware rows based on color order
    // baseRow will be 0, 3, 6, or 9 for logical rows 0-3
    // Add 1 to convert to 1-based indexing for SetPixelMode
    uint8_t baseRow = idx * 3 + 1;
 
    // Set mode for each channel (all three use the same ABM mode for "color")
    SetPixelMode(baseRow + 0, col, mode);
    SetPixelMode(baseRow + 1, col, mode);
    SetPixelMode(baseRow + 2, col, mode);
}

SetPixelMode()

void IS31FL3733::IS31FL3733::SetPixelMode	(	uint8_t	row,
		uint8_t	col,
		ABMMode	mode
	)

Set mode for a single LED (hardware coordinates, Page 2).

Parameters

row	Hardware row (1..12 = SW1..SW12).
col	Hardware column (1..16 = CS1..CS16).
mode	LED mode value (PWM/ABM1/ABM2/ABM3).

Definition at line 466 of file is31fl3733.cpp.

                                                                    {
    // guard against out-of-bounds and 0 (1-based indexing)
    if (row > kHardwareRows || col > kHardwareCols || !row || !col)
        return;
 
    // Convert 1-based to 0-based index
    uint8_t idx = row - 1;
 
    // [idx][0] is reserved for row address, so column data starts at offset 1
    _abm_matrix[idx][col] = static_cast<uint8_t>(mode);
 
    // Enqueue row for transmission (if not already enqueued)
    uint16_t rowBit = 1 << idx;
    if (_abmEnqueued & rowBit)
        return; // Already enqueued
 
    _abmEnqueued |= rowBit;
    _abmPendingRows.store(idx);
 
    // Kick transmission if not already in-flight
    if (!_abmTxn.txPtr && !_abmLocked)
        _sendRowMode();
}

SetPixelPWM()

void IS31FL3733::IS31FL3733::SetPixelPWM	(	uint8_t	row,
		uint8_t	col,
		uint8_t	pwm
	)

Set PWM duty cycle for a single LED (hardware coordinates).

Parameters

row	Hardware row (1..12 = SW1..SW12).
col	Hardware column (1..16 = CS1..CS16).
pwm	PWM value (0..255).

Definition at line 329 of file is31fl3733.cpp.

                                                                  {
    // guard against out-of-bounds and 0 (1-based indexing)
    if (row > kHardwareRows || col > kHardwareCols || !row || !col)
        return;
 
    // Convert 1-based to 0-based index
    uint8_t idx = row - 1;
 
    // [idx][0] is reserved for row address, so column data starts at offset 1
    _pwm_matrix[idx][col] = pwm;
 
    // Enqueue row for transmission (if not already enqueued)
    uint16_t rowBit = 1 << idx;
    if (_pwmEnqueued & rowBit)
        return; // Already enqueued
 
    _pwmEnqueued |= rowBit;
    _pwmPendingRows.store(idx);
 
    // Kick transmission if not already in-flight
    if (!_pwmTxn.txPtr && !_pwmLocked)
        _sendRowPWM();
}

SetRowMode()

void IS31FL3733::IS31FL3733::SetRowMode	(	uint8_t	row,
		ABMMode	mode
	)

Set mode for an entire row (hardware coordinates, Page 2).

Parameters

row	Hardware row (1..12 = SW1..SW12).
mode	LED mode value (PWM/ABM1/ABM2/ABM3).

Definition at line 490 of file is31fl3733.cpp.

                                                     {
    // guard against out-of-bounds and 0 (1-based indexing)
    if (row > kHardwareRows || !row)
        return;
 
    // Convert 1-based to 0-based index
    uint8_t idx = (row - 1) & 0x0F;
 
    // Update mode buffer for the row (starting at offset 1 since [idx][0] is reserved for row
    // address)
    memset(_abm_matrix[idx] + 1, static_cast<uint8_t>(mode), kHardwareCols);
 
    // Enqueue row for transmission (if not already enqueued)
    uint16_t rowBit = 1 << idx;
    if (_abmEnqueued & rowBit)
        return; // Already enqueued
 
    _abmEnqueued |= rowBit;
    _abmPendingRows.store(idx);
 
    // Kick transmission if not already in-flight
    if (!_abmTxn.txPtr && !_abmLocked)
        _sendRowMode();
}

SetRowPWM()

void IS31FL3733::IS31FL3733::SetRowPWM	(	uint8_t	row,
		const uint8_t *	pwmValues
	)

Set PWM values for an entire row (hardware coordinates).

Parameters

row	Hardware row (1..12 = SW1..SW12).
pwmValues	Array of 16 PWM values.

Definition at line 353 of file is31fl3733.cpp.

                                                                {
    // guard against out-of-bounds and 0 (1-based indexing)
    if (row > kHardwareRows || !row)
        return;
 
    // Convert 1-based to 0-based index
    uint8_t idx = (row - 1) & 0x0F;
 
    // Update pwm buffer for the row (starting at offset 1 since [idx][0] is reserved for row
    // address)
    memcpy(_pwm_matrix[idx] + 1, pwmValues, kHardwareCols);
 
    // Enqueue row for transmission (if not already enqueued)
    uint16_t rowBit = 1 << idx;
    if (_pwmEnqueued & rowBit)
        return; // Already enqueued
 
    _pwmEnqueued |= rowBit;
    _pwmPendingRows.store(idx);
 
    // Kick transmission if not already in-flight
    if (!_pwmTxn.txPtr && !_pwmLocked)
        _sendRowPWM();
}

SetShortFaultMaskEnabled()

void IS31FL3733::IS31FL3733::SetShortFaultMaskEnabled ( bool  enable )

inline

Control whether LEDSHORT bits are applied when computing LEDONOFF mask.

Some boards can report persistent short false-positives on specific channels during OSD. When disabled, only LEDOPEN contributes to LEDONOFF masking.

Parameters

enable

True to mask shorts and opens, false to mask opens only.

Definition at line 353 of file is31fl3733.hpp.

                                               {
        _maskShortFaults = enable;
    }

SetSWPUR()

void IS31FL3733::IS31FL3733::SetSWPUR

(

uint8_t

pur

)

Set SW pull-up resistor control (Page 3 SWPUR).

Parameters

pur	Pull-up value (lower 3 bits are used).

Definition at line 305 of file is31fl3733.cpp.

                                     {
    uint8_t purValue = static_cast<uint8_t>(pur & 0x07);
    _asyncWrite(SWPUR, &purValue, 1, nullptr, nullptr);
}

TriggerABM()

void IS31FL3733::IS31FL3733::TriggerABM

(

)

Latch ABM timing updates by writing TUR on Page 3.

Definition at line 712 of file is31fl3733.cpp.

                            {
    // Ensure Page 3
    _ensurePage(3);
 
    // Write any value to TUR (0x0E) to latch configuration
    // Per datasheet: "Any write to 0Eh will latch the ABM configuration"
    // We write 0x00 as the trigger value
    uint8_t tur_value = 0x00;
    _asyncWrite(TUR, &tur_value, 1, nullptr, nullptr);
}

Member Data Documentation

_abm_matrix

uint8_t IS31FL3733::IS31FL3733::_abm_matrix[kHardwareRows][kHardwareCols+1]

private

[row][0] = Page 2 row addr, [1..16] = ABM data

Definition at line 553 of file is31fl3733.hpp.

_abmCallbacks

std::function<void()> IS31FL3733::IS31FL3733::_abmCallbacks[3]

private

Completion callbacks for ABM1/2/3.

Definition at line 563 of file is31fl3733.hpp.

_abmEnqueued

uint16_t IS31FL3733::IS31FL3733::_abmEnqueued

private

Bitfield tracking enqueued rows (0x0001..0x0FFF)

Definition at line 559 of file is31fl3733.hpp.

_abmLocked

bool IS31FL3733::IS31FL3733::_abmLocked

private

True when command chain has preempted ABM.

Definition at line 561 of file is31fl3733.hpp.

_abmPendingRows

RingBufferN<kHardwareRows + 1> IS31FL3733::IS31FL3733::_abmPendingRows

private

Effective capacity: kHardwareRows.

Definition at line 558 of file is31fl3733.hpp.

_abmTxn

SercomTxn IS31FL3733::IS31FL3733::_abmTxn

private

Single in-flight ABM transaction descriptor.

Definition at line 555 of file is31fl3733.hpp.

_abmTxPtr

uint8_t IS31FL3733::IS31FL3733::_abmTxPtr[kHardwareCols+1]

private

Shadow buffer for current transaction.

Definition at line 556 of file is31fl3733.hpp.

_addr

uint8_t IS31FL3733::IS31FL3733::_addr

private

7-bit I2C address

Definition at line 523 of file is31fl3733.hpp.

_begun

bool IS31FL3733::IS31FL3733::_begun

private

True after successful begin(); used for destructor auto-end safety.

Definition at line 597 of file is31fl3733.hpp.

_cmdCtx

CmdTxnContext IS31FL3733::IS31FL3733::_cmdCtx[4]

private

Context for each command transaction (for callbacks)

Definition at line 583 of file is31fl3733.hpp.

_cmdError

volatile uint8_t IS31FL3733::IS31FL3733::_cmdError

private

Bitfield of command transactions with nonzero status.

Definition at line 590 of file is31fl3733.hpp.

_cmdReturn

volatile uint8_t IS31FL3733::IS31FL3733::_cmdReturn

private

Bitfield of completed command transactions (bits 0..3)

Definition at line 589 of file is31fl3733.hpp.

_cmdRx

uint8_t IS31FL3733::IS31FL3733::_cmdRx[24]

private

RX buffer (max: 24 bytes for LED Open/Short)

Definition at line 587 of file is31fl3733.hpp.

_cmdTx

uint8_t IS31FL3733::IS31FL3733::_cmdTx[25]

private

TX buffer (max: 1 addr + 24 data for LED On/Off)

Definition at line 586 of file is31fl3733.hpp.

_cmdTxn

SercomTxn IS31FL3733::IS31FL3733::_cmdTxn[4]

private

[0]=unlock, [1]=page, [2]=write, [3]=read

Definition at line 571 of file is31fl3733.hpp.

_colorOrder

ColorOrder IS31FL3733::IS31FL3733::_colorOrder

private

RGB pixel color order.

Definition at line 616 of file is31fl3733.hpp.

_crValue

uint8_t IS31FL3733::IS31FL3733::_crValue

private

Shadow of CR register state for runtime updates.

Definition at line 615 of file is31fl3733.hpp.

_crwlTx

uint8_t IS31FL3733::IS31FL3733::_crwlTx[2]

private

Pre-staged unlock transaction {PSWL, PSWL_ENABLE}.

Definition at line 584 of file is31fl3733.hpp.

_currentPage

uint8_t IS31FL3733::IS31FL3733::_currentPage

private

Tracks current page (0-3, 0xFF=unknown) to minimize page selects.

Definition at line 526 of file is31fl3733.hpp.

_hw

SERCOM* IS31FL3733::IS31FL3733::_hw

private

SERCOM I2C hardware interface.

Definition at line 522 of file is31fl3733.hpp.

_instance

IS31FL3733 * IS31FL3733::IS31FL3733::_instance = nullptr

staticprivate

Static instance pointer for ISR access.

Definition at line 528 of file is31fl3733.hpp.

_irqPin

uint8_t IS31FL3733::IS31FL3733::_irqPin

private

IRQ pin (0xFF = not used)

Definition at line 525 of file is31fl3733.hpp.

_lastISR

uint8_t IS31FL3733::IS31FL3733::_lastISR

private

Cached ISR value from last fault detection.

Definition at line 607 of file is31fl3733.hpp.

_ledOn

uint8_t IS31FL3733::IS31FL3733::_ledOn[24]

private

Computed LED On/Off mask (Page 0, 0x00)

Definition at line 606 of file is31fl3733.hpp.

_ledOpen

uint8_t IS31FL3733::IS31FL3733::_ledOpen[24]

private

Cached LED open status (Page 0, 0x18)

Definition at line 604 of file is31fl3733.hpp.

_ledShort

uint8_t IS31FL3733::IS31FL3733::_ledShort[24]

private

Cached LED short status (Page 0, 0x30)

Definition at line 605 of file is31fl3733.hpp.

_maskShortFaults

bool IS31FL3733::IS31FL3733::_maskShortFaults

private

Include LEDSHORT bits in computed LEDONOFF mask.

Definition at line 617 of file is31fl3733.hpp.

_pgSelTx

uint8_t IS31FL3733::IS31FL3733::_pgSelTx[2]

private

Page select transaction buffer {PSR, page}.

Definition at line 585 of file is31fl3733.hpp.

_pwm_matrix

uint8_t IS31FL3733::IS31FL3733::_pwm_matrix[kHardwareRows][kHardwareCols+1]

private

[row][0] = Page 1 row addr, [1..16] = PWM data

Definition at line 536 of file is31fl3733.hpp.

_pwmBatchActive

bool IS31FL3733::IS31FL3733::_pwmBatchActive

private

True while staged PWM updates are being batched.

Definition at line 545 of file is31fl3733.hpp.

_pwmEnqueued

uint16_t IS31FL3733::IS31FL3733::_pwmEnqueued

private

Bitfield tracking enqueued rows (0x0001..0x0FFF)

Definition at line 542 of file is31fl3733.hpp.

_pwmLocked

bool IS31FL3733::IS31FL3733::_pwmLocked

private

True when command chain has preempted PWM.

Definition at line 544 of file is31fl3733.hpp.

_pwmPendingRows

RingBufferN<kHardwareRows + 1> IS31FL3733::IS31FL3733::_pwmPendingRows

private

Effective capacity: kHardwareRows.

Definition at line 541 of file is31fl3733.hpp.

_pwmTxn

SercomTxn IS31FL3733::IS31FL3733::_pwmTxn

private

Single in-flight PWM transaction descriptor.

Definition at line 538 of file is31fl3733.hpp.

_pwmTxPtr

uint8_t IS31FL3733::IS31FL3733::_pwmTxPtr[kHardwareCols+1]

private

Shadow buffer for current transaction.

Definition at line 539 of file is31fl3733.hpp.

_sdbPin

uint8_t IS31FL3733::IS31FL3733::_sdbPin

private

SDB (shutdown) pin (0xFF = not used)

Definition at line 524 of file is31fl3733.hpp.

_syncComplete

volatile bool IS31FL3733::IS31FL3733::_syncComplete

private

Blocking command completion flag.

Definition at line 592 of file is31fl3733.hpp.

_syncStatus

volatile int IS31FL3733::IS31FL3733::_syncStatus

private

Blocking command final status.

Definition at line 593 of file is31fl3733.hpp.

_syncTargetCmd

volatile int8_t IS31FL3733::IS31FL3733::_syncTargetCmd

private

Index of command awaited by blocking API.

Definition at line 594 of file is31fl3733.hpp.

---

The documentation for this class was generated from the following files:

• is31fl3733.hpp
• is31fl3733.cpp