# 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 a git repository
  # - source: github://<user>/<repo>@main
  #   components: [spi_led_strip]
```

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`.
- **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
    data_rate: 1MHz
    effects:
      - addressable_rainbow:
      - addressable_scan:
```

For an APA102 strip, omit `chipset` (or set it to `APA102`).