Max7219 new documentation (#585)
* updates * push last status docs on clen next * travis * Update max7219digit.rst Added updated scroll and rotate function to the manual * Update max7219digit.rst boolean -> integer * Update max7219digit.rst order list * Update max7219digit.rst * Update max7219digit.rst add note and warning * Update max7219digit.rst * Update max7219digit.rst * Update max7219digit.rst * Update max7219digit.rst * Update index.rst added max7219 dot matrix link * Add files via upload add image file for index.rst * Update max7219digit.rst EDIT Documentation due to change to ENUM and removed offset value * Update max7219digit.rst * Some formatting * Update max7219digit.rst * Some updates in formating * Update max7219digit.rst updated the invert block to match current code * Update max7219digit.rst Added some hidden commands to the end of the file * Update max7219digit.rst minor detail update * Update max7219digit.rst travis updates Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>
This commit is contained in:
rspaargaren
GitHub
parent
0cc24a4aff
commit
d8b50119c8
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
|
|
@ -0,0 +1,209 @@
|
|||
MAX7219 Digit Display
|
||||
=====================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up MAX7219 Digit displays.
|
||||
:image: max7219digit.png
|
||||
|
||||
The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this integration
|
||||
is *only* for the digit "matrix" display, for the 7 segment display see :doc:`max7219`.
|
||||
|
||||
.. figure:: images/max7219digit.png
|
||||
:align: center
|
||||
:width: 75.0%
|
||||
|
||||
MAX7219 Digit Display.
|
||||
|
||||
As the communication with the MAX7219 Digit 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: max7219digit
|
||||
cs_pin: D2
|
||||
num_chips: 4
|
||||
intensity: 15
|
||||
lambda: |-
|
||||
it.print(0, 0, id(digit_font), "HELLO!");
|
||||
|
||||
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
|
||||
``4``.
|
||||
- **rotate_chip** (*Optional*): Rotates every 8x8 chip. Valid values are ``0``, ``90``, ``180`` and ``270``.
|
||||
Defaults to ``0``.
|
||||
- **scroll_enable** (*Optional*, boolean): Turn scroll mode on when content does not fit. Defaults to ``True``.
|
||||
- **scroll_mode** (*Optional*): Set the scroll mode. One of ``CONTINUOUS`` or ``STOP``. Defaults to ``CONTINUOUS``
|
||||
|
||||
- ``CONTINUOUS``: Always scrolls and the text repeats continuously, you might need to add some
|
||||
separation at the end.
|
||||
- ``STOP``: When text is over it waits the ``scroll_dwell`` time and scroll is set back to the start.
|
||||
|
||||
- **scroll_speed** (*Optional*, :ref:`config-time`): Set scroll speed. Defaults to ``250ms``
|
||||
- **scroll_delay** (*Optional*, :ref:`config-time`): Set delay time before scroll starts. Defaults to ``1s``.
|
||||
- **scroll_dwell** (*Optional*, :ref:`config-time`): Sets the wait time at the end of the scroll before starting
|
||||
over. This is only used in mode ``STOP``. Defaults to ``1s``.
|
||||
- **intensity** (*Optional*, integer): The intensity with which the MAX7219 should drive the outputs. Range is
|
||||
from ``0``, least intense to ``15`` the brightest. Defaults to ``15``.
|
||||
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the
|
||||
MAX7219. See :ref:`display-max7219digit_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-max7219digit_lambda:
|
||||
|
||||
Rendering Lambda
|
||||
----------------
|
||||
|
||||
The MAX7219 digit is based on the fully fledged :ref:`display-engine`, as it has a concept of individual pixels 8 X 8
|
||||
per max7219 chip. In the lambda you're passed a variable called ``it`` as with all other displays. Some "Special"
|
||||
commands have been added to the basic display set.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: max7219digit
|
||||
cs_pin: D8
|
||||
num_chips: 4
|
||||
lambda: |-
|
||||
it.strftime(0, 0, id(digit_font), "%H:%M", id(hass_time).now());
|
||||
it.image(24, 0, id(my_image));
|
||||
it.line(1, 7, 21, 7);
|
||||
font:
|
||||
- file: "pixelmix.ttf"
|
||||
id: digit_font
|
||||
size: 6
|
||||
|
||||
time:
|
||||
- platform: homeassistant
|
||||
id: hass_time
|
||||
|
||||
image:
|
||||
- file: "smile.png"
|
||||
id: my_image
|
||||
|
||||
This is roughly the code used to display the MAX7219 pictured in the image.
|
||||
|
||||
Scrolling
|
||||
*********
|
||||
|
||||
By default the MAX7219Digit display has scroll enabled. The paramaters can be set in the YAML file.
|
||||
They can also be changed in the Lambda by adding the following command:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
it.scroll(<on/off>, <mode>, <speed>, <delay>, <dwell>);
|
||||
|
||||
|
||||
- **on/off** -> switch scrolling on or off, use true or false
|
||||
- **mode** -> 0 = Continuous scrolling, 1 = Stop at end and reset
|
||||
- **speed** -> Set speed of scrolling (ms for every step of one dot)
|
||||
- **delay** -> pause time at start of scrolling
|
||||
- **dwell** -> pause at end of scrolling (only in mode 1)
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: max7219digit
|
||||
# ...
|
||||
lambda: |-
|
||||
# ...
|
||||
it.scroll(true, 0, 100, 5000, 1500);
|
||||
// OR
|
||||
it.scroll(true, 0);
|
||||
// OR
|
||||
it.scroll(true);
|
||||
|
||||
- The screen does not scroll if the text fits within the screen.
|
||||
- ``printdigit("...")`` and ``printdigitf("...")`` the alternative way of displaying text does not scroll
|
||||
|
||||
Screen inversion
|
||||
****************
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: max7219digit
|
||||
# ...
|
||||
lambda: |-
|
||||
it.invert_on_off(true);
|
||||
// Print Hello at position 0 (left)
|
||||
it.print(0,0, id(digit_font), "Hello!");
|
||||
|
||||
The function ``it.invert_on_off(true);`` will invert the display. So background pixels are on and texts pixels are
|
||||
off. ``it.invert_on_off(false);`` sets the display back to normal. In case no argument is used: ``it.inverst_on_off();``
|
||||
the inversion will toggle from on to off or visa versa. This will happen every time the display is updated.
|
||||
So a blinking effect is created. The background pixels are only set at the next update, the pixels drawn in
|
||||
the various function like print, line, etc. are directly influenced by the invert command.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: max7219digit
|
||||
# ...
|
||||
lambda: |-
|
||||
it.invert_on_off(true);
|
||||
// Print Hello at position 0 (left)
|
||||
it.print(0,0, id(digit_font), "Hello!");
|
||||
it.line(0, 0, 31, 7, COLOR_OFF);
|
||||
|
||||
This code will only affect the line drawn on the screen. The line will wipe the pixels from top left to right bottom.
|
||||
The background is not affected.
|
||||
|
||||
Screen intensity
|
||||
****************
|
||||
|
||||
The intensity of the screen can be set "dynamically" within the lambda code with the following command: it.intensity(``0`` .. ``15``).
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: max7219digit
|
||||
# ...
|
||||
lambda: |-
|
||||
it.intensity(10);
|
||||
|
||||
Screen ON/OFF
|
||||
*************
|
||||
|
||||
The display can be switched on and off "dynamically" within the lambda code with the following command: it.turn_on_off(true or false).
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: max7219digit
|
||||
# ...
|
||||
lambda: |-
|
||||
it.turn_on_off(true);
|
||||
|
||||
For a quick display some additional commands are embedded in the code with a related 8 pixel font. Three methods
|
||||
(``printdigit``, ``printdigitf`` and ``strftimedigit``) can be used for diplaying characters. Each 8 X 8 grid is used to
|
||||
display a single character. So not very space efficient. The format of the command is: ``it.printdigit("1234");`` or
|
||||
``it.printdigitf("%s","1234")``;
|
||||
|
||||
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.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`index`
|
||||
- :apiref:`max7219/max7219.h`
|
||||
- `MAX7219 Library <https://github.com/nickgammon/MAX7219>`__ by `Nick Gammon <https://github.com/nickgammon>`__
|
||||
- :ghedit:`Edit`
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
|
|
@ -262,6 +262,7 @@ Display Components
|
|||
Display Core, components/display/index, folder-open.svg
|
||||
LCD Display, components/display/lcd_display, lcd.jpg
|
||||
MAX7219, components/display/max7219, max7219.jpg
|
||||
MAX7219 Dot Matrix, components/display/max7219digit, max7219digit.png
|
||||
TM1637, components/display/tm1637, tm1637.jpg
|
||||
Nextion, components/display/nextion, nextion.jpg
|
||||
SSD1306, components/display/ssd1306, ssd1306.jpg
|
||||
|
|
|
|||
Loading…
Reference in New Issue