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 API
object:
api.websocket
# >>> <simplipy.websocket.Websocket object>
Connecting
await api.websocket.async_connect()
Then, once you are connected to the websocket, you can start listening for events:
await api.websocket.async_listen()
Disconnecting
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 establisheddisconnect
: occurs when the websocket connection is terminatedevent
: occurs when any data is transmitted from the SimpliSafe™ cloud
Note that you can register as many callbacks as you’d like.
connect
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
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
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
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 eventsensor_name
: the name of the entity that triggered the eventsensor_serial
: the serial number of the entity that triggered the eventsensor_type
: the type of the entity that triggered the eventsystem_id
: the SimpliSafe™ system IDtimestamp
: the UTC timestamp that the event occurredmedia_urls
: a dict containing media URLs if theevent_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:
{
"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:
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.