Skip to content

Adding the LED & Buzzer module

The LED & Buzzer is the starter kit's notification module, a strip of ten addressable RGB LEDs and a small piezo buzzer behind the ESPHome logo silkscreen. By the end of this tutorial you'll have the lights and buzzer wired to your ESP32-C6, surfaced in your YAML, and ready to flash, animate, or sing in response to anything else you build.

Before you start

Work through the two prerequisites first:

  • Start Here to snap the RGB & Buzzer module off the panel.
  • First Steps to install ESPHome Device Builder and create your starter kit device.

Attach LED & Buzzer module

Connect the LED & Buzzer module to the ESP32-C6 using one of the FPC ribbon cables that came with the kit. Either FPC connector on the ESP32-C6 works, top or bottom.

1. Unplug the USB-C cable from the ESP32-C6 so it is powered off.

Unplugging the USB-C cable from the ESP32-C6 board

Handle the FPC connectors gently

The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself.

2. Flip up the latch on the FPC connector then gently slide the ribbon cable into the connector with the blue side facing upwards. Gently press the latch down to lock it in place.

Sliding the FPC ribbon cable, blue side up, into the ESP32-C6 connector and closing the latch

3. Slide the ribbon cable into the LED & Buzzer module with the blue side facing upwards then press the latch down to lock it in place.

Connecting the other end of the FPC ribbon cable to the LED & Buzzer module

4. Plug the ESP32-C6 back into your computer.

Add to ESPHome Device Builder

ESPHome Device Builder ships an Add Component flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the LED strip and buzzer config by hand, and you'll get the right GPIOs, chipset, and PWM setup on the first try.

  1. Open your starter kit device in Device Builder and click Edit.

  2. Navigate to the Components section and look for a GPIO Switch named Accessory Power. The LED & Buzzer module gets its power from that switch, so without it the LEDs and buzzer don't get enough power to work. (1)

    1. Projects you created from the Apollo ESPHome Starter Kit board already include it, and the component picker hides it once your device has it. That's why it isn't in the list of components you can add.

  3. If it isn't there, click Add Component, find the Accessory Power Rail card, and click Add. (1)

    1. Accessory Power Rail covers what the switch does and the settings worth knowing about.

  4. Click Add Component in the editor toolbar.

  5. Select the RGB LED + Buzzer Module Bundle at the top.
  6. Click Add -> Click Add -> Click Add -> Click Add. Each section lets you make changes but we will leave them at defaults for now. Device Builder inserts the light, output, and rtttl blocks into your YAML.

ESPHome Device Builder adding the RGB LED + Buzzer Module bundle and clicking Add through each step

What the LED & Buzzer Module YAML does

The blocks Add Component drops into your config look like this:

light:
  - platform: esp32_rmt_led_strip
    name: RGB LEDs
    pin: 14
    id: rgb_leds
    chipset: WS2812
    num_leds: 10
    channel_colors: GRB
    rmt_symbols: 48

output:
  - platform: ledc
    pin: 18
    id: buzzer_output

rtttl:
  - output: buzzer_output
    id: rtttl_player

Each option does something specific:

Option What it does
LED strip
light.platform: esp32_rmt_led_strip Uses the ESP32's RMT peripheral to drive addressable LEDs with precise timing.
light.name: RGB LEDs The friendly name shown in Home Assistant and the web server.
light.pin: 14 The data line (GPIO14) going to the first LED on the PCB.
light.id: rgb_leds Internal handle you can reference from automations and lambdas elsewhere in the config.
light.chipset: WS2812 Which addressable LED protocol to use. WS2812 is the most common, sometimes also called NeoPixel.
light.num_leds: 10 The number of LEDs on the RGB & Buzzer module.
light.channel_colors: GRB Color channel order. WS2812 LEDs receive color data in green-red-blue order, so this makes sure red looks red and not green.
light.rmt_symbols: 48 Low-level RMT setting needed on the ESP32-C6. Leave it at 48.
Piezo buzzer
output.platform: ledc PWM output for driving the buzzer. PWM is how digital pins create audio tones on a piezo.
output.pin: 18 The pin the buzzer is wired to (GPIO18).
output.id: buzzer_output Internal handle the rtttl component uses to send tones to this output.
rtttl.output: buzzer_output Tells rtttl to use the buzzer output for playback.
rtttl.id: rtttl_player Internal handle for triggering tunes from automations and lambdas.

Install the software

Flash the device so the new RGB & Buzzer entities go live.

  1. Click Install at the bottom right of the editor. (1)

    1. We say software because it's the friendlier word. The technically correct term is firmware: code that runs directly on the chip instead of on a computer. That's the word ESPHome's own docs use.

  2. Choose On the network if the device is already on your Wi-Fi, or Plug into this computer to flash over USB.

  3. Wait for the compile and flash to finish. First builds can take a few minutes.
  4. The device reboots and reconnects to your Wi-Fi on its own.

ESPHome Device Builder clicking Install, choosing On the network, and compiling the LED and buzzer config

Test the LEDs

With the device back online, the RGB LED light entity is live on the web server. Open it in a browser on the same network and play with it.

  1. In a browser, open http://<your-device-name>.local/. If you used esphome-starter-kit as the device name in First Steps, that's http://esphome-starter-kit.local/.
  2. Toggle the RGB LEDs entity and play around with the colors and brightness. (1)
  1. There's a lot you can do with a light entity. See the Light Effects tutorial for advanced configurations, or the ESPHome light strip effects documentation to go deeper.

Starter kit web server turning on the RGB LEDs and picking a new color

LEDs stay dark?

Check that the Accessory Power switch on the same web page is on, and that it's still in your project's Components section. The module runs off the Accessory Power Rail, so without it the LEDs and buzzer don't get enough power to work.

Your LED & Buzzer notification module is wired up!

Your LED & Buzzer Module is now ready for some fun tasks, like toggling lights on and off, playing with the colors, or using the buzzer to play fun tunes!

The buzzer doesn't have its own web server control, since it's an output rather than a switch. Once you've added the device to Home Assistant, you can trigger tunes with the rtttl.play action or by exposing your own service. See Play a Tune from Home Assistant to learn how to set it up.

Try it in an automation

Your notification module is ready. Drive it from any of these automations:

ESPHome logo Button Controlled LEDs ESPHome logo Play a Tune ESPHome logo Temp-Reactive LEDs ESPHome logo Motion-Activated Light

New to ESPHome? We're here to help.

Stuck on a step or want to show off what you built? Ask questions and share projects with the Apollo community.

Join our Discord Community Forum