From 3c085c95da9393ae9616d8a732f79e0434f4d591 Mon Sep 17 00:00:00 2001 From: Nc Hodges <86037210+Hodnc@users.noreply.github.com> Date: Wed, 17 Sep 2025 00:28:42 +0000 Subject: [PATCH 1/4] Improve Elk-M1 integration documentation for clarity and completeness --- source/_integrations/elkm1.markdown | 271 ++++++++++++++-------------- 1 file changed, 133 insertions(+), 138 deletions(-) diff --git a/source/_integrations/elkm1.markdown b/source/_integrations/elkm1.markdown index bc2dde98f4e6..1b24eb81681e 100644 --- a/source/_integrations/elkm1.markdown +++ b/source/_integrations/elkm1.markdown @@ -1,6 +1,6 @@ --- title: Elk-M1 Control -description: Instructions to setup the Elk-M1 controller. +description: Instructions to set up the Elk-M1 controller for home security and automation. ha_release: 0.81 ha_category: - Alarm @@ -32,35 +32,36 @@ related: title: Configuration file --- -The Elk-M1 is a home security and automation controller that is capable of alarm control panel functions and automation. +The **Elk-M1 Control** {% term integration %} allows you to integrate Elk-M1 Gold and EZ8 alarm panels with Home Assistant. The Elk-M1 is a comprehensive home security and automation controller capable of alarm control panel functions and extensive automation features. The Elk-M1 controller is manufactured by [Elk Products](https://www.elkproducts.com). +{% include integrations/config_flow.md %} + +## Supported functionality + There is currently support for the following device types within Home Assistant: -- **Alarm** - An ElkM1 area (also known as partition) is represented as an `alarm_control_panel`. -- **Binary sensor** - ElkM1 zones that have 4 states (i.e.: are not analog zones) are represented as `binary_sensor` entities. `Normal` is `off` and any of the other values is `on`. -- **Climate** - An ElkM1 thermostat is represented as a `climate` entity. -- **Light** - An ElkM1 light (which can be X10, Insteon, UPB) is represented as a `light`. -- **Scene** - ElkM1 tasks are represented as `scene` entities. -- **Sensor** - ElkM1 counters, keypads, panel, settings, and zones are represented as `sensor` entities. -- **Switch** - ElkM1 outputs are represented as `switch` entities. +- **Alarm control panel** - Elk-M1 areas (also known as partitions) are represented as `alarm_control_panel` entities +- **Binary sensor** - Elk-M1 zones with 4 states (non-analog zones) are represented as `binary_sensor` entities. `Normal` state is `off` and any other state is `on` +- **Climate** - Elk-M1 thermostats are represented as `climate` entities +- **Light** - Elk-M1 lights (X10, Insteon, UPB) are represented as `light` entities +- **Scene** - Elk-M1 tasks are represented as `scene` entities +- **Sensor** - Elk-M1 counters, keypads, panel status, settings, and zones are represented as `sensor` entities +- **Switch** - Elk-M1 outputs are represented as `switch` entities -The implementation follows the Elk Products ElkM1 "ASCII Protocol & Interface -Specification, Revision 1.84" document. This document can be found on the Internet. +The implementation follows the Elk Products ElkM1 "ASCII Protocol & Interface Specification, Revision 1.84" document. This document can be found on the Internet. -## ElkM1 configuration and version +## Prerequisites -In order for the ElkM1 integration to work to its fullest with Home Assistant the -ElkM1 panel must be configured correctly. This section describes the configuration -required on the ElkM1 panel. +Before setting up the Elk-M1 integration, ensure your system meets these requirements: ### ElkM1 version ElkM1 should be running: - Version 4.6.8, or -- Version 5.2.0 or higher. +- Version 5.2.0 or higher Force arm away and stay are available in 5.3.0 or higher. @@ -68,38 +69,44 @@ Many features will work with lower versions of the ElkM1. Check the "ElkM1 RS232 ### ELK-M1XEP version -The ELK-M1XEP is the Ethernet controller board for the ElkM1. If connecting the integration -in secure mode the version of the ELK-M1XEP determines which secure protocol is supported. -ELK-M1XEP versions less than 2.0.46 support TLS 1.0, while version 2.0.46 and above support -TLS 1.2. When adding the ElkM1 integration in the user interface use `secure` for TLS 1.0 and -use `TLS 1.2` for TLS 1.2. Note that ELK-M1XEP does not support auto-negotiation of the -version of the TLS protocol, the user must specify the TLS version to connect. +The ELK-M1XEP is the Ethernet controller board for the ElkM1. If connecting the integration in secure mode, the version of the ELK-M1XEP determines which secure protocol is supported. + +- ELK-M1XEP versions less than 2.0.46 support TLS 1.0 (use `secure` in the UI) +- ELK-M1XEP version 2.0.46 and above support TLS 1.2 (use `TLS 1.2` in the UI) + +{% note %} +ELK-M1XEP does not support auto-negotiation of the TLS protocol version. You must specify the correct TLS version when connecting. +{% endnote %} -### Global Setting 35 +## ElkM1 configuration and setup -The ElkM1 integration tracks the user number and name of the last username to -arm or disarm the panel. The `changed_by` and `changed_by_id` attributes of -the `alarm_control_panel` hold those two attributes. +### Required global settings -On the ElkM1 panel Global Setting 35, "Transmit Event Log" must be -enabled for this to fully work. +For optimal functionality, configure the following global settings on your ElkM1 panel: -Note that without Global Setting 35 set and in a single area system, -`changed_by` and `changed_by_id` are updated when a user enters a valid -code on a physical keypad. +#### Global Setting 35 - Transmit Event Log -### Global Setting 36 — 40 +The ElkM1 integration tracks the user number and name of the last user to arm or disarm the panel. The `changed_by` and `changed_by_id` attributes of the `alarm_control_panel` entities hold this information. -If you are using the features below then these respective global options -should be enabled: +{% important %} +Global Setting 35, "Transmit Event Log" must be enabled for this feature to work properly. +{% endimportant %} -| Option # | Option Name | Description | -| -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 36 | Transmit Zone Changes | If you are using Zones this allows Home Assistant to track the status of the Zones. | -| 37 | Transmit Output Changes | If you are using Outputs this allows Home Assistant to track the status of the Outputs. | -| 38 | Transmit Automation Task Changes | If you are using ElkM1 Tasks this allows Home Assistant to track the status of the Tasks. | -| 39 | Transmit Light Changes | If you are using ElkM1 Lights this allows Home Assistant to track the status of the lights. | -| 40 | Transmit Keypad Changes | Oddly, this option tracks keypad changes and alarm status. If you are wishing to track keypresses on ElkM1 keypad or if you are wishing to track the armed, disarmed, and alarm state of the ElkM1 then this option should be set. | +{% note %} +Without Global Setting 35 enabled, in single area systems, `changed_by` and `changed_by_id` are only updated when a user enters a valid code on a physical keypad. +{% endnote %} + +#### Global Settings 36-40 - Feature-specific settings + +Enable these settings based on the features you want to use: + +| Setting | Option Name | Description | +| ------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 36 | Transmit Zone Changes | Enable if using zones. Allows Home Assistant to track zone status changes. | +| 37 | Transmit Output Changes | Enable if using outputs. Allows Home Assistant to track output status changes. | +| 38 | Transmit Automation Task Changes | Enable if using ElkM1 tasks. Allows Home Assistant to track task status changes. | +| 39 | Transmit Light Changes | Enable if using ElkM1 lights. Allows Home Assistant to track light status changes. | +| 40 | Transmit Keypad Changes | Enable to track keypad changes and alarm status. Required for keypress events and tracking armed/disarmed/alarm states. | ## System Trouble Status @@ -146,15 +153,9 @@ The complete list of trouble statuses are: ## Manual configuration -Alternatively, configuration through the {% term "`configuration.yaml`" %} file -is supported (example below). +Alternatively, you can configure the integration through the {% term "`configuration.yaml`" %} file for advanced setups. -Both methods of configuration support "auto configuration". This works by -reporting only elements on the ElkM1 that have a "Name" configured. -So, for example, if counter #11 on the panel was configured with -the name "Test counter" then this element would show up in Home Assistant. If -an element is being used but does not have a name configured then -it will not appear in Home Assistant through the auto-configuration feature. +Both configuration methods support **auto configuration**, which automatically discovers and adds only elements that have a "Name" configured on your ElkM1 panel. For example, if counter #11 on the panel is configured with the name "Test counter", it will appear in Home Assistant. Elements without names will not appear unless auto configuration is disabled. ```yaml # Example configuration.yaml entry @@ -443,131 +444,125 @@ The `event_data` contains the following: ## Actions -Besides the standard Home Assistant actions for Alarm control panel, Climate, Light, Scene, Sensor, -and Switch the ElkM1 integration offers these additional actions: +The ElkM1 integration provides additional actions beyond the standard Home Assistant actions for alarm control panels, climate, lights, scenes, sensors, and switches. -- `elkm1.alarm_arm_home_instant` -- `elkm1.alarm_arm_night_instant` -- `elkm1.alarm_arm_vacation` -- `elkm1.alarm_bypass` -- `elkm1.alarm_clear_bypass` -- `elkm1.alarm_display_message` -- `elkm1.sensor_counter_refresh` -- `elkm1.sensor_counter_set` -- `elkm1.sensor_zone_bypass` -- `elkm1.sensor_zone_trigger` -- `elkm1.set_time` -- `elkm1.speak_phrase` -- `elkm1.speak_word` +### Alarm actions -### Actions `elkm1.alarm_arm_home_instant`, `elkm1.alarm_arm_night_instant`, and `elkm1.alarm_arm_vacation` +#### Arm modes -Arms the ElkM1 area in "home instant", "night instant", or "vacation" modes -respectively. +- `elkm1.alarm_arm_home_instant` - Arms the area in "home instant" mode +- `elkm1.alarm_arm_night_instant` - Arms the area in "night instant" mode +- `elkm1.alarm_arm_vacation` - Arms the area in "vacation" mode | Data attribute | Optional | Description | -| ---------------------- | -------- | --------------------------------------------- | -| `entity_id` | yes | ElkM1 area which to arm. | -| `code` | no | Alarm code to arm the system (4 or 6 digits). | +| -------------- | -------- | --------------------------------------------- | +| `entity_id` | yes | ElkM1 area to arm | +| `code` | no | Alarm code to arm the system (4 or 6 digits) | -### Actions `elkm1.alarm_bypass` and `elkm1.alarm_clear_bypass` +#### Zone management -For all zones associated with the specified alarm panel these actions respectively -bypass or clear the bypass the zones. +- `elkm1.alarm_bypass` - Bypasses all zones associated with the specified alarm panel +- `elkm1.alarm_clear_bypass` - Clears bypass for all zones associated with the specified alarm panel | Data attribute | Optional | Description | -| ---------------------- | -------- | ----------------------------------------------------- | -| `entity_id` | yes | ElkM1 area which to bypass or clear bypass. | -| `code` | no | Alarm code to bypass the alarm panel (4 or 6 digits). | - -### Action `elkm1.alarm_display_message` +| -------------- | -------- | ----------------------------------------------------- | +| `entity_id` | yes | ElkM1 area to bypass or clear bypass | +| `code` | no | Alarm code to bypass the alarm panel (4 or 6 digits) | -Display text on an area's keypads. +#### Display message -| Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------------------------------------------- | -| `entity_id` | yes | ElkM1 area which to display the message. | -| `clear` | yes | 0=clear message, 1=clear message with * key, 2=Display until timeout; default 2 | -| `beep` | yes | 0=no beep, 1=beep; default 0 | -| `timeout` | yes | Time to display message, 0=forever, max 65535, default 0 | -| `line1` | yes | Up to 16 characters of text (truncated if too long). Default blank. | -| `line2` | yes | Up to 16 characters of text (truncated if too long). Default blank. | +- `elkm1.alarm_display_message` - Display text on an area's keypads -### Action `elkm1.sensor_counter_refresh` +| Data attribute | Optional | Description | +| -------------- | -------- | -------------------------------------------------------------------------------- | +| `entity_id` | yes | ElkM1 area where to display the message | +| `clear` | yes | 0=clear message, 1=clear message with * key, 2=display until timeout; default 2 | +| `beep` | yes | 0=no beep, 1=beep; default 0 | +| `timeout` | yes | Time to display message, 0=forever, max 65535, default 0 | +| `line1` | yes | Up to 16 characters of text (truncated if too long). Default blank | +| `line2` | yes | Up to 16 characters of text (truncated if too long). Default blank | -Refresh the value of a counter. Note that under certain conditions the -panel does not automatically send a new value under certain -conditions. This action retrieves the current counter value. +### Sensor actions -| Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------- | -| `entity_id` | yes | ElkM1 counter to refresh. | +#### Counter management -### Action `elkm1.sensor_counter_set` +- `elkm1.sensor_counter_refresh` - Refresh the value of a counter +- `elkm1.sensor_counter_set` - Set counter to a specific value -Set counter to value. +{% note %} +The panel does not automatically send counter value updates under certain conditions. Use the refresh action to retrieve the current counter value. +{% endnote %} | Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------- | -| `entity_id` | yes | ElkM1 counter to refresh. | -| `value` | no | Value to set the counter to Can be 0-65536. | +| -------------- | -------- | ------------------------------------------- | +| `entity_id` | yes | ElkM1 counter to refresh or set | +| `value` | no* | Value to set the counter to (0-65536). *Required for `sensor_counter_set` only | -### Action `elkm1.sensor_zone_bypass` +#### Zone management -Bypass a zone. Note that the only mechanism ElkM1 offers to clear the bypass -is to clear all the bypassed zones in a given alarm panel (area). +- `elkm1.sensor_zone_bypass` - Bypass a zone +- `elkm1.sensor_zone_trigger` - Trigger a zone virtually -| Data attribute | Optional | Description | -| ---------------------- | -------- | ---------------------------------------------- | -| `entity_id` | yes | ElkM1 zone which to bypass. | -| `code` | no | Alarm code to bypass the zone (4 or 6 digits). | +{% note %} +The only mechanism ElkM1 offers to clear zone bypass is to clear all bypassed zones in a given alarm panel (area). +{% endnote %} -### Action `elkm1.sensor_zone_trigger` +| Data attribute | Optional | Description | +| -------------- | -------- | ----------------------------------------------- | +| `entity_id` | yes | ElkM1 zone to bypass or trigger | +| `code` | no* | Alarm code (4 or 6 digits). *Required for bypass only | -Cause a zone on the panel to trigger. This command creates a virtual momentary -open condition on the zone as if the EOL hardwired loop had been physically opened. +{% note %} +The `sensor_zone_trigger` action creates a virtual momentary open condition on the zone as if the EOL hardwired loop had been physically opened. +{% endnote %} -| Data attribute | Optional | Description | -| ---------------------- | -------- | ---------------------------- | -| `entity_id` | yes | ElkM1 zone which to trigger. | +### System actions -### Action `elkm1.set_time` +#### Time synchronization -Set the time on the panel. Uses the current time on the instance of Home Assistant. +- `elkm1.set_time` - Set the time on the panel to match Home Assistant's current time | Data attribute | Optional | Description | -| ---------------------- | -------- | --------------------------------------------------------- | -| `prefix` | yes | Prefix to identify panel when multiple panels configured. | +| -------------- | -------- | --------------------------------------------------------- | +| `prefix` | yes | Prefix to identify panel when multiple panels configured | -### Action `elkm1.speak_phrase` +#### Voice announcements -Speak a phrase. The list of phrases is defined in the ElkM1 ASCII Protocol documentation. +- `elkm1.speak_phrase` - Speak a predefined phrase +- `elkm1.speak_word` - Speak a predefined word + +{% note %} +The list of available phrases and words is defined in the ElkM1 ASCII Protocol documentation. +{% endnote %} | Data attribute | Optional | Description | -| ---------------------- | -------- | --------------------------------------------------------- | -| `phrase` | no | Phrase to speak. | -| `prefix` | yes | Prefix to identify panel when multiple panels configured. | +| -------------- | -------- | --------------------------------------------------------- | +| `phrase` | no* | Phrase to speak. *Required for `speak_phrase` only | +| `word` | no* | Word to speak. *Required for `speak_word` only | +| `prefix` | yes | Prefix to identify panel when multiple panels configured | -### Action `elkm1.speak_word` +## Debugging -Speak a word. The list of words is defined in the ElkM1 ASCII Protocol documentation. +If you encounter issues with the ElkM1 integration, debug logs can help identify the problem. -| Data attribute | Optional | Description | -| ---------------------- | -------- | --------------------------------------------------------- | -| `word` | no | Word to speak. | -| `prefix` | yes | Prefix to identify panel when multiple panels configured. | +### Enable debug logging -## Debugging -Debug logs are often required to solve an issue. Follow the instructions on [Enabling debug logging](/docs/configuration/troubleshooting/#enabling-debug-logging). +1. Add the following to your {% term "`configuration.yaml`" %} file: -Sometimes, for example, a problem can occur while starting Home Assistant. In this case, follow these instructions. -Add the following to your {% term "`configuration.yaml`" %} file in your Home Assistant `config` directory: + ```yaml + logger: + logs: + elkm1_lib: debug + homeassistant.components.elkm1: debug + ``` -```yaml -logger: - logs: - elkm1_lib: debug - homeassistant.components.elkm1: debug -``` +2. Restart Home Assistant. +3. Check the debug logs in the `homeassistant.log` file in your Home Assistant `config` directory. + +For more information, see [Enabling debug logging](/docs/configuration/troubleshooting/#enabling-debug-logging). + +## Removing the integration + +This integration follows standard integration removal. No extra steps are required. -After updating your configuration file, restart Home Assistant. The debug logs will be in the file `homeassistant.log` in the `config` directory. +{% include integrations/remove_device_service.md %} From 2c7c50ad1569402b9f3bfafd7fd4cfc99fab274f Mon Sep 17 00:00:00 2001 From: Nc Hodges <86037210+Hodnc@users.noreply.github.com> Date: Wed, 17 Sep 2025 10:39:24 +1000 Subject: [PATCH 2/4] Update source/_integrations/elkm1.markdown Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- source/_integrations/elkm1.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/elkm1.markdown b/source/_integrations/elkm1.markdown index 1b24eb81681e..4c2039d22995 100644 --- a/source/_integrations/elkm1.markdown +++ b/source/_integrations/elkm1.markdown @@ -451,7 +451,7 @@ The ElkM1 integration provides additional actions beyond the standard Home Assis #### Arm modes - `elkm1.alarm_arm_home_instant` - Arms the area in "home instant" mode -- `elkm1.alarm_arm_night_instant` - Arms the area in "night instant" mode +- `elkm1.alarm_arm_night_instant` - Arms the area in "night instant" mode - `elkm1.alarm_arm_vacation` - Arms the area in "vacation" mode | Data attribute | Optional | Description | From 29032d510a602a2961e1fb7dd9f0a1e8c5a5d3bd Mon Sep 17 00:00:00 2001 From: Nc Hodges <86037210+Hodnc@users.noreply.github.com> Date: Wed, 17 Sep 2025 00:51:07 +0000 Subject: [PATCH 3/4] Minor Changes based on Co-Pilot Recommendations --- source/_integrations/elkm1.markdown | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/source/_integrations/elkm1.markdown b/source/_integrations/elkm1.markdown index 4c2039d22995..156310a5221f 100644 --- a/source/_integrations/elkm1.markdown +++ b/source/_integrations/elkm1.markdown @@ -31,8 +31,7 @@ related: - docs: /docs/configuration/ title: Configuration file --- - -The **Elk-M1 Control** {% term integration %} allows you to integrate Elk-M1 Gold and EZ8 alarm panels with Home Assistant. The Elk-M1 is a comprehensive home security and automation controller capable of alarm control panel functions and extensive automation features. +The **Elk-M1 Control** {% term integration %} lets you connect your Elk-M1 Gold and EZ8 alarm panels to Home Assistant. These advanced home security and automation controllers offer robust alarm control panel capabilities, along with a wide range of automation features to help you manage and protect your home. The Elk-M1 controller is manufactured by [Elk Products](https://www.elkproducts.com). @@ -493,25 +492,25 @@ The ElkM1 integration provides additional actions beyond the standard Home Assis The panel does not automatically send counter value updates under certain conditions. Use the refresh action to retrieve the current counter value. {% endnote %} -| Data attribute | Optional | Description | +| Data attribute | Required | Description | | -------------- | -------- | ------------------------------------------- | -| `entity_id` | yes | ElkM1 counter to refresh or set | -| `value` | no* | Value to set the counter to (0-65536). *Required for `sensor_counter_set` only | +| `entity_id` | No | ElkM1 counter to refresh or set | +| `value` | Yes (for `sensor_counter_set`) | Value to set the counter to (0-65536) | #### Zone management - `elkm1.sensor_zone_bypass` - Bypass a zone - `elkm1.sensor_zone_trigger` - Trigger a zone virtually +| Data attribute | Required | Description | +| -------------- | -------- | ----------------------------------------------- | +| `entity_id` | No | ElkM1 zone to bypass or trigger | +| `code` | Yes (for bypass only) | Alarm code (4 or 6 digits) | + {% note %} The only mechanism ElkM1 offers to clear zone bypass is to clear all bypassed zones in a given alarm panel (area). {% endnote %} -| Data attribute | Optional | Description | -| -------------- | -------- | ----------------------------------------------- | -| `entity_id` | yes | ElkM1 zone to bypass or trigger | -| `code` | no* | Alarm code (4 or 6 digits). *Required for bypass only | - {% note %} The `sensor_zone_trigger` action creates a virtual momentary open condition on the zone as if the EOL hardwired loop had been physically opened. {% endnote %} From c81ac27fb7e90be29abd3726e9d8c979ea652d40 Mon Sep 17 00:00:00 2001 From: Nc Hodges <86037210+Hodnc@users.noreply.github.com> Date: Fri, 12 Dec 2025 09:16:16 +0000 Subject: [PATCH 4/4] Corrected wording to point to debug UI instructions first. --- source/_integrations/elkm1.markdown | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/_integrations/elkm1.markdown b/source/_integrations/elkm1.markdown index 156310a5221f..154fd27917c9 100644 --- a/source/_integrations/elkm1.markdown +++ b/source/_integrations/elkm1.markdown @@ -542,9 +542,9 @@ The list of available phrases and words is defined in the ElkM1 ASCII Protocol d ## Debugging -If you encounter issues with the ElkM1 integration, debug logs can help identify the problem. +If you encounter issues with the ElkM1 integration, debug logs can help identify the problem. For detailed instructions on enabling debug logging, see [Enabling debug logging](/docs/configuration/troubleshooting/#enabling-debug-logging). -### Enable debug logging +Alternatively, you can manually enable debug logging in your {% term "`configuration.yaml`" %} file: 1. Add the following to your {% term "`configuration.yaml`" %} file: @@ -558,8 +558,6 @@ If you encounter issues with the ElkM1 integration, debug logs can help identify 2. Restart Home Assistant. 3. Check the debug logs in the `homeassistant.log` file in your Home Assistant `config` directory. -For more information, see [Enabling debug logging](/docs/configuration/troubleshooting/#enabling-debug-logging). - ## Removing the integration This integration follows standard integration removal. No extra steps are required.