Skip to content
Home-Assistant component for person detection with Sighthound Cloud
Branch: master
Clone or download
Latest commit 46dd717 Dec 24, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
custom_components/sighthound Fix draw_box import Dec 24, 2019
images Update usage.png Nov 7, 2019



Home Assistant custom component for people detection with Sighthound Cloud. To use Sighthound Cloud you must register with Sighthound to get an api key. The Sighthound Developer tier (free for non-commercial use) allows 5000 requests per month. If you need more requests per month you will need to sign up for a production account (i.e. Basic or Pro account).

This component adds an image processing entity where the state of the entity is the number of people detected in an image. The number of faces are exposed as an attribute of the sensor. Note that whenever a face is detected in an image, a person is always detected. However a person can be detected without a face being detected (e.g. if they have their back to the camera). The time of the last detected person is in the last_person attribute.

If save_file_folder is configured, on each new detection of a person an annotated image with the name sighthound_latest.jpg is saved in the configured folder if it doesnt already exist, and over-written if it does exist. The sighthound_latest.jpg image shows the bounding box around detected people and can be displayed on the Home Assistant front end using a local_file camera, and used in notifications. Additionally if save_timestamped_file is configred as True then an image file is created of the processed image, where the file name includes the time of detection. It is the users responsibility to manage these files, e.g. using an automation to clean up files older than some time.

For each person detected, an image_processing.person_detected event is fired. The event data includes the entity_id of the image processing entity firing the event, and the bounding box around the detected person. Similarly, for each face detected an image_processing.face_detected event is fired, which in addition to the bounding box and entity_id contains the age and gender of the face. To see these events in your logs, configure the logger level to debug.

Note that in order to prevent accidentally using up your requets to Sighthound, by default the component will not automatically scan images, but requires you to call the image_processing.scan service e.g. using an automation triggered by motion. Alternativley, periodic scanning can be enabled by configuring a scan_interval.

Place the custom_components folder in your configuration directory (or add its contents to an existing custom_components folder). Add to your Home-Assistant config:

  - platform: sighthound
    api_key: your_api_key
    save_file_folder: /config/www/
    save_timestamped_file: True
    # scan_interval: 30 # optional, in seconds
      - entity_id: camera.local_file

Configuration variables:

  • api_key: Your developer api key.
  • account_type: (Optional, default dev for Developer) If you have a paid account, used prod.
  • save_file_folder: (Optional) The folder to save processed images to. Note that folder path should be added to whitelist_external_dirs
  • save_timestamped_file: (Optional, default False, requires save_file_folder to be configured) Save the processed image with the time of detection in the filename.
  • source: Must be a camera.

Displaying the sighthound_latest.jpg image

It is easy to display the sighthound_latest.jpg image with a local_file camera. An example configuration is:

  - platform: local_file
    file_path: /config/www/sighthound_latest.jpg
    name: sighthound

Automation to send the processed image in a notification

We can use a notification platform such as Telegram to send a message including the processed image.

- action:
  - data_template:
      caption: "Person detected by Sighthound"
      file: "{{}}"
    service: telegram_bot.send_photo
  alias: New person alert
  condition: []
  id: 'persondetectedautomation'
  - platform: event
    event_type: image_processing.file_saved

Count people using the image_processing.person_detected event

Using a counter an automation can be used to count the number of people seen. In configuration.yaml:

    name: People
    icon: mdi:alert

In automations.yaml:

- id: 'peoplecounterautomation'
  alias: People Counting Automation
    platform: event
    event_type: image_processing.person_detected
      entity_id: image_processing.sighthound_local_file
    service: counter.increment
    entity_id: counter.people_counter

The counter is incremented each time a person is detected. The bounding box can in principle be used to include/exclude people based on their location in the image. TODO: add example of using bounding box.

Info on the bounding box

The bounding boxes are formatted to be consumed by the image_processing.draw_box() function. The formatting convention is identical to that used by Tensorflow, where the bounding box is defined by the tuple (y_min, x_min, y_max, x_max) where the coordinates are floats in the range [0.0, 1.0] and relative to the width and height of the image.

Support this work

If you or your business find this work useful please consider becoming a sponsor at the link above, this really helps justify the time I invest in maintaining this repo. As we say in England, 'every little helps' - thanks in advance!

You can’t perform that action at this time.