Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-11-12 10:24:00 +01:00
Code Issues Projects Releases Wiki Activity

Split display widgets documentation (#4101)

Browse Source 
Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
guillempages 2024-08-06 07:06:57 +02:00 committed by GitHub
parent 6c4e581ec3
commit 2ffcef1815
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 392 additions and 361 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
components/animation.rst Normal file
View File

@ -0,0 +1,86 @@
.. _display-animation:
Animation
=========
Allows to use animated images on displays. Animation inherits all options from the image component.
It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_frame()`` to change the shown picture of a gif.
.. code-block:: yaml
animation:
- file: "animation.gif"
id: my_animation
resize: 100x100
The animation can be rendered just like the image component with the ``image()`` function of the display component.
To show the next frame of the animation call ``id(my_animation).next_frame()``, to show the previous picture use ``id(my_animation).prev_frame()``. To show a specific picture use ``id(my_animation).set_frame(int frame)``.
This can be combined with all Lambdas:
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
//Ingress shown animation Frame.
id(my_animation).next_frame();
// Draw the animation my_animation at position [x=0,y=0]
it.image(0, 0, id(my_animation), COLOR_ON, COLOR_OFF);
Additionally, you can use the ``animation.next_frame``, ``animation.prev_frame`` or ``animation.set_frame`` actions.
.. note::
To draw the next animation independent of Display draw cycle use an interval:
.. code-block:: yaml
interval:
- interval: 5s
then:
animation.next_frame: my_animation
Configuration variables:
------------------------
- **file** (**Required**, string): The path (relative to where the .yaml file is) of the gif file.
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the animation later
in your display code.
- **resize** (*Optional*, string): If set, this will resize all the frames to fit inside the given dimensions ``WIDTHxHEIGHT``
and preserve the aspect ratio.
- **type** (*Optional*): Specifies how to encode each frame internally. Defaults to ``BINARY``.
- ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
per pixel, 8 pixels per byte.
- ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
- ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
- ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
- ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
- ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
- **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over.
- **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation.
- **end_frame** (*Optional*, int): The last frame to show in the loop; when this frame is reached it will loop back to ``start_frame``. Defaults to the last frame in the animation.
- **repeat** (*Optional*, int): Specifies how many times the loop will run. When the count is reached, the animation will continue with the next frame after ``end_frame``, or restart from the beginning if ``end_frame`` was the last frame. Defaults to "loop forever".
Actions:
--------
- **animation.next_frame**: Moves the animation to the next frame. This is equivalent to the ``id(my_animation).next_frame();`` lambda call.
- **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
- **animation.prev_frame**: Moves the animation to the previous frame. This is equivalent to the ``id(my_animation).prev_frame();`` lambda call.
- **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
- **animation.set_frame**: Moves the animation to a specific frame. This is equivalent to the ``id(my_animation).set_frame(frame);`` lambda call.
- **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
- **frame** (**Required**, int): The frame index to show next.

362
components/display/index.rst
View File

@ -459,364 +459,6 @@ Configuration variables:
RGB displays use red, green, and blue, while grayscale displays may use white.
.. _display-graphs:
Graph Component
---------------
You can display a graph of a sensor value(s) using this component. The states used for the graph are stored in
memory at the time the sensor updates and will be lost when the device reboots.
Examples:
.. figure:: images/display_rendering_graph.png
:align: center
Graph component with options for grids, border and line-types.
.. code-block:: yaml
graph:
# Show bare-minimum auto-ranged graph
- id: single_temperature_graph
sensor: my_temperature
duration: 1h
width: 151
height: 51
# Show multi-trace graph
- id: multi_temperature_graph
duration: 1h
x_grid: 10min
y_grid: 1.0 # degC/div
width: 151
height: 51
traces:
- sensor: my_inside_temperature
line_type: DASHED
line_thickness: 2
color: my_red
- sensor: my_outside_temperature
line_type: SOLID
continuous: true
line_thickness: 3
color: my_blue
- sensor: my_beer_temperature
line_type: DOTTED
line_thickness: 2
color: my_green
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the graph later
in your display code.
- **width** (**Required**, int): The graph width in pixels
- **height** (**Required**, int): The graph height in pixels
- **duration** (**Required**, :ref:`config-time`): The total graph history duration.
- **border** (*Optional*, boolean): Specifies if a border will be drawn around the graph. Default is True.
- **x_grid** (*Optional*): Specifies the time per division. If not specified, no vertical grid will be drawn.
- **y_grid** (*Optional*, float): Specifies the number of units per division. If not specified, no horizontal grid will be drawn.
- **max_range** (*Optional*): Specifies the maximum Y-axis range.
- **min_range** (*Optional*): Specifies the minimum Y-axis range.
- **max_value** (*Optional*): Specifies the maximum Y-axis value.
- **min_value** (*Optional*): Specifies the minimum Y-axis value.
- **traces** (*Optional*): Use this to specify more than a single trace.
Trace specific fields:
- **sensor** (*Optional*, :ref:`config-id`): The sensor value to plot
- **line_thickness** (*Optional*): Defaults to 3
- **line_type** (*Optional*): Specifies the plot line-type. Can be one of the following: ``SOLID``, ``DOTTED``, ``DASHED``. Defaults to ``SOLID``.
- **continuous** (*Optional*): connects the individual points to make a continuous line. Defaults to ``false``.
- **color** (*Optional*): Sets the color of the sensor trace.
And then later in code:
.. code-block:: yaml
display:
- platform: ...
# ...
pages:
- id: page1
lambda: |-
// Draw the graph at position [x=10,y=20]
it.graph(10, 20, id(single_temperature_graph));
- id: page2
lambda: |-
// Draw the graph at position [x=10,y=20]
it.graph(10, 20, id(multi_temperature_graph), my_yellow);
color:
- id: my_red
red: 100%
green: 0%
blue: 0%
- id: my_green
red: 0%
green: 100%
blue: 0%
- id: my_blue
red: 0%
green: 0%
blue: 100%
- id: my_yellow
red: 100%
green: 100%
blue: 0%
.. note::
Here are some things to note:
- Setting ``y_grid`` will expand any specified range to the nearest multiple of grid spacings.
- Axis labels are currently not possible without manually placing them.
- The grid and border color is set with it.graph(), while the traces are defined separately.
.. _display-qrcode:
QR Code Component
-----------------
Use this component to generate a QR-code containing a string on the device, which can then be drawn on compatible displays.
.. code-block:: yaml
qr_code:
- id: homepage_qr
value: esphome.io
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the QR-code later
in your display code.
- **value** (**Required**, string): The string which you want to encode in the QR-code.
- **ecc** (*Optional*, string): The error correction code level you want to use. Defaults to ``LOW``. You can use one of the following values:
- ``LOW``: The QR Code can tolerate about 7% erroneous codewords
- ``MEDIUM``: The QR Code can tolerate about 15% erroneous codewords
- ``QUARTILE``: The QR Code can tolerate about 25% erroneous codewords
- ``HIGH``: The QR Code can tolerate about 30% erroneous codewords
To draw the QR-code, call the ``it.qr_code`` function from your render lambda:
.. code-block:: yaml
display:
- platform: ...
# ...
pages:
- id: page1
lambda: |-
// Draw the QR-code at position [x=50,y=0] with white color and a 2x scale
it.qr_code(50, 0, id(homepage_qr), Color(255,255,255), 2);
// Draw the QR-code in the center of the screen with white color and a 2x scale
auto size = id(homepage_qr).get_size() * 2; // Multiply by scale
auto x = (it.get_width() / 2) - (size / 2);
auto y = (it.get_height() / 2) - (size / 2);
it.qr_code(x, y, id(homepage_qr), Color(255,255,255), 2);
.. _display-image:
Images
------
Use this component to store graphical images on the device, you can then draw the images on compatible displays.
.. code-block:: yaml
image:
- file: "image.png"
id: my_image
resize: 100x100
.. code-block:: yaml
image:
- file: mdi:alert-outline
id: alert
resize: 80x80
.. code-block:: yaml
image:
- file: https://esphome.io/_images/logo.png
id: esphome_logo
resize: 200x162
Configuration variables:
- **file** (**Required**, string):
- **Local files**: The path (relative to where the .yaml file is) of the image file.
- **Material Design Icons**: Specify the `Material Design Icon <https://pictogrammers.com/library/mdi/>`_
id in the format ``mdi:icon-name``, and that icon will automatically be downloaded and added to the configuration.
- **Remote files**: The URL of the image file.
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later
in your display code.
- **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT``
and preserve the aspect ratio.
- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY`` for local images and ``TRANSPARENT_BINARY`` for MDIs.
- ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
per pixel, 8 pixels per byte.
- ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
- ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
- ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
- ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
- ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
- **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here <https://pillow.readthedocs.io/en/stable/reference/Image.html?highlight=Dither#PIL.Image.Image.convert>`__ and `here <https://en.wikipedia.org/wiki/Dither>`__.
- ``NONE``: Every pixel convert to its nearest color.
- ``FLOYDSTEINBERG``: Uses Floyd-Steinberg dither to approximate the original image luminosity levels.
.. note::
To use images you will need to have the python ``pillow`` package installed.
If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be
installed. Otherwise you need to install it using ``pip install pillow``.
Additionally, if you want to use SVG images (including MDI images), you will additionally need to have the python ``cairosvg`` package installed.
If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should also already be
installed. Otherwise you need to install it using ``pip install cairosvg``.
And then later in code:
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
// Draw the image my_image at position [x=0,y=0]
it.image(0, 0, id(my_image));
By default, ESPHome will *align* the image at the top left. That means if you enter the coordinates
``[0,10]`` for your image, the top left of the image will be at ``[0,10]``. If you want to draw some
image at the right side of the display, it is however sometimes useful to choose a different **image alignment**.
When you enter ``[0,10]`` you're really telling ESPHome that it should position the **anchor point** of the image
at ``[0,10]``. When using a different alignment, like ``TOP_RIGHT``, the image will be positioned left of the anchor
pointed, so that, as the name implies, the anchor point is a the *top right* corner of the image.
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
// Aligned on left by default
it.image(0, 0, id(my_image));
// Aligned on right edge
it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT);
For binary images the ``image`` method accepts two additional color parameters which can
be supplied to modify the color used to represent the on and off bits respectively. e.g.
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
// Draw the image my_image at position [x=0,y=0]
// with front color red and back color blue
it.image(0, 0, id(my_image), id(red), id(blue));
// Aligned on right edge
it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT, id(red), id(blue));
You can also use this to invert images in two colors display, use ``COLOR_OFF`` then ``COLOR_ON``
as the additional parameters.
Animation
---------
Allows to use animated images on displays. Animation inherits all options from the image component.
It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_frame()`` to change the shown picture of a gif.
.. code-block:: yaml
animation:
- file: "animation.gif"
id: my_animation
resize: 100x100
The animation can be rendered just like the image component with the ``image()`` function of the display component.
To show the next frame of the animation call ``id(my_animation).next_frame()``, to show the previous picture use ``id(my_animation).prev_frame()``. To show a specific picture use ``id(my_animation).set_frame(int frame)``.
This can be combined with all Lambdas:
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
//Ingress shown animation Frame.
id(my_animation).next_frame();
// Draw the animation my_animation at position [x=0,y=0]
it.image(0, 0, id(my_animation), COLOR_ON, COLOR_OFF);
Additionally, you can use the ``animation.next_frame``, ``animation.prev_frame`` or ``animation.set_frame`` actions.
.. note::
To draw the next animation independent of Display draw cycle use an interval:
.. code-block:: yaml
interval:
- interval: 5s
then:
animation.next_frame: my_animation
Configuration variables:
^^^^^^^^^^^^^^^^^^^^^^^^
- **file** (**Required**, string): The path (relative to where the .yaml file is) of the gif file.
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the animation later
in your display code.
- **resize** (*Optional*, string): If set, this will resize all the frames to fit inside the given dimensions ``WIDTHxHEIGHT``
and preserve the aspect ratio.
- **type** (*Optional*): Specifies how to encode each frame internally. Defaults to ``BINARY``.
- ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
per pixel, 8 pixels per byte.
- ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
- ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
- ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
- ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
- ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
- **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over.
- **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation.
- **end_frame** (*Optional*, int): The last frame to show in the loop; when this frame is reached it will loop back to ``start_frame``. Defaults to the last frame in the animation.
- **repeat** (*Optional*, int): Specifies how many times the loop will run. When the count is reached, the animation will continue with the next frame after ``end_frame``, or restart from the beginning if ``end_frame`` was the last frame. Defaults to "loop forever".
Actions:
^^^^^^^^
- **animation.next_frame**: Moves the animation to the next frame. This is equivalent to the ``id(my_animation).next_frame();`` lambda call.
- **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
- **animation.prev_frame**: Moves the animation to the previous frame. This is equivalent to the ``id(my_animation).prev_frame();`` lambda call.
- **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
- **animation.set_frame**: Moves the animation to a specific frame. This is equivalent to the ``id(my_animation).set_frame(frame);`` lambda call.
- **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
- **frame** (**Required**, int): The frame index to show next.
.. _display-pages:
@ -964,6 +606,10 @@ See Also
- :apiref:`display/display_buffer.h`
- :ref:`Fonts <display-fonts>`
- :ref:`Graph Component <display-graphs>`
- :ref:`QR Code Component <display-qrcode>`
- :ref:`Image Component <display-image>`
- :ref:`Animation Component <display-animation>`
- :ghedit:`Edit`
.. toctree::

0
components/display/fonts.rst → components/fonts.rst
View File

119
components/graph.rst Normal file
View File

@ -0,0 +1,119 @@
.. _display-graphs:
Graph Component
===============
.. seo::
:description: Instructions for displaying graphs in ESPHome.
:image: chart-line.svg
You can display a graph of a sensor value(s) using this component. The states used for the graph are stored in
memory at the time the sensor updates and will be lost when the device reboots.
Examples:
.. figure:: images/display_rendering_graph.png
:align: center
Graph component with options for grids, border and line-types.
.. code-block:: yaml
graph:
# Show bare-minimum auto-ranged graph
- id: single_temperature_graph
sensor: my_temperature
duration: 1h
width: 151
height: 51
# Show multi-trace graph
- id: multi_temperature_graph
duration: 1h
x_grid: 10min
y_grid: 1.0 # degC/div
width: 151
height: 51
traces:
- sensor: my_inside_temperature
line_type: DASHED
line_thickness: 2
color: my_red
- sensor: my_outside_temperature
line_type: SOLID
continuous: true
line_thickness: 3
color: my_blue
- sensor: my_beer_temperature
line_type: DOTTED
line_thickness: 2
color: my_green
Configuration variables:
------------------------
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the graph later
in your display code.
- **width** (**Required**, int): The graph width in pixels
- **height** (**Required**, int): The graph height in pixels
- **duration** (**Required**, :ref:`config-time`): The total graph history duration.
- **border** (*Optional*, boolean): Specifies if a border will be drawn around the graph. Default is True.
- **x_grid** (*Optional*): Specifies the time per division. If not specified, no vertical grid will be drawn.
- **y_grid** (*Optional*, float): Specifies the number of units per division. If not specified, no horizontal grid will be drawn.
- **max_range** (*Optional*): Specifies the maximum Y-axis range.
- **min_range** (*Optional*): Specifies the minimum Y-axis range.
- **max_value** (*Optional*): Specifies the maximum Y-axis value.
- **min_value** (*Optional*): Specifies the minimum Y-axis value.
- **traces** (*Optional*): Use this to specify more than a single trace.
Trace specific fields:
- **sensor** (*Optional*, :ref:`config-id`): The sensor value to plot
- **line_thickness** (*Optional*): Defaults to 3
- **line_type** (*Optional*): Specifies the plot line-type. Can be one of the following: ``SOLID``, ``DOTTED``, ``DASHED``. Defaults to ``SOLID``.
- **continuous** (*Optional*): connects the individual points to make a continuous line. Defaults to ``false``.
- **color** (*Optional*): Sets the color of the sensor trace.
And then later in code:
.. code-block:: yaml
display:
- platform: ...
# ...
pages:
- id: page1
lambda: |-
pages:
- id: page1
lambda: |-
// Draw the graph at position [x=10,y=20]
it.graph(10, 20, id(single_temperature_graph));
- id: page2
lambda: |-
// Draw the graph at position [x=10,y=20]
it.graph(10, 20, id(multi_temperature_graph), my_yellow);
color:
- id: my_red
red: 100%
green: 0%
blue: 0%
- id: my_green
red: 0%
green: 100%
blue: 0%
- id: my_blue
red: 0%
green: 0%
blue: 100%
- id: my_yellow
red: 100%
green: 100%
blue: 0%
.. note::
Here are some things to note:
- Setting ``y_grid`` will expand any specified range to the nearest multiple of grid spacings.
- Axis labels are currently not possible without manually placing them.
- The grid and border color is set with it.graph(), while the traces are defined separately.

124
components/images.rst Normal file
View File

@ -0,0 +1,124 @@
.. _display-image:
Images
======
.. seo::
:description: Instructions to display static images on ESPHome
:image: image-outline.svg
Use this component to store graphical images on the device, you can then draw the images on compatible displays.
.. code-block:: yaml
image:
- file: "image.png"
id: my_image
resize: 100x100
.. code-block:: yaml
image:
- file: mdi:alert-outline
id: alert
resize: 80x80
.. code-block:: yaml
image:
- file: https://esphome.io/_images/logo.png
id: esphome_logo
resize: 200x162
Configuration variables:
------------------------
- **file** (**Required**, string):
- **Local files**: The path (relative to where the .yaml file is) of the image file.
- **Material Design Icons**: Specify the `Material Design Icon <https://pictogrammers.com/library/mdi/>`_
id in the format ``mdi:icon-name``, and that icon will automatically be downloaded and added to the configuration.
- **Remote files**: The URL of the image file.
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later
in your display code.
- **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT``
and preserve the aspect ratio.
- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY`` for local and remote images and ``TRANSPARENT_BINARY`` for MDIs.
- ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
per pixel, 8 pixels per byte.
- ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
- ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
- ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
- ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
- ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
- **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here <https://pillow.readthedocs.io/en/stable/reference/Image.html?highlight=Dither#PIL.Image.Image.convert>`__ and `here <https://en.wikipedia.org/wiki/Dither>`__.
- ``NONE``: Every pixel convert to its nearest color.
- ``FLOYDSTEINBERG``: Uses Floyd-Steinberg dither to approximate the original image luminosity levels.
.. note::
To use images you will need to have the python ``pillow`` package installed.
Additionally, if you want to use SVG images (including MDI images), you will
additionally need to have the python ``cairosvg`` package installed.
If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed.
Use ``pip install "esphome[displays]"`` to install these optional dependencies with
the versions that ESPHome requires.
And then later in code:
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
// Draw the image my_image at position [x=0,y=0]
it.image(0, 0, id(my_image));
By default, ESPHome will *align* the image at the top left. That means if you enter the coordinates
``[0,10]`` for your image, the top left of the image will be at ``[0,10]``. If you want to draw some
image at the right side of the display, it is however sometimes useful to choose a different **image alignment**.
When you enter ``[0,10]`` you're really telling ESPHome that it should position the **anchor point** of the image
at ``[0,10]``. When using a different alignment, like ``TOP_RIGHT``, the image will be positioned left of the anchor
pointed, so that, as the name implies, the anchor point is a the *top right* corner of the image.
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
// Aligned on left by default
it.image(0, 0, id(my_image));
// Aligned on right edge
it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT);
For binary images the ``image`` method accepts two additional color parameters which can
be supplied to modify the color used to represent the on and off bits respectively. e.g.
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
// Draw the image my_image at position [x=0,y=0]
// with front color red and back color blue
it.image(0, 0, id(my_image), id(red), id(blue));
// Aligned on right edge
it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT, id(red), id(blue));
You can also use this to invert images in two color displays, use ``COLOR_OFF`` then ``COLOR_ON``
as the additional parameters.

0
components/display/images/display_rendering_graph.png → components/images/display_rendering_graph.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 674 B

After

Width:  |  Height:  |  Size: 674 B

50
components/qr_code.rst Normal file
View File

@ -0,0 +1,50 @@
.. _display-qrcode:
QR Code Component
=================
.. seo::
:description: Instructions for displaying a QR Code in ESPHome
:image: qr-code.svg
Use this component to generate a QR-code containing a string on the device, which can then be drawn on compatible displays.
.. code-block:: yaml
qr_code:
- id: homepage_qr
value: esphome.io
Configuration variables:
------------------------
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the QR-code later
in your display code.
- **value** (**Required**, string): The string which you want to encode in the QR-code.
- **ecc** (*Optional*, string): The error correction code level you want to use. Defaults to ``LOW``. You can use one of the following values:
- ``LOW``: The QR Code can tolerate about 7% erroneous codewords
- ``MEDIUM``: The QR Code can tolerate about 15% erroneous codewords
- ``QUARTILE``: The QR Code can tolerate about 25% erroneous codewords
- ``HIGH``: The QR Code can tolerate about 30% erroneous codewords
To draw the QR-code, call the ``it.qr_code`` function from your render lambda:
.. code-block:: yaml
display:
- platform: ...
# ...
pages:
- id: page1
lambda: |-
// Draw the QR-code at position [x=50,y=0] with white color and a 2x scale
it.qr_code(50, 0, id(homepage_qr), Color(255,255,255), 2);
// Draw the QR-code in the center of the screen with white color and a 2x scale
auto size = id(homepage_qr).get_size() * 2; // Multiply by scale
auto x = (it.get_width() / 2) - (size / 2);
auto y = (it.get_height() / 2) - (size / 2);
it.qr_code(x, y, id(homepage_qr), Color(255,255,255), 2);

1
images/chart-line.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16,11.78L20.24,4.45L21.97,5.45L16.74,14.5L10.23,10.75L5.46,19H22V21H2V3H4V17.54L9.5,8L16,11.78Z" /></svg>
Side by Side

After

Width:  |  Height:  |  Size: 175 B

1
images/image-multiple-outline.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21,17H7V3H21M21,1H7A2,2 0 0,0 5,3V17A2,2 0 0,0 7,19H21A2,2 0 0,0 23,17V3A2,2 0 0,0 21,1M3,5H1V21A2,2 0 0,0 3,23H19V21H3M15.96,10.29L13.21,13.83L11.25,11.47L8.5,15H19.5L15.96,10.29Z" /></svg>
Side by Side

After

Width:  |  Height:  |  Size: 260 B

1
images/image-outline.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19,19H5V5H19M19,3H5A2,2 0 0,0 3,5V19A2,2 0 0,0 5,21H19A2,2 0 0,0 21,19V5A2,2 0 0,0 19,3M13.96,12.29L11.21,15.83L9.25,13.47L6.5,17H17.5L13.96,12.29Z" /></svg>
Side by Side

After

Width:  |  Height:  |  Size: 227 B

7
index.rst
View File

@ -816,9 +816,12 @@ Display Components
.. imgtable::
Display Core, components/display/index, folder-open.svg, dark-invert
Font Renderer, components/fonts, format-font.svg, dark-invert
Graph, components/graph, chart-line.svg, dark-invert
QR Code, components/qr_code, qr-code.svg, dark-invert
Image, components/images, image-outline.svg, dark-invert
Animation, components/animation, image-multiple-outline.svg, dark-invert
Display Menu Core, components/display_menu/index, folder-open.svg, dark-invert
Font Renderer, components/display/fonts, format-font.svg, dark-invert
Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.png
LCD Menu, components/display_menu/lcd_menu, lcd_menu.png

2
lint.py
View File

@ -395,7 +395,7 @@ def lint_directive_formatting(fname, content):
include=["*.rst"],
exclude=[
"components/web_server.rst",
"components/display/index.rst",
"components/images.rst",
],
)
def lint_esphome_io_link(fname, match):