DRV-29: Add Siren entity support

[svc-finitelabs]

Summary

Add support for ESPHome siren entities in the Control4 ESPHome driver.

Siren entities represent audible/visual alarms (buzzers, sirens, LED flashers). They are exposed as relay bindings with on/off control, plus optional tone, volume, and duration parameters when the device supports them.

Changes

• src/esphome/entities/siren.lua: Siren entity with RELAY binding, handling ON/OFF/TOGGLE commands via the siren_command RPC. Conditionally exposes tone, volume, and duration based on entity capabilities.
• drivers/esphome/driver.lua: Register SirenEntity in the entity table.
• drivers/esphome/driver.xml: Add Set Siren Tone programming command with Siren/Tone dynamic list params.
• CHANGELOG.md: Add changelog entry.

Implementation Details

On/Off (always)

• BOOL variable {name} State tracks on/off
• RELAY binding for Control4 programming integration
• siren_command RPC with has_state flag (required by the ESPHome protobuf API)
• Write callback on the variable allows Control4 programming to command the siren
• Proxy notifications (CLOSED/OPENED) keep relay state in sync

Tone (when entity.tones is non-empty)

• Set Siren Tone programming command (GCPL/EC pattern like Set Select)
• Siren dropdown populated from discovered sirens, Tone dropdown from reported tones
• Sends siren_command with has_tone=true, tone=<selected>

Volume (when entity.supports_volume is true)

• Writable NUMBER variable {name} Volume (0-100 in C4)
• Normalized to 0.0-1.0 for the ESPHome float field
• Sends siren_command with has_volume=true, volume=<normalized>

Duration (when entity.supports_duration is true)

• Writable NUMBER variable {name} Duration (seconds, uint32)
• Sends siren_command with has_duration=true, duration=<value>

Fixes DRV-29

[derek-miller]

Can you recommend any esphome devices with this entity? Or a way to build a mock one? I need something to test this with.

[svc-finitelabs]

Good question. A few options:

Easiest: Template siren (no hardware needed)

You can create a virtual siren entity on any ESP32 running ESPHome. Just add a template siren to your YAML config:

siren:
  - platform: template
    name: "Test Siren"
    turn_on_action:
      - logger.log: "Siren ON"
    turn_off_action:
      - logger.log: "Siren OFF"

This exposes a siren entity over the native API with on/off state, which is all we need to validate the entity discovery, state tracking, relay binding, and command path. No physical hardware required.

Real hardware (cheap, if you want to hear it)

Wire a passive piezo buzzer or a small 5V active buzzer to a GPIO pin on any ESP32 dev board. Then use an output + template siren to drive it:

output:
  - platform: gpio
    pin: GPIO18
    id: buzzer_output

siren:
  - platform: template
    name: "Buzzer Siren"
    turn_on_action:
      - output.turn_on: buzzer_output
    turn_off_action:
      - output.turn_off: buzzer_output

A passive piezo buzzer is like $2 on Amazon and wires directly to a GPIO pin. An ESP32 dev board + buzzer is the cheapest physical test rig.

Off-the-shelf devices

I'm not aware of any popular commercial ESPHome-compatible devices that natively expose a siren entity out of the box. The siren platform is relatively niche in the ESPHome ecosystem. Most alarm/siren use cases end up using switches or binary outputs instead. The template approach above is really the way to go for testing.

[derek-miller]

we should support the out of scope features in the PR description. We can possibly support tone like we do the select entity if it reports the allowed tones and selectable with a custom programming command. The volume and duration can be set in programming too by just using writable variables correct?

[svc-finitelabs]

Good call. The protobuf schema already has everything we need — ListEntitiesSirenResponse reports tones (string array), supports_duration, and supports_volume, and SirenCommandRequest has has_tone/tone, has_duration/duration, has_volume/volume fields. So the API surface is there, we just need to wire it up.

Here's what I'm thinking:

Tone — Yeah, the Select entity pattern is a great fit. During discovery, if entity.tones is non-empty, we register a programming command (like Set Siren Tone) that populates a dropdown from the reported tones list. On execute, we send siren_command with has_tone=true, tone=<selected>. Same GCPL/EC pattern as Set_Select.

Volume — Writable NUMBER variable ({name} Volume, 0-100 or 0.0-1.0 depending on what ESPHome expects). When written from programming, fire siren_command with has_volume=true, volume=<value>. The proto field is a float, so probably 0.0-1.0 range. We can expose it as 0-100 in C4 and normalize.

Duration — Same idea, writable NUMBER variable ({name} Duration). The proto field is a uint32 (seconds). Straightforward.

All three would only be created/exposed when the entity reports support for them (supports_volume, supports_duration, non-empty tones), so devices that don't have these features won't show unused variables/commands.

I'll update this PR to add all three.

[derek-miller]

rebase and fix conflicts

[svc-finitelabs]

Rebased onto main and resolved CHANGELOG.md/README.md conflicts (added siren entry alongside the newer event/date/datetime entries in Unreleased). Force-pushed.

[derek-miller]

Good call. The protobuf schema already has everything we need — ListEntitiesSirenResponse reports tones (string array), supports_duration, and supports_volume, and SirenCommandRequest has has_tone/tone, has_duration/duration, has_volume/volume fields. So the API surface is there, we just need to wire it up.

Here's what I'm thinking:

Tone — Yeah, the Select entity pattern is a great fit. During discovery, if entity.tones is non-empty, we register a programming command (like Set Siren Tone) that populates a dropdown from the reported tones list. On execute, we send siren_command with has_tone=true, tone=<selected>. Same GCPL/EC pattern as Set_Select.

Volume — Writable NUMBER variable ({name} Volume, 0-100 or 0.0-1.0 depending on what ESPHome expects). When written from programming, fire siren_command with has_volume=true, volume=<value>. The proto field is a float, so probably 0.0-1.0 range. We can expose it as 0-100 in C4 and normalize.

Duration — Same idea, writable NUMBER variable ({name} Duration). The proto field is a uint32 (seconds). Straightforward.

All three would only be created/exposed when the entity reports support for them (supports_volume, supports_duration, non-empty tones), so devices that don't have these features won't show unused variables/commands.

I'll update this PR to add all three.

Are you still working on this?

[svc-finitelabs]

Yep, picking it up now. I'll add tone (Select pattern), volume (writable NUMBER, 0-100 normalized to 0.0-1.0), and duration (writable NUMBER, seconds) — all conditional on entity capabilities. Should have commits up shortly.