diff --git a/source/_integrations/simplisafe.markdown b/source/_integrations/simplisafe.markdown index d7e8a1ae5d1..7fc14341a9c 100644 --- a/source/_integrations/simplisafe.markdown +++ b/source/_integrations/simplisafe.markdown @@ -27,7 +27,7 @@ There is currently support for the following device types within Home Assistant: - **Freeze Sensor**: reports on the freeze sensor temperature*. - **Glass Break Sensor**: reports on the glass breakage sensor status*. - **Lock**: reports on `Door Locks` and can be used to lock and unlock a lock. -- **Motion Sensor**: reports on motion detected. +- **Motion Sensor**: reports on motion detected*. - **Siren**: reports on the siren status*. - **Smoke Detector**: reports on the smoke sensor status*. - **Water Sensor**: reports on water sensor status*. @@ -67,7 +67,8 @@ entity. ### `simplisafe.clear_notifications` Clear any existing notifications within the SimpliSafe cloud; this will mark existing -notifications as "read" in the SimpliSafe web and mobile apps. +notifications as "read" in the SimpliSafe web and mobile apps, as well as prevent them +from triggering future `SIMPLISAFE_NOTIFICATION` events. ### `simplisafe.remove_pin` @@ -113,6 +114,69 @@ For any property denoting a volume, the following values should be used: ## Events +### `SIMPLISAFE_EVENT` + +`SIMPLISAFE_EVENT` events represent events that appear on the timeline of the SimpliSafe +web and mobile apps. When received, they come with event data that contains the +following keys: + +* `changed_by`: the PIN that triggered the event (if appropriate) +* `event_type`: the type of event +* `info`: a human-friendly string describing the event in more detail +* `sensor_name`: the sensor that triggered the event (if appropriate) +* `sensor_serial`: the serial number of the sensor that triggered the event (if appropriate) +* `sensor_type`: the type of sensor that triggered the event (if appropriate) +* `system_id`: the system ID to which the event belongs +* `timestamp`: the UTC datetime at which the event was received + +For example, when someone rings the doorbell, a +`SIMPLISAFE_EVENT` event will fire with the following event data: + +```python +{ + "event_type": "SIMPLISAFE_EVENT", + "data": { + "last_event_changed_by": "", + "last_event_type": "doorbell_detected", + "last_event_info": "Someone is at your \"Front Door\"", + "last_event_sensor_name": "Front Door", + "last_event_sensor_serial": "", + "last_event_sensor_type": "doorbell", + "system_id": [systemid], + "last_event_timestamp": "2021-01-28T22:01:32+00:00" + }, + "origin": "LOCAL", + "time_fired": "2021-01-28T22:01:37.478539+00:00", + "context": { + "id": "[id]", + "parent_id": null, + "user_id": null + } +} +``` + +`last_event_type` can have the following values: + +* `automatic_test` +* `camera_motion_detected` +* `doorbell_detected` +* `device_test` +* `secret_alert_triggered` +* `sensor_paired_and_named` +* `user_initiated_test` + +To build an automation using one of these, 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: + +```yaml +trigger: + - platform: event + event_type: SIMPLISAFE_EVENT + event_data: + last_event_type: doorbell_detected +``` + ### `SIMPLISAFE_NOTIFICATION` `SIMPLISAFE_NOTIFICATION` events represent system notifications that would appear in the