83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
# ESPHome Custom Components
|
|
|
|
A collection of custom components for [ESPHome](https://esphome.io), loaded via
|
|
[`external_components`](https://esphome.io/components/external_components/).
|
|
|
|
## Usage
|
|
|
|
Reference this repository (or a local checkout of it) in your device configuration:
|
|
|
|
```yaml
|
|
external_components:
|
|
# from a local checkout
|
|
- source:
|
|
type: local
|
|
path: /path/to/esphome_custom/components
|
|
components: [spi_led_strip]
|
|
|
|
# or from the git repository
|
|
- source:
|
|
type: git
|
|
url: https://git.mindplots.home-webserver.de/esphome/custom-components.git
|
|
ref: main
|
|
components: [spi_led_strip]
|
|
```
|
|
|
|
*Note:* Listing a component under `components:` overrides an ESPHome built-in component with the same name.
|
|
|
|
## Components
|
|
|
|
| Component | Platform | Description |
|
|
|-----------|----------|-------------|
|
|
| [`spi_led_strip`](#spi_led_strip) | `light` | Addressable LED strips driven over SPI (APA102, WS2801) |
|
|
|
|
---
|
|
|
|
### `spi_led_strip`
|
|
|
|
An addressable light for LED strips with separate clock and data lines, driven over the
|
|
[SPI bus](https://esphome.io/components/spi/). It is based on ESPHome's built-in
|
|
`spi_led_strip` and adds support for the **WS2801** chipset next to **APA102**.
|
|
|
|
| Chipset | Frame format | SPI mode |
|
|
|----------|--------------|----------|
|
|
| `APA102` (default) | 4-byte start frame, `0xFF` + B, G, R per LED, 4-byte end frame | default (`MODE3`) |
|
|
| `WS2801` | R, G, B per LED, no framing; data latches when the clock stays low for 500 µs | `MODE0` (clock idles low) |
|
|
|
|
The component exposes an RGB light and supports all
|
|
[addressable light effects](https://esphome.io/components/light/#light-effects).
|
|
|
|
**Configuration variables**
|
|
|
|
- **chipset** (*Optional*, string): `APA102` or `WS2801`. Defaults to `APA102`.
|
|
- **num_leds** (*Optional*, int): Number of LEDs in the strip. Defaults to `1`.
|
|
- **rgb_order** (*Optional*, string): The order in which the color bytes of each LED are sent.
|
|
One of `RGB`, `RBG`, `GRB`, `GBR`, `BGR`, `BRG`. Defaults to `BGR` for `APA102` and `RGB` for `WS2801`.
|
|
Change this if the colors on your strip come out swapped.
|
|
- **data_rate** (*Optional*): SPI clock frequency. Defaults to `1MHz`.
|
|
- **spi_id** (*Optional*, ID): The SPI bus to use, if more than one is configured.
|
|
- All other options from [Light](https://esphome.io/components/light/#config-light).
|
|
|
|
The strip has no chip select line, so `cs_pin` is not required.
|
|
|
|
**Example**
|
|
|
|
```yaml
|
|
spi:
|
|
clk_pin: GPIO18
|
|
mosi_pin: GPIO23
|
|
|
|
light:
|
|
- platform: spi_led_strip
|
|
name: "WS2801 Strip"
|
|
chipset: WS2801
|
|
num_leds: 32
|
|
rgb_order: RGB
|
|
data_rate: 1MHz
|
|
effects:
|
|
- addressable_rainbow:
|
|
- addressable_scan:
|
|
```
|
|
|
|
For an APA102 strip, omit `chipset` (or set it to `APA102`).
|