Output - NeoPixel (BusFX)

NeoPixel special effects library BusFX

Plugin details

Type: Output

Name: NeoPixel (BusFX)

Status ESP32: NEOPIXEL

Status ESP8266: NEOPIXEL

GitHub: P128_NeoPixelBusFX.ino

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

Device 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:

ESP8266 GPIO instruction

  • 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 Acquisition

This group of settings are standard available configuration items.

  • Single event with all values: When this setting is enabled, all available values will be sent in a single event <TaskName>#All, with all values in order as arguments to the event.

  • Show derived values: When checked, the Devices overview page, and the /json endpoint (used for updating the Devices overview page) will include any Derived values as defined. See the TaskValueSetDerived and TaskValueSetPresentation commands.

  • Event & Log derived values: When checked, the Derived values will be generated as Events, to be handled in Rules, and sent to logging devices like the Syslog server and/or SD-card logging.

(The derived values options are only available if String variables feature is included in the build.)


  • Send to Controller: Select the Controller(s) to send the Values to, either on a TaskRun command applied to the task, or on an Interval time action.

Send to Controller is only visible when one or more Controllers are configured.

Depending on the controller capabilities, some configuration settings may be shown:

../_images/Task_config_page_Controllers_section.png

All configured Controllers are shown here, including the enabled or disabled state (multiple Controllers can be enabled, only a single MQTT Controller can be enabled at one time!).

For each controller the user can select wether the data should be sent on each Interval (or explicit TaskRun).

For the Domoticz controllers the value index (IDX) has to be configured.

For some controllers, like Home Assistant/openHAB, there are extra options available.

  • Group: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default Group <n>, can be adjusted in Home Assistant. If the Group value matches the current Unit nr, the Unit name, %sysname%, is used instead of Group <nr>.

  • Retained: For MQTT Controllers, this setting can be enabled to send the values for the current task with the Retain flag set. The Publish Retain flag in the Controller settings will override this by sending all task values with Retain flag enabled.

  • Send derived: This checkbox determines if any configured Derived values should also be sent to the controller (and included in the AutoDiscovery if that’s available and enabled).

  • Resend MQTT Discovery: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any changed settings will be updated in the MQTT broker. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.

Other controllers, like f.e. FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.


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.