Display - NeoPixel (7-Segment)¶
NeoPixel 7-Segment display
Plugin details¶
Type: Display
Name: NeoPixel (7-Segment)
Status ESP32: NEOPIXEL
Status ESP8266: NEOPIXEL
GitHub: P165_7SegNeopixel.ino
Maintainer: tonhuisman
Used libraries: Noiasca NeopixelDisplay (modified)
Description¶
NeoPixels are very versatile, multi-color led pixels, that can be used in a lot of situations, and only need a single GPIO to be able to control multiple leds as they are connected sequentially.
This plugin offers multiple layout 7-sement displays, for use as clock, score-board, news-ticker etc.
Configurations can have from 1..7 pixels per segment, and up to 15 extra pixels, that can f.e. be used as a time-colon. Options for initial, unused, pixels and several settings for generating the number-plan, for connecting the pixels in the correct order and position, are available.
The minimum size for a display would have 1 digit, starting from 7 pixels with 1 pixel per segment and no decimal point, and the max. configuration possible has 16 digits, split in 4 groups that can be addressed as a single display or per group, with up to 1100 pixels, though that may have issues as that number of pixels hasn’t been tested. Technically, larger displays are possible, but that might cause even more (signal-timing) issues because of the huge number of pixels needed.
Hardware¶
Most of the work is probably spent in mounting the pixels in a panel or casing, so experimenting with layouts may be helpful in finding the optimal configuration, as f.e. changing the number of pixels per segment, decimal point or extra pixels later can be a lot of work.
Signal wiring¶
Note
If the strips use a VCC higher than 3.3V, f.e. 5V (and they usually do), a level converter for 3V3 to 5V should be used when connecting the display to the ESP, as the ESP might be damaged, or the logic levels don’t match the requirements of the display (high level ~70% of VCC = 3.5V @ VCC 5V), and may not work properly.
ESP Level converter 5V Strip 1 5V Strip 2 5V Strip n
---- --------------- | ----------- | ----------- | -----------
3V3 --> LV HV <-+-> VCC +-> VCC +-> VCC ...
GND --- GND ------- GND --- GND - GND --- GND - GND --- GND ...
GPIO --> LV1 ------> HV1 -[470]- DIN - DOUT --> DIN - DOUT --> DIN ...
NB: It is advised to use a single 220 to 470 ohm resistor in the wiring from ESP (after the level converter) to the first strip Din for better signal stability.
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.
Also, when using several strips sequentially, separate wiring should be added for VCC and GND to each strip (or group of strips), to avoid burning out the pcb traces of the strip where the power is connected. For a group of strips of 100 to 150 LEDs, it is advised to use separate wiring for power to each group, and only connect the GND and signal connections Dout/GND to Din/GND of the next group, but never the VCC pins.
Configuration¶
Name: Required by ESPEasy, must be unique among the list of available devices/tasks.
Enabled: The device can be disabled or enabled. When not enabled the device should not use any resources.
Actuator¶
GPIO -> Strip: Select the GPIO pin where the NeoPixel strip will be connected. This has to be a pin that allows output (not input-only).
Device Settings¶
Strip Type: Select the type of the LEDs mounted on the strip:
GRB : Most commonly, the LEDs are of GRB type.
GRBW : If the LEDs also support Brightness control, then the GRBW type should be selected.
Initial brightness: The brightness that the display is initially set to. Default is 40, to protect both the eyes and the power-supply powering the display. Range: 0..255.
Maximum allowed brightness: The brightness that is the maximum it can be set to, either from UI or via the
7dbcommand, to optionally help protect both the eyes and the power-supply powering the display. Default is 255. Range: 1..255.Font set: Select the font set from this list: (These fonts are the same fonts as available in Display - 7-segment display)
Default: The original font as initially included in plugin P073. Includes digits 0..9, special characters: space, dash, degree (when using a ^), equal sign, slash, underscore and letters A..Z. Uppercase and lowercase characters are shown exactly the same, but as the possible shapes are quite limited, some can be somewhat hard to recognize at first.
Siekoo: The character set as documented here Fakoo.de: Siekoo alphabet (See below for the extra special characters supported)
Siekoo with uppercase ‘CHNORUX’: This font is the same as the normal Siekoo character set, but supports uppercase versions for characters ‘CHNORUX’, even though they duplicate other characters in the set.
dSEG7: the character set as documented here Keshikan.net: dSEG7 special characters: space, dash, degree (when using a ^), equal sign, slash, underscore and letters A..Z. (Again single-case, like the default font)
If the Font set configuration option is not available, then a different font layout, default from the used library, is used.
Siekoo:
The four marked characters, Ä, Ö, Ü and ß, are not included, as they can not reliably be sent to the unit because of conversion issues from ASCII/UTF-8/ISO charactersets. And they are possibly not often used, except in German, and some closely related, languages.
dSEG7:
The ^ character is again used to display the degree symbol, and the degree symbol is not recognized!
Note
By default, any periods used in tekst to be displayed by the plugin will be placed at the previous digit decimal point position and removed from the text, regardless of a decimal point is defined for the digit! When non of the groups has decimal dot pixels defined then this feature will be disabled, and the dot/period character defined in the font will be used.
Options¶
Suppress leading 0 on day/hour: When enabled, will show the hours of the time and days of the date without a leading 0 when < 10.
Use decimal dot for blink: When enabled will use the decimal dot on the second digit (with offset accounted for) for blinking, when no extra pixels are available.
Scroll text > display width: Normally the
7dtext,<text>command only show the left n characters the display can hold. This option enables the Scroll Text feature, that will scroll text sent using the7dtextor7dbincommands from right to left when the content is longer than the display can show at once.Scroll text in from right: Normally the Scroll Text feature starts with the display filled with the left part of the text to scroll, with this option enabled, the display starts empty and the text is scrolled in from the right side of the display to the left, until all text is scrolled off. Then the scrolling restarts.
Scroll speed (0.1 sec/step): Determines the speed of scrolling the text. Default value is 10, so 1 character per second.
Clear display on exit When checked, will clear the display when the task is disabled, either from settings or via the
TaskDisablecommand. This will fill the strip with black pixels, turning all NeoPixels off.
Display¶
Note
Some field-labels show an asterisk * as the last character, to indicate that when a different option is selected on these fields, the current settings are stored and the page is reloaded, so the changed configuration will reflect in the page.
Number of Groups *: Select the number of digit-groups to use. With current configuration, extra pixels can only be applied at the end of a group, so if f.e. a time display is to be made with a colon between the hours and minutes (that can optionally blink every other second), 2 groups should be defined, 1 with 2 digits and extra pixels, and a second with 2 digits only. The max. number of groups is 4, for settings-technical reasons.
Foreground color
Background color
These are the default colors, used to display the content.
Colors can be specified in 3 ways:
Color name Some named colors are recognized: White, Black, Red, Green, Blue, Yellow, Orange, Navy, Darkgreen, Cyan, Darkcyan, Maroon, Purple, Olive, Magenta, Lightgrey, Darkgrey, Pink and Greenyellow. If any of these colors is recognized, the name will be shown.
#RGB565 A
#prefixed, 1 to 4 digit, hex-coded color value in RGB565 format (5 bits red, 6 bits green, 5 bits blue) giving the max. number of 65535 colors. This is the value that is shown after the settings are saved, and it is not one of the known color names.#RRGGBB A
#prefixed, 6 digit, hex coded RGB color value. Will be transformed to an RGB565 value on save!Show Pixel number-plan *: When changed to Yes, the digit preview display will change from showing pixels, to showing the number-index of each pixel as wired in the strip. This also blocks changing any of the digit options below (calculation of the number-plan is not implemented in the front-end Javascript code).
Groups and Digits¶
This section shows 1 to 4 groups of digit configurations, depending on the Number of Groups selection. All groups have the exact same settings options.
The group-order is reverted (4..1) if all groups have the Right to Left digits option enabled.
These options determine the layout of the digits:
Number of Digits *: Select the number of digits in this group. Currently limited to 4.
Segment Width pixels: The number of pixels to use in the horizontal segments, range 1..7.
Segment Height pixels: The number of pixels to use in the vertical segments, range 1..7.
Segment Corners overlap: When enabled, 6 extra pixels, where the segments (can) overlap, will be added. These pixels will light up if either of the segments it belongs to is lit.
Decimal dot pixels: The number of pixels to use for a decimal point, to the lower-right of each digit, range 0..7.
Extra pixels after: The number of pixels to be used, either as a ‘bridge’ to the next digit, or as an optional colon or other shape, that will light up when using a time or date display output, and can also be controlled via the
7dextracommand.Pixels in group: A read-only field that shows the currently needed number of pixels in this group. This will be updated dynamically when any of the above settings is changed.
These options determine the number-plan of the pixels in this group:
Pixel-offset before: The number of pixels to skip before the first digit is planned. Sometimes used to ‘fix’ the signal level for the pixels if the strip is connected to the ESP without a level converter, but that’s an unreliable fix, so a level converter should best be used when powering the pixels with the ‘suggested’ (strongly advised) 5V. These pixels can also be used as an extra indicator, as the
7dbeforecommand can be used to set these pixels to a color.Starting segment: By default the number-plan starts at the left pixel of the top segment (a) of a digit, and flows clock-wise along all pixels for a single digit. With this setting you can select to start at the top of the top-right segment (b) or the left of the center-segment (g), when assigning the number-plan. (See remark when using counter-clockwise option, below.)
a (top): The default starting segment.
b/f (right/left): For the default clockwise numbering, the b-segment is the first segment to be numbered. Starting point is the f-segment when Numbering counter-clockwise is enabled.
g (center): This is a very optimal numbering plan, as the segment-order is g, c, dp, d, e, f, a, b, and as it ends at the b-segment the next digit can easily be coupled to this one. When this option is selected, the Split g-segment pixels and Decimal dot last segment options are disabled (and ignored), as they don’t make sense to be used.
Split g-segment pixels: The default number-plan assigns pixel-indexes to the g-segment between the e and f segment. When using a larger number of Width pixels, wiring the g-segment can be challenging. When enabled, this option assigns pixel-indexes to the right-half set of pixels between the b and c segment, and the remaining pixels between the e and f segment.
Decimal dot last segment: Similar to the g-segment, also the dp-segment can be challening to wire, as by default the f-segment is assigned the last pixel-index. So the default here is to assign pixel-indexes to the dp-segment between the c and d-segments. If you explicitly want to have these dp-pixels assigned as the last pixel-indexes, this option can be enabled.
Numbering counter-clockwise: By default the pixel-indexes are assigned in a clock-wise order, but if your wiring-plan works better when numbering counter-clockwise, this is the setting to enable. This also changes how the Starting pixel is interpreted: Top-left will start from the f-segment, and end with the a-segment, and top-right will start assigning pixel-indexes from the right side of the a-segment, and work down the f, g, e, d, dp, c and b segments. When this option is used with the Starting segment set to g (center), also the Right to left digits option should best be enabled too, for most optimal result
Right to Left digits: When creating larger displays, or building a 2 1/2 or 3 1/2 digit display for displaying f.e. numbers up to 100 or 1000, starting the digits at the left is not efficient, as the entire left digit will get pixel-indexes assigned. When using the Right to Left digits option, the digits will be virtually reverted, and pixel-indexes assigned from the right digit to the left digit. The extra pixels, not needed to show anything else than
1can be left out of the display. An example config is included below, showing this.
Total digits: Shows the number of digits, as currently configured.
Total pixels to connect: Shows the number of pixels to connect, as currently configured. If building a 3 1/2 or 2 1/2 digit display, the excess pixels of the left most digit can be manually subtracted.
Commands available¶
Command Syntax |
Extra information |
|---|---|
|
Turn the display on, if it was turned off before using the |
|
Turn the display off, can later be turned on again by using the |
|
Changes the Initial brightness config setting, and the brightness of the strip. The setting is not saved unless the |
|
Change the Display Output setting, available options:
|
|
Select a different font, either by name: |
Examples:
|
To display a text on the display. Any variable can be used. Unsupported characters (like accented letters) will show as a space (empty digit). With the Scroll Text option disabled, the first n characters the display can show are displayed, if the Scroll Text option is enabled, longer texts will scroll from right to left across the display, at the set speed. |
|
Draw a single character in the exact group & digit. When followed by a period, the decimal point will also be used. |
Example:
|
To display any bit pattern on the display. The example shows each digit with a different segment on, including the dot/colon, and assuming an 8 digit configuration, or Scroll Text enabled. See explanation on how the bits map to segments, below. |
|
Set the default group any command should be applied to. Group 0 is the entire display, and the default. |
|
Set the foreground, and/or background colors for the entire display. When a GRBW strip is configured, the brightness/white values have to be provided too. For only setting the background colors, leave out values for the foreground colors, but keep the commas. Color values can be in range 0..255. When group or digit colors are configured, then those will get priority. |
|
Set the foreground, and/or background colors for a specific digit of a group. When a GRBW strip is configured, the brightness/white values have to be provided too. For only setting the background colors, leave out values for the foreground colors, but keep the commas. Both <grp> (group) and <dgt> (digit) are required, and must be in range 1..<available groups/digits for that group>. Color values can be in range 0..255. To clear a digit color, to use the group or global defaults, provide Digit colors have highest priority. |
|
Set the foreground, and/or background colors for a all digits of a group. When a GRBW strip is configured, the brightness/white values have to be provided too. For only setting the background colors, leave out values for the foreground colors, but keep the commas. Group <grp> is required, and must be in range 1..<available groups>. Color values can be in range 0..255. To clear a group color, to use the global defaults, provide Group color will be overridden by a digit color, when set. |
|
Set the extra pixels after or before the digit On or Off, according to the state. The optionally supplied color will be used for the state. If not used, the the global background color will be used for Off, and the global foreground color for On. State:
|
Bit to segment mapping for 7dbin command¶
The 7dbin command allows to show any combination of segments on the display according to a (sequence of) bit pattern(s).
The mapping from bits to segments is: 0Bhabcdefg (Similar to the segment mapping used by Display - 7-segment display)
ESPEasy allows decimal, hexadecimal and binary notation for numbers. This makes creating the desired display pattern easy when using the binary notation (starting with 0B or 0b).
Switching on all horizontal segments for a digit can be done by the command 7dbin,0b01001001, or in hexadecimal notation: 7dbin,0x49
Example configurations¶
Example 1¶
For displaying the time in a 24 hour format, and an optionally blinking colon as the hours/minutes separator, you can define this Group/Digit setup:
This defines 2 Groups of each 2 Digits. The height and width of the segments can be configured as preferred, this example uses 3 pixels for both. When using more pixels per segment, like 5, 6 or 7, it is probably better to define a larger decimal point, if that is to be used, 3 seems appropriate in that case, and also the extra pixels, used to add the colon separator, could have 4 to 8 pixels to get a matching size with the large segments.
The number-plan for this layout is presented like this:
Example 2¶
For displaying the time in a 12 hour format, and an optionally blinking colon as the hours/minutes separator, you can define this Group/Digit setup:
The option to suppress the leading 0 on day/hour option is enabled now, so the left-most digit will be empty most of the time.
We have defined 2 Groups of each 2 Digits, but effectively use only 3 1/2 digit. The height and width of the segments can be configured as preferred, this example uses 3 pixels for both. When using more pixels per segment, like 5, 6 or 7, it is probably better to define a larger decimal point, if that is to be used, 3 seems appropriate in that case, and also the extra pixels, used to add the colon separator, could have 4 to 8 pixels to get a matching size with the large segments.
Note
This layout is presented in reverse order, as all groups use the Right to Left digits option. The actual positioning is still with Group 1 as the left-most group, and then using the numerically next group(s). This layout is needed to make the number-plan work from right to left.
The number-plan for this layout is presented like this:
The number-plan starts at the Right-Top pixel, instead of the Left-Top pixel, so the a-segment for the left-most digit can be excluded.
To save space and a few pixels, or create a larger display with a standard strip-length, the marked numbers (76..90) can be excluded from the build, as for a 12 hour clock the left-most digit is 0 most of the time, and that 0 is being suppressed, so no pixels will light up.
This shows an increased layout, using 4-pixel segments and a 4-pixel colon, that can be built from exactly 100 pixels, 2 50-pixel wired-pixelchains as available from EBay, Aliexpress etc.
Again, the marked pixels (101..120) can be excluded.
Example 3¶
For displaying a game score, with an indicator of the active player by using a half of the extra pixels, you can define this Group/Digit setup:
We have defined 2 Groups of each 2 Digits, and enabled the Corners Overlap option to have a more explicitly defined digit. The height and width of the segments can be configured as preferred, this example uses 3 pixels for both. When using more pixels per segment, like 5, 6 or 7, the extra pixels, used to add the left/right player indicator, could have 4 to 8 pixels to get a matching size with the large segments.
The number-plan for this layout is presented like this:
The number-plan starts at the Left-Top pixel.
For mounting the middle segment easier/more efficient, this segment can be split in a left and right half, by checking the Split g-segment pixels. The number-plan then looks like this:
The right half of the g-segment is placed between the b and c segments, and the left half of the g-segment between the e and f segments.
To control the player-indicator, the extra pixels 41 and 42 should be placed to indicate the digits from Group 1 being the active player score, and extra pixels 43 and 44 placed to indicate the digits from Group 2 for the other player.
These rules can be added to use 2 buttons (PlayerA and PlayerB) to select the active player:
On PlayerA#State=0 Do
7dextra,0,4 // Player B Off
7dextra,0,3 // Player A On
Endon
On PlayerB#State=0 Do
7dextra,0,2 // Player A Off
7dextra,0,5 // Player B On
Endon
Change log¶
Changed in version 2.0: …
added 2024-08-30 Initial release version.