Output - NeoPixel (BusFX)¶

NeoPixel special effects library BusFX

Plugin details¶

Type: Output

Name: NeoPixel (BusFX)

Status: NEOPIXEL

Maintainer: tonhuisman

Used libraries: https://github.com/Makuna/NeoPixelBus and https://github.com/djcysmic/NeopixelBusFX (forked from ESPEasyPluginPlayground)

Description¶

The NeoPixel (BusFX) plugin is designed to use strings of NeoPixel LEDs, like the WS2811/WS2812/WS2813, to show light-effects.

Supported hardware¶

LED strips (sometimes called stripes) using the WS281x type (and clones) of multi-color LEDs, capable of displaying 24 bits of color (16 million colors). Each LED is separately addressable, and the entire stripe can be controlled using a single GPIO pin on the ESP.

Power consumption¶

By the physical design of these modules, using NeoPixel leds for display that can consume up to 60 mA each, the power consumption is dependent on the number of neopixels that are activated and the brightness that is set. On a set of NeoPixels, like consisting of 64 pixels, the max. power used 60 mA * 64 = 3840 mA @ 5V = 19.2 watt with all leds on at max brightness (255), so it requires an adequate power supply, preferably separate from the power supply used to power the ESP.

When reducing the brightness to 40% (0.4 * 255 = 102), that power is reduced to ca. 1.5 A @ 5V = ca. 7.5 watt. 40% is usually enough during daylight conditions, at night the brightness can often be reduced to 20%.

For a set of 300 pixels, the max. power would count up to 300 * 60 mA @ 5V = 90 W. At 40% brightness, that is reduced to 36 W.

Reasoning back from the available power supply max. load (f.e. 30 W), the max. allowed brightness can be calculated by dividing the max. load by the voltage (5V) and the number of pixels (300) = 20 mA, 60 / 20 = 3 = ~33% brightness = 85. That will still be bright enough, but will put quite a strain at the power supply.

Configuration¶

Name A unique name should be entered here.
Enabled The device can be disabled or enabled. When not enabled the device should not use any resources.

Actuator¶

GPIO -> Stripe data: Select the GPIO pin the stripe is connected to (Only available on ESP32!)

Due to the design of the used library and the methods used, on ESP8266 only GPIO-2 can be used to connect the LED stripe:

Led Count: Set up the number of leds that are available on the stripe. (Current maximum is 300).
Max brightness: The maximum brightness allowed for the stripe. Range: 1..255. This is also the initial brightness set during initialization. Can not be overridden by the dim subcommand, and also the maximum value for the rainbow subcommand.

Data Aquisition¶

The Data Acquisition, Send to Controller and Interval settings are standard available configuration items. Send to Controller only when one or more Controllers are configured.

Interval By default, Interval will be set to 0 sec. This is optional. When set, the Values will be sent to any configured controllers, and events generated to be handled in rules.

Values¶

The value names are fixed and not configurable. These names are:

Mode: The currently active mode (numeric value)
Lastmode: The previously active mode (numeric value)
Fadetime: Currently set fade time value (milliseconds)
Fadedelay: The delay time used during fade in or out (milliseconds)

Commands available¶

Command Syntax	Extra information
NB: The `neopixelfx` command can be abbreviated to `nfx`.
For brevity the `nfx` command is used here.

Led count == Number of pixels.
`nfx,off[,fadetime[,delay]]`	Switches the stripe off, using the optional fadetime and delay timings (milliseconds).
`nfx,on[,fadetime[,delay]]`	Restores the last state of the stripe, active before a `nfx off` command was applied, using the optional fadetime and delay timings (milliseconds).
`nfx,dim[,dimvalue]`	Set the brightness of the stripe, range `0` to `255` (max. brightness), set to 0 when not specified. If the provided dimvalue exceeds the configured Max brightness configuration setting, or is negative, it is ignored (invalid command).
`nfx,line,<startpixel>,<endpixel>,<color>`	Light up the pixels from startpixel (range: 1..number of pixels) to endpixel (range: number of pixels..startpixel) with the specified color. Color is to be specified in a hex RRGGBB value.
`nfx,hsvline,<startpixel>.<endpixel>,<hue>,<saturation>,<brightness>`	Light up the pixels from startpixel (range: 1..number of pixels) to endpixel (range: number of pixels..startpixel) with the specified hsvcolor values.
`nfx,one,<pixel>,<color>`	Light up 1 pixel (range: 1..number of pixels) with the specified color. Color is to be specified in a hex RRGGBB value.
`nfx,hsvone,<pixel>,<hue>,<saturation>,<brightness>`	Light up 1 pixel (range: 1..number of pixels) with the specified hsvcolor values.
`nfx,all,<color>[,fadetime[,delay]]` `nfx,rgb,<color>[,fadetime[,delay]]` `nfx,fade,<color>[,fadetime[,delay]]`	Light up all pixels with the specified color, using the optional fadetime and delay timings (milliseconds). Color is to be specified in a hex RRGGBB value. For the `all` and `rgb` subcommands, the delay is set to 0 if not specified. When using the `fade` subcommand, a previously set delay is used.
`nfx,hsv,<hue>,<saturation>,<brightness>[,fadetime[,delay]]`	Light up all pixels with the specified hsvcolor values, using the optional fadetime and delay timings (milliseconds). Delay is set to 0 if not specified.
`nfx,colorfade,<startcolor>,<endcolor>[,startpixel[,endpixel]]`	Change the color for all or specified start- to end-pixels, from startcolor to endcolor. Colors are to be specified in a hex RRGGBB value.
`nfx,rainbow[,speed[,fadetime]]`	Run a rainbow effect color loop effect using speed and fadetime timings (in milliseconds).
`nfx,kitt,<color>[,speed]`	Run a `kitt` (from the TV-series Knight Rider) effect across the pixels, using an optional speed value (range: -50..50, default: 25, negative = reverse).
`nfx,comet,<color>[,speed]`	Run a comet effect across the pixels, using an optional speed value (range: -50..50, default: 25, negative = reverse).
`nfx,theatre,<color>[,backgroundcolor[,count[,speed]]]`	Run a theatre effect across the pixels, using optional backgroundcolor, count (default: 1) and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
`nfx,scan,<color>[,backgroundcolor[,speed[,startpixel[,endpixel]]]]`	Run a scan effect across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
`nfx,dualscan,<color>[,backgroundcolor[,speed[,startpixel[,endpixel]]]]`	Run a dual scan effect, 2 scans in opposite direction, across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
`nfx,twinkle,<color>[,backgroundcolor[,speed]]`	Run a twinkle effect across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
`nfx,twinklefade,<color>[,count[,speed]]`	Run a fading twinkle effect across the pixels, using optional count (default: 1) and speed values (range: -50..50, default: 25, negative = reverse). Color is to be specified in a hex RRGGBB value.
`nfx,sparkle,<color>[,backgroundcolor[,speed]]`	Run a sparkle effect across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
`nfx,wipe,<color>[,dotcolor[,speed]]`	Run a wipe effect across the pixels, using optional dotcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
`nfx,dualwipe[,dotcolor[,speed]]`	Run a dual wipe effect, in opposite direction, across the pixels, using optional dotcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
`nfx,fire[,fps[,brightness[,cooling[,sparking]]]]`	Run a fire effect accross the pixels, with optional fps (default: 50), brightness (default: 31), cooling (range 20..100, default: 50) and sparking (range: 20..200, default: 120) values.
`nfx,fireflicker[,intensity[,speed]]`	Run a flickering fire effect across the pixels, with optional intensity (default: 3) and speed (range -50..50, default: 25, negative = reverse) values.
`nfx,faketv[,startpixel[,endpixel]]`	Run a fake TV effect on the pixels, optionally specifying a start- end end-pixel. Used for simulating an active TV-set, f.e. when not at home during the evening, to scare off potential burglars. NB: This effect may be excluded from the build for size reasons, by default it is not included in ESP8266 builds. It can be included in self-built Custom builds.
`nfx,simpleclock[,bigtickcolor[,smalltickcolor[,hourcolor[,minutecolor[,secondcolor (set 'off' to disable)[,backgroundcolor]]]]]]`	Display a simple clock on the pixels. TODO: Optional arguments and setup to be determined.
`nfx,stop`	Stops the effect.
`nfx,statusrequest`	Send back the status as a JSON message to the source it was requested from.
`nfx,fadetime,<time>`	Set the fade time per pixel in milliseconds.
`nfx,fadedelay,<delay>`	Set the fade delay to next pixel in milliseconds.
`nfx,speed,<speed>`	Set the default effect speed, range -50..50. Negative value will revert the direction.
`nfx,count,<count>`	Set the NeoPixel LED-count.
`nfx,bgcolor,<backgroundcolor>`	Sets the default background color. Backgroundcolor is to be specified in a hex RRGGBB value.

Change log¶

Added in version 2.0: …

added 2022-07-02: Max brightness setting.

added Initial release version.