[P157] Add plugin for 14-segment displays (HT16K33)

docs/source/Plugin/P157.rst

@@ -0,0 +1,221 @@
+.. include:: ../Plugin/_plugin_substitutions_p15x.repl
+.. _P157_page:
+
+|P157_typename|
+==================================================
+
+|P157_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P157_type|
+
+Name: |P157_name|
+
+Status ESP32: |P157_status|
+
+Status ESP8266: |P157_status_lb|
+
+GitHub: |P157_github|_
+
+Maintainer: |P157_maintainer|
+
+Used libraries: |P157_usedlibraries|
+
+Description
+-----------
+
+The 14-/7-segment display plugin allows to display date, time, temperatures, numbers, text and self-created shapes on 14 segment LED displays, also supporting 7-segment displays, using a HT16K33 I2C driver.
+
+Up to 8 displays can be combined, and as these displays are available with 4 and 8 digits, up to 64 characters can be shown from a single plugin instance.
+
+For 14-segment displays a single font is available, and for 7-segment displays the 3 fonts available in P073 (when also included in the build) can be selected for presenting text on the display, where the character shapes are somewhat different.
+
+When text to be displayed can't fit on the width of the display, scrolling text can be used so longer messages are shown like a ticker-tape display. Scrolling is always from right to left, and optionally starts with an empty display, so text can be read as it scrolls in.
+
+Periods, comma's, colons and semicolons in text are always shown on the dots of the display, when available (all 14-segment, and most 7-segment, HT16K33 displays have a dot per digit).
+
+For temperature display commands, ``7dt,<temp>`` and ``7ddt,<temp1>,<temp2>``, the degree symbol after the temperature can be turned off so there's room for 1 more digit of temperature on the display.
+
+Hardware
+^^^^^^^^
+
+Most available 14-segment display units have 4 digits:
+
+.. image:: P157_ht16k33-4-dgt-module.png
+
+When multiple modules are combined to form a single display, the adjacent modules must get consecutive addresses, and placed from left to right with low to high addresses. The address for each unit (0x70 .. 0x77) is adjusted by adding a connection on the A0/A1/A2 solder bridges at the backside of the module. All 3 bridges open is address 0x70:
+
+.. image:: P157_ht16k33-address.png
+
+To make the A0/A1/A2 addressing of the modules explicit:
+
++---------+-------------------+
+| address | A0/A1/A2          |
++=========+===================+
+| 0x70    | all open          |
++---------+-------------------+
+| 0x71    | A0 closed         |
++---------+-------------------+
+| 0x72    | A1 closed         |
++---------+-------------------+
+| 0x73    | A0, A1 closed     |
++---------+-------------------+
+| 0x74    | A2 closed         |
++---------+-------------------+
+| 0x75    | A0, A2 closed     |
++---------+-------------------+
+| 0x76    | A1, A2 closed     |
++---------+-------------------+
+| 0x77    | A0, A1, A2 closed |
++---------+-------------------+
+
+
+Wiring
+~~~~~~
+
+Wiring multiple modules is as simple as connecting the ``Vi2c``, ``VCC``, ``GND``, ``SDA`` and ``SCL`` of all modules in parallel, and connect ``Vi2c`` to ``3V3``, ``VCC`` to ``5V``, ``GND`` to ``GND`` at the ESP, and ``SDA`` and ``SCL`` to the configured I2C pins of the ESP. The modules using red LEDs will usually work at a VCC of 3V3, but connecting more than 1 module to the 3V3 of the ESP will overload the 3V3 regulator, installed on the ESP board. This split power pinout design makes it very easy to connect these modules, as no level-converter is needed to protect the GPIO pins of the ESP.
+
+.. image:: P157_ht16k33-pinout.png
+
+When connecting more than 4 modules to the same ESP, it's best to **not** connect ``Vi2c`` to more than 4 modules, as each module comes with its own pair of 10k pull-up resistors, and having too many of these in parallel will result in a too low value, causing possible display errors.
+
+Configuration
+^^^^^^^^^^^^^^
+
+.. image:: P157_DeviceConfiguration.png
+
+* **Name**: In the Name field a unique name should be entered.
+
+* **Enabled**: When unchecked the plugin is not enabled.
+
+I2C options
+^^^^^^^^^^^
+
+* **I2C Address**: Select the address the chip is set for, available options:
+
+.. image:: P157_I2CAddressOptions.png
+
+The available settings here depend on the build and hardware configuration used. At least the **Force Slow I2C speed** option is available, but selections for the I2C Multiplexer can also be shown. For details see the :ref:`i2c-bus` page
+
+
+
+Device Settings
+~~~~~~~~~~~~~~~
+
+* **Display Type**: Select the type of display that's connected:
+
+.. image:: P157_DisplayTypeOptions.png
+
+* **Nr. of digits**: Up to 8 displays can be connected on the same I2C bus, or when using a multiplexer on the multiplexer channel.
+
+If a longer than the default size display is needed, multiple displays of the same type can be combined. They must have incremental I2C addresses.
+
+When multiple displays are connected, but the content must be set independent, multiple tasks can be configured, using the I2C address of the display for the next task.
+
+* **Display Output**: Here the type of output can be selected:
+
+.. image:: P157_DisplayOutputOptions.png
+
+*Manual*: The content can be set from rules by using the commands available (see below)
+
+*Clock 24h - Blink*: Displays the current time in 24h format, with a blinking colon or dot.
+
+*Clock 24h - No Blink*: Displays the current time in 24h format.
+
+*Clock 12h - Blink*: Displays the current time in 12h format, with a blinking colon or dot.
+
+*Clock 12h - No Blink*: Displays the current time in 12h format.
+
+*Date*: Displays the current date.
+
+*NB: Clock and Date outputs assume a time-source is available, f.e. the via NTP or External Time Source settings in Tools/Advanced, by connecting a GPS module, or via the ESPEasy P2P network.*
+
+The Clock and Date outputs are updated every second, and the blinking selections are 1 second on then 1 second off.
+
+Clock formats are shown in HH.MM format on 4 digit displays, and in HH.MM.SS format on displays with 8 or more available digits. Date is shown in DD MM format on 4 digit displays, and DD MM YYYY format on 8 digit and wider displays.
+
+* **Brightness**: The brightness level of the display can be set here. 0 is 'Default' brightness, 1..15 from low to high brightness.
+
+* **Font set**: Select the font set from this list: (Only available for 7-segment displays, and when plugin :ref:`P073_page` is also included in the build)
+
+.. image:: P157_FontSetOptions.png
+
+*Default*: The standard font. 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 <https://fakoo.de/siekoo.html>`_ (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, they are somewhat better recognizable.
+
+*dSEG7*: the character set as documented here `Keshikan.net: dSEG7 <https://www.keshikan.net/fonts-e.html>`_ special characters: space, dash, degree (when using a ``^``), equal sign, slash, underscore and letters A..Z. (Again single-case, like the default font)
+
+**Siekoo**:
+
+.. image:: P073_SiekooSet.png
+
+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**:
+
+.. image:: P073_dSEG7Set.png
+
+The ``^`` character is again used to display the degree symbol, and the degree symbol is not recognized!
+
+Options
+^^^^^^^
+
+* **Hide ° for Temperatures**: Will leave out the degree symbol from the display for temperature commands ``7dt,<temp>`` (and ``7ddt,<temp1>,<temp2>`` when available), allowing 1 more digit for actual temperature display.
+
+* **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. (Not available in all builds for size reasons)
+
+* **Scroll text > display width**: Normally the ``7dtext,<text>`` and ``7dbin,...`` commands only show the left n characters the display can hold. This option enables the Scroll Text feature, that will scroll text sent using the ``7dtext`` command (or ``7dbin`` command when available) 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.
+
+(The Scroll options and feature are not included in some builds for size reasons)
+
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P157_commands.repl
+
+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).
+
+14-segment
+~~~~~~~~~~
+
+.. image:: P157_14-segment-dp-map.png
+
+The mapping from bits to segments is ``0B(dp)ponmlkhgfedcba`` where the decimal point only takes 1 bit, of course
+
+7-segment
+~~~~~~~~~
+
+.. image:: P073_7Segments.png
+
+The mapping from bits to segments is: ``0Bhgfedcba``
+
+
+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 14-segment digit can be done by the command ``7dbin,0b11001001`` or ``7dbin,0b01001001`` for a 7-segment digit. This can also be entered in hexadecimal notation: ``7dbin,0xC9`` (14 segment) or ``7dbin,0x49`` (7-segment).
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added| 2026-05-24: Initial release version.
+
+
+
+
+

docs/source/Plugin/P157_commands.repl

@@ -0,0 +1,129 @@
+.. csv-table::
+        :header: "Command", "Extra information"
+        :widths: 20, 30
+
+        "
+        ``7dn,<number>``
+
+        Example:
+
+        ``7dn,[BME280#Humidity]`` to display the humidity measured by a BME280 sensor.
+
+        ","
+        Displays a numeric value on the display, with 1 decimal.
+        "
+        "
+        ``7dt,<temperature>``
+
+        Example:
+
+        ``7dt,[BME280#Temperature]``
+
+        ","
+        To display the temperature measured by a BME280 sensor. By default includes a ° symbol, unless option 'Hide ° for Temperatures' is enabled.
+        "
+        "
+        ``7ddt,<temperature1>,<temperature2>``
+
+        Example:
+
+        ``7ddt,[BME280#Temperature],[DS18b20#Temperature]``
+
+        ","
+        To display two temperatures measured, f.e. by a BME280 sensor and a DS18b20 sensor. Applicable for 8 digit or wider displays.
+        "
+        "
+        ``7dst,<hh>,<mm>,<ss>``
+
+        Example:
+
+        ``7dst,%syshour%+6,%sysmin%,%syssec%``
+
+        ","
+        To display the time, f.e. for a different time zone.
+
+        Can also be used to set a next appointment time externally.
+        "
+        "
+        ``7dsd,<dd>,<mm>,<yy>``
+
+        ","
+        To display a date.
+        "
+        "
+        ``7dtext,<text>``
+
+        Examples:
+
+        ``7dtext,OUT [BLK#Temperature#d2.1]^``
+
+        ``7dtext,HU. [BLK#Humidity#d2.1]^o`` Will result in 'HU. 57.2°o' being displayed (8 digit or wider display)
+        ","
+        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.
+        "
+        "
+        ``7dfont,<font>``
+
+        ","
+        Select a different font, either by name: ``Default`` or ``7dgt`` for the original font (0), ``Siekoo`` for standard Siekoo font (1), ``Siekoo_Upper`` for the Siekoo font with uppercase 'CHNORUX' characters (2), and ``dSEG7`` for the dSEG7 font (3). Numbers can also be used, 0, 1, 2, or 3 as noted. Fontnames are not case-sensitive.
+
+        Only applicable when a 7-segment **Display Type** is selected.
+        "
+        "
+        ``7dbin,[<byte>,|'<quoted text>']...``
+
+        Example:
+
+        ``7dbin,0x40,0x20,0x10,0x08,0x04,0x02,0x01,0x80`` (7-segment Display Type)
+
+        ``7dbin,'ESPEasy is fun! and costs 0.00 ',2441,'uro'`` (14-segment Display Type, using the € sign)
+        ","
+        To display any bit pattern on the display.
+
+        The example shows each digit with a different segment on, including the dot/colon, and assuming Scroll Text enabled.
+
+        See explanation on how the bits map to segments, below.
+        "
+        "
+        ``7don``
+
+        ","
+        Turn the display on.
+        "
+        "
+        ``7doff``
+
+        ","
+        Turn the display off.
+        "
+        "
+        ``7db,<0..15>``
+
+        ","
+        Set the brightness to the provided level.
+        "
+        "
+        ``7output,<0..5>``
+
+        ","
+        Change the Display Output setting, available options:
+
+        * 0 - Manual
+        * 1 - Clock 24h - Blink
+        * 2 - Clock 24h - No Blink
+        * 3 - Clock 12h - Blink
+        * 4 - Clock 12h - No Blink
+        * 5 - Date
+        "
+        "
+        ``7digit,<dgt>,<char/text>``
+
+        ","
+        Write content to a specific digit, or range of digits up to the end of the display (no scrolling supported)
+
+        ``7digit,8,C.`` : Write a C with a period attached to digit 8 of the display (assuming it has at least 8 digits available).
+
+        ``7digit,-4,0b110110`` : Write a bitmap (``||`` used here), similar to ``7dbin`` command, to a digit (the ``abs(dgt)`` value is used).
+        "

docs/source/Plugin/_Plugin.rst

@@ -492,6 +492,7 @@ There are different released versions of ESP Easy:
    ":ref:`P152_page`","|P152_status|","|P152_status_lb|","P152"
    ":ref:`P153_page`","|P153_status|","|P153_status_lb|","P153"
    ":ref:`P154_page`","|P154_status|","|P154_status_lb|","P154"
+   ":ref:`P157_page`","|P157_status|","|P157_status_lb|","P157"
    ":ref:`P159_page`","|P159_status|","|P159_status_lb|","P159"
    ":ref:`P162_page`","|P162_status|","|P162_status_lb|","P162"
    ":ref:`P163_page`","|P163_status|","|P163_status_lb|","P163"

docs/source/Plugin/_plugin_categories.repl

@@ -2,7 +2,7 @@
 .. |Plugin_Acceleration| replace:: :ref:`P120_page`, :ref:`P125_page`
 .. |Plugin_Color| replace:: :ref:`P112_page`
 .. |Plugin_Communication| replace:: :ref:`P016_page`, :ref:`P020_page`, :ref:`P035_page`, :ref:`P044_page`, :ref:`P054_page`, :ref:`P071_page`, :ref:`P087_page`, :ref:`P089_page`, :ref:`P094_page`, :ref:`P101_page`, :ref:`P118_page`, :ref:`P176_page`
-.. |Plugin_Display| replace:: :ref:`P012_page`, :ref:`P023_page`, :ref:`P036_page`, :ref:`P057_page`, :ref:`P073_page`, :ref:`P075_page`, :ref:`P095_page`, :ref:`P104_page`, :ref:`P116_page`, :ref:`P131_page`, :ref:`P148_page`
+.. |Plugin_Display| replace:: :ref:`P012_page`, :ref:`P023_page`, :ref:`P036_page`, :ref:`P057_page`, :ref:`P073_page`, :ref:`P075_page`, :ref:`P095_page`, :ref:`P104_page`, :ref:`P116_page`, :ref:`P131_page`, :ref:`P148_page`, :ref:`P157_page`, :ref:`P165_page`
 .. |Plugin_Distance| replace:: :ref:`P013_page`, :ref:`P110_page`, :ref:`P113_page`, :ref:`P134_page`
 .. |Plugin_Dust| replace:: :ref:`P018_page`, :ref:`P053_page`, :ref:`P056_page`, :ref:`P144_page`, :ref:`P175_page`
 .. |Plugin_Energy_AC| replace:: :ref:`P076_page`, :ref:`P077_page`, :ref:`P078_page`, :ref:`P092_page`, :ref:`P102_page`, :ref:`P108_page`, :ref:`P176_page`

docs/source/Plugin/_plugin_substitutions_p05x.repl

@@ -96,9 +96,9 @@
 .. |P056_compileinfo| replace:: `.`
 .. |P056_usedlibraries| replace:: `.`
 
-.. |P057_name| replace:: :cyan:`HT16K33`
+.. |P057_name| replace:: :cyan:`HT16K33 4 digit clock/num`
 .. |P057_type| replace:: :cyan:`Display`
-.. |P057_typename| replace:: :cyan:`Display - HT16K33`
+.. |P057_typename| replace:: :cyan:`Display - HT16K33 4 digit clock/num`
 .. |P057_porttype| replace:: `.`
 .. |P057_status| replace:: :yellow:`DISPLAY` :yellow:`COLLECTION`
 .. |P057_status_lb| replace:: :yellow:`DISPLAY` :yellow:`COLLECTION`