Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-11-05 09:20:08 +01:00
Code Issues Projects Releases Wiki Activity
9420c45a01
esphome-docs/components/display/max7219.rst
Otto Winter f22ac1a550
Partially Revert make SPI CS pin optional (#706)
2020-07-25 14:24:02 +02:00

347 lines
15 KiB
ReStructuredText
Raw Blame History

MAX7219 7-Segment Display
=========================
.. seo::
:description: Instructions for setting up MAX7219 7-segment displays.
:image: max7219.jpg
The ``max7219`` display platform allows you to use MAX7219 7-segment display drivers (
`datasheet <https://datasheets.maximintegrated.com/en/ds/MAX7219-MAX7221.pdf>`__,
`hobbycomponents <https://hobbycomponents.com/displays/597-max7219-8-digit-seven-segment-display-module>`__)
with ESPHome. Please note that this integration is *only* for 7-segment display, not matrix configurations.
.. figure:: images/max7219-full.jpg
:align: center
:width: 75.0%
MAX7219 7-Segment Display.
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
CS to your set ``cs_pin`` and finally GND to GND.
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.
.. code-block:: yaml
# 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:
------------------------
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin you have the CS line hooked up to.
- **num_chips** (*Optional*, integer): The number of chips you wish to use for daisy chaining. Defaults to
``1``.
- **intensity** (*Optional*, integer): The intensity with which the MAX7219 should drive the outputs. Range is from
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.
.. _display-max7219_lambda:
Rendering Lambda
----------------
The MAX7219 has a similar API to the fully fledged :ref:`display-engine`, but it's only a subset as the MAX7219
7-segment displays don't have a concept of individual pixels. In the lambda you're passed a variable called ``it``
as with all other displays. In this case however, ``it`` is an MAX7219 instance (see API Reference).
The most basic operation with the MAX7219 is wiring a simple number to the screen as in the configuration example
at the top of this page. But even though you're passing in a string (here ``"01234567"``), ESPHome converts it
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");``.
Also note that the ``.`` (dot) character is special because when ESPHome encounters it in the string the dot
segment of the previous position will be enabled.
.. code-block:: yaml
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)
it.printf(3, "%.1f", id(my_sensor).state);
// 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
it.printf("SENS%4.0f", id(my_sensor).state);
// Result: "SENS 42"
// Print the current time
it.print(" ");
it.strftime("%H.%M.%S");
// Result for 10:06:42 -> "10.06.42 "
// Change the display intnsity based on another id.
// Value should be from 0-15.
it.set_intensity(id(my_brightness));
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:
All 7-Segment Characters
------------------------
============================== ==============================
**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| ``_``
------------------------------ ------------------------------
|max721909| ``=``
------------------------------ ------------------------------
|max721906| ``|``
------------------------------ ------------------------------
|max72190D| ``c``
------------------------------ ------------------------------
|max721917| ``h``
------------------------------ ------------------------------
|max72191D| ``o``
------------------------------ ------------------------------
|max72191C| ``u``, ``v``
------------------------------ ------------------------------
|max72198E| ``~``
============================== ==============================
.. |max721900| image:: images/max7219/seg00.svg
:class: component-image
.. |max721980| image:: images/max7219/seg80.svg
:class: component-image
.. |max7219B0| image:: images/max7219/segB0.svg
:class: component-image
.. |max72197E| image:: images/max7219/seg7E.svg
:class: component-image
.. |max721930| image:: images/max7219/seg30.svg
:class: component-image
.. |max72196D| image:: images/max7219/seg6D.svg
:class: component-image
.. |max721979| image:: images/max7219/seg79.svg
:class: component-image
.. |max721933| image:: images/max7219/seg33.svg
:class: component-image
.. |max72195B| image:: images/max7219/seg5B.svg
:class: component-image
.. |max72195F| image:: images/max7219/seg5F.svg
:class: component-image
.. |max721970| image:: images/max7219/seg70.svg
:class: component-image
.. |max72197F| image:: images/max7219/seg7F.svg
:class: component-image
.. |max721973| image:: images/max7219/seg73.svg
:class: component-image
.. |max721937| image:: images/max7219/seg37.svg
:class: component-image
.. |max72194E| image:: images/max7219/seg4E.svg
:class: component-image
.. |max721931| image:: images/max7219/seg31.svg
:class: component-image
.. |max721978| image:: images/max7219/seg78.svg
:class: component-image
.. |max721907| image:: images/max7219/seg07.svg
:class: component-image
.. |max721920| image:: images/max7219/seg20.svg
:class: component-image
.. |max721902| image:: images/max7219/seg02.svg
:class: component-image
.. |max721922| image:: images/max7219/seg22.svg
:class: component-image
.. |max72196F| image:: images/max7219/seg6F.svg
:class: component-image
.. |max721965| image:: images/max7219/seg65.svg
:class: component-image
.. |max721910| image:: images/max7219/seg10.svg
:class: component-image
.. |max721949| image:: images/max7219/seg49.svg
:class: component-image
.. |max721940| image:: images/max7219/seg40.svg
:class: component-image
.. |max721948| image:: images/max7219/seg48.svg
:class: component-image
.. |max721958| image:: images/max7219/seg58.svg
:class: component-image
.. |max721977| image:: images/max7219/seg77.svg
:class: component-image
.. |max72191F| image:: images/max7219/seg1F.svg
:class: component-image
.. |max72193D| image:: images/max7219/seg3D.svg
:class: component-image
.. |max72194F| image:: images/max7219/seg4F.svg
:class: component-image
.. |max721947| image:: images/max7219/seg47.svg
:class: component-image
.. |max72195E| image:: images/max7219/seg5E.svg
:class: component-image
.. |max72193C| image:: images/max7219/seg3C.svg
:class: component-image
.. |max72190E| image:: images/max7219/seg0E.svg
:class: component-image
.. |max721915| image:: images/max7219/seg15.svg
:class: component-image
.. |max721967| image:: images/max7219/seg67.svg
:class: component-image
.. |max7219FE| image:: images/max7219/segFE.svg
:class: component-image
.. |max721905| image:: images/max7219/seg05.svg
:class: component-image
.. |max72193E| image:: images/max7219/seg3E.svg
:class: component-image
.. |max72193F| image:: images/max7219/seg3F.svg
:class: component-image
.. |max721927| image:: images/max7219/seg27.svg
:class: component-image
.. |max721901| image:: images/max7219/seg01.svg
:class: component-image
.. |max721908| image:: images/max7219/seg08.svg
:class: component-image
.. |max721909| image:: images/max7219/seg09.svg
:class: component-image
.. |max721906| image:: images/max7219/seg06.svg
:class: component-image
.. |max72190D| image:: images/max7219/seg0D.svg
:class: component-image
.. |max721917| image:: images/max7219/seg17.svg
:class: component-image
.. |max72191D| image:: images/max7219/seg1D.svg
:class: component-image
.. |max72191C| image:: images/max7219/seg1C.svg
:class: component-image
.. |max72198E| image:: images/max7219/seg8E.svg
:class: component-image
.. note::
Original 7-segment display base image taken from Wikipedia at https://de.wikipedia.org/wiki/Datei:7_Segment_Display.svg
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`
- :apiref:`max7219/max7219.h`
- `MAX7219 Library <https://github.com/nickgammon/MAX7219>`__ by `Nick Gammon <https://github.com/nickgammon>`__
- :ghedit:`Edit`
Reference in New Issue View Git Blame Copy Permalink