1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
# Websocket
`simplipy` provides a websocket that allows for near-real-time detection of certain
events from a user's SimpliSafe™ system. This websocket can be accessed via the
`websocket` property of the {meth}`API <simplipy.api.API>` object:
```python
api.websocket
# >>> <simplipy.websocket.Websocket object>
```
## Connecting
```python
await api.websocket.async_connect()
```
Then, once you are connected to the websocket, you can start listening for events:
```python
await api.websocket.async_listen()
```
## Disconnecting
```python
await api.websocket.async_disconnect()
```
## Responding to Events
Users respond to events by defining callbacks (synchronous functions _or_ coroutines).
The following events exist:
- `connect`: occurs when the websocket connection is established
- `disconnect`: occurs when the websocket connection is terminated
- `event`: occurs when any data is transmitted from the SimpliSafe™ cloud
Note that you can register as many callbacks as you'd like.
### `connect`
```python
async def async_connect_handler():
await asyncio.sleep(1)
print("I connected to the websocket")
def connect_handler():
print("I connected to the websocket")
remove_1 = api.websocket.add_connect_callback(async_connect_handler)
remove_2 = api.websocket.add_connect_callback(connect_handler)
# remove_1 and remove_2 are functions that, when called, remove the callback.
```
### `disconnect`
```python
async def async_connect_handler():
await asyncio.sleep(1)
print("I disconnected from the websocket")
def connect_handler():
print("I disconnected from the websocket")
remove_1 = api.websocket.add_disconnect_callback(async_connect_handler)
remove_2 = api.websocket.add_disconnect_callback(connect_handler)
# remove_1 and remove_2 are functions that, when called, remove the callback.
```
### `event`
```python
async def async_connect_handler(event):
await asyncio.sleep(1)
print(f"I received a SimpliSafe™ event: {event}")
def connect_handler():
print(f"I received a SimpliSafe™ event: {event}")
remove_1 = api.websocket.add_event_callback(async_connect_handler)
remove_2 = api.websocket.add_event_callback(connect_handler)
# remove_1 and remove_2 are functions that, when called, remove the callback.
```
#### Response Format
The `event` argument provided to event callbacks is a
{meth}`simplipy.websocket.WebsocketEvent` object, which comes with several properties:
- `changed_by`: the PIN that caused the event (in the case of arming/disarming/etc.)
- `event_type`: the type of event (see below)
- `info`: a longer string describing the event
- `sensor_name`: the name of the entity that triggered the event
- `sensor_serial`: the serial number of the entity that triggered the event
- `sensor_type`: the type of the entity that triggered the event
- `system_id`: the SimpliSafe™ system ID
- `timestamp`: the UTC timestamp that the event occurred
- `media_urls`: a dict containing media URLs if the `event_type` is "camera_motion_detected" (see below)
The `event_type` property will be one of the following values:
- `alarm_canceled`
- `alarm_triggered`
- `armed_away_by_keypad`
- `armed_away_by_remote`
- `armed_away`
- `armed_home`
- `automatic_test`
- `away_exit_delay_by_keypad`
- `away_exit_delay_by_remote`
- `camera_motion_detected`
- `connection_lost`
- `connection_restored`
- `disarmed_by_keypad`
- `disarmed_by_remote`
- `doorbell_detected`
- `entity_test`
- `entry_detected`
- `home_exit_delay`
- `lock_error`
- `lock_locked`
- `lock_unlocked`
- `motion_detected`
- `power_outage`
- `power_restored`
- `sensor_not_responding`
- `sensor_paired_and_named`
- `sensor_restored`
- `user_initiated_test`
If the `event_type` is `camera_motion_detected`, then the `event` attribute `media_urls`
will be a dictionary that looks like this:
```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
retrieve the raw bytes of the media files at these URLs with the following method:
```python
bytes = await api.async_media(url)
```
If the `event_type` is not `camera_motion_detected`, then `media_urls` will be set to None.
If you should come across an event type that the library does not know about (and see
a log message about it), please open an issue at
<https://github.com/bachya/simplisafe-python/issues>.
|
