2018-08-24 22:44:01 +02:00
MAX7219 7-Segment Display
2018-08-22 22:05:28 +02:00
=========================
2018-11-14 22:12:27 +01:00
.. seo ::
2019-02-07 13:54:45 +01:00
:description: Instructions for setting up MAX7219 7-segment displays.
2018-11-14 22:12:27 +01:00
:image: max7219.jpg
2019-02-27 18:32:47 +01:00
The `` max7219 `` display platform allows you to use MAX7219 7-segment display drivers (
`datasheet <https://datasheets.maximintegrated.com/en/ds/MAX7219-MAX7221.pdf> `__ ,
2018-08-22 22:05:28 +02:00
`hobbycomponents <https://hobbycomponents.com/displays/597-max7219-8-digit-seven-segment-display-module> `__ )
2019-02-16 23:25:23 +01:00
with ESPHome. Please note that this integration is *only* for 7-segment display, not matrix configurations.
2018-08-22 22:05:28 +02:00
.. figure :: images/max7219-full.jpg
:align: center
:width: 75.0%
2018-08-24 22:44:01 +02:00
MAX7219 7-Segment Display.
2018-08-22 22:05:28 +02:00
As the communication with the MAX7219 is done using SPI for this integration, you need
to have an :ref: `SPI bus <spi>` in your configuration with both the **mosi_pin** set (miso_pin is not required).
Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your `` mosi_pin `` and
2020-07-25 14:24:02 +02:00
CS to your set `` cs_pin `` and finally GND to GND.
2018-08-22 22:05:28 +02:00
You can even daisy-chain multiple MAX7219s by connecting the DOUT of the previous chip in the chain to the
next DIN. With more than ~3 chips the 3.3V will probably not be enough, so then you will have to potentially
use a logic level converted.
2018-11-19 18:32:16 +01:00
.. code-block :: yaml
2018-08-22 22:05:28 +02:00
# Example configuration entry
spi:
clk_pin: D0
mosi_pin: D1
display:
- platform: max7219
cs_pin: D2
num_chips: 1
lambda: |-
it.print("01234567");
Configuration variables:
------------------------
2020-07-25 14:24:02 +02:00
- **cs_pin** (**Required** , :ref: `Pin Schema <config-pin_schema>` ): The pin you have the CS line hooked up to.
2021-11-28 19:57:01 +01:00
- **num_chips** (*Optional* , int): The number of chips you wish to use for daisy chaining. Defaults to
2018-08-22 22:05:28 +02:00
`` 1 `` .
2021-11-28 19:57:01 +01:00
- **intensity** (*Optional* , int): The intensity with which the MAX7219 should drive the outputs. Range is from
2018-08-22 22:05:28 +02:00
0 (least intense) to 15 (the default).
- **lambda** (*Optional* , :ref: `lambda <config-lambda>` ): The lambda to use for rendering the content on the MAX7219.
See :ref: `display-max7219_lambda` for more information.
- **update_interval** (*Optional* , :ref: `config-time` ): The interval to re-draw the screen. Defaults to `` 1s `` .
- **spi_id** (*Optional* , :ref: `config-id` ): Manually specify the ID of the :ref: `SPI Component <spi>` if you want
to use multiple SPI buses.
- **id** (*Optional* , :ref: `config-id` ): Manually specify the ID used for code generation.
2021-07-28 23:56:11 +02:00
- **reverse_enable** (*Optional* , boolean): For some displays the order of the chips is reversed so you'll see "56781234" instead of "12345678". This option will adjust the output to compensate. Defaults to `` false `` .
2021-02-17 20:26:43 +01:00
2018-08-22 22:05:28 +02:00
.. _display-max7219_lambda:
Rendering Lambda
----------------
2019-02-07 13:54:45 +01:00
The MAX7219 has a similar API to the fully fledged :ref: `display-engine` , but it's only a subset as the MAX7219
2018-08-24 22:44:01 +02:00
7-segment displays don't have a concept of individual pixels. In the lambda you're passed a variable called `` it ``
2019-02-07 13:54:45 +01:00
as with all other displays. In this case however, `` it `` is an MAX7219 instance (see API Reference).
2018-08-22 22:05:28 +02:00
The most basic operation with the MAX7219 is wiring a simple number to the screen as in the configuration example
2019-02-16 23:25:23 +01:00
at the top of this page. But even though you're passing in a string (here `` "01234567" `` ), ESPHome converts it
2018-08-22 22:05:28 +02:00
into a representation that the MAX7219 can understand: The exact pixels that should be turned on. And of course,
not all characters can be represented. You can see a full list of characters :ref: `below <display-max7219_characters>` .
Each of the three methods (`` print `` , `` printf `` and `` strftime `` ) all optionally take a position argument at the
beginning which can be used to print the text at a specific position. This argument is `` 0 `` by default which
means the first character of the first MAX7219. For example to start the first character of your text at
the end of the first MAX7219, you would write `` it.print(7, "0"); `` .
2019-02-16 23:25:23 +01:00
Also note that the `` . `` (dot) character is special because when ESPHome encounters it in the string the dot
2018-08-22 22:05:28 +02:00
segment of the previous position will be enabled.
2018-11-19 18:32:16 +01:00
.. code-block :: yaml
2018-08-22 22:05:28 +02:00
display:
- platform: max7219
# ...
lambda: |-
// Print 0 at position 0 (left)
it.print("0");
// Result: "0 "
// Print 1 at position 1 (second character)
it.print(1, "1");
// Result: "01 "
// Let's write a sensor value (let's assume it's 42.1)
2018-10-20 14:53:27 +02:00
it.printf(3, "%.1f", id(my_sensor).state);
2018-08-22 22:05:28 +02:00
// Result: "01 42.1 " (the dot will appear on the "2" segment)
// Overwrite the previous content with blank
it.print(" ");
// Print a right-padded sensor value with 0 digits after the decimal
2018-10-20 14:53:27 +02:00
it.printf("SENS%4.0f", id(my_sensor).state);
2018-08-22 22:05:28 +02:00
// Result: "SENS 42"
// Print the current time
it.print(" ");
2023-04-19 16:27:50 +02:00
it.strftime("%H.%M.%S", id(esptime).now());
2018-08-22 22:05:28 +02:00
// Result for 10:06:42 -> "10.06.42 "
2020-05-02 01:04:52 +02:00
// Change the display intnsity based on another id.
// Value should be from 0-15.
it.set_intensity(id(my_brightness));
2018-08-22 22:05:28 +02:00
Please see :ref: `display-printf` for a quick introduction into the `` printf `` formatting rules and
:ref: `display-strftime` for an introduction into the `` strftime `` time formatting.
.. _display-max7219_characters:
2018-08-24 22:44:01 +02:00
All 7-Segment Characters
2018-08-22 22:05:28 +02:00
------------------------
2023-07-09 23:49:12 +02:00
.. raw :: html
<style>
/* dark theme * /
@media (prefers-color-scheme: dark) {
#all-7-segment-characters img {
background-color: #6b6b6b;
}
}
</style>
2019-02-14 16:19:07 +01:00
============================== ==============================
**MAX7219 Representation** **Character**
------------------------------ ------------------------------
|max721900| *(space)*
------------------------------ ------------------------------
|max721980| `` . ``
------------------------------ ------------------------------
|max7219B0| `` ! ``
------------------------------ ------------------------------
|max72197E| `` 0 `` , `` O ``
------------------------------ ------------------------------
|max721930| `` 1 `` , `` I ``
------------------------------ ------------------------------
|max72196D| `` 2 `` , `` Z ``
------------------------------ ------------------------------
|max721979| `` 3 ``
------------------------------ ------------------------------
|max721933| `` 4 ``
------------------------------ ------------------------------
|max72195B| `` 5 `` , `` S `` , `` s ``
------------------------------ ------------------------------
|max72195F| `` 6 ``
------------------------------ ------------------------------
|max721970| `` 7 ``
------------------------------ ------------------------------
|max72197F| `` 8 ``
------------------------------ ------------------------------
|max721973| `` 9 ``
------------------------------ ------------------------------
|max721937| `` H ``
------------------------------ ------------------------------
|max72194E| `` ( `` , `` [ `` , `` C ``
------------------------------ ------------------------------
|max721931| `` { ``
------------------------------ ------------------------------
|max721978| `` ) `` , `` ] ``
------------------------------ ------------------------------
|max721907| `` } `` , `` T `` , `` t ``
------------------------------ ------------------------------
|max721920| `` \ ` ``
------------------------------ ------------------------------
|max721902| `` ' ``
------------------------------ ------------------------------
|max721922| `` " ``
------------------------------ ------------------------------
|max72196F| `` @ ``
------------------------------ ------------------------------
|max721965| `` ? ``
------------------------------ ------------------------------
|max721910| `` , `` , `` i ``
------------------------------ ------------------------------
|max721949| `` % ``
------------------------------ ------------------------------
|max721940| `` * ``
------------------------------ ------------------------------
|max721948| `` : ``
------------------------------ ------------------------------
|max721958| `` ; ``
------------------------------ ------------------------------
|max721977| `` A `` , `` a ``
------------------------------ ------------------------------
|max72191F| `` B `` , `` b ``
------------------------------ ------------------------------
|max72193D| `` D `` , `` d ``
------------------------------ ------------------------------
|max72194F| `` E `` , `` e ``
------------------------------ ------------------------------
|max721947| `` F `` , `` f ``
------------------------------ ------------------------------
|max72195E| `` G `` , `` g ``
------------------------------ ------------------------------
|max72193C| `` J `` , `` j ``
------------------------------ ------------------------------
|max72190E| `` L `` , `` l ``
------------------------------ ------------------------------
|max721915| `` N `` , `` n ``
------------------------------ ------------------------------
|max721967| `` P `` , `` p ``
------------------------------ ------------------------------
|max7219FE| `` Q ``
------------------------------ ------------------------------
|max721905| `` R `` , `` r ``
------------------------------ ------------------------------
|max72193E| `` U `` , `` V ``
------------------------------ ------------------------------
|max72193F| `` W ``
------------------------------ ------------------------------
|max721927| `` Y `` , `` y ``
------------------------------ ------------------------------
|max721901| `` - ``
------------------------------ ------------------------------
|max721908| `` _ ``
------------------------------ ------------------------------
2020-03-02 23:54:28 +01:00
|max721909| `` = ``
------------------------------ ------------------------------
2019-02-14 16:19:07 +01:00
|max721906| `` | ``
------------------------------ ------------------------------
|max72190D| `` c ``
------------------------------ ------------------------------
|max721917| `` h ``
------------------------------ ------------------------------
|max72191D| `` o ``
------------------------------ ------------------------------
|max72191C| `` u `` , `` v ``
2020-01-12 15:18:34 +01:00
------------------------------ ------------------------------
|max72198E| `` ~ ``
2019-02-14 16:19:07 +01:00
============================== ==============================
2018-08-22 22:05:28 +02:00
.. |max721900| image :: images/max7219/seg00.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721980| image :: images/max7219/seg80.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max7219B0| image :: images/max7219/segB0.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72197E| image :: images/max7219/seg7E.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721930| image :: images/max7219/seg30.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72196D| image :: images/max7219/seg6D.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721979| image :: images/max7219/seg79.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721933| image :: images/max7219/seg33.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72195B| image :: images/max7219/seg5B.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72195F| image :: images/max7219/seg5F.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721970| image :: images/max7219/seg70.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72197F| image :: images/max7219/seg7F.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721973| image :: images/max7219/seg73.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721937| image :: images/max7219/seg37.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72194E| image :: images/max7219/seg4E.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721931| image :: images/max7219/seg31.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721978| image :: images/max7219/seg78.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721907| image :: images/max7219/seg07.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721920| image :: images/max7219/seg20.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721902| image :: images/max7219/seg02.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721922| image :: images/max7219/seg22.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72196F| image :: images/max7219/seg6F.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721965| image :: images/max7219/seg65.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721910| image :: images/max7219/seg10.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721949| image :: images/max7219/seg49.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721940| image :: images/max7219/seg40.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721948| image :: images/max7219/seg48.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721958| image :: images/max7219/seg58.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721977| image :: images/max7219/seg77.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72191F| image :: images/max7219/seg1F.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72193D| image :: images/max7219/seg3D.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72194F| image :: images/max7219/seg4F.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721947| image :: images/max7219/seg47.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72195E| image :: images/max7219/seg5E.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72193C| image :: images/max7219/seg3C.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72190E| image :: images/max7219/seg0E.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721915| image :: images/max7219/seg15.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721967| image :: images/max7219/seg67.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max7219FE| image :: images/max7219/segFE.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721905| image :: images/max7219/seg05.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72193E| image :: images/max7219/seg3E.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72193F| image :: images/max7219/seg3F.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721927| image :: images/max7219/seg27.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721901| image :: images/max7219/seg01.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721908| image :: images/max7219/seg08.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2020-03-02 23:54:28 +01:00
.. |max721909| image :: images/max7219/seg09.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721906| image :: images/max7219/seg06.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72190D| image :: images/max7219/seg0D.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max721917| image :: images/max7219/seg17.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72191D| image :: images/max7219/seg1D.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. |max72191C| image :: images/max7219/seg1C.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2020-01-12 15:18:34 +01:00
.. |max72198E| image :: images/max7219/seg8E.svg
2023-07-09 23:49:12 +02:00
:class: component-image segment
2018-08-22 22:05:28 +02:00
.. note ::
2018-08-24 22:44:01 +02:00
Original 7-segment display base image taken from Wikipedia at https://de.wikipedia.org/wiki/Datei:7_Segment_Display.svg
2018-08-22 22:05:28 +02:00
by user `h2g2bob <https://commons.wikimedia.org/wiki/User:H2g2bob> `__ under
`Creative Commons BY-SA 3.0 <https://creativecommons.org/licenses/by-sa/3.0/deed.de> `__ and modified
for this documentation.
See Also
--------
- :doc: `index`
2019-05-12 22:44:59 +02:00
- :apiref: `max7219/max7219.h`
2018-08-24 22:44:01 +02:00
- `MAX7219 Library <https://github.com/nickgammon/MAX7219> `__ by `Nick Gammon <https://github.com/nickgammon> `__
2019-02-07 13:54:45 +01:00
- :ghedit: `Edit`
