From 2ffcef1815beffe9c55e61ddd61cd57bb8319b4e Mon Sep 17 00:00:00 2001 From: guillempages Date: Tue, 6 Aug 2024 07:06:57 +0200 Subject: [PATCH] Split display widgets documentation (#4101) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: H. Árkosi Róbert Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/animation.rst | 86 +++++ components/display/index.rst | 362 +----------------- components/{display => }/fonts.rst | 0 components/graph.rst | 119 ++++++ components/images.rst | 124 ++++++ .../images/display_rendering_graph.png | Bin components/qr_code.rst | 50 +++ images/chart-line.svg | 1 + images/image-multiple-outline.svg | 1 + images/image-outline.svg | 1 + index.rst | 7 +- lint.py | 2 +- 12 files changed, 392 insertions(+), 361 deletions(-) create mode 100644 components/animation.rst rename components/{display => }/fonts.rst (100%) create mode 100644 components/graph.rst create mode 100644 components/images.rst rename components/{display => }/images/display_rendering_graph.png (100%) create mode 100644 components/qr_code.rst create mode 100644 images/chart-line.svg create mode 100644 images/image-multiple-outline.svg create mode 100644 images/image-outline.svg diff --git a/components/animation.rst b/components/animation.rst new file mode 100644 index 000000000..1a8d282fe --- /dev/null +++ b/components/animation.rst @@ -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. + diff --git a/components/display/index.rst b/components/display/index.rst index 4db857c2c..dc305ca4f 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -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 `_ - 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 `__ and `here `__. - - - ``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 ` +- :ref:`Graph Component ` +- :ref:`QR Code Component ` +- :ref:`Image Component ` +- :ref:`Animation Component ` - :ghedit:`Edit` .. toctree:: diff --git a/components/display/fonts.rst b/components/fonts.rst similarity index 100% rename from components/display/fonts.rst rename to components/fonts.rst diff --git a/components/graph.rst b/components/graph.rst new file mode 100644 index 000000000..a2df8b6b6 --- /dev/null +++ b/components/graph.rst @@ -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. + diff --git a/components/images.rst b/components/images.rst new file mode 100644 index 000000000..c9962db99 --- /dev/null +++ b/components/images.rst @@ -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 `_ + 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 `__ and `here `__. + + - ``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. + diff --git a/components/display/images/display_rendering_graph.png b/components/images/display_rendering_graph.png similarity index 100% rename from components/display/images/display_rendering_graph.png rename to components/images/display_rendering_graph.png diff --git a/components/qr_code.rst b/components/qr_code.rst new file mode 100644 index 000000000..fb178b033 --- /dev/null +++ b/components/qr_code.rst @@ -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); + + diff --git a/images/chart-line.svg b/images/chart-line.svg new file mode 100644 index 000000000..eeb7259fd --- /dev/null +++ b/images/chart-line.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/image-multiple-outline.svg b/images/image-multiple-outline.svg new file mode 100644 index 000000000..d89398cb5 --- /dev/null +++ b/images/image-multiple-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/image-outline.svg b/images/image-outline.svg new file mode 100644 index 000000000..cc75caa65 --- /dev/null +++ b/images/image-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 01d4d46fb..a125265a0 100644 --- a/index.rst +++ b/index.rst @@ -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 diff --git a/lint.py b/lint.py index e0d3e4c3f..0d2b1a08a 100644 --- a/lint.py +++ b/lint.py @@ -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):