ObjectFLED.h

Go to the documentation of this file.

/*  ObjectFLED - Teensy 4.x DMA to all pins for independent control of large and
    multiple LED display objects
 
    Copyright (c) 2024 Kurt Funderburg
 
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
 
    OctoWS2811 library code was well-studied and substantial portions of it used 
    to implement high-speed, non-blocking DMA for LED signal output in this library.
    See ObjectFLED.cpp for a summary of changes made to the original OctoWS2811.
 
    OctoWS2811 - High Performance WS2811 LED Display Library
    Copyright (c) 2013 Paul Stoffregen, PJRC.COM, LLC
    http://www.pjrc.com/teensy/td_libs_OctoWS2811.html
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
*/
 
#include "platforms/arm/teensy/is_teensy.h"
 
#ifndef FL_IS_TEENSY_4X
#error "Sorry, ObjectFLED only works on Teensy 4.x boards."
#endif
#if TEENSYDUINO < 121
#error "Teensyduino version 1.21 or later is required to compile this library."
#endif
#ifndef ObjectFLED_h
#define ObjectFLED_h
#include <WProgram.h>
#include "DMAChannel.h"
#include "ObjectFLEDDmaManager.h"
 
#include "fl/stl/stdint.h"
 
//Experimentally found DSE=3, SPEED=0 gave best LED overclocking
//boot defaults DSE=6, SPEED=2.
#define OUTPUT_PAD_DSE      3       //Legal values 0-7
#define OUTPUT_PAD_SPEED    0       //Legal values 0-3
 
// Ordinary RGB data is converted to GPIO bitmasks on-the-fly using
// a transmit buffer sized for 2 DMA transfers.  The larger this setting,
// the more interrupt latency OctoWS2811 can tolerate, but the transmit
// buffer grows in size.  For good performance, the buffer should be kept
// smaller than the half the Cortex-M7 data cache.
//bitdata[B_P_D * 64]       buffer holds data (10KB) for 80 LED bytes: 4DW * 8b = 32DW/LEDB = 96DW/LED
//framebuffer_index = B_P_D * 2 = pointer to next block for transfer (80 LEDB / bitdata buffer)
// Doubled from 60 to 120 to lengthen the eDMA major loop on dma2 (the
// chunked half-buffer used for ESG-chained refill). With BYTES_PER_DMA=60
// the ISR had only ~1.25 us between dma2's ESG reload and the next TMR4
// trigger, but the ISR's memset + fillbits + dcache_flush takes ~10 us
// on Cortex-M7 @ 600 MHz -- so dma2next was reading a partially-refilled
// chunk on the first ~10 us of each new chunk. That race is the most
// plausible mechanism behind the residual mid-byte 0->1 phantom bit flips
// reported in #3406 (statistical analysis shows errors cluster at the
// 20-LED chunk boundaries that BYTES_PER_DMA=60 produces). 120 doubles
// the inter-ISR margin with the same memset overhead, +15 KB DMAMEM cost.
// BYTES_PER_DMA is defined in ObjectFLEDDmaManager.h to keep a single
// source of truth (CodeRabbit-flagged on PR #3419 -- previously this
// header also had a #ifndef guard with default 120, while
// ObjectFLEDDmaManager.h had 150, creating an include-order-dependent
// ODR hazard between the bitdata[] array size and any consumer that
// arithmetic-references BYTES_PER_DMA). The definition itself now
// lives in ObjectFLEDDmaManager.h next to the static_assert and the
// bitdata array declaration that depends on it.
#include "ObjectFLEDDmaManager.h"
 
#define CORDER_RGB  0   //* WS2811, YF923
#define CORDER_RBG  1
#define CORDER_GRB  2   //* WS2811B, Most LED strips are wired this way
#define CORDER_GBR  3   //*
#define CORDER_BRG  4   //* Adafruit Product ID: 5984 As of November 5, 2024 - this strand has different 'internal' color ordering. It's now BRG not RGB,
#define CORDER_BGR  5   //* Adafruit Dotstar LEDs SK9822 uses this CO but they use inverted start/stop bits
#define CORDER_RGBW 6   //* Popular
#define CORDER_RBGW 7
#define CORDER_GRBW 8
#define CORDER_GBRW 9
#define CORDER_BRGW 10
#define CORDER_BGRW 11  // Adafruit Dotstar LEDs SK9822 uses this CO but they use inverted start/stop bits
#define CORDER_WRGB 12
#define CORDER_WRBG 13
#define CORDER_WGRB 14
#define CORDER_WGBR 15
#define CORDER_WBRG 16
#define CORDER_WBGR 17
#define CORDER_RWGB 18
#define CORDER_RWBG 19
#define CORDER_GWRB 20
#define CORDER_GWBR 21
#define CORDER_BWRG 22
#define CORDER_BWGR 23
#define CORDER_RGWB 24
#define CORDER_RBWG 25
#define CORDER_GRWB 26
#define CORDER_GBWR 27
#define CORDER_BRWG 28
#define CORDER_BGWR 29
 
namespace fl {
 
 
//Usage: ObjectFLED myCube ( Num_LEDs, *drawBuffer, LED_type, numPins, *pinList, serpentineNumber )
class ObjectFLED {
public:
    // Teensy 4.x hardware ownership:
    // ObjectFLED owns QTimer4 channels 0-2, XBAR1 DMA request outputs 30/31/94,
    // the corresponding DMAMUX requests, its allocated DMA channels, and the
    // selected pins' standard GPIO aliases while an instance is active. It does
    // not restore prior owners for those resources; conflicting peripherals must
    // be treated as unsupported while ObjectFLED is in use.
    // Usage: ObjectFLED myCube ( Num_LEDs, *drawBuffer, LED_type, numPins, *pinList, serpentineNumber )
    // Example:
    // byte pinList[NUM_CHANNELS] = {1, 8, 14, 17, 24, 29, 20, 0, 15, 16, 18, 19, 21, 22, 23, 25};
    // byte pinListBlank[7] = {1, 8, 14, 17, 24, 29, 20};
    // CRGB testCube[NUM_PLANES][NUM_ROWS][PIX_PER_ROW];
    // CRGB blankLeds[7][8][8];
    // ObjectFLED leds(PIX_PER_ROW * NUM_ROWS * NUM_PLANES, testCube, CORDER_RGB, NUM_CHANNELS, pinList);
    // void setup() {
    //    leds.begin(1.6, 72);    //1.6 ocervlock factor, 72uS LED latch delay
    //    leds.setBrightness(64);
    // }
    // void loop() {
    //    leds.show();
    //    delay(100);
    // }
    ObjectFLED(uint16_t numLEDs, void* drawBuf, uint8_t config, uint8_t numPins, const uint8_t* pinList, \
                uint8_t serpentine = 0);
 
    ~ObjectFLED();

    template <typename TIMING>
    void begin(uint16_t latch_delay_us = TIMING::RESET) {
        // Extract T1, T2, T3 directly from TIMING struct
        // T1 = high time for '0' bit
        // T2 = additional high time for '1' bit
        // T3 = low tail duration
        begin(TIMING::T1, TIMING::T2, TIMING::T3, latch_delay_us);
    }

    void begin(uint16_t t1, uint16_t t2, uint16_t t3, uint16_t latch_delay_us = 300);
 
private:
    //begin() - Use defalut LED timing: 1.0 OC Factor, 1250 nS CLK (=800 KHz), 300 nS T0H, 750 nS T1H, 300 uS LED Latch Delay.
    void begin(void);
 
    //begin(LED_Latch_Delay_uS) - sets the LED Latch Delay.
    void begin(uint16_t);
 
    //beginInternal(LED_CLK_nS, LED_T0H_nS, LED_T1H_nS, LED_Latch_Delay_uS) - specifies full LED waveform timing.
    void beginInternal(uint16_t, uint16_t, uint16_t, uint16_t = 300);
 
public:
 
    void show(void);
    void showRawFrameBuffer(void);
    void waitForDmaToFinish();
 
    int busy(void);
 
    //Brightness values 0-255
    void setBrightness(uint8_t);
 
    //Color Balance is 3-byte number in RGB order.  Each byte is a brightness value for that color.
    void setBalance(uint32_t);
 
    uint8_t getBrightness();
 
    uint32_t getBalance();
 
    // Frame buffer for direct pixel access (used by FastLED integration)
    uint8_t* frameBufferLocal;
 
private:
    static void isr(void);
 
    void genFrameBuffer(uint32_t);
    void showInternal(bool regenerateFrameBuffer);
 
    uint32_t update_begin_micros = 0;
    uint8_t brightness = 255;
    uint32_t colorBalance = 0xFFFFFF;
    uint32_t rLevel = 65025;
    uint32_t gLevel = 65025;
    uint32_t bLevel = 65025;
public:
    void* drawBuffer;
private:
    uint16_t stripLen;
    uint8_t params;
    uint8_t pinlist[NUM_DIGITAL_PINS];
    uint16_t comp1load[3];
    uint8_t serpNumber;
    uint16_t TH_TL = 1250;         //nS- period of LED output
    uint16_t T0H = 300;              //nS- duration of T0H
    uint16_t T1H = 750;              //nS- duration of T1H
    uint16_t LATCH_DELAY = 300;      //uS time to hold output low for LED latch.
 
    //for show context switch
    // Force 32-byte alignment so arm_dcache_flush_delete in begin() operates
    // on a whole cache line. Without alignment the 16-byte flush is unsafe
    // per Cortex-M7 cache maintenance semantics (#3406).
    // #3416 OF-MED-1: bitmaskLocal is 16 bytes (alignas 32 = its own line
    // start) but the adjacent numpinsLocal/numbytesLocal share the second
    // half of the same 32-byte cache line. Padding to a full 32 bytes
    // guarantees the flush_delete invalidates only data this driver owns
    // and never an adjacent instance's fields.
    alignas(32) uint32_t bitmaskLocal[8];  // 4 valid words + 4 pad
    uint8_t numpinsLocal;
    uint32_t numbytesLocal;
    uint8_t pin_bitnumLocal[NUM_DIGITAL_PINS];
    uint8_t pin_offsetLocal[NUM_DIGITAL_PINS];
    bool initialized = false;
};  // class ObjectFLED
 
 
//fadeToColorBy(RGB_array, LED_count, Color, FadeAmount)
//Fades an RGB array towards the background color by amount. 
void fadeToColorBy(void*, uint16_t, uint32_t, uint8_t);
 
 
//drawSquare(RGB_Array, LED_Rows, LED_Cols, Y_Corner, X_Corner, square_Size)
//Draws square in a 2D RGB array with lower left corner at (Y_Corner, X_Corner).
//Safe to specify -Y, -X corner, safe to draw a box which partially fits on LED plane.
void drawSquare(void*, uint16_t, uint16_t, int, int, uint32_t, uint32_t);
 
}   // namespace fl
 
#endif