Add online_image documentation
Add the documentation for the new feature "online image"
This commit is contained in:
Guillem Pagès Gassull
parent
76abb6a0ae
commit
34ce4d9276
|
|
@ -853,6 +853,109 @@ Actions:
|
|||
|
||||
.. _display-pages:
|
||||
|
||||
Online Images
|
||||
*************
|
||||
|
||||
Use this component to define images that will be downloaded and drawn at runtime.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
online_image:
|
||||
- url: "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
|
||||
id: my_online_image
|
||||
on_download_finished:
|
||||
component.update: my_display
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **url** (**Required**, url): The URL where the image will be downloaded from.
|
||||
- **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``.
|
||||
|
||||
- ``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*, boolean): 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``.
|
||||
|
||||
- **follow_redirects** (*Optional*, boolean): Defines whether HTTP redirect responses are to be followed (``True``) or rejected (``False``). Defaults to ``True``.
|
||||
- **redirect_limit** (*Optional*, int): The maximum amount of redirects that will be followed if ``follow_redirects`` is ``True``. Defaults to ``3``
|
||||
|
||||
- **timeout** (*Optional*, int): Timeout to abort the HTTP connection if an error occurs. Defaults to 5 seconds.
|
||||
|
||||
- **user_agent** (*Optional*, string): The user agent string to send to the server. Defaults to *ESPHome*.
|
||||
|
||||
- **update_interval** (*Optional*, int): Redownload the image when the specified time has elapsed. Defaults to ``never`` (i.e. the update component action needs to be called manually).
|
||||
|
||||
Automations:
|
||||
|
||||
- **on_download_finished** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the image has been successfully downloaded.
|
||||
- **on_error** (*Optional*, :ref:`Automation <automation>`): An automation to perform when an error happened during download or decode.
|
||||
|
||||
And then later in code:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: ...
|
||||
id: my_display
|
||||
# ...
|
||||
lambda: |-
|
||||
// Draw the image my_online_image at position [x=0,y=0]
|
||||
it.image(0, 0, id(my_online_image))
|
||||
|
||||
For monochrome displays the ``image`` method accepts two additional color parameters which can
|
||||
be supplied to specify the color used to draw bright and dark pixels respectively.
|
||||
In this case the image will be internally converted to a grayscale image and then to monochrome
|
||||
based on an internally defined threshold.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
display:
|
||||
- platform: ...
|
||||
id: my_display
|
||||
# ...
|
||||
lambda: |-
|
||||
// Draw the image my_image at position [x=0,y=0]
|
||||
// with front color "OFF" and back color "ON"
|
||||
it.image(0, 0, id(my_online_image), COLOR_OFF, COLOR_ON);
|
||||
|
||||
Actions:
|
||||
^^^^^^^^
|
||||
**online_image.set_url**: Change the URL where the image is downloaded from. The image needs to be manually updated afterwards.
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): The image to update the URL for.
|
||||
- **url** (**Required**, url): The new URL to download the image from.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
- online_image.set_url:
|
||||
id: my_online_image
|
||||
url: "https://www.example.com/new_image.png"
|
||||
- component.update: my_online_image
|
||||
|
||||
**online_image.release**: Release the memory currently used by an image. Can be used if different display pages need different images, to avoid wasting memory on an image that is currently not being displayed.
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): The image to update the URL for.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
- online_image.release: my_online_image
|
||||
|
||||
Display Pages
|
||||
-------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue