diff --git a/source/_integrations/elkm1.markdown b/source/_integrations/elkm1.markdown index bc2dde98f4e6..154fd27917c9 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 @@ -31,36 +31,36 @@ related: - docs: /docs/configuration/ 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 %} 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). +{% 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 +68,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 %} + +## ElkM1 configuration and setup + +### Required global settings + +For optimal functionality, configure the following global settings on your ElkM1 panel: -### Global Setting 35 +#### Global Setting 35 - Transmit Event Log -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. +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. -On the ElkM1 panel Global Setting 35, "Transmit Event Log" must be -enabled for this to fully work. +{% important %} +Global Setting 35, "Transmit Event Log" must be enabled for this feature to work properly. +{% endimportant %} -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. +{% 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 Setting 36 — 40 +#### Global Settings 36-40 - Feature-specific settings -If you are using the features below then these respective global options -should be enabled: +Enable these settings based on the features you want to use: -| 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. | +| 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 +152,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 +443,123 @@ 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). | +| -------------- | -------- | ----------------------------------------------------- | +| `entity_id` | yes | ElkM1 area to bypass or clear bypass | +| `code` | no | Alarm code to bypass the alarm panel (4 or 6 digits) | -### Action `elkm1.alarm_display_message` +#### Display message -Display text on an area's keypads. +- `elkm1.alarm_display_message` - Display text on an area's keypads -| 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. | +| 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 | -### Action `elkm1.sensor_counter_refresh` +### Sensor actions -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. +#### Counter management -| Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------- | -| `entity_id` | yes | ElkM1 counter to refresh. | +- `elkm1.sensor_counter_refresh` - Refresh the value of a counter +- `elkm1.sensor_counter_set` - Set counter to a specific value -### Action `elkm1.sensor_counter_set` +{% note %} +The panel does not automatically send counter value updates under certain conditions. Use the refresh action to retrieve the current counter value. +{% endnote %} -Set counter to value. +| Data attribute | Required | Description | +| -------------- | -------- | ------------------------------------------- | +| `entity_id` | No | ElkM1 counter to refresh or set | +| `value` | Yes (for `sensor_counter_set`) | Value to set the counter to (0-65536) | -| Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------- | -| `entity_id` | yes | ElkM1 counter to refresh. | -| `value` | no | Value to set the counter to Can be 0-65536. | +#### Zone management -### Action `elkm1.sensor_zone_bypass` +- `elkm1.sensor_zone_bypass` - Bypass a zone +- `elkm1.sensor_zone_trigger` - Trigger a zone virtually -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). +| Data attribute | Required | Description | +| -------------- | -------- | ----------------------------------------------- | +| `entity_id` | No | ElkM1 zone to bypass or trigger | +| `code` | Yes (for bypass only) | Alarm code (4 or 6 digits) | -| 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` +{% 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 %} -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. +### System actions -| Data attribute | Optional | Description | -| ---------------------- | -------- | ---------------------------- | -| `entity_id` | yes | ElkM1 zone which to trigger. | +#### Time synchronization -### Action `elkm1.set_time` - -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 | + +#### Voice announcements -### Action `elkm1.speak_phrase` +- `elkm1.speak_phrase` - Speak a predefined phrase +- `elkm1.speak_word` - Speak a predefined word -Speak a phrase. The list of phrases is defined in the ElkM1 ASCII Protocol documentation. +{% 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. For detailed instructions on enabling debug logging, see [Enabling debug logging](/docs/configuration/troubleshooting/#enabling-debug-logging). -| Data attribute | Optional | Description | -| ---------------------- | -------- | --------------------------------------------------------- | -| `word` | no | Word to speak. | -| `prefix` | yes | Prefix to identify panel when multiple panels configured. | +Alternatively, you can manually enable debug logging in your {% term "`configuration.yaml`" %} file: -## 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. + +## 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 %}