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

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
    rgb_order: RGB
    data_rate: 1MHz
    effects:
      - addressable_rainbow:
      - addressable_scan:

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