https://github.com/renggli/esphome-elements
ESPHome custom component for driving LED Matrix.
https://github.com/renggli/esphome-elements
esp32 esphome esphome-component led-matrix
Last synced: 2 months ago
JSON representation
ESPHome custom component for driving LED Matrix.
- Host: GitHub
- URL: https://github.com/renggli/esphome-elements
- Owner: renggli
- License: mit
- Created: 2025-02-01T18:12:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-13T14:23:32.000Z (about 1 year ago)
- Last Synced: 2025-04-13T14:41:09.032Z (about 1 year ago)
- Topics: esp32, esphome, esphome-component, led-matrix
- Language: C++
- Homepage:
- Size: 750 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ESPHome Elements
[](https://github.com/renggli/esphome-elements/actions/workflows/ci.yml)
[](https://github.com/renggli/esphome-elements/issues)
[](https://github.com/renggli/esphome-elements/network)
[](https://github.com/renggli/esphome-elements/stargazers)
[](https://raw.githubusercontent.com/renggli/esphome-elements/main/LICENSE)
Personalize your LED matrix with [ESPHome](https://esphome.io) Elements, a custom component to easily combine text, images, and custom visualizations.
## Basic Setup
To integrate _ESPHome Elements_ into your project, simply add the following to your ESPHome configuration file:
```yaml
external_components:
- source: github://renggli/esphome-elements
```
Next, define an [Addressable Light Component](https://esphome.io/components/light/index.html) that is connected to an [Addressable Light Display](https://esphome.io/components/display/addressable_light.html). Configure both parts according to your display hardware. You do not need to define a `lambda` for rendering, as _ESPHome Elements_ will manage the display updates.
```yaml
light:
# configuration of addressable light component
- id: led_light
...
display:
# configuration of addressable light display
- platform: addressable_light
id: led_display
addressable_light_id: led_light
...
```
Finally, define the `elements` configuration block. This is where you'll bring your display to life. Here's an example showing a default animation of the [custom element](#custom-element):
```yaml
elements:
id: elements_display
display: led_display
element:
type: custom
```
[](https://www.youtube.com/shorts/Ih7tS33tRmk)
For a complete configuration example demonstrating various features, refer to [example.yaml](example.yaml).
## Elements
_ESPHome Elements_ provides a variety of configurable elements to dynamically compose and sequence content on your LED matrix, allowing for sophisticated displays with text, images, and advanced visualizations.
### Common Element Triggers
All elements support the following triggers out-of-the-box:
- **on_show** (Optional, Action): An automation to perform when the element becomes visible on the display. This is useful for performing setup tasks or starting other actions.
- **on_hide** (Optional, Action): An automation to perform when the element is no longer visible on the display. This can be used to clean up resources or stop actions.
### Text Elements
_Displays textual information, labels, or dynamic messages._
There are three text elements with the following specific configuration variables:
1. `static_text` displays a fixed string:
- **text** (Required, string): The string to be displayed. This string remains constant and does not change dynamically.
2. `dynamic_text` uses a lambda function to generate the string
- **lambda** (Required, lambda): A lambda function that returns the string to be displayed. This allows the text to update dynamically based on sensor values, variables, or other changing conditions. The lambda function should return a value of type string, possibly an empty string.
3. `time_text` uses a format string to display date and time
- **time** (Required, ID): The ID of a [time component](https://esphome.io/components/time/index.html). This specifies the source of the time for the clock.
- **format** (Required, string): A format string that defines how the date and time should be displayed. This string uses format specifiers (e.g., `%Y` for year, `%m` for month, `%H` for hour) as defined by the C `strftime` function.
All text elements support the following configuration variables:
- **font** (Required, ID): The ID of the font to use for rendering the text. This links to a font definition within your ESPHome configuration, allowing you to customize the text's appearance.
- **color** (Optional, ID or #rrggbb): The color of the text specified either as an ID reference or as a hexadecimal color code. Defaults to white if not specified.
- **background_color** (Optional, ID or #rrggbb): The background color of the text. Similar to color, this can be an ID reference or a hexadecimal color code. If not specified, the background is transparent.
- **anchor** (Optional, Anchor): Specifies the reference point of the text box with an absolute `offset` and/or a relative `fraction`. This is used in conjunction with align to position the text.
- **align** (Optional, enum): Specifies how the text is aligned at the point defined by the anchor. Possible values are
`TOP`, `CENTER_VERTICAL`, `BASELINE`, `BOTTOM`, `LEFT`, `CENTER_HORIZONTAL`, `RIGHT`, `TOP_LEFT`, `TOP_CENTER`, `TOP_RIGHT`, `CENTER_LEFT`, `CENTER` (default), `CENTER_RIGHT`, `BASELINE_LEFT`, `BASELINE_CENTER`, `BASELINE_RIGHT`, `BOTTOM_LEFT`, `BOTTOM_CENTER`, and `BOTTOM_RIGHT`.
- **scroll_mode** (Optional, enum): Specifies the scrolling behavior of the text, if any. Useful for long texts that exceed the display area. Possible values are `NONE` (default), `LEFT_TO_RIGHT`, `RIGHT_TO_LEFT`, `BOTTOM_TO_TOP`, and `TOP_TO_BOTTOM`. If scrolling is enabled, an `on_complete` trigger is fired each time the animation completes a full pass.
- **scroll_speed** (Optional, float): Specifies the speed of the scrolling animation in pixels per second.
- **on_complete** (Optional, Action): An automation to perform when the text has finished displaying. For scrolling text, this fires once per completed scroll pass. For static or empty text, this fires once per visibility cycle.
The following example scrolls the string "Hello World" over the display:
```yaml
type: static_text
font: font_matrix_chunky_8
scroll_mode: LEFT_TO_RIGHT
text: "Hello World"
```
The following example displays a sensor value:
```yaml
type: dynamic_text
font: font_matrix_chunky_8
lambda: |-
if (id(outside_temperature).has_state()) {
float temp = id(outside_temperature).state;
return str_snprintf("%.1f °C", 12, temp);
}
return "";
```
The following example displays the current time:
```yaml
type: time_text
time: current_time
font: font_matrix_chunky_8
format: "%H:%M:%S"
```
### Image Element
Shows static or animated images on the display.
The following configuration variables are supported:
- **image** (Required, ID): The ID of the image to display. This references an image definition in your configuration.
- **anchor** (Optional, Anchor): Specifies the reference point of the image with an absolute `offset` and/or a relative `fraction`. This is used in conjunction with align to position the image.
- **align** (Optional, enum): Specifies how the image is aligned relative to its anchor point. This determines where the rest of the image is positioned, given the anchor's location. Possible values are `TOP`, `CENTER_VERTICAL`, `BOTTOM`, `LEFT`, `CENTER_HORIZONTAL`, `RIGHT`, `TOP_LEFT`, `TOP_CENTER`, `TOP_RIGHT`, `CENTER_LEFT`, `CENTER` (default), `CENTER_RIGHT`, `BOTTOM_LEFT`, `BOTTOM_CENTER`, `BOTTOM_RIGHT`, `HORIZONTAL_ALIGNMENT`, and `VERTICAL_ALIGNMENT`.
The following example displays the image of a cat:
```yaml
type: image
image: cat
```
### Clock Element
Shows a configurable analog clock on the display.
The following configuration variables are supported:
- **time** (Required, ID): The ID of a [time component](https://esphome.io/components/time/index.html). This specifies the source of the time for the clock.
- **minute_markers** (Optional, AnalogClockOptions): Configuration options for the minute markers. This allows you to customize the appearance of the small lines or dots that indicate the minutes on the clock face.
- **hour_markers** (Optional, AnalogClockOptions): Configuration options for the hour markers. This allows you to customize the appearance of the lines or numbers that indicate the hours on the clock face.
- **quarter_markers** (Optional, AnalogClockOptions): Configuration options for the quarter-hour markers. This allows you to customize the appearance of the markers that indicate the 15-minute intervals.
- **second_hand** (Optional, AnalogClockOptions): Configuration options for the second hand.
- **minute_hand** (Optional, AnalogClockOptions): Configuration options for the minute hand.
- **hour_hand** (Optional, AnalogClockOptions): Configuration options for the hour hand.
For each of the `AnalogClockOptions` the following fields can be defined:
- **start** (Optional, float): The starting position of the marker or hand as a fraction of the clock radius. A value of 0 indicates the center of the clock, and 1 indicates the edge.
- **end** (Optional, float): The ending position of the marker or hand, expressed as a fraction of the clock radius, using the same scale as start.
- **color** (Optional, ID or #rrggbb): The color of the marker or hand. This can be specified as an ID reference to a color defined elsewhere or as a hexadecimal color code.
- **visible** (Optional, boolean): Whether the marker or hand is visible. If set to `false`, the marker or hand will not be displayed.
- **smooth** (Optional, boolean): Whether the hand moves smoothly. If set to `false`, the hand steps to the next increment.
The following example configures the default clock settings. Use this as a template to create your own unique clock face:
```yaml
type: clock
time: current_time
minute_markers:
start: 0.95
end: 1.00
color: "#0000ff"
visible: false
hour_markers:
start: 0.90
end: 1.00
color: "#0000ff"
visible: true
quarter_markers:
start: 0.75
end: 1.00
color: "#0000ff"
visible: true
second_hand:
start: 0.00
end: 0.75
color: "#ff0000"
visible: true
smooth: true
minute_hand:
start: 0.00
end: 0.95
color: "#ffffff"
visible: true
smooth: false
hour_hand:
start: 0.00
end: 0.66
color: "#ffffff"
visible: true
smooth: true
```
### Animation Elements
Provides complex procedural animations to serve as backgrounds or standalone visualizations. The following animations are available:
`aurora_animation`, `fire_animation`, `interference_animation`, `julia_animation`, `kaleidoscope_animation`, `matrix_animation`, `meatballs_animation`, `parallax_animation`, `plasma_animation`, `ripples_animation`, `solid_animation`, `spiral_animation`, `stars_animation`, `tunnel_animation`, `voronoi_animation`, and `wave_animation`.
All animations support the following configuration variables:
- **color_scheme** (Optional, ColorScheme): Configures the color palette and gradients of the animation. Depending on the `type`, it can be `static`, `gradient`, `sequence`, `mirror`, `inverse`, `monochromatic`, `analogous`, `complementary`, `split_complementary`, `triadic`, or `square`.
- **speed** (Optional, float): A multiplier to speed up or slow down the animation. Defaults to `1.0`.
Depending on the animation type, extra options like `strength`, `cooling`, `length`, `density`, `fade_steps`, `count`, `shape`, or `layers` might also be available.
The `solid_animation` supports the following shapes:
- **Platonic solids:** `tetrahedron`, `cube`, `octahedron`, `icosahedron`, `dodecahedron`
- **Archimedean solids:** `truncated_tetrahedron`, `cuboctahedron`, `truncated_cube`, `truncated_octahedron`, `rhombicuboctahedron`, `truncated_cuboctahedron`, `snub_cube`, `icosidodecahedron`, `truncated_dodecahedron`, `truncated_icosahedron`, `rhombicosidodecahedron`, `truncated_icosidodecahedron`, `snub_dodecahedron`
- **Others:** `triangular_prism`, `pentagonal_prism`, `square_antiprism`, `pentagonal_antiprism`, `triangular_bipyramid`, `square_bipyramid`, `pentagonal_bipyramid`, `sphere`
### Custom Element
Allows for user-defined, highly specific visual elements or behaviors beyond the built-in options.
The following configuration variables are supported:
- **draw** (Optional, lambda): A lambda function that defines how the element is rendered on the display. This is the core of a custom element, allowing you to draw anything you want using the [Display](https://esphome.io/components/display/index.html#display-rendering-engine) drawing primitives. The variable `element` refers to the custom element, `display` to the render display. If the lambda is not set, the [default lissajous animation](#basic-setup) is displayed.
- **is_active** (Optional, lambda): A lambda that returns a boolean which determines whether the element is currently active and should be displayed. The variable `element` refers to the custom element.
The following example displays a yellow circle when the weather is sunny, and otherwise a blue rectangle:
```yaml
type: custom
is_active: |-
return id(outside_weather).has_state();
draw: |-
auto state = id(outside_weather).state;
if (state == "sunny") {
display.filled_circle(16, 16, 8, Color(0xffff00));
} else {
display.filled_rectangle(8, 8, 16, 16, Color(0x0000ff));
}
```
### Composition Elements
Arranges multiple elements within the display area to create a cohesive visual layout.
1. `horizontal` displays its children evenly spaced horizontally from left to right.
2. `vertical` displays its children evenly spaced vertically from top to bottom.
3. `overlay` displays its children on top of each other.
The following configuration variables are supported:
- **active_mode** (Optional, enum): Specifies how the activity state of the children should propagate to the container. Possible values are:
- `ALWAYS`: the container is always active;
- `ANY`: the container is active, if any of its children are (default for `overlay`);
- `ALL`: the container is active, if all of its children are (default for `horizontal` and `vertical`); and
- `NEVER`: the container is never active.
- **elements** (Required, Array<Element>): A list of child elements in the desired drawing order.
The following example displays the string "Time" above the current time:
```yaml
type: vertical
elements:
- type: static_text
font: font_matrix_chunky_8
text: "Time"
- type: time_text
time: current_time
font: font_matrix_chunky_8
format: "%H:%M:%S"
```
### Selection Elements
This category of elements displays exactly one child at a time, with different strategies for choosing which one.
- `priority`: Displays the first active child element in its list, re-evaluated each frame based on each child's `is_active` state.
- `sequence`: Presents its children in a defined order. Use the `elements.next` and `elements.prev` actions to advance to the next or previous active child.
- `random`: Shows its active children in a random order, avoiding recently shown items. Use the `elements.next` and `elements.prev` actions to advance to another child.
**Navigation Actions:**
To control `sequence` and `random` elements from automations, use their respective actions:
- `elements.next` / `elements.prev`
Both require the `id` of the target element.
The following configuration variables are supported:
- **elements** (Required, Array<Element>): A list of child elements.
- **on_change** (Optional, Action): An automation to perform when the active child changes. The variables `from_index` and `to_index` provide the indices of the transition.
### Delegate Elements
Changes the default behavior of elements by wrapping them.
- `timeout`: Wraps a single child element and fires an `on_complete` trigger after a configurable duration of being visible. The timer resets each time the element becomes visible.
- **duration** (Optional, time): The time after which the `on_complete` trigger fires.
- **on_complete** (Optional, Action): An automation to perform when the timeout elapses.
The following configuration variable is supported:
- **element** (Required, Element): A single child element.