Skip to content

Control an LED strip with the GPIO Header

The GPIO Header addon brings the AIR-1's spare pins out to a row of headers, so you can hang your own hardware off the sensor. This guide wires a WS2812B strip to one of those pins and gets it into Home Assistant as its own light entity, color picker and effects included.

Click any photo to see it full size.

What you need

  • An Apollo AIR-1.
  • The Apollo GPIO Header addon, which ships with a replacement AIR-1 lid.
  • A WS2812B (neopixel) RGB strip. SK6812 RGBW strips work too.
  • Three male-to-male DuPont wires. A set comes with the header.
  • A USB-C cable and power brick.

Watch the current draw

The 5V pin supplies up to 300mA. A meter of 60 LEDs at full white draws far more than that, so anything longer than a short strip needs its own 5V supply. You can power the AIR-1 itself from the 5V and GND pins instead of the USB-C port, but use one or the other, never both.

Choosing a data pin

IO2, IO4, IO6, and IO7 are free for LED data, and you can drive more than one strip by giving each its own pin. IO18 and IO19 are unavailable, and IO0 and IO1 are reserved for I2C sensors. This guide uses IO7, plus the 5V and GND pins at the top of the header for power.

Pinout diagram of the Apollo GPIO Header showing the 5V, GND, and IO pins

Attaching the GPIO Header

Opening an AIR-1 takes a few more steps than the other Apollo sensors, because the PCB slides out of the case. The GPIO Header addon page has photos of each one.

  1. Unplug the AIR-1, lift the lid off, and slide the PCB out to the left.

  2. Flip the PCB over and find the small black mezzanine connector in the top right corner. An X marks the corner, and the GPIO Header has a matching X on its own board.

    Mezzanine connector on the back of the AIR-1 PCB with the X marking The matching X marking on the GPIO Header board

  3. Line the two X markings up and press the header gently onto the connector.

    GPIO Header aligned over the AIR-1 mezzanine connector GPIO Header being pressed onto the connector GPIO Header fully seated on the AIR-1 PCB

  4. Flip the PCB back over and slide it into the new lid that came with the addon. There are three channels in the plastic for it to run in, so it should go most of the way with light pressure.

    AIR-1 PCB sliding into the replacement GPIO lid PCB seated in the channels of the new lid

  5. Push the case back together.

    AIR-1 case being closed around the new lid AIR-1 case closing with the GPIO Header inside Reassembled AIR-1 with the GPIO Header pins exposed

Wiring the strip

  1. Run three wires from the header to the strip: 5V, GND, and data. Matching the colors to the strip's own wiring saves a lot of squinting later, so use red for 5V, white for GND, and green for data on IO7.

    Red, white, and green DuPont wires laid out next to the GPIO Header DuPont wires pushed onto the 5V, GND, and IO7 pins Close-up of the three wires seated on the GPIO Header

  2. Plug the other end into the strip. Most strips come with a JST-SM pigtail carrying the same three colors, so the wires match up directly. The connector is rated to 3A.

    JST-SM connector on the end of a WS2812B strip DuPont wires plugged into the strip's JST-SM connector

  3. Check the direction before you power anything on. Arrows printed along the strip show which way data flows, and they need to point away from the AIR-1.

    Direction arrow printed on the LED strip pointing away from the sensor The wired end of the strip with the arrow running down its length

A dab of hot glue across the outer shells of the three DuPont connectors stiffens them into a single plug. (1)

  1. Keep glue out of the header's female pins. It will ruin the addon.

Hot glue joining the outer shells of three DuPont connectors

Adding the strip to your YAML

The AIR-1 knows nothing about the strip until you tell it how many LEDs there are and which pin they sit on.

  1. Open the ESPHome Device Builder app, find your AIR-1, and click Edit.

    The ESPHome Device Builder editor open on an Apollo device configuration

  2. Add the block below at the bottom of the file, flush with the left margin so light: lines up with packages: and wifi:. Set num_leds to the number of LEDs on your strip, and change pin if you wired to a different port.

    light:
  - platform: esp32_rmt_led_strip
    id: bed_led
    name: "Bed LED"
    pin: GPIO7
    chipset: WS2812
    rgb_order: grb
    num_leds: 60
    default_transition_length: 0s
    effects:
      - pulse:
          name: "Slow Pulse"
          transition_length: 1000ms
          update_interval: 1000ms
          min_brightness: 50%
          max_brightness: 100%
      - pulse:
          name: "Fast Pulse"
          transition_length: 100ms
          update_interval: 100ms
          min_brightness: 50%
          max_brightness: 100%
      - addressable_rainbow:

  3. Check that the editor shows no red error markers.

    The ESPHome editor showing the new light block with no errors flagged

  4. Click Save, then Install, and pick Wirelessly. ESPHome compiles the firmware and sends it to the AIR-1. The first build takes a few minutes.

Older versions of this guide set rmt_channel: 1 on the light. ESPHome dropped that option, and leaving it in now fails validation, so the block above does not use it.

The ESPHome light effects reference covers everything else you can add under effects:, including addressable_scan.

Controlling it from Home Assistant

Once the install finishes, the AIR-1 exposes a new light entity called Bed LED.

The Bed LED entity listed on the device page in Home Assistant

Click the entity name to open the light card. The color wheel covers the full range, and the effects list holds the two pulses and the rainbow from the YAML above.

Home Assistant light card for Bed LED Color wheel open on the Bed LED card Effect list showing Slow Pulse, Fast Pulse, and rainbow

WS2812B strip lit up in color behind a bed

That's all folks! Thanks to Smart Home Sellout for putting this tutorial together.