diff --git a/changelog/v1.10.0.rst b/changelog/v1.10.0.rst index 66bdd6690..b31f91710 100644 --- a/changelog/v1.10.0.rst +++ b/changelog/v1.10.0.rst @@ -134,7 +134,7 @@ Other notable changes: (:ref:`wifi-networks`) - GPIO Switches have a new option ``restore_mode`` to configure how their values should be restored on boot. (:doc:`/components/switch/gpio`) -- Added :ref:`substitutions ` to reduce repeating across configs. +- Added :doc:`/components/substitutions/index` to reduce repeating across configs. - Validation error messages are now displayed even better. Now all errors are shown with the exact context where the error appeared. Try it, it's so much better. Next step will be to upgrade to a better YAML reader to provide better error messages when the YAML syntax is invalid. 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/inkplate6.rst b/components/display/inkplate6.rst index 0ef6d520d..5d1b7741a 100644 --- a/components/display/inkplate6.rst +++ b/components/display/inkplate6.rst @@ -180,7 +180,7 @@ Wi-Fi, API, and OTA configuration. - platform: adc id: battery_voltage update_interval: never - attenuation: 11db + attenuation: 12db pin: 35 - platform: template name: "Inkplate Battery Voltage" diff --git a/components/esp32.rst b/components/esp32.rst index da12e7beb..e714b21de 100644 --- a/components/esp32.rst +++ b/components/esp32.rst @@ -18,7 +18,7 @@ Configuration variables: - **board** (**Required**, string): The PlatformIO board ID that should be used. Choose the appropriate board from - `this list `__ (the icon next to the name + `this list `__ (the icon next to the name can be used to copy the board ID). *This only affects pin aliases, flash size and some internal settings*, if unsure choose a generic board from Espressif such as ``esp32dev``. - **framework** (*Optional*): Options for the underlying framework used by ESPHome. 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/index.rst b/components/index.rst index f937b80a2..fb1f9a27a 100644 --- a/components/index.rst +++ b/components/index.rst @@ -34,4 +34,6 @@ Components text/index update/index valve/index + packages/index + substitutions/index * diff --git a/components/packages/index.rst b/components/packages/index.rst new file mode 100644 index 000000000..1973730aa --- /dev/null +++ b/components/packages/index.rst @@ -0,0 +1,203 @@ +Packages +======== + +.. seo:: + :description: How to use packages in ESPHome + :image: settings.svg + +When you have many ESPHome devices (or are producing and distributing them at scale), a common need tends to surface: +configuration modularization. You'll likely want to break your configuration into common (groups of) elements, building +it into reusable pieces which can subsequently be used by many/all devices. Only unique pieces of your configuration +remain in any given device's YAML configuration file. + +This can be accomplished with ESPHome's ``packages`` feature. + +All definitions from packages will be merged with your device's main configuration in a non-destructive way. This +allows overriding (parts of) configuration contained in the package(s). Substitutions in your main configuration will +override substitutions with the same name in a package. + +Dictionaries are merged key-by-key. Lists of components are merged by component ID (if specified). Other lists are +merged by concatenation. All other configuration values are replaced with the later value. + +ESPHome uses ``!include`` to "bring in" packages; this is a syntax brought over from +`Home Assistant's YAML configuration directives `__. + +Local Packages +-------------- + +Consider the following example where the author put common pieces of configuration (like Wi-Fi and API) into base files +and then extends it with some device-specific configuration in the main configuration. + +Note how the piece of configuration describing ``api`` component in ``device_base.yaml`` gets merged with the services +definitions from main configuration file. + +.. code-block:: yaml + + # In config.yaml + packages: + wifi: !include common/wifi.yaml + device_base: !include common/device_base.yaml + + api: + services: + - service: start_laundry + then: + - switch.turn_on: relay + + # any additional configuration... + +.. code-block:: yaml + + # In wifi.yaml + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + +.. code-block:: yaml + + # In device_base.yaml + esphome: + name: ${node_name} + + esp32: + board: wemos_d1_mini32 + + logger: + + api: + encryption: + key: !secret api_encryption_key + +.. _config-git_packages: + +Remote/Git Packages +------------------- + +Packages can also be loaded from a Git repository by utilizing the correct configuration syntax. +:doc:`/components/substitutions/index` can be used inside the remote packages which allows users to override +them locally with their own substitution value. + +.. note:: + + Remote packages cannot have ``secret`` lookups in them. They should instead make use of substitutions with an + optional default in the packaged YAML, which the local device YAML can set using values from the local secrets. + +.. code-block:: yaml + + # Git repo examples + packages: + # shorthand form github://username/repository/[folder/]file-path.yml[@branch-or-tag] + remote_package_shorthand: github://esphome/non-existant-repo/file1.yml@main + + remote_package_files: + url: https://github.com/esphome/non-existant-repo + files: [file1.yml, file2.yml] # optional; if not specified, all files will be included + ref: main # optional + refresh: 1d # optional + +Configuration variables: +------------------------ + +For each package: + +- **url** (**Required**, string): The URL for the repository. +- **username** (*Optional*, string): Username to be used for authentication, if required. +- **password** (*Optional*, string): Password to be used for authentication, if required. +- **files** (**Required**, list of strings): List of files to include. +- **ref** (*Optional*, string): The Git ref(erence) to be used when pulling content from the repository. +- **refresh** (*Optional*, :ref:`config-time`): The interval at which the content from the repository should be refreshed. + +Packages as Templates +--------------------- + +Since packages are incorporated using the ``!include`` system, variables can be provided to them. This means that +packages can be used as *templates*, allowing complex or repetitive configurations to be stored in a package file +and then incorporated into the configuration more than once. + +Packages may also contain a ``defaults`` block which provides subsitutions for variables not provided by the +``!include`` block. + +As an example, if the configuration needed to support three garage doors using the ``gpio`` switch platform and the +``time_based`` cover platform, it could be constructed like this: + +.. code-block:: yaml + + # In config.yaml + packages: + left_garage_door: !include + file: garage-door.yaml + vars: + door_name: Left + vars: + door_name: Middle + vars: + door_name: Right + + +.. code-block:: yaml + + # In garage-door.yaml + switch: + - name: ${door_name} Garage Door Switch + platform: gpio + # ... + +Extend +------ + +To make changes or add additional configuration to included configurations, ``!extend config_id`` can be used, where +``config_id`` is the ID of the configuration to modify. + +For example, to set a specific update interval on a common uptime sensor that is shared between configurations: + +.. code-block:: yaml + + # In common.yaml + captive_portal: + + sensor: + - platform: uptime + id: uptime_sensor + update_interval: 1min + +.. code-block:: yaml + + packages: + common: !include common.yaml + + sensor: + - id: !extend uptime_sensor + update_interval: 10s + +Remove +------ + +To remove existing entries from included configurations, ``!remove [config_id]`` can be used, where ``config_id`` is +the ID of the entry to modify. + +For example, to remove a common uptime sensor that is shared between configurations: + +.. code-block:: yaml + + packages: + common: !include common.yaml # see above + + sensor: + - id: !remove uptime_sensor + +To remove captive portal for a specific device: + +.. code-block:: yaml + + packages: + common: !include common.yaml # see above + + captive_portal: !remove + +See Also +-------- + +- :doc:`ESPHome index ` +- :doc:`/guides/getting_started_command_line` +- :doc:`/guides/faq` +- :ghedit:`Edit` 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/components/remote_receiver.rst b/components/remote_receiver.rst index 20ef6b324..490b635cc 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -32,7 +32,7 @@ Configuration variables: - **dump** (*Optional*, list): Decode and dump these remote codes in the logs (at log.level=DEBUG). Set to ``all`` to dump all available codecs: - - **abbwelcome**: Decode and dump ABB-Welcome codes. Messages are sent via copper wires. See :ref:`remote_transmitter-transmit_abbwelcome` + - **abbwelcome**: Decode and dump ABB-Welcome codes. Messages are sent via copper wires. See :ref:`transmitter description ` for more details. - **aeha**: Decode and dump AEHA infrared codes. - **byronsx**: Decode and dump Byron SX doorbell RF codes. - **canalsat**: Decode and dump CanalSat infrared codes. @@ -242,17 +242,14 @@ Configuration variables: Remote code selection (exactly one of these has to be included): -- **abbwelcome**: Trigger on a decoded ABB-Welcome code with the given data. +- **abbwelcome**: Trigger on a decoded ABB-Welcome code with the given data, see the :ref:`transmitter description ` for more info. - - **source_address** (**Required**, int): The source address to trigger on, see :ref:`remote_transmitter-transmit_abbwelcome` - for more info. - - **destination_address** (**Required**, int): The destination address to trigger on, see - :ref:`remote_transmitter-transmit_abbwelcome` for more info. + - **source_address** (**Required**, int): The source address to trigger on. + - **destination_address** (**Required**, int): The destination address to trigger on. - **three_byte_address** (**Optional**, boolean): The length of the source and destination address. ``false`` means two bytes and ``true`` means three bytes. Defaults to ``false``. - **retransmission** (**Optional**, boolean): ``true`` if the message was re-transmitted. Defaults to ``false``. - - **message_type** (**Required**, int): The message type to trigger on, see :ref:`remote_transmitter-transmit_abbwelcome` - for more info. + - **message_type** (**Required**, int): The message type to trigger on. - **message_id** (**Optional**, int): The random message ID to trigger on, see dumper output for more info. Defaults to any ID. - **data** (**Optional**, 0-7 bytes list): The code to listen for. Usually you only need to copy this directly from the dumper output. Defaults to ``[]`` @@ -260,7 +257,7 @@ Remote code selection (exactly one of these has to be included): - **aeha**: Trigger on a decoded AEHA remote code with the given data. - **address** (**Required**, int): The address to trigger on, see dumper output for more info. - - **data** (**Required**, 3-35 bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_aeha` + - **data** (**Required**, 3-35 bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **byronsx**: Trigger on a decoded Byron SX Doorbell RF remote code with the given data. @@ -317,7 +314,7 @@ Remote code selection (exactly one of these has to be included): - **haier**: Trigger on a Haier remote code with the given code. - - **code** (**Required**, 13-bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_haier` + - **code** (**Required**, 13-bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **lg**: Trigger on a decoded LG remote code with the given data. @@ -332,7 +329,7 @@ Remote code selection (exactly one of these has to be included): - **midea**: Trigger on a Midea remote code with the given code. - - **code** (**Required**, 5-bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_midea` + - **code** (**Required**, 5-bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy first 5 bytes directly from the dumper output. - **nec**: Trigger on a decoded NEC remote code with the given data. @@ -359,14 +356,14 @@ Remote code selection (exactly one of these has to be included): - **pronto**: Trigger on a Pronto remote code with the given code. - - **data** (**Required**, string): The code to listen for, see :ref:`remote_transmitter-transmit_raw` + - **data** (**Required**, string): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **delta** (**Optional**, integer): This parameter allows you to manually specify the allowed difference between what Pronto code is specified, and what IR signal has been sent by the remote control. - **raw**: Trigger on a raw remote code with the given code. - - **code** (**Required**, list): The code to listen for, see :ref:`remote_transmitter-transmit_raw` + - **code** (**Required**, list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **rc5**: Trigger on a decoded RC5 remote code with the given data. @@ -440,7 +437,7 @@ Remote code selection (exactly one of these has to be included): - **mirage**: Trigger on a Mirage remote code with the given code. - - **code** (**Required**, 14-bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_mirage` + - **code** (**Required**, 14-bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. .. note:: @@ -495,8 +492,9 @@ See Also - :doc:`index` - :doc:`/components/remote_transmitter` +- :ref:`remote-setting-up-infrared` +- :ref:`remote-setting-up-rf` - :doc:`/components/rf_bridge` - `RCSwitch `__ by `Suat Özgür `__ -- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ - :apiref:`remote/remote_receiver.h` - :ghedit:`Edit` diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index 1774a35d0..8f47bd223 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -2,9 +2,9 @@ Remote Transmitter ================== .. seo:: - :description: Instructions for setting up switches that send out pre-defined sequences of IR or RF signals + :description: Instructions for setting up configurations that send out pre-defined sequences of IR or RF signals :image: remote.svg - :keywords: Infrared, IR, RF, Remote, TX + :keywords: Infrared, IR, RF, Remote, TX, 433, Blaster The ``remote_transmitter`` component lets you send digital packets to control devices in your home. For example this includes infrared data or 433MHz RF signals. @@ -71,8 +71,8 @@ Configuration variables: - **repeat** (*Optional*): Optionally set the code to be repeated a number of times. Defaults to sending the code only once. - - **times** (int): The number of times to repeat the code. - - **wait_time** (:ref:`config-time`): The time to wait between repeats. + - **times** (:ref:`templatable `, int): The number of times to repeat the code. + - **wait_time** (:ref:`templatable `, :ref:`config-time`): The time to wait between repeats (in µs as a result of a :ref:`lambda `). - **transmitter_id** (*Optional*, :ref:`config-id`): The remote transmitter to send the remote code with. Defaults to the first one defined in the configuration. @@ -82,8 +82,7 @@ Home Assistant, you'll want to set the **times** to 10 and the **wait_time** to .. _remote_transmitter-transmit_abbwelcome: -``remote_transmitter.transmit_abbwelcome`` Action -************************************************* +``remote_transmitter.transmit_abbwelcome`` **Action** This :ref:`action ` sends a ABB-Welcome message to the intercom bus. The message type, addresses, address length and data can vary a lot between ABB-Welcome @@ -123,6 +122,7 @@ Configuration variables: Defaults to a randomly generated ID if this message is not a reply or retransmission. - **data** (**Optional**, 0-7 bytes list): The code to send. Usually you only need to copy this directly from the dumper output. Defaults to ``[]`` +- All other options from :ref:`remote_transmitter-transmit_action`. .. note:: @@ -132,8 +132,7 @@ Configuration variables: .. _remote_transmitter-transmit_aeha: -``remote_transmitter.transmit_aeha`` Action -********************************************* +``remote_transmitter.transmit_aeha`` **Action** This :ref:`action ` sends a AEHA code to a remote transmitter. @@ -150,13 +149,13 @@ Configuration variables: - **data** (**Required**, list): The command to send, A length of 2-35 bytes can be specified for one packet. - **carrier_frequency** (*Optional*, float): Set a frequency to send the signal with for infrared signals. Defaults to ``38000Hz``. +- All other options from :ref:`remote_transmitter-transmit_action`. AEHA refers to the Association for Electric Home Appliances in Japan, a format used by Panasonic and many other companies. .. _remote_transmitter-transmit_byronsx: -``remote_transmitter.transmit_byronsx`` Action -********************************************** +``remote_transmitter.transmit_byronsx`` **Action** This :ref:`action ` sends a Byron Doorbell RF protocol code to a remote transmitter. @@ -171,10 +170,11 @@ Configuration variables: - **address** (**Required**, int): The 8-bit ID to send, see dumper output for more info. - **command** (**Required**, int): The command to send, see dumper output for more info. -- All other options from :ref:`remote_transmitter-transmit_action`... _remote_transmitter-transmit_canalsat: +- All other options from :ref:`remote_transmitter-transmit_action`. -``remote_transmitter.transmit_canalsat`` Action -*********************************************** +.. _remote_transmitter-transmit_canalsat: + +``remote_transmitter.transmit_canalsat`` **Action** This :ref:`action ` sends a CanalSat infrared remote code to a remote transmitter. @@ -200,8 +200,7 @@ Configuration variables: .. _remote_transmitter-transmit_canalsatld: -``remote_transmitter.transmit_canalsatld`` Action -************************************************* +``remote_transmitter.transmit_canalsatld`` **Action** This :ref:`action ` sends a CanalSatLD infrared remote code to a remote transmitter. @@ -227,8 +226,7 @@ Configuration variables: .. _remote_transmitter-transmit_coolix: -``remote_transmitter.transmit_coolix`` Action -********************************************* +``remote_transmitter.transmit_coolix`` **Action** This :ref:`action ` sends one or two (stricted or not) 24-bit Coolix infrared remote codes to a remote transmitter. @@ -243,11 +241,11 @@ Configuration variables: - **first** (**Required**, :ref:`templatable `, uint32_t): The first 24-bit Coolix code to send, see dumper output for more info. - **second** (*Optional*, :ref:`templatable `, uint32_t): The second 24-bit Coolix code to send, see dumper output for more info. +- All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_dish: -``remote_transmitter.transmit_dish`` Action -******************************************* +``remote_transmitter.transmit_dish`` **Action** This :ref:`action ` sends a Dish Network infrared remote code to a remote transmitter. @@ -268,8 +266,7 @@ You can find a list of commands in the `LIRC project ` sends a Dooya RF remote code to a remote transmitter. @@ -292,8 +289,7 @@ Configuration variables: .. _remote_transmitter-transmit_drayton: -``remote_transmitter.transmit_drayton`` Action -********************************************** +``remote_transmitter.transmit_drayton`` **Action** This :ref:`action ` sends a Draton Digistat RF remote code to a remote transmitter. @@ -314,8 +310,7 @@ Configuration variables: .. _remote_transmitter-transmit_jvc: -``remote_transmitter.transmit_jvc`` Action -****************************************** +``remote_transmitter.transmit_jvc`` **Action** This :ref:`action ` sends a JVC infrared remote code to a remote transmitter. @@ -328,11 +323,11 @@ This :ref:`action ` sends a JVC infrared remote code to a remote Configuration variables: - **data** (**Required**, int): The JVC code to send, see dumper output for more info. +- All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_keeloq: -``remote_transmitter.transmit_keeloq`` Action -********************************************** +``remote_transmitter.transmit_keeloq`` **Action** This :ref:`action ` sends KeeLoq RF remote code to a remote transmitter. @@ -358,8 +353,7 @@ Configuration variables: .. _remote_transmitter-transmit_haier: -``remote_transmitter.transmit_haier`` Action -******************************************** +``remote_transmitter.transmit_haier`` **Action** This :ref:`action ` sends a 104-bit Haier code to a remote transmitter. 8-bits of checksum added automatically. @@ -376,8 +370,7 @@ Configuration variables: .. _remote_transmitter-transmit_lg: -``remote_transmitter.transmit_lg`` Action -***************************************** +``remote_transmitter.transmit_lg`` **Action** This :ref:`action ` sends an LG infrared remote code to a remote transmitter. @@ -396,8 +389,7 @@ Configuration variables: .. _remote_transmitter-transmit_magiquest: -``remote_transmitter.transmit_magiquest`` Action -************************************************ +``remote_transmitter.transmit_magiquest`` **Action** This :ref:`action ` sends a MagiQuest wand code to a remote transmitter. @@ -416,8 +408,7 @@ Configuration variables: .. _remote_transmitter-transmit_midea: -``remote_transmitter.transmit_midea`` Action -******************************************** +``remote_transmitter.transmit_midea`` **Action** This :ref:`action ` sends a 40-bit Midea code to a remote transmitter. 8-bits of checksum added automatically. @@ -438,8 +429,7 @@ Configuration variables: - **code** (**Required**, list, :ref:`templatable `): The 40-bit Midea code to send as a list of hex or integers. - All other options from :ref:`remote_transmitter-transmit_action`. -``remote_transmitter.transmit_nec`` Action -****************************************** +``remote_transmitter.transmit_nec`` **Action** This :ref:`action ` sends an NEC infrared remote code to a remote transmitter. @@ -466,8 +456,7 @@ Configuration variables: - **command_repeats** (*Optional*, int): The number of times the command bytes are sent in one transmission. Defaults to `1`. - All other options from :ref:`remote_transmitter-transmit_action`. -``remote_transmitter.transmit_nexa`` Action -******************************************* +``remote_transmitter.transmit_nexa`` **Action** This :ref:`action ` a Nexa RF remote code to a remote transmitter. @@ -492,8 +481,7 @@ Configuration variables: .. _remote_transmitter-transmit_panasonic: -``remote_transmitter.transmit_panasonic`` Action -************************************************ +``remote_transmitter.transmit_panasonic`` **Action** This :ref:`action ` sends a Panasonic infrared remote code to a remote transmitter. @@ -512,8 +500,7 @@ Configuration variables: .. _remote_transmitter-transmit_pioneer: -``remote_transmitter.transmit_pioneer`` Action -********************************************** +``remote_transmitter.transmit_pioneer`` **Action** This :ref:`action ` sends a Pioneer infrared remote code to a remote transmitter. @@ -543,8 +530,7 @@ are largely shared among devices within a given class. .. _remote_transmitter-transmit_pronto: -``remote_transmitter.transmit_pronto`` Action -********************************************* +``remote_transmitter.transmit_pronto`` **Action** This :ref:`action ` sends a raw code to a remote transmitter specified in Pronto format. @@ -562,8 +548,7 @@ Configuration variables: .. _remote_transmitter-transmit_raw: -``remote_transmitter.transmit_raw`` Action -****************************************** +``remote_transmitter.transmit_raw`` **Action** This :ref:`action ` sends a raw code to a remote transmitter. @@ -590,8 +575,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc5: -``remote_transmitter.transmit_rc5`` Action -****************************************** +``remote_transmitter.transmit_rc5`` **Action** This :ref:`action ` sends an RC5 infrared remote code to a remote transmitter. @@ -610,8 +594,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc6: -``remote_transmitter.transmit_rc6`` Action -****************************************** +``remote_transmitter.transmit_rc6`` **Action** This :ref:`action ` sends an RC6 infrared remote code to a remote transmitter. @@ -630,8 +613,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_raw: -``remote_transmitter.transmit_rc_switch_raw`` Action -**************************************************** +``remote_transmitter.transmit_rc_switch_raw`` **Action** This :ref:`action ` sends a raw RC-Switch code to a remote transmitter. @@ -650,28 +632,9 @@ Configuration variables: for more information. - All other options from :ref:`remote_transmitter-transmit_action`. -.. _remote_transmitter-rc_switch-protocol: - -RC Switch Protocol -^^^^^^^^^^^^^^^^^^ - -All RC Switch ``protocol`` settings have these settings: - -- Either the value is an integer, then the inbuilt protocol definition with the given number - is used. -- Or a key-value mapping is given, then there are these settings: - - - **pulse_length** (**Required**, int): The pulse length of the protocol - how many microseconds - one pulse should last for. - - **sync** (*Optional*): The number of high/low pulses for the sync header, defaults to ``[1, 31]`` - - **zero** (*Optional*): The number of high/low pulses for a zero bit, defaults to ``[1, 3]`` - - **one** (*Optional*): The number of high/low pulses for a one bit, defaults to ``[3, 1]`` - - **inverted** (*Optional*, boolean): If this protocol is inverted. Defaults to ``false``. - .. _remote_transmitter-transmit_rc_switch_type_a: -``remote_transmitter.transmit_rc_switch_type_a`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_a`` **Action** This :ref:`action ` sends a type A RC-Switch code to a remote transmitter. @@ -696,8 +659,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_type_b: -``remote_transmitter.transmit_rc_switch_type_b`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_b`` **Action** This :ref:`action ` sends a type B RC-Switch code to a remote transmitter. @@ -722,8 +684,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_type_c: -``remote_transmitter.transmit_rc_switch_type_c`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_c`` **Action** This :ref:`action ` sends a type C RC-Switch code to a remote transmitter. @@ -750,8 +711,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_type_d: -``remote_transmitter.transmit_rc_switch_type_d`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_d`` **Action** This :ref:`action ` sends a type D RC-Switch code to a remote transmitter. @@ -776,8 +736,7 @@ Configuration variables: .. _remote_transmitter-transmit_roomba: -``remote_transmitter.transmit_roomba`` Action -********************************************* +``remote_transmitter.transmit_roomba`` **Action** This :ref:`action ` sends a Roomba infrared remote code to a remote transmitter. @@ -799,8 +758,7 @@ Configuration variables: .. _remote_transmitter-transmit_samsung: -``remote_transmitter.transmit_samsung`` Action -********************************************** +``remote_transmitter.transmit_samsung`` **Action** This :ref:`action ` sends a Samsung infrared remote code to a remote transmitter. It transmits codes up to 64 bits in length in a single packet. @@ -823,8 +781,7 @@ Configuration variables: .. _remote_transmitter-transmit_samsung36: -``remote_transmitter.transmit_samsung36`` Action -************************************************ +``remote_transmitter.transmit_samsung36`` **Action** This :ref:`action ` sends a Samsung36 infrared remote code to a remote transmitter. It transmits the ``address`` and ``command`` in two packets separated by a "space". @@ -844,8 +801,7 @@ Configuration variables: .. _remote_transmitter-transmit_sony: -``remote_transmitter.transmit_sony`` Action -******************************************* +``remote_transmitter.transmit_sony`` **Action** This :ref:`action ` a Sony infrared remote code to a remote transmitter. @@ -864,8 +820,7 @@ Configuration variables: .. _remote_transmitter-transmit_toshiba_ac: -``remote_transmitter.transmit_toshiba_ac`` Action -************************************************* +``remote_transmitter.transmit_toshiba_ac`` **Action** This :ref:`action ` sends a Toshiba AC infrared remote code to a remote transmitter. @@ -885,13 +840,11 @@ Configuration variables: - **rc_code_1** (**Required**, int): The remote control code to send, see dumper output for more details. - **rc_code_2** (*Optional*, int): The secondary remote control code to send; some codes are sent in two parts. - - All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_mirage: -``remote_transmitter.transmit_mirage`` Action -********************************************* +``remote_transmitter.transmit_mirage`` **Action** This :ref:`action ` sends a 112-bit Mirage code to a remote transmitter. 8-bits of checksum added automatically. @@ -906,6 +859,24 @@ Configuration variables: - **code** (**Required**, list): The 14 byte Mirage code to send. - All other options from :ref:`remote_transmitter-transmit_action`. +.. _remote_transmitter-rc_switch-protocol: + +RC Switch Protocol +****************** + +All RC Switch ``protocol`` settings have these settings: + +- Either the value is an integer, then the inbuilt protocol definition with the given number + is used. +- Or a key-value mapping is given, then there are these settings: + + - **pulse_length** (**Required**, int): The pulse length of the protocol - how many microseconds + one pulse should last for. + - **sync** (*Optional*): The number of high/low pulses for the sync header, defaults to ``[1, 31]`` + - **zero** (*Optional*): The number of high/low pulses for a zero bit, defaults to ``[1, 3]`` + - **one** (*Optional*): The number of high/low pulses for a one bit, defaults to ``[3, 1]`` + - **inverted** (*Optional*, boolean): If this protocol is inverted. Defaults to ``false``. + Lambda calls ************ @@ -924,202 +895,15 @@ See the full API Reference for more info. call.set_send_times(2); call.perform(); - -.. _remote-setting-up-infrared: - -Setting up Infrared Devices ---------------------------- - -In this guide an infrared device will be set up with ESPHome. First, the remote code -will be captured with an IR receiver module (like `this one `__). -We will use ESPHome's dumping ability to output the decoded remote code directly. - -Then we will set up a new remote transmitter with an infrared LED (like -`this one `__) to transmit the -code when a switch is triggered. - -First, connect the infrared receiver module to a pin on your board and set up a -remote_receiver instance: - -.. code-block:: yaml - - remote_receiver: - pin: GPIOXX - dump: all - -Compile and upload the code. While viewing the log output from the ESP, -press a button on an infrared remote you want to capture (one at a time). - -You should see log output like below: - -.. code-block:: text - - # If the codec is known: - [D][remote.panasonic] Received Panasonic: address=0x4004 command=0x8140DFA2 - - # Or raw output if it's not known yet - # The values may fluctuate a bit, but as long as they're similar it's ok - [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 - -If the codec is already implemented in ESPHome, you will see the decoded value directly - -otherwise you will see the raw data dump (which you can use just as well). You have -just successfully captured your first infrared code. - -Now let's use this information to emulate a button press from the ESP. First, wire up the -IR diode to a new pin on the ESP and configure a global ``remote_transmitter`` instance: - -.. code-block:: yaml - - remote_transmitter: - pin: GPIOXX - # Infrared remotes use a 50% carrier signal - carrier_duty_percent: 50% - -This will allow us to send any data we want via the IR LED. To replicate the codes we decoded -earlier, create a new template switch that sends the infrared code when triggered: - -.. code-block:: yaml - - switch: - - platform: template - name: Panasonic Power Button - turn_on_action: - - remote_transmitter.transmit_panasonic: - address: 0x4004 - command: 0x8140DFA2 - - # Or for raw code - switch: - - platform: template - name: Raw Code Power Button - turn_on_action: - - remote_transmitter.transmit_raw: - carrier_frequency: 38kHz - code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] - -Recompile again, when you power up the device the next time you will see a new switch -in the frontend. Click on it and you should see the remote signal being transmitted. Done! - -.. _remote-setting-up-rf: - -Setting Up RF Devices ---------------------- - -The ``remote_transmitter`` and ``remote_receiver`` components can also be used to send -and receive 433MHz RF signals. This guide will discuss setting up a 433MHz receiver to -capture a device's remote codes. After that we will set up a 433MHz transmitter to replicate -the remote code with the press of a switch in the frontend. - -First, connect the RF module to a pin on the ESP and set up a remote_receiver instance: - -.. code-block:: yaml - - remote_receiver: - pin: GPIOXX - dump: all - # Settings to optimize recognition of RF devices - tolerance: 50% - filter: 250us - idle: 4ms - buffer_size: 2kb - -Compile and upload the code. While viewing the log output from the ESP, -press a button on an RF remote you want to capture (one at a time). - -You should see log output like below: - -.. code-block:: text - - # If the codec is known: - [D][remote.rc_switch] Received RCSwitch: protocol=2 data='100010000000000010111110' - - # Or raw output if it's not known yet - # The values may fluctuate a bit, but as long as they're similar it's ok - [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 - -.. note:: - - If the log output is flooded with "Received Raw" messages, you can also disable raw - remote code reporting and rely on rc_switch to decode the values. - - .. code-block:: yaml - - remote_receiver: - pin: GPIOXX - dump: - - rc_switch - tolerance: 50% - filter: 250us - idle: 4ms - buffer_size: 2kb - -If the codec is already implemented in ESPHome, you will see the decoded value directly - -otherwise you will see the raw data dump (which you can use just as well). You have -just successfully captured your first RF code. - -Now let's use this information to emulate a button press from the ESP. First, wire up the -RF transmitter to a new pin on the ESP and configure a global ``remote_transmitter`` instance: - -.. code-block:: yaml - - remote_transmitter: - pin: GPIOXX - # RF uses a 100% carrier signal - carrier_duty_percent: 100% - -This will allow us to send any data we want via the RF transmitter. To replicate the codes we decoded -earlier, create a new template switch that sends the RF code when triggered: - -.. code-block:: yaml - - switch: - - platform: template - name: RF Power Button - optimistic: true - turn_on_action: - - remote_transmitter.transmit_rc_switch_raw: - code: '100010000000000010111110' - protocol: 2 - repeat: - times: 10 - wait_time: 0s - - - # Or for raw code - switch: - - platform: template - name: Raw Code Power Button - turn_on_action: - - remote_transmitter.transmit_raw: - code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] - -Recompile again, when you power up the device the next time you will see a new switch -in the frontend. Click on it and you should see the remote signal being transmitted. Done! - -.. note:: - - Some devices require that the transmitted code be repeated for the signal to be picked up - as valid. Also the interval between repetitions can be important. Check that the pace of - repetition logs are consistent between the remote controller and the transmitter node. - You can adjust the ``repeat:`` settings accordingly. - - - See Also -------- - :doc:`index` - :doc:`/components/remote_receiver` +- :ref:`remote-setting-up-infrared` +- :ref:`remote-setting-up-rf` +- :doc:`/components/rf_bridge` - :ref:`lambda_magic_rf_queues` - `RCSwitch `__ by `Suat Özgür `__ -- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ - :apiref:`remote_transmitter/remote_transmitter.h` - :ghedit:`Edit` diff --git a/components/rf_bridge.rst b/components/rf_bridge.rst index 6aa4bc6e1..da6b51dc2 100644 --- a/components/rf_bridge.rst +++ b/components/rf_bridge.rst @@ -21,6 +21,8 @@ which is 19200bps. :align: center :width: 60.0% + Sonoff RF Bridge 433, version R1 or R2 V1.0 + .. code-block:: yaml # Example configuration entry diff --git a/components/sensor/adc.rst b/components/sensor/adc.rst index a95c690e1..d5fe6c2ef 100644 --- a/components/sensor/adc.rst +++ b/components/sensor/adc.rst @@ -63,7 +63,7 @@ ESP32 Attenuation ----------------- On the ESP32 the voltage measured with the ADC caps out at ~1.1V by default as the sensing range (attenuation of the ADC) is set to ``0db`` by default. -Measuring higher voltages requires setting ``attenuation`` to one of the following values: ``0db``, ``2.5db``, ``6db``, ``11db``. +Measuring higher voltages requires setting ``attenuation`` to one of the following values: ``0db``, ``2.5db``, ``6db``, ``12db``. There's more information `at the manufacturer's website `__. To simplify this, we provide the setting ``attenuation: auto`` for an automatic/seamless transition among scales. `Our implementation diff --git a/components/substitutions/index.rst b/components/substitutions/index.rst new file mode 100644 index 000000000..ab83615ee --- /dev/null +++ b/components/substitutions/index.rst @@ -0,0 +1,162 @@ +Substitutions +============= + +.. seo:: + :description: How to use substitutions in ESPHome + :image: settings.svg + +ESPHome has a powerful way to reduce repetition in configuration files: substitutions. +With substitutions, you can have a single generic source file for all nodes of one kind and +substitute expressions in as required. + +.. code-block:: yaml + + substitutions: + bme280_temperature_offset: "-1.0" + + sensor: + - platform: bme280_i2c + temperature: + name: BME280 Temperature + filters: + - offset: ${bme280_temperature_offset} + + +In the top-level ``substitutions`` section, you can put as many key-value pairs as you want. Before +validating your configuration, ESPHome will automatically replace all occurrences of substitutions +by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or +``${substitution_key}`` (same). + +Two substitution passes are performed allowing compound replacements. + +.. code-block:: yaml + + substitutions: + foo: yellow + bar_yellow_value: !secret yellow_secret + bar_green_value: !secret green_secret + + something: + test: ${bar_${foo}_value} + +.. _substitute-include-variables: + +Substitute !include variables +----------------------------- + +ESPHome's ``!include`` accepts a list of variables that can be substituted within the included file. + +.. code-block:: yaml + + binary_sensor: + - platform: gpio + id: button1 + pin: GPIOXX + on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax + - platform: gpio + id: button2 + pin: GPIOXX + on_multi_click: !include + # multi-line syntax + file: on-multi-click.yaml + vars: + id: 2 + +``on-multi-click.yaml``: + +.. code-block:: yaml + + - timing: !include click-single.yaml + then: + - mqtt.publish: + topic: ${device_name}/button${id}/status + payload: single + - timing: !include click-double.yaml + then: + - mqtt.publish: + topic: ${device_name}/button${id}/status + payload: double + +.. _command-line-substitutions: + +Command line substitutions +-------------------------- + +You can define or override substitutions from the command line by adding the ``-s`` switch with arguments ``KEY`` and +``VALUE``. This will override the substitution ``KEY`` and assign it the value ``VALUE``. This switch can be included +multiple times. Consider the following ``example.yaml`` file: + +.. code-block:: yaml + + substitutions: + name: my_default_name + + esphome: + name: $name + +...and the following command: + +.. code-block:: bash + + esphome -s name my_device01 config example.yaml + +You will get something like the following output: + +.. code-block:: yaml + + substitutions: + name: my_device01 + + esphome: + name: my_device01 + # ... + +Command line substitutions take precedence over those in your configuration file. This can be used to create generic +"template" configuration files (like ``example.yaml`` above) which can be used by multiple devices, leveraging +substitutions which are provided on the command line. + +.. _YAML-insertion-operator: + +Bonus: YAML insertion operator +------------------------------ + +Additionally, you can use the YAML insertion operator ``<<`` syntax to create a single YAML file from which a number +of nodes inherit: + +.. code-block:: yaml + + # In common.yaml + esphome: + name: $devicename + # ... + + sensor: + - platform: dht + # ... + temperature: + name: Temperature + humidity: + name: Humidity + +.. code-block:: yaml + + # In nodemcu1.yaml + substitutions: + devicename: nodemcu1 + + <<: !include common.yaml + +.. tip:: + + To hide these base files from the dashboard, you can + + - Place them in a subdirectory (dashboard only shows files in top-level directory) + - Prepend a dot to the filename, like ``.base.yaml`` + +See Also +-------- + +- :doc:`ESPHome index ` +- :doc:`/guides/getting_started_command_line` +- :doc:`/guides/faq` +- :ghedit:`Edit` diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst index 4b39a4b3e..23a943668 100644 --- a/guides/configuration-types.rst +++ b/guides/configuration-types.rst @@ -163,423 +163,6 @@ There are several ways of doing this. See below examples to see how you can spec update_interval: never # never update update_interval: 0ms # update in every loop() iteration -.. _config-substitutions: - -Substitutions -------------- - -ESPHome has a powerful new way to reduce repetition in configuration files: Substitutions. -With substitutions, you can have a single generic source file for all nodes of one kind and -substitute expressions in. - -.. code-block:: yaml - - substitutions: - devicename: livingroom - upper_devicename: Livingroom - - esphome: - name: $devicename - # ... - - sensor: - - platform: dht - # ... - temperature: - name: ${upper_devicename} Temperature - humidity: - name: ${upper_devicename} Humidity - -In the top-level ``substitutions`` section, you can put as many key-value pairs as you want. Before -validating your configuration, ESPHome will automatically replace all occurrences of substitutions -by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or -``${substitution_key}`` (same). - -Two substitution passes are performed allowing compound replacements. - -.. code-block:: yaml - - substitutions: - foo: yellow - bar_yellow_value: !secret yellow_secret - bar_green_value: !secret green_secret - - something: - test: ${bar_${foo}_value} - -.. _YAML-insertion-operator: - -YAML insertion operator -*********************** - -Additionally, you can use the YAML insertion operator ``<<`` syntax to create a single YAML file from which a number -of nodes inherit: - -.. code-block:: yaml - - # In common.yaml - esphome: - name: $devicename - # ... - - sensor: - - platform: dht - # ... - temperature: - name: ${upper_devicename} Temperature - humidity: - name: ${upper_devicename} Humidity - -.. code-block:: yaml - - # In nodemcu1.yaml - substitutions: - devicename: nodemcu1 - upper_devicename: NodeMCU 1 - - <<: !include common.yaml - -.. tip:: - - To hide these base files from the dashboard, you can - - - Place them in a subdirectory (dashboard only shows files in top-level directory) - - Prepend a dot to the filename, like ``.base.yaml`` - -.. _substitute-include-variables: - -Substitute !include variables -***************************** - -ESPHome's ``!include`` accepts a list of variables that can be substituted within the included file. - -.. code-block:: yaml - - binary_sensor: - - platform: gpio - id: button1 - pin: GPIOXX - on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax - - platform: gpio - id: button2 - pin: GPIOXX - on_multi_click: !include - # multi-line syntax - file: on-multi-click.yaml - vars: - id: 2 - -``on-multi-click.yaml``: - -.. code-block:: yaml - - - timing: !include click-single.yaml - then: - - mqtt.publish: - topic: ${device_name}/button${id}/status - payload: single - - timing: !include click-double.yaml - then: - - mqtt.publish: - topic: ${device_name}/button${id}/status - payload: double - -.. _command-line-substitutions: - -Command line substitutions -************************** - -You can define or override substitutions from the command line by adding e.g. ``-s KEY VALUE`` -which overrides substitution KEY and gives it value VALUE. This can be issued multiple times, -so e.g. with the following ``example.yaml`` file: - -.. code-block:: yaml - - substitutions: - name: default - platform: ESP8266 - - esphome: - name: $name - platform: $platform - board: $board - -and the following command: - -.. code-block:: bash - - esphome -s name device01 -s board esp01_1m example.yaml config - -You will get something like the following output (please note the unchanged ``platform``, -added ``board``, and overridden ``name`` substitutions): - -.. code-block:: yaml - - substitutions: - name: device01 - platform: ESP8266 - board: esp01_1m - esphome: - name: device01 - platform: ESP8266 - board: esp01_1m - includes: [] - libraries: [] - esp8266_restore_from_flash: false - build_path: device01 - platformio_options: {} - arduino_version: espressif8266@2.2.3 - -We can observe here that command line substitutions take precedence over the ones in -your configuration file. This can be used to create generic 'template' configuration -files (like the ``example.yaml`` above) which can be used for multiple devices, -using substitutions which are provided on the command line. - -.. _config-packages: - -Packages --------- - -Another way to modularize and reuse your configuration is to use packages. This feature allows -you to put common pieces of configuration in separate files and keep only unique pieces of your -config in the main yaml file. All definitions from packages will be merged with your main -config in non-destructive way so you could always override some bits and pieces of package -configuration. Substitutions in your main config will override substitutions with the same -name in a package. - -Dictionaries are merged key-by-key. Lists of components are merged by component -ID if specified. Other lists are merged by concatenation. All other config -values are replaced with the later value. - -Local packages -************** - -Consider the following example where the author put common pieces of configuration like WiFi and -I²C into base files and extends it with some device specific configurations in the main config. - -Note how the piece of configuration describing ``api`` component in ``device_base.yaml`` gets -merged with the actions definitions from main config file. - -.. code-block:: yaml - - # In config.yaml - substitutions: - node_name: mydevice - device_verbose_name: "My Device" - - packages: - wifi: !include common/wifi.yaml - device_base: !include common/device_base.yaml - - api: - actions: - - action: start_laundry - then: - - switch.turn_on: relay - - delay: 3h - - switch.turn_off: relay - - sensor: - - platform: mhz19 - co2: - name: "CO2" - temperature: - name: "Temperature" - update_interval: 60s - automatic_baseline_calibration: false - -.. code-block:: yaml - - # In wifi.yaml - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - domain: .yourdomain.lan - fast_connect: true - -.. code-block:: yaml - - # In device_base.yaml - esphome: - name: ${node_name} - platform: ESP32 - board: wemos_d1_mini32 - build_path: ./build/${node_name} - - # I²C Bus - i2c: - sda: GPIOXX - scl: GPIOXX - scan: true - frequency: 100kHz - - # Enable logging - logger: - level: ${log_level} - - api: - encryption: - key: !secret api_encryption_key - reboot_timeout: 1h - - sensor: - - <<: !include common/sensor/uptime.config.yaml - - <<: !include common/sensor/wifi_signal.config.yaml - binary_sensor: - - <<: !include common/binary_sensor/connection_status.config.yaml - - switch: - - <<: !include common/switch/restart_switch.config.yaml - -.. _config-git_packages: - -Remote/git Packages -******************* - -Packages can also be loaded from a git repository by utilizing the correct config syntax. -:ref:`config-substitutions` can be used inside the remote packages which allows users to override -them locally with their own subsitution value. - -.. note:: - - Remote packages cannot have ``secret`` lookups in them. They should instead make use of substitutions with an - optional default in the packaged YAML, which the local device YAML can set using values from the local secrets. - -.. code-block:: yaml - - packages: - # Git repo examples - remote_package: - url: https://github.com/esphome/non-existant-repo - ref: main # optional - files: [file1.yml, file2.yml] - refresh: 1d # optional - - # A single file can be expressed using `file` or `files` as a string - remote_package_two: - url: https://github.com/esphome/non-existant-repo - file: file1.yml # cannot be combined with `files` - # files: file1.yml - - # shorthand form github://username/repository/[folder/]file-path.yml[@branch-or-tag] - remote_package_three: github://esphome/non-existant-repo/file1.yml@main - -Packages as Templates -********************* - -Since packages are incorporated using the ``!include`` system, -variables can be provided to them. This means that packages can be -used as `templates`, allowing complex or repetitive configurations to -be stored in a package file and then incorporated into the -configuration more than once. -Additionally packages could contain a ``defaults`` block which provides -subsitutions for variables not provided by the ``!include`` block. - -As an example, if the configuration needed to support three garage -doors using the ``gpio`` switch platform and the ``time_based`` cover -platform, it could be constructed like this: - -.. code-block:: yaml - - # In config.yaml - packages: - left_garage_door: !include - file: garage-door.yaml - vars: - door_name: Left - door_location: left - open_switch_gpio: 25 - close_switch_gpio: 26 - middle_garage_door: !include - file: garage-door.yaml - vars: - door_name: Middle - door_location: middle - open_switch_gpio: 27 - close_switch_gpio: 29 - right_garage_door: !include - file: garage-door.yaml - vars: - door_name: Right - door_location: right - open_switch_gpio: 15 - close_switch_gpio: 18 - open_duration: "1min" - close_duration: "50s" - - -.. code-block:: yaml - - # In garage-door.yaml - defaults: - open_duration: "2.1min" - close_duration: "2min" - - switch: - - id: open_${door_location}_door_switch - name: ${door_name} Garage Door Open Switch - platform: gpio - pin: ${open_switch_gpio} - - - id: close_${door_location}_door_switch - name: ${door_name} Garage Door Close Switch - platform: gpio - pin: ${close_switch_gpio} - - cover: - - platform: time_based - name: ${door_name} Garage Door - - open_action: - - switch.turn_on: open_${door_location}_door_switch - open_duration: ${open_duration} - - close_action: - - switch.turn_on: close_${door_location}_door_switch - close_duration: ${close_duration} - - stop_action: - - switch.turn_off: open_${door_location}_door_switch - - switch.turn_off: close_${door_location}_door_switch - -Extend ------- - -To make changes or add additional configuration to included configurations ``!extend config_id`` can be used, where ``config_id`` is the ID of the configuration to modify. -For example to set a specific update interval on a common uptime sensor that is shared between configurations: - -.. code-block:: yaml - - packages: - common: !include common.yaml - - sensor: - - id: !extend uptime_sensor - update_interval: 10s - -Remove ------- - -To remove existing entries from included configurations ``!remove [config_id]`` can be used, where ``config_id`` is the ID of the entry to modify. -For example to remove a common uptime sensor that is shared between configurations: - -.. code-block:: yaml - - packages: - common: !include common.yaml - - sensor: - - id: !remove uptime_sensor - -To remove captive portal for a specific device: - -.. code-block:: yaml - - packages: - common: !include common.yaml - - captive_portal: !remove - See Also -------- diff --git a/guides/faq.rst b/guides/faq.rst index 722ffdde2..69044a2b3 100644 --- a/guides/faq.rst +++ b/guides/faq.rst @@ -48,7 +48,7 @@ Tips for using ESPHome payload: double - For even more configuration templating, take a look at :ref:`config-substitutions`. + For even more configuration templating, take a look at :doc:`/components/substitutions/index`. 2. If you want to see how ESPHome interprets your configuration, run @@ -66,7 +66,7 @@ Tips for using ESPHome 5. You can view the full list of command line interface options here: :doc:`/guides/cli` -6. Use :ref:`substitutions ` to reduce repetition in your configuration files. +6. Use :doc:`/components/substitutions/index` to reduce repetition in your configuration files. .. |secret| replace:: ``!secret`` .. _secret: https://www.home-assistant.io/docs/configuration/secrets/ diff --git a/guides/setting_up_rmt_devices.rst b/guides/setting_up_rmt_devices.rst new file mode 100644 index 000000000..944161499 --- /dev/null +++ b/guides/setting_up_rmt_devices.rst @@ -0,0 +1,192 @@ +.. seo:: + :description: Set up guide for configuring IR and RF devices in ESPHome. + :image: remote.svg + +.. _remote-setting-up-infrared: + +Setting up IR Devices +===================== + +In this guide an infrared device will be set up with ESPHome. First, the remote code +will be captured with an IR receiver module (like `this one `__). +We will use ESPHome's dumping ability to output the decoded remote code directly. + +Then we will set up a new remote transmitter with an infrared LED (like +`this one `__) to transmit the +code when a button is pressed. + +First, connect the infrared receiver module to a pin on your board and set up a +remote_receiver instance: + +.. code-block:: yaml + + remote_receiver: + pin: GPIOXX + dump: all + +Compile and upload the code. While viewing the log output from the ESP, +press a button on an infrared remote you want to capture (one at a time). + +You should see log output like below: + +.. code-block:: text + + # If the codec is known: + [D][remote.panasonic] Received Panasonic: address=0x4004 command=0x8140DFA2 + + # Or raw output if it's not known yet + # The values may fluctuate a bit, but as long as they're similar it's ok + [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 + +If the codec is already implemented in ESPHome, you will see the decoded value directly - +otherwise you will see the raw data dump (which you can use just as well). You have +just successfully captured your first infrared code. + +Now let's use this information to emulate a button press from the ESP. First, wire up the +IR diode to a new pin on the ESP and configure a global ``remote_transmitter`` instance: + +.. code-block:: yaml + + remote_transmitter: + pin: GPIOXX + # Infrared remotes use a 50% carrier signal + carrier_duty_percent: 50% + +This will allow us to send any data we want via the IR LED. To replicate the codes we decoded +earlier, create a new template button that sends the infrared code when triggered: + +.. code-block:: yaml + + button: + - platform: template + name: Panasonic Power Button + on_press: + - remote_transmitter.transmit_panasonic: + address: 0x4004 + command: 0x8140DFA2 + + # Or for raw code + button: + - platform: template + name: Raw Code Power Button + on_press: + - remote_transmitter.transmit_raw: + carrier_frequency: 38kHz + code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] + +Recompile again, when you power up the device the next time you will see a new button +in the frontend. Click on it and you should see the remote signal being transmitted. Done! + +.. _remote-setting-up-rf: + +Setting up RF Devices +===================== + +The ``remote_transmitter`` and ``remote_receiver`` components can also be used to send +and receive 433MHz Radio Frequency (RF) signals. This guide will discuss setting up a 433MHz +receiver to capture a device's remote codes. After that we will set up a 433MHz transmitter +to replicate the remote code with the press of a button in the frontend. + +First, connect the RF module to a pin on the ESP and set up a remote_receiver instance: + +.. code-block:: yaml + + remote_receiver: + pin: GPIOXX + dump: all + # Settings to optimize recognition of RF devices + tolerance: 50% + filter: 250us + idle: 4ms + buffer_size: 2kb # only for ESP8266 + +Compile and upload the code. While viewing the log output from the ESP, +press a button on an RF remote you want to capture (one at a time). + +You should see log output like below: + +.. code-block:: text + + # If the codec is known: + [D][remote.rc_switch] Received RCSwitch: protocol=2 data='100010000000000010111110' + + # Or raw output if it's not known yet + # The values may fluctuate a bit, but as long as they're similar it's ok + [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 + +.. note:: + + If the log output is flooded with "Received Raw" messages, you can also disable raw + remote code reporting and rely on rc_switch to decode the values. + + .. code-block:: yaml + + remote_receiver: + pin: GPIOXX + dump: + - rc_switch + ... + +If the codec is already implemented in ESPHome, you will see the decoded value directly - +otherwise you will see the raw data dump (which you can use just as well). You have +just successfully captured your first RF code. + +Now let's use this information to emulate a button press from the ESP. First, wire up the +RF transmitter to a new pin on the ESP and configure a global ``remote_transmitter`` instance: + +.. code-block:: yaml + + remote_transmitter: + pin: GPIOXX + # RF uses a 100% carrier signal + carrier_duty_percent: 100% + +This will allow us to send any data we want via the RF transmitter. To replicate the codes we decoded +earlier, create a new template button that sends the RF code when triggered: + +.. code-block:: yaml + + button: + - platform: template + name: RF Power Button + optimistic: true + on_press: + - remote_transmitter.transmit_rc_switch_raw: + code: '100010000000000010111110' + protocol: 2 + repeat: + times: 10 + wait_time: 0s + + + # Or for raw code + button: + - platform: template + name: Raw Code Power Button + on_press: + - remote_transmitter.transmit_raw: + code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] + +Recompile again, when you power up the device the next time you will see a new button +in the frontend. Click on it and you should see the remote signal being transmitted. Done! + +.. note:: + + Some devices require that the transmitted code be repeated for the signal to be picked up + as valid. Also the interval between repetitions can be important. Check that the pace of + repetition logs are consistent between the remote controller and the transmitter node. + You can adjust the ``repeat:`` settings accordingly. + +See Also +-------- + +- :doc:`/components/remote_receiver` +- :doc:`/components/remote_transmitter` 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 2bd2a1caa..f10dcbe5a 100644 --- a/index.rst +++ b/index.rst @@ -174,6 +174,17 @@ ESPHome-specific components or components supporting ESPHome device provisioning Interval, components/interval, description.svg, dark-invert Script, components/script, description.svg, dark-invert +ESPHome Configuration +--------------------- + +Streamline your ESPHome configuration and/or use components provided by other contributors. + +.. imgtable:: + + External Components, components/external_components, external_components.svg, dark-invert + Packages, components/packages/index, description.svg, dark-invert + Substitutions, components/substitutions/index, description.svg, dark-invert + Network Hardware ---------------- @@ -675,7 +686,6 @@ Miscellaneous PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg Pylontech Batteries, components/pylontech, pylontech.jpg Qwiic PIR Motion, components/binary_sensor/qwiic_pir, qwiic_pir.jpg - Remote Receiver, components/remote_receiver, remote.svg, dark-invert Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg Tuya Binary Sensor, components/binary_sensor/tuya, tuya.png WireGuard, components/wireguard, wireguard_custom_logo.svg @@ -808,9 +818,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):