search

user2684 / imou_life

Home Assistant custom component for controlling Imou devices
MIT License
119 stars 20 forks source link
camera home-assistant home-automation imou imou-life motion-detection webcam

readme

Home Assistant custom component for controlling Imou devices

hacs_badge hacs_badge Donate

This Home Assistant component helps in interacting with devices registered with the Imou Life App and specifically enabling/disabling motion detection, siren, and other switches.

Despite Imou webcams video streams can be integrated in Home Assistant through Onvif, the only way to interact with the device as if using the Imou Life App is to leverage the Imou API, that is what this component under the hood does.

Once an Imou device is added to Home Assistant, switches can be controlled through the frontend or convenientely used in your automations.

Features

Supported Models

You can find here a list with all the Imou models which have been tested and if they are working or not with the integration. Please feel free to report any missing model or additional information.

Installation

HACS (recommended)

After installing and configuring HACS, go to "Integrations", "Explore & Download Repositories", search for "Imou Life" and download the integration.

Manual installation

  1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
  2. If you do not have a custom_components directory (folder) there, you need to create it.
  3. In the custom_components directory (folder) create a new folder called imou_life.
  4. Download all the files from the custom_components/imou_life/ directory (folder) in this repository.
  5. Place the files you downloaded in the new directory (folder) you created.
  6. Restart Home Assistant

This integration depends on the library imouapi for interacting with the end device. The library should be installed automatically by Home Assistante when initializing the integration. If this is not happening, install it manually with:

pip3 install imouapi

Requirements

To interact with the Imou API, valid App Id and App Secret are required.

In order to get them:

Configuration

The configuration of the component is done entirely through the UI.

  1. In the Home Assistant UI to "Configuration" -> "Integrations" click "+" and search for "Imou Life"
  2. Fill in App Id and App Secret
    1. If Discover registered devices is selected:
      • A list of all the devices associated with your account is presented
      • Select the device you want to add
      • Optionally provide a name (otherwise the same name used in Imou Life will be used)
    2. If Discover registered devices is NOT selected:
      • Provide the Device ID of the device you want to add
      • Optionally provide a name (otherwise the same name used in Imou Life will be used)

Once done, you should see the integration added to Home Assistant, a new device and a few entities associated with it.

The following entities are created (if supported by the device):

If you need to add another device, repeat the process above.

Advanced Options

The following options can be customized through the UI by clicking on the "Configure" link:

Motion Detection

When adding a new device, a Motion Alarm binary sensor is created (provided your device supports motion detection). You can use it for building your automations, when its state changes, like any other motion sensors you are already familiar with. There are multiple options available to keep the motion alarm sensor regularly updated, described below. All the options will update the same "Motion Alarm" sensor, just the frequency changes depending on the option. Option 1 and 2 does not require Home Assistant to be exposed over the Internet, Option 3 does but ensure realtime updates of the sensor.

Option 1

If you do nothing, by default the sensor will be updated every 15 minutes, like any other sensor of the device. If a motion is detected, the sensor triggers and it will get back to a "Clear" state at the next update cycle (e.g. after other 15 minutes)

Option 2

If you want to increase the frequency, you can force an update of the "Motion Alarm" sensor state manually or automatically, through the "Refresh Alarm" button which is created in the same device. For example, you can create an automation like the below which press every 30 seconds the "Refresh Alarm" button for you, causing an update of the "Motion Alarm" sensor state (replace button.webcam_refreshalarm with the name of your entity):

alias: Imou - Refresh Alarm
description: ""
trigger:
  - platform: time_pattern
    seconds: "30"
condition: []
action:
  - service: button.press
    data: {}
    target:
      entity_id: <button.webcam_refreshalarm>
mode: single

Please note, the underlying Imou API is limited to 20000 calls per day.

Option 3

If you want relatime updates of the "Motion Alarm" sensor, you need to enable push notifications. In this scenario, upon an event occurs (e.g. alarm, device offline, etc.) a realtime notification is sent by the Imou API directly to your Home Assistance instance so you can immediately react upon it. Since this is happening via a direct HTTP call to your instance, your Home Assistance must be exposed to the Internet as a requirement. Please note, push notification is a global configuration, not per device, meaning once enabled on one device it applies to ALL devices registered in your Imou account.

Requirements

Configuration

alias: Imou Push Notifications
description: "Handle Imou push notifications by requesting to update the Motion Alarm sensor of the involved device (v1)"
trigger:
  - platform: webhook
    webhook_id: <your_string_difficult_to_guess>
condition:
  - condition: template
    value_template: |
      {% for entity_name in integration_entities("imou_life") %}
        {%- if entity_name is match('.+_refreshalarm$') and is_device_attr(entity_name, "hw_version", trigger.json.did) %}
          true
        {%-endif%}
        {% else %}
          false
      {%- endfor %}
  - condition: template
    value_template: |-
      {%- if trigger.json.msgType in ("videoMotion", "human", "openCamera") %}
        true
      {% else %}
        false
      {%-endif%}
action:
  - service: button.press
    data: {}
    target:
      entity_id: |
        {% for entity_name in integration_entities("imou_life") %}
          {%- if entity_name is match('.+_refreshalarm$') and is_device_attr(entity_name, "hw_version", trigger.json.did) %}
            {{entity_name}}
          {%-endif%}
        {%- endfor %}
    enabled: true
mode: queued
max: 10

When using this option, please note the following:

PTZ Controls

The integration exposes two services for interacting with the PTZ capabilities of the device:

Those services can be invoked on the camera entity. To test this capability, in Home Assistant go to "Developer Tools", click on "Services", select one of the services above, select the target entity, provide the required information and click on "Call Service". If something will go wrong, have a look at the logs.

Presets are instead not apparently supported by the Imou APIs but could be implemented by combining HA scripts and calls to the imou_life.ptz_location service.

Limitations / Known Issues

Troubleshooting

If anything fails, you should find the error message and the full stack trace on your Home Assistant logs. This can be helpful for either troubleshoot the issue or reporting it.

Device Diagnostics

Diagnostics information is provided by visiting the device page in Home Assistant and clicking on "Download Diagnostics".

Debugging

To gain more insights on what the component is doing or why is failing, you can enable debug logging:

logger:
  default: info
  logs:
    custom_components.imou_life: debug

Since this integration depends on the library imouapi for interacting with the end device, you may want to enable debug level logging to the library itself:

logger:
  default: info
  logs:
    custom_components.imou_life: debug
    imouapi: debug

Bugs or feature requests

Bugs and feature requests can be reported through Github Issues. When reporting bugs, ensure to include also diagnostics and debug logs. Please review those logs to redact any potential sensitive information before submitting the request.

Contributing

Any contribution is more than welcome. Github is used to host the code, track issues and feature requests, as well as submitting pull requests. Detailed information on how the code is structured, how to setup a development environment and how to test your code before submitting pull requests is detailed here.

Roadmap

A high level roadmap of this integration can be found here