mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-02-02 23:31:30 +01:00
Add docs for addressable_light display (#755)
This commit is contained in:
parent
e7c82f4c5b
commit
ced6164e59
146
components/display/addressable_light.rst
Normal file
146
components/display/addressable_light.rst
Normal file
@ -0,0 +1,146 @@
|
|||||||
|
Addressable Light
|
||||||
|
=================
|
||||||
|
|
||||||
|
.. seo::
|
||||||
|
:description: Instructions for setting up displays using addressable lights and LED matrix
|
||||||
|
:image: addressable_light.jpg
|
||||||
|
|
||||||
|
The ``addressable_light`` display platform allows to display text and graphics on an addressable
|
||||||
|
light that has been arranged in a display matrix.
|
||||||
|
|
||||||
|
The display requires that an :apiclass:`AddressableLight <light::AddressableLight>` component, such as
|
||||||
|
:doc:`/components/light/fastled` or :doc:`/components/light/neopixelbus`, be defined.
|
||||||
|
|
||||||
|
.. figure:: images/addressable_light.jpg
|
||||||
|
:align: center
|
||||||
|
:width: 75.0%
|
||||||
|
|
||||||
|
WS2812B Addressable Light Display
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
light:
|
||||||
|
- platform: fastled_clockless
|
||||||
|
chipset: WS2812B
|
||||||
|
pin: GPIO4
|
||||||
|
num_leds: 64
|
||||||
|
rgb_order: GRB
|
||||||
|
name: "led_matrix"
|
||||||
|
id: led_matrix_light
|
||||||
|
default_transition_length: 0s
|
||||||
|
color_correct: [50%, 50%, 50%]
|
||||||
|
restore_mode: ALWAYS_ON
|
||||||
|
|
||||||
|
display:
|
||||||
|
- platform: addressable_light
|
||||||
|
id: led_matrix_display
|
||||||
|
addressable_light_id: led_matrix_light
|
||||||
|
width: 8
|
||||||
|
height: 8
|
||||||
|
rotation: 180°
|
||||||
|
update_interval: 16ms
|
||||||
|
lambda: |-
|
||||||
|
// Draw a bulls-eye pattern
|
||||||
|
Color red = Color(0xFF0000);
|
||||||
|
Color green = Color(0x00FF00);
|
||||||
|
Color blue = Color(0x0000FF);
|
||||||
|
it.rectangle(0, 0, 8, 8, red);
|
||||||
|
it.rectangle(1, 1, 6, 6, green);
|
||||||
|
it.rectangle(2, 2, 4, 4, blue);
|
||||||
|
it.rectangle(3, 3, 2, 2, red);
|
||||||
|
|
||||||
|
Configuration variables:
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
- **addressable_light_id** (**Required**, :ref:`config-id`): The id of the addressable light component to use
|
||||||
|
as a display.
|
||||||
|
- **width** (**Required**, int): The width of the LED matrix in pixels.
|
||||||
|
- **height** (**Required**, int): The height of the LED matrix in pixels.
|
||||||
|
- **rotation** (*Optional*): Set the rotation of the display. Everything you draw in ``lambda:`` will be rotated
|
||||||
|
by this option. One of ``0°`` (default), ``90°``, ``180°``, ``270°``.
|
||||||
|
- **update_interval** (*Optional*, :ref:`config-time`): The interval to call the lambda to update the display.
|
||||||
|
Defaults to ``16ms``.
|
||||||
|
- **pixel_mapper** (*Optional*, :ref:`lambda <config-lambda>`): A lambda that returns the integer address of the LED
|
||||||
|
given the supplied the ``x`` and ``y`` pixel coordinate. By default, a left-to-right direct pixel mapper is used.
|
||||||
|
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
|
||||||
|
``it`` will be an instance of :apiclass:`DisplayBuffer <display::DisplayBuffer>`.
|
||||||
|
See :ref:`display-engine` for more information.
|
||||||
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||||
|
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
When enabled (the default, but also via ``it.set_enabled(true)``), any effect currently running on the
|
||||||
|
addressable light will be disabled. When disabled (``it.set_enabled(false)``), the last configured effect will
|
||||||
|
be restored.
|
||||||
|
|
||||||
|
While the display is enabled, it is still possible to control the parent addressable light component in some
|
||||||
|
limited capacity. Changing the brightness will still work, but changing the color will have no affect. It is not
|
||||||
|
adivsable to enable any effects (ex: rainbow, color wipe, etc) while the display is enabled, as this will cause a
|
||||||
|
great deal of flickering while the effect competes with the display for rendering.
|
||||||
|
|
||||||
|
|
||||||
|
pixel_mapper
|
||||||
|
------------
|
||||||
|
|
||||||
|
An addressable LED matrix is just an addressable LED strip laid out in a matrix -- the path often snaking
|
||||||
|
down-up-down, left-right-left, or whichever way the manufacturer has chosen. Like an addressable LED strip,
|
||||||
|
each pixel on a matrix is addressed as an offset from the first pixel (0). The job of the pixel mapper is
|
||||||
|
to translate a logical x-y pixel coordinate to the address of the expected physical LED.
|
||||||
|
|
||||||
|
Determining the correct algorithm for the pixel mapper for your matrix will hopefully only require some graph paper and a little bit of math.
|
||||||
|
|
||||||
|
|
||||||
|
Default
|
||||||
|
*******
|
||||||
|
|
||||||
|
The default pixel mapper assumes that the led matrix is addressed starting with the top left LED, moving to the right, and
|
||||||
|
then starting with the left-most row of the next row.
|
||||||
|
|
||||||
|
.. figure:: images/addressable_light_pixel_map_default.png
|
||||||
|
:align: center
|
||||||
|
:width: 75.0%
|
||||||
|
|
||||||
|
Default pixel_mapper as used with a 4x4 led matrix
|
||||||
|
|
||||||
|
|
||||||
|
BTF-Lighting 8x32 WS2812B Flexible LED Matrix
|
||||||
|
*********************************************
|
||||||
|
|
||||||
|
The following image illustrates the path the addressable strip takes through the common the BTF-Lighting 8x32 matrix.
|
||||||
|
|
||||||
|
.. figure:: images/addressable_light_pixel_map_8x32.png
|
||||||
|
:align: center
|
||||||
|
:width: 75.0%
|
||||||
|
|
||||||
|
LED layout for BTF-Lighting 8x32 WS2812B Flexible LED Matrix
|
||||||
|
|
||||||
|
|
||||||
|
Below is a definition that includes a pixel_mapper suitable for these 8x32 matrices.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
display:
|
||||||
|
- platform: addressable_light
|
||||||
|
id: led_matrix_32x8_display
|
||||||
|
addressable_light_id: led_matrix_32x8
|
||||||
|
width: 32
|
||||||
|
height: 8
|
||||||
|
pixel_mapper: |-
|
||||||
|
if (x % 2 == 0) {
|
||||||
|
return (x * 8) + y;
|
||||||
|
}
|
||||||
|
return (x * 8) + (7 - y);
|
||||||
|
rotation: 0°
|
||||||
|
update_interval: 16ms
|
||||||
|
|
||||||
|
|
||||||
|
See Also
|
||||||
|
--------
|
||||||
|
|
||||||
|
- :apiref:`addressable_light/addressable_light_display.h`
|
||||||
|
- :doc:`/components/light/index`
|
||||||
|
- :doc:`/components/light/fastled`
|
||||||
|
- :doc:`/components/light/neopixelbus`
|
||||||
|
- :doc:`/components/light/partition`
|
||||||
|
- :ghedit:`Edit`
|
BIN
components/display/images/addressable_light.jpg
Normal file
BIN
components/display/images/addressable_light.jpg
Normal file
Binary file not shown.
After Width: | Height: | Size: 92 KiB |
BIN
components/display/images/addressable_light_pixel_map_8x32.png
Normal file
BIN
components/display/images/addressable_light_pixel_map_8x32.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
After Width: | Height: | Size: 20 KiB |
BIN
images/addressable_light.jpg
Normal file
BIN
images/addressable_light.jpg
Normal file
Binary file not shown.
After Width: | Height: | Size: 26 KiB |
@ -281,6 +281,7 @@ Display Components
|
|||||||
.. imgtable::
|
.. imgtable::
|
||||||
|
|
||||||
Display Core, components/display/index, folder-open.svg
|
Display Core, components/display/index, folder-open.svg
|
||||||
|
Addressable Light, components/display/addressable_light, addressable_light.jpg
|
||||||
LCD Display, components/display/lcd_display, lcd.jpg
|
LCD Display, components/display/lcd_display, lcd.jpg
|
||||||
MAX7219, components/display/max7219, max7219.jpg
|
MAX7219, components/display/max7219, max7219.jpg
|
||||||
MAX7219 Dot Matrix, components/display/max7219digit, max7219digit.png
|
MAX7219 Dot Matrix, components/display/max7219digit, max7219digit.png
|
||||||
|
Loading…
Reference in New Issue
Block a user