diff --git a/source/_integrations/simplisafe.markdown b/source/_integrations/simplisafe.markdown index b4c39a37a14a..52034dbdd40a 100644 --- a/source/_integrations/simplisafe.markdown +++ b/source/_integrations/simplisafe.markdown @@ -37,6 +37,7 @@ There is currently support for the following device types within Home Assistant: - **Smoke Detector**: reports on the smoke sensor status*. - **Smoke+CO Detector**: reports on the smoke and carbon monoxide sensor status*. - **Water Sensor**: reports on water sensor status*. +- **Outdoor Camera**: capture motion event images and media clips - Sensor status is only available for SimpliSafe V3 systems and is updated once every 30 seconds, so information displayed in Home Assistant may be delayed. @@ -88,6 +89,25 @@ Set one or more system properties. | `light` | yes | Whether the light on the base station should display when armed | | `voice_prompt_volume` | yes | The volume of the base station's voice prompts | +### `simplisafe.capture_motion_image` + +Capture a motion event jpeg image. + +| Service Data Attribute | Optional | Description | +| ---------------------- | -------- | ---------------------------------------------------------------------------- | +| `entity_id` | no | The entity id of a camera | +| `width` | yes | Desired width in pixels of the captured image. Default is 720. 240-1080. | +| `filename` | no | A file name (or template) to save the image to | + +### `simplisafe.capture_motion_clip` + +Capture a motion event mp4 clip. + +| Service Data Attribute | Optional | Description | +| ---------------------- | -------- | ---------------------------------------------------------------------------- | +| `entity_id` | no | The entity id of a camera | +| `filename` | no | A file name (or template) to save the video clip to | + ## Events ### `SIMPLISAFE_EVENT` @@ -104,6 +124,7 @@ following keys: - `last_event_sensor_type`: the type of sensor that triggered the event (if appropriate) - `system_id`: the system ID to which the event belongs - `last_event_timestamp`: the UTC datetime at which the event was received +- `media_urls`: a dict containing media URLs if the event_type is `camera_motion_detected` (see below) For example, when someone rings the doorbell, a `SIMPLISAFE_EVENT` event will fire with the following event data: @@ -141,7 +162,22 @@ For example, when someone rings the doorbell, a - `sensor_paired_and_named` - `user_initiated_test` -To build an automation using one of these, use `SIMPLISAFE_EVENT` +If `last_event_type` is `camera_motion_detected` then `SIMPLISAFE_EVENT` will include +a `media_urls` key that is a dictionary that looks like + +```python +{ + 'image_url': "https://xxx.us-east-1.prd.cam.simplisafe.com/xxx", + 'clip_url': "https://xxx.us-east-1.prd.cam.simplisafe.com/xxx" +} +``` + +The 'image_url' is an absolute URL to a JPEG file. The 'clip_url' is an absolute URL +to a short MPEG4 video clip. Both refer to the motion detected by the camera. You +can obtain these files locally using the "capture_motion_image" and "capture_motion_clip" +services respectively. + +To build an automation using one of these event types, use `SIMPLISAFE_EVENT` as an event trigger, with `last_event_type` as the `event_data`. For example, the following will trigger when the doorbell rings: @@ -166,5 +202,59 @@ event data that contains the following keys: Note that when Home Assistant restarts, `SIMPLISAFE_NOTIFICATION` events will fire once again for any notifications still active in the SimpliSafe web and mobile apps. To -prevent this, either (a) clear them in the web/mobile app or (b) utilize the +prevent this, either (a) clear them in the web/mobile app or (b) utilize the `clear_notifications` button provided by the alarm control panel. + +### `MOTION EVENT AUTOMATIONS` + +When a `camera_motion_event` occurs on a camera (currently only outdoor cameras are supported), +you may want to capture the image and video clip associated with that event. First create a trigger +that looks something like this: + +```yaml +trigger: + - platform: event + event_type: SIMPLISAFE_EVENT + event_data: + last_event_type: camera_motion_detected + last_event_sensor_type: OUTDOOR_CAMERA + last_event_sensor_serial: f11b6abd +``` + +where the `last_event_sensor_serial` is the serial number of a specifc camera you are targeting. One +way to obtain that serial number is to use the "Developer tools" and listen on `SIMPLISAFE_EVENT` events +and then walk in front of your camera. `last_event_sensor_serial` will contain that serial number. + +Then for actions associated with that trigger, something like this: + +{% raw %} + +```yaml +service: simplisafe.capture_motion_clip +data: + entity_id: camera.back_yard_camera_one + filename: >- + /config/www/simplisafe/back_yard/clips/{{now().strftime('%Y%m%d%H%M%S')}}.mp4 +``` + +{% endraw %} + +and + +```yaml +service: simplisafe.capture_motion_image +data: + width: 720 + filename: "/config/www/simplisafe/back_yard/latest.jpg" + entity_id: camera.back_yard_camera_one +``` + +In this example, we are creating a directory structure that contains the latest image, and a history of +video clips. You could use the "files" integration and this snippet in your "configuration.yaml" file: + +```yaml +sensor: + - platform: files + folder: /config/www/simplisafe/back_yard/clips + name: back_yard_media +```