DRV-27: Add Alarm Control Panel entity support

[svc-finitelabs]

Summary

Adds support for ESPHome alarm_control_panel entities using Option B (variables + device actions) as recommended in the ticket.

What's New

• Entity module: src/esphome/entities/alarm_control_panel.lua
• State variable: {name} State (STRING) tracks the current alarm state with human-readable names (Disarmed, Armed Home, Armed Away, Armed Night, Armed Vacation, Armed Custom Bypass, Pending, Arming, Disarming, Triggered)
• Programming command: "Alarm Command" with:
  • Dynamic Panel dropdown (populated from discovered panels)
  • Dynamic Command dropdown (Arm Away, Arm Home, Arm Night, Arm Vacation, Arm Custom Bypass, Disarm, Trigger)
  • Optional Code string parameter for panels that require a code
• Registered in driver.lua entity table
• Added command definition to driver.xml
• Updated README (entity table, variables, bindings, commands)
• Added CHANGELOG entry

Pattern

Follows the same patterns as Button (for programming commands with GCPL/EC) and Switch/Text (for state variables via values:update). No sub-driver or proxy bindings, keeping it simple and adequate for most use cases.

Fixes DRV-27

[derek-miller]

Hmm, the approach will need to be looked at again. We will need to use the companion driver approach and integrate the panel using the security panel/partition proxy.

[svc-finitelabs]

Got it — I'll rework this to use a companion sub-driver with security panel/partition proxies instead of the current variables + device actions approach. Similar pattern to how climate (PR #44) uses a thermostatV2 sub-driver.

I'll move the ticket back to In Progress and update the PR once the rewrite is ready.

[svc-finitelabs]

Rewrite: Security Panel/Partition Sub-Driver Approach

This PR has been completely rewritten to use a proper security panel/partition sub-driver approach instead of the original variables + device actions approach.

What changed

Entity handler (src/esphome/entities/alarm_control_panel.lua):

• Follows the exact pattern of climate/fan/light/lock entities
• Creates ESPHOME_ALARM dynamic bindings for discovered alarm control panel entities
• Forwards state updates and commands between main driver and sub-driver

Sub-driver (drivers/esphome_alarm/):

• Security panel proxy (binding 5001) + single partition proxy (binding 5002)
• ESPHome binding on 5003 (consumer, connects to main driver)
• Maps ESPHome alarm states → C4 partition states:
  • DISARMED → DISARMED_READY
  • ARMED_HOME/AWAY/NIGHT/VACATION/CUSTOM_BYPASS → ARMED (with type)
  • PENDING/ARMING → EXIT_DELAY
  • DISARMING → ENTRY_DELAY
  • TRIGGERED → ALARM (Burglary)
• Handles PARTITION_ARM, PARTITION_DISARM, ARM_CANCEL commands
• Reports capabilities: arm_states from supported_features bitmask, code requirements
• Sends proper partition notifications: PARTITION_STATE, PARTITION_ENABLED, PARTITION_STATE_INIT, CODE_REQUIRED
• Panel notifications: PANEL_INITIALIZED, PANEL_PARTITION_STATE

Main driver:

• Added AlarmControlPanelEntity to entity table
• Added esphome_alarm.c4z to OSS filenames

Both drivercentral and oss builds pass.

[derek-miller]

Can you download https://github.com/snap-one/docs-driverworks-proxyprotocol-security and make sure we are fully implementing the proxy correctly?

[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]

You don't need a specific device — ESPHome's Template Alarm Control Panel platform lets you turn any ESP32 into a mock alarm panel using GPIO binary sensors (or even virtual ones from HA).

Minimal mock config (ESP32 + zero hardware):

# Use template binary sensors so you can toggle zones from HA
binary_sensor:
  - platform: homeassistant
    id: zone_1
    name: "Zone 1 - Front Door"
    entity_id: input_boolean.mock_zone_1
  - platform: homeassistant
    id: zone_2
    name: "Zone 2 - Motion"
    entity_id: input_boolean.mock_zone_2

alarm_control_panel:
  - platform: template
    name: "Mock Alarm Panel"
    id: acp1
    codes:
      - "1234"
    requires_code_to_arm: true
    arming_away_time: 5s
    arming_home_time: 2s
    pending_time: 5s
    trigger_time: 30s
    binary_sensors:
      - input: zone_1
        trigger_mode: delayed
      - input: zone_2
        bypass_armed_home: true
        trigger_mode: delayed_follower

Then create input_boolean.mock_zone_1 and input_boolean.mock_zone_2 helpers in HA to simulate zone faults from the dashboard.

If you want real GPIO zones, just wire momentary buttons or reed switches to any two GPIO pins on a spare ESP32 and swap the homeassistant platform for gpio:

binary_sensor:
  - platform: gpio
    id: zone_1
    name: "Zone 1"
    device_class: door
    pin:
      number: GPIO4
      mode: INPUT_PULLUP
      inverted: true

What you get to test with: arm_away, arm_home, arm_night, disarm (with code), arming/pending/triggered state transitions, zone bypass, and the chime callback. Covers all the states the driver would need to handle.

The full template alarm control panel docs are here: https://esphome.io/components/alarm_control_panel/template/

[svc-finitelabs]

Security Proxy Spec Review

Downloaded and reviewed the full snap-one security proxy protocol docs. Here's how the current implementation maps:

✅ Implemented correctly

Spec Area	Implementation
Partition states	All 8 states mapped in alarmStateToPartitionState() (ARMED, ALARM, OFFLINE, EXIT_DELAY, ENTRY_DELAY, DISARMED_READY, DISARMED_NOT_READY, CONFIRMATION_REQUIRED)
PARTITION_STATE notification	Sends STATE + TYPE params correctly
PARTITION_STATE_INIT	Used on first state update (no programming fired)
PARTITION_ARM command	Handles ArmType + UserCode, maps to ESPHome commands
PARTITION_DISARM command	Handles UserCode param
ARM_CANCEL command	Maps to DISARM (no ESPHome equivalent)
PARTITION_ENABLED notification	Sent on init
CODE_REQUIRED notification	Sent based on entity.requires_code
PANEL_INITIALIZED notification	Sent on init
PANEL_PARTITION_STATE notification	Panel binding also notified
Arm states capability	Built from ESPHome supported_features bitmask

⚠️ Missing from spec (may want to add)

Spec Item	Priority	Notes
EXECUTE_EMERGENCY command	Medium	Spec supports Fire/Medical/Police/Panic emergency types. ESPHome has no emergency command, but we could map to TRIGGER if supported.
KEY_PRESS command	Low	Virtual keypad support. ESPHome panels don't have keypads.
EXECUTE_FUNCTION command	Low	Custom function execution. No ESPHome equivalent.
ARM_FAILED / DISARM_FAILED notifications	Medium	Spec has these. Currently no failure handling — if ESPHome rejects a command, we don't notify C4.
DISPLAY_TEXT / TROUBLE_TEXT variables	Low	Panel display text. ESPHome doesn't expose these.
Zone management (HAS_ZONE, ZONE_STATE, etc.)	Low	ESPHome alarm entities don't expose zone data.
Partition capabilities (has_fire, has_medical, has_police, has_panic)	Low	Emergency button visibility. Default false is fine unless we add EXECUTE_EMERGENCY.
supports_virtual_keypad capability	Low	Should explicitly set to false since ESPHome panels don't support it.

🎯 Recommendation

The core is solid. The main gaps are around failure notifications (ARM_FAILED/DISARM_FAILED) and emergency support. Since ESPHome's alarm_control_panel doesn't expose failure callbacks, we'd need to handle these with timeouts or ignore them. The zone/keypad/display features don't apply to ESPHome panels.

One thing I'd add: explicitly send supports_virtual_keypad = false as a capability so C4 doesn't show the keypad UI.