From 8ef746f25174030257416d0e51472d3a4f163f95 Mon Sep 17 00:00:00 2001 From: KurtMF Date: Sun, 2 Feb 2025 16:04:45 -0500 Subject: [PATCH] Update README about using FastLED with and without ObjectFLED.h --- README.md | 87 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 3816884..7efcc82 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ -# ObjectFLED.h +# ObjectFLED - Non-Blocking Teensy 4.x DMA Display Driver for Clockless WS28xx LEDs -FastLED-friendly LED display driver allows for configuration and control of multiple digital LED display devices -independently in code. Display objects use DMA transfer (from [OctoWS2811 library](http://www.pjrc.com/teensy/td_libs_OctoWS2811.html)) -on any or all 40 or 55 pins of Teensy 4.0 or 4.1 to drive digital LEDs with massive parallelism. +FastLED-friendly LED display driver allows for configuration and control of multiple LED display +devices independently in code. Display objects use DMA transfer (from [OctoWS2811 library](http://www.pjrc.com/teensy/td_libs_OctoWS2811.html)) +on any or all 40 or 55 digital pins of Teensy 4.0 or 4.1 to drive digital LEDs with massive +parallelism if needed. The show() function is non-blocking, returning control to the graphics drawing code in just 6% of the time it takes to complete buffer transmission to an LED string (tested with WS2812B, 1.6 @@ -14,23 +15,24 @@ ObjectFLED works with FastLED arrays of CRGB, or other drawing buffer in RGB 3-b * "LED object" or "display object" refers to the ObjectFLED display object(s) in your code. * "LED device" refers to physical LEDs: strings, planes, cubes, etc. -* "Segment" refers to physical LEDs connected to a single pin. This can be a string or a group -of LED devices (physically daisy-chained), or a subset of LED devices in a larger LED device (rows of a plane, -planes of a cube, etc. +* "Segment" refers to physical LEDs connected to a single pin. This can be a string or a subset +of LED devices in a larger LED device (rows of a plane, planes of a cube, spokes of a wheel, etc.) ## SUPPORTED - For Teensy 4.x only. It may be possible to add other boards if they support DMA driven by configurable timers, and ability to map digital pins to a data register which DMA can target. - LED data color formats: RGB, GRB, BRG, GBR, BGR and RGBW + - Known compatible LED types: SK6812, WS2811, WS2812, WS2812B, WS2812C, WS2812D, WS2812S, WS2813, +WS2813E, WS2815B ## MAIN BENEFITS -* You can independently configure, control and display multiple LED devices connected to your -Teensy 4.x, even if the devices use different LED types with different specs. Combine LED devices -into a single display object, or define separate objects for segments of each device, or just plain -one display object for each device. It is also possible to define 2 display objects to display the +* Independently configure, control and display multiple LED devices connected to your Teensy 4.x, +even if the devices use different LED types with different specs. Combine LED devices into a +single display object, or define separate objects for segments of each device, or just plain one +display object for each device. It is also possible to define 2 display objects to display the same drawing buffer on 2 different LED devices. * Large LED devices can be driven with parallel output to separate segments of the device, allowing @@ -42,22 +44,41 @@ for your object, in the same order they are connected physically to the segments functions of FastLED. But you can use any memory object for drawing buffer, so long as it is 3- bytes per LED in RGB order. -* You can tweak the shape of the LED data waveform generated by this driver. By calling begin() -with full pulse timing specs, you can tweak the waveform to achieve the highest possible overclock -(and highest back-to-back refresh rate). ObjectFLED sends a latch pulse at the end of every frame, -and defaults to a 300 uS latch period. Some WS2812s specify only 50 uS latch period. To make a -noticable increase in refresh rate, try 75 uS latch if yours are rated for 50 (I had to use 72 on a -50 uS latch LED). +* You can tweak the shape of the LED data waveform generated by this driver to achieve the highest +possible overclock. ObjectFLED sends a latch pulse at the end of every frame, and defaults to +300 uS latch period. Some WS2812s specify only 50 uS latch period. To make a noticable increase +in refresh rate, try 75 uS latch if yours are rated for 50 (I had to use 72 on a 50 uS latch LED). -* Show() function has built-in handling for serpentine, color order, brightness, and color balance -for each object. Like in FastLED, these are applied to the frame buffer, not your drawing buffer. -Get and set functions for brightness and colormask are included (the ones in FastLED won't work on -ObjectFLED display objects). These are applied independently to each display object in your sketch. +* Show() function has built-in handling for serpentine rows of a plane, color order, brightness, +and color balance for each object. Like in FastLED, these are applied to the frame buffer, not +your drawing buffer. Get and set functions for brightness and colormask are included (the ones in +FastLED won't work on ObjectFLED display objects). These are applied independently to each display +object in your sketch. * Accessory functions included to fade a drawing array to a color other than black, and to draw a square on an LED plane. +## USING OBJECTFLED WITH FASTLED + +As of FastLED relase 3.9.8, FastLED has built-in non-blocking DMA driver for Teensy 4.x, ported +from ObjectFLED. Since this release, it is possible to have the speed and parallelism benefits +of ObjectFLED without installing and including ObjectFLED library. However there are some +functional differences between running FastLED with and without including ObjectFLED.h, which may +impact your project: + +|FastLED Without ObjectFLED.h|FastLED With ObjectFLED.h|| +|:----------:|:----------:|:--------------------------------------------------------------------| +|YES|YES|Explicitly assign pins to 1D arrays for LED strings| +|NO|YES|Auto-assign ordered pin list to segments of 2D and 3D arrays for LED string collections, planes and cubes| +|YES|NO|Show, brightness, color balance are global to all LED objects defined in sketch| +|NO|YES|Show, brightness, color balance are specific to each LED object defined in sketch| +|NO|YES|Built-in support for serpentine rows in LED planes| + +2 new sketches were added to the examples directory to illustrate both methods: UsesFastLED.ino and +UsesObjectFLED.ino. + + ## LED DEVICES Physical LED devices are connected to Teensy's digital pins via a buffer circuit to step the 3.3v @@ -65,8 +86,8 @@ Teensy squarewave up to 5v for the LEDs. For buffering, use [OctoWS2811 boards] LED planes can have their data paths physically wired for serpentine (reverse direction on every other row). ObjectFLED will automatically perform serpentine output if you specify an LED count -(row size) for your display object. However, with planes in a cube, ObjectFLED expects the last LED -of a plane to connect to the first LED of the next plane (no plane-level serpentine, only row- +(row size) for your display object. However, with planes in a cube, ObjectFLED expects the last +LED of a plane to connect to the first LED of the next plane (no plane-level serpentine, only row- level). When taking advantage of parallel inputs into an LED device, each pin is assumed to drive the same @@ -75,8 +96,8 @@ list which matches the order in which the pins connect to the device. Individual LEDs come with various formats for RGB color order, data signal clock frequency, and pulse timing specs. ObjectFLED defaults will work for popular RGB-order LEDs with 800KHz clock and -300uS latch delay. Use the begin(params) function on an ObjectFLED object in order to use timing specs -from your LED's datasheet. Specify the color order when you instantiate ObjectFLED. +300uS latch delay. Use the begin(params) function on an ObjectFLED object in order to use timing +specs from your LED's datasheet. Specify the color order when you instantiate ObjectFLED. ## USAGE @@ -104,7 +125,7 @@ where Z is plane, Y is row, X is pixel in row. **Best Practice:** Use variable names which partially match for creating a drawing array and it's matching display -object. Ex.- +object. CRGB grid4[Y][X]; ObjectFLED dspGrid4( Y*X, grid4, etc. ); @@ -123,7 +144,7 @@ begin(uint16_t latchDelay); // Overclock default timing and optionally overrde default latch delay begin(double OCF, uint16_t latchDelay = 300); -// Fully specify output waveform timing TH_TL (clk period), T0H, T1H, and optionally Latch Delay_ +// Fully specify output waveform timing TH_TL (clk period), T0H, T1H, and optionally Latch Delay begin(uint16_t period, uint16_t t0h, uint16_t t1h, uint16_t latchDelay = 300); - OCF = Overclocking factor multiples the clock rate (by dividing the pulse width values below) @@ -141,12 +162,12 @@ period = 1250nS. This is the default setting. ### show() FUNCTION -See MAIN BENEFITS above for details. When calling show() back-to-back, each must wait for the prior to complete it's -latch pulse at the end of writing. This is also true when calling show() for one object right after -calling show() for another object. All display objects share the same DMA-Timer pipeline in hardware. -Therefore, for code which controls a large LED device and a small one, with sequential calls to each -show(): show the small one first, then show the large one, then update your drawing while the large -display is still DMA-transmitting 94% of it's LED data. +See MAIN BENEFITS above for details. When calling show() back-to-back, each must wait for the +prior to complete it's latch pulse at the end of writing. This is also true when calling show() +for one object right after calling show() for another object. All display objects share the same +DMA-Timer pipeline in hardware. Therefore, for code which controls a large LED device and a small +one, with sequential calls to each show(): show the small one first, then show the large one, then +update your drawing while the large display is still DMA-transmitting 94% of it's LED data. **Example:**