electron-rare/ObjectFLED_CLS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README about using FastLED with and without ObjectFLED.h

Browse Source
This commit is contained in:
KurtMF
2025-02-02 16:04:45 -05:00
parent ea33deeab1
commit 8ef746f251
1 changed files with 54 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+54 -33
View File
@@ -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:**