custom-components/README.md

ESPHome Custom Components

A collection of custom components for ESPHome, loaded via external_components.

Usage

Reference this repository (or a local checkout of it) in your device configuration:

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	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. 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.

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.

The strip has no chip select line, so cs_pin is not required.

Example

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).