Skip to content

Latest commit

 

History

History
233 lines (164 loc) · 10.9 KB

README.md

File metadata and controls

233 lines (164 loc) · 10.9 KB
Raw

Home Assistant Elmo/IESS Integration

Linting Testing Coverage Status hacs_badge

This project is a Home Assistant integration for your Elmo/IESS Alarm connected to e-Connect cloud or Metronet.

Supported Systems

This integration supports Elmo/IESS alarm systems. The following systems are known to work:

Available functionalities

  • Configuration flow implemented to add login credentials and home and night areas
  • Arm and disarm the alarm based on sectors you have configured
  • Query the system and get the status of your sectors and inputs (e.g. doors, windows, etc.) and see if they are triggered or not
  • A service is available and you can configure automations via YAML or via UI
  • EconnectAlarm entity is available and you can use the AlarmPanel card to control it in lovelace

Alarm status

  • Arm Away: arms all areas
  • Disarm: disarm all areas
  • Arm Home: based on the configuration, arms given areas (optional)
  • Arm Night: based on the configuration, arms given areas (optional)

If you are curious about the project and want to know more, check out our Discord channel!

Installation

Download the Integration

  1. Create a new folder in your configuration folder (where the configuration.yaml lives) called custom_components
  2. Download the latest version into the custom_components folder so that the full path from your config folder is custom_components/econnect_metronet/
  3. Restart Home Assistant. If it's your only custom component you'll see a warning in your logs.
  4. Once Home Assistant is started, from the UI go to Configuration > Integrations > Add Integrations. Search for "Elmo/IESS Alarm". After selecting, dependencies will be downloaded and it could take up to a minute.

Setup

  • Username: is your username to access Elmo/IESS via web or app.
  • Password: is your password to access Elmo/IESS via web or app.
  • System: pick the brand of alarm system you are using.
  • Domain name: domain used to access your login page via web. If you access to https://connect.elmospa.com/vendor/, you must set the domain to vendor. In case you don't have a vendor defined, leave it to default.

Options

In the option page you can configure your alarm presets in case you want to fine-tune which sectors are armed. To proceed with the configuration, open the integration page and click on Elmo/IESS integration. Once the page is opened, you should see the following integration page:

To configure the integration, click on "Configure".

You can now define your presets:

  • Armed areas while at home: list areas you want to arm when you select Arm Home.
  • Armed areas at night (optional): list areas you want to arm when you select Arm Night.
  • Armed areas on vacation (optional): list areas you want to arm when you select Arm Vacation.

In case you don't define any sector for a given preset, no actions are taken when you use the preset from your alarm panel.

Automations

If you use automations, remember that in the payload you must send the code so that the system will be properly armed/disarmed.

YAML example:

service: alarm_control_panel.alarm_arm_away
target:
  entity_id: alarm_control_panel.<YOUR ALARM ENTITY ID>
data:
  code: !secret alarm_code  # (check how to use secrets if you are not familiar)

You can find <YOUR ALARM ENTITY ID> under Settings > Devices & Services > e-Connect/Metronet Alarm opening the list of entities and searching for Alarm Panel

UI example:

Apple Home integration (HomeKit)

If you want to integrate your alarm with the Apple Home to use Siri or automations, follow these steps:

  1. Add these entries inside configuration.yaml to let Home Assistant create a new HomeKit bridge with just the Alarm Panel exposed.
homekit:
  - name: HASS Bridge Alarm
    port: 21065
    filter:
      include_domains:
        - alarm_control_panel
    entity_config:
      alarm_control_panel.<YOUR ALARM ENTITY ID>:
        code: <PIN CODE>
  1. Please replace <PIN CODE> with your specific alarm code and <YOUR ALARM ENTITY ID> with your alarm entity id.
  2. Reboot Home Assistant.
  3. Scan the QR code available in your Home Assistant Notifications area (bottom-left badge) with your iPhone to add the alarm into the Apple Home app.

Multiple HomeKit bridges: If you have others HomeKit integrations created via the UI (i.e., Settings > Devices & Services), be careful to not use the same port twice to prevent conflicts. Also note, if you don't specify a port the default 21063 is used.

Please note that Apple Home requires you to confirm automations that involves security devices such as lockers and alarm systems.

As a result of the integration you should have a similar configuration in your Home app:

Alarm panel Alarm panel opened

Troubleshooting

If you encounter an issue, providing DEBUG logs can greatly assist us in identifying the bug. Please follow these steps to send us the debug logs:

  1. Navigate to the integration configuration page in Home Assistant: Settings > Devices & Services > e-Connect/Metronet Alarm.
  2. Enable debug logging by clicking on Enable debug logging.
  3. Restart the integration by selecting Restart from the three-dot menu.
  4. Reproduce the error (e.g., arm the system or modify the configuration).
  5. After reproducing the error, return to the Integration configuration page and click Disable debug logging.
  6. Your browser will prompt you to download the log file.
  7. Ensure that the logs do not contain sensitive information, as we do not log credentials or access tokens.
  8. Send the logs to us via a secure method. Do not post your logs on public platforms like our Discord general channel or GitHub issues, as they are publicly accessible.

Contributing

We are very open to the community's contributions - be it a quick fix of a typo, or a completely new feature! You don't need to be a Python expert to provide meaningful improvements. To learn how to get started, check out our Contributor Guidelines first, and ask for help in our Discord channel if you have questions.

Development

We welcome external contributions, even though the project was initially intended for personal use. If you think some parts could be exposed with a more generic interface, please open a GitHub issue to discuss your suggestion.

Dev Environment

To create a virtual environment and install the project and its dependencies, execute the following commands in your terminal:

# Initialize the environment with the latest version of Home Assistant
E_HASS_VERSION=$(curl --silent "https://api.github.com/repos/home-assistant/core/releases/latest" | grep -Po "(?<=\"tag_name\": \").*(?=\")")
./scripts/init $E_HASS_VERSION
source venv/bin/activate

# Install pre-commit hooks
pre-commit install

Instead, if you want to develop and test this integration with a different Home Assistant version, just pass the version to the init script:

# Initialize the environment Home Assistant 2024.1.1
./scripts/init 2024.1.1
source venv/bin/activate

# Install pre-commit hooks
pre-commit install

Testing Changes in Home Assistant

To test your changes in an actual Home Assistant environment, you may use the Docker container available in our compose.yaml file. Launch the container with the following command:

docker compose up -d

Then, navigate to http://localhost:8123 in your web browser to set up your Home Assistant instance. Follow the standard procedure to install the integration, as you would in a typical installation.

The container is configured to automatically mount the custom_components/ and config/ directories from your local workspace. To see changes reflected in Home Assistant, make sure to restart the instance through the UI each time you update the integration.

Coding Guidelines

To maintain a consistent codebase, we utilize flake8 and black. Consistency is crucial as it helps readability, reduces errors, and facilitates collaboration among developers.

To ensure that every commit adheres to our coding standards, we've integrated pre-commit hooks. These hooks automatically run flake8 and black before each commit, ensuring that all code changes are automatically checked and formatted.

For details on how to set up your development environment to make use of these hooks, please refer to the Development section of our documentation.

Testing

Ensuring the robustness and reliability of our code is paramount. Therefore, all contributions must include at least one test to verify the intended behavior.

To run tests locally, execute the test suite using pytest with the following command:

pytest tests --cov --cov-branch -vv

For a comprehensive test that mirrors the Continuous Integration (CI) environment across all supported Python versions, use tox:

tox

Note: To use tox effectively, ensure you have all the necessary Python versions installed. If any versions are missing, tox will provide relevant warnings.