API Reference

API

Define functionality for interacting with the SimpliSafe API.

class simplipy.api.API(*, request_retries: int = 4, media_retries: int = 4, session: ClientSession)

An API object to interact with the SimpliSafe cloud.

Note that this class shouldn’t be instantiated directly; instead, the simplipy.api.API.async_from_auth() and simplipy.api.API.async_from_refresh_token() methods should be used.

Parameters:

session – session: An optional aiohttp ClientSession.
request_retries – The default number of request retries to use.
media_retries – The default number of request retries to use to fetch media files.

async classmethod async_from_auth(authorization_code: str, code_verifier: str, *, request_retries: int = 4, session: ClientSession) → API

Get an authenticated API object from an Authorization Code and Code Verifier.

Parameters:

authorization_code – The Authorization Code.
code_verifier – The Code Verifier.
request_retries – The default number of request retries to use.
session – An optional aiohttp ClientSession.

Returns:

An authenticated API object.

Raises:

InvalidCredentialsError – Raised on invalid username/password.
RequestError – Raised on general HTTP error.
SimplipyError – Raised on an unknown error.

async classmethod async_from_refresh_token(refresh_token: str, *, request_retries: int = 4, session: ClientSession) → API

Get an authenticated API object from a refresh token.

Parameters:

refresh_token – A refresh token.
request_retries – The default number of request retries to use.
session – An optional aiohttp ClientSession.

Returns:

An authenticated API object.

async async_media(url: str) → bytes | None

Fetch a media file and return raw bytes to caller.

Parameters:: url – An absolute url for the media file.
Returns:: The raw bytes of the media file.

static is_fatal_error(retriable_error_codes: list[int]) → Callable[[ClientResponseError], bool]

Determine whether a ClientResponseError is fatal and shouldn’t be retried.

When sending general API requests:

401: We catch this, refresh the access token, and retry the original request.
409: SimpliSafe base stations regular synchronize themselves with the API,
which is where this error can occur; we can’t control when/how that happens (e.g., we might query the API in the middle of a base station update), so it should be viewed as retryable.

But when fetching media files:

404: When fetching media files, you may get a 404 if the media file is not
yet available to read. Keep trying however, and it will eventually return a 200.

Parameters:: retriable_error_codes – A list of retriable error status codes.
Returns:: A callable function used by backoff to check for errors.

disable_request_retries() → None: Disable the request retry mechanism.

enable_request_retries() → None: Enable the request retry mechanism.

add_refresh_token_callback(callback: Callable[[str], Awaitable[None] | None]) → Callable[[], None]

Add a callback that should be triggered when tokens are refreshed.

Note that callbacks should expect to receive a refresh token as a parameter.

Parameters:: callback – The callback to execute.
Returns:: A callable to cancel the callback.

async async_get_systems() → dict[int, SystemV2 | SystemV3]

Get systems associated to the associated SimpliSafe account.

In the dict that is returned, the keys are the subscription ID and the values are actual System objects.

Returns:: A dictionary of system IDs to System objects.

async async_refresh_access_token() → None

Initiate a refresh of the access/refresh tokens.

Note that this will execute any callbacks added via add_refresh_token_callback.

Raises:

InvalidCredentialsError – Raised on invalid username/password.
RequestError – Raised on general HTTP error.
SimplipyError – Raised on an unknown error.

async async_update_subscription_data() → None: Get the latest subscription data.

Websocket Communication

class simplipy.websocket.WebsocketClient(api: API)

A websocket connection to the SimpliSafe cloud.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_from_auth() or simplipy.API.async_from_refresh_token().

Parameters:: api – A simplipy API object.

property connected: bool

Return if currently connected to the websocket.

Returns:: Whether the websocket is connected.

add_connect_callback(callback: Callable[[], Awaitable[None] | None]) → Callable[[], None]

Add a callback to be called after connecting.

Parameters:: callback – The callback to execute.
Returns:: A callable to cancel the callback.

add_disconnect_callback(callback: Callable[[], Awaitable[None] | None]) → Callable[[], None]

Add a callback to be called after disconnecting.

Parameters:: callback – The callback to execute.
Returns:: A callable to cancel the callback.

add_event_callback(callback: Callable[[WebsocketEvent], Awaitable[None] | None]) → Callable[[], None]

Add a callback to be called upon receiving an event.

Note that callbacks should expect to receive a WebsocketEvent object as a parameter.

Parameters:: callback – The callback to execute.
Returns:: A callable to cancel the callback.

async async_connect() → None

Connect to the websocket server.

Raises:: CannotConnectError – Raises when we cannot connect to the websocket.

async async_disconnect() → None: Disconnect from the websocket server.

async async_listen() → None: Start listening to the websocket server.

async async_reconnect() → None: Reconnect (and re-listen, if appropriate) to the websocket.

class simplipy.websocket.WebsocketEvent(event_cid: InitVar[int], info: str, system_id: int, _raw_timestamp: float, _video: dict | None, _vid: str | None, changed_by: str | None = None, sensor_name: str | None = None, sensor_serial: str | None = None, sensor_type: DeviceTypes | None = None)

Define a representation of a message.

event_cid: InitVar[int]

info: str

system_id: int

event_type: str | None

timestamp: datetime

media_urls: dict[str, str] | None

changed_by: str | None = None

sensor_name: str | None = None

sensor_serial: str | None = None

sensor_type: DeviceTypes | None = None

Devices

class simplipy.device.Device(system: System, device_type: DeviceTypes, serial: str)

A base SimpliSafe device.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_get_systems().

Parameters:

system – A simplipy.system.System() object (or one of its subclasses).
device_type – The type of device represented.
serial – The serial number of the device.

property name: str

Return the device name.

Returns:: The device name.

property serial: str

Return the device’s serial number.

Returns:: The device serial number.

property type: DeviceTypes

Return the device type.

Returns:: The device type.

as_dict() → dict[str, Any]

Return dictionary version of this device.

Returns:: Returns a dict representation of this device.

async async_update(cached: bool = True) → None

Retrieve the latest state/properties for the device.

The cached parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (True) or retrieves new data.

Parameters:: cached – Whether to used cached data.

class simplipy.device.DeviceTypes(value)

Device types based on internal SimpliSafe ID number.

REMOTE = 0

KEYPAD = 1

KEYCHAIN = 2

PANIC_BUTTON = 3

MOTION = 4

ENTRY = 5

GLASS_BREAK = 6

CARBON_MONOXIDE = 7

SMOKE = 8

LEAK = 9

TEMPERATURE = 10

CAMERA = 12

SIREN = 13

SMOKE_AND_CARBON_MONOXIDE = 14

DOORBELL = 15

LOCK = 16

OUTDOOR_CAMERA = 17

MOTION_V2 = 20

OUTDOOR_ALARM_SECURITY_BELL_BOX = 22

LOCK_KEYPAD = 253

UNKNOWN = 99

class simplipy.device.DeviceV3(system: System, device_type: DeviceTypes, serial: str)

A base device for V3 systems.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_get_systems().

property error: bool

Return the device’s error status.

Returns:: The device’s error status.

property low_battery: bool

Return whether the device’s battery is low.

Returns:: The device’s low battery status.

property offline: bool

Return whether the device is offline.

Returns:: The device’s offline status.

property settings: dict[str, Any]

Return the device’s settings.

Note that these can change based on what device type the device is.

Returns:: A settings dictionary.

as_dict() → dict[str, Any]

Return dictionary version of this device.

Returns:: A dict representation of this device.

Lock

class simplipy.device.lock.Lock(request: Callable[..., Awaitable[dict[str, Any]]], system: System, device_type: DeviceTypes, serial: str)

A lock that works with V3 systems.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_get_systems().

Parameters:

request – The request method from the simplipy.API() object.
system – A simplipy.system.System() object (or one of its subclasses).
device_type – The type of device represented.
serial – The serial number of the device.

property disabled: bool

Return whether the lock is disabled.

Returns:: The lock’s disable status.

property lock_low_battery: bool

Return whether the lock’s battery is low.

Returns:: The lock’s low battery status.

property pin_pad_low_battery: bool

Return whether the pin pad’s battery is low.

Returns:: The pinpad’s low battery status.

property pin_pad_offline: bool

Return whether the pin pad is offline.

Returns:: The pinpad’s offline status.

property state: LockStates

Return the current state of the lock.

Returns:: The lock’s state.

as_dict() → dict[str, Any]

Return dictionary version of this device.

Returns:: A dict representation of this device.

async async_lock() → None: Lock the lock.

async async_unlock() → None: Unlock the lock.

class simplipy.device.lock.LockStates(value)

States that a lock can be in.

UNLOCKED = 0

LOCKED = 1

JAMMED = 2

UNKNOWN = 99

Sensors

class simplipy.device.sensor.v2.SensorV2(system: System, device_type: DeviceTypes, serial: str)

A V2 (old) sensor.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_get_systems().

property data: int

Return the sensor’s current data flag (currently not understood).

Returns:: The current data flag.

property error: bool

Return the sensor’s error status.

Returns:: The current error status.

property low_battery: bool

Return whether the sensor’s battery is low.

Returns:: The current low battery status.

property settings: bool

Return the sensor’s settings.

Returns:: The current settings.

property trigger_instantly: bool

Return whether the sensor will trigger instantly.

Returns:: The “instant trigger” settings.

property triggered: bool

Return whether the sensor has been triggered.

Returns:: The triggered status.
Raises:: SimplipyError – Raised when the state can’t be determined.

class simplipy.device.sensor.v3.SensorV3(system: System, device_type: DeviceTypes, serial: str)

A V3 (new) sensor.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_get_systems().

property trigger_instantly: bool

Return whether the sensor will trigger instantly.

Returns:: The “instant trigger” status.

property triggered: bool

Return whether the sensor has been triggered.

Returns:: The triggered status.

property temperature: int

Return the temperature of the sensor (as appropriate).

If the sensor isn’t a temperature sensor, an AttributeError will be raised.

Returns:: The temperature.
Raises:: AttributeError – Raised when property is read on a non-temperature device.

as_dict() → dict[str, Any]

Return dictionary version of this device.

Returns:: A dict representation of this device.

Systems

class simplipy.system.System(api: API, sid: int)

Define a system.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_get_systems().

Parameters:

api – A simplipy.API() object.
sid – A subscription ID.

property address: str | None

Return the street address of the system.

Returns:: The street address.

property alarm_going_off: bool

Return whether the alarm is going off.

Returns:: Whether the alarm is going off.

property connection_type: str | None

Return the system’s connection type (cell or WiFi).

Returns:: The connection type.

property notifications: list[SystemNotification]

Return the system’s current messages/notifications.

Returns:: A list of simplipy.system.SystemNotification() objects.

property serial: str

Return the system’s serial number.

Returns:: The system serial number.

property state: SystemStates

Return the current state of the system.

Returns:: The system state.

property system_id: int

Return the SimpliSafe identifier for this system.

Returns:: The system ID.

property temperature: int | None

Return the overall temperature measured by the system.

Returns:: The average system temperature.

property version: int | None

Return the system version.

Returns:: The system version.

as_dict() → dict[str, Any]

Return dictionary version of this device.

Returns:: A dict representation of this device.

async async_clear_notifications() → None

Clear all active notifications.

This will remove the notifications from SimpliSafe’s cloud, meaning they will no longer visible in the SimpliSafe mobile and web apps.

generate_device_objects() → None

Generate device objects for this system.

Raises:: NotImplementedError – Raises when not implemented.

async async_get_events(from_datetime: datetime | None = None, num_events: int | None = None) → list[dict[str, Any]]

Get events recorded by the base station.

If no parameters are provided, this will return the most recent 50 events.

Parameters:

from_datetime – The starting datetime (if desired).
num_events – The number of events to return.

Returns:

An API response payload.

async async_get_latest_event() → dict[str, Any]

Get the most recent system event.

Returns:: An API response payload.
Raises:: SimplipyError – Raised when there are no events.

async async_get_pins(cached: bool = True) → dict[str, str]

Return all of the set PINs, including master and duress.

The cached parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (True) or retrieves new data.

Parameters:: cached – Whether to used cached data.
Raises:: NotImplementedError – Raises when not implemented.

async async_remove_pin(pin_or_label: str) → None

Remove a PIN by its value or label.

Parameters:: pin_or_label – The PIN value or label to remove.
Raises:: PinError – Raised when attempting to remove a PIN that doesn’t exist.

async async_set_away() → None: Set the system in “Away” mode.

async async_set_home() → None: Set the system in “Home” mode.

async async_set_off() → None: Set the system in “Off” mode.

async async_set_pin(label: str, pin: str) → None

Set a PIN.

Parameters:

label – The label to use for the PIN (shown in the SimpliSafe app).
pin – The pin value.

Raises:

MaxUserPinsExceededError – Raised when attempting to add more than the maximum number of user PINs.
PinError – Raised when setting an invalid PIN.

async async_update(*, include_subscription: bool = True, include_settings: bool = True, include_devices: bool = True, cached: bool = True) → None

Get the latest system data.

The cached parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (True) or retrieves new data.

Parameters:

include_subscription – Whether system state/properties should be updated.
include_settings – Whether system settings (like PINs) should be updated.
include_devices – whether sensors/locks/etc. should be updated.
cached – Whether to used cached data.

class simplipy.system.v2.SystemV2(api: API, sid: int)

Define a V2 (original) system.

generate_device_objects() → None: Generate device objects for this system.

async async_get_pins(cached: bool = True) → dict[str, str]

Return all of the set PINs, including master and duress.

The cached parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (True) or retrieves new data.

Parameters:: cached – Whether to update with cached data.
Returns:: A dictionary of PINs.

class simplipy.system.v3.SystemV3(api: API, system_id: int)

Define a V3 (new) system.

Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via simplipy.API.async_get_systems().

Parameters:

api – A simplipy.API() object.
sid – A subscription ID.

property alarm_duration: int | None

Return the number of seconds an activated alarm will sound for.

Returns:: The alarm duration.

property alarm_volume: Volume

Return the volume level of the alarm.

Returns:: The alarm volume.

property battery_backup_power_level: int

Return the power rating of the battery backup.

Returns:: The battery backup power rating.

property chime_volume: Volume

Return the volume level of the door chime.

Returns:: The door chime volume.

property entry_delay_away: int

Return the number of seconds to delay when returning to an “away” alarm.

Returns:: The entry delay when returning to an “away” alarm.

property entry_delay_home: int

Return the number of seconds to delay when returning to a “home” alarm.

Returns:: The entry delay when returning to a “home” alarm.

property exit_delay_away: int

Return the number of seconds to delay when exiting an “away” alarm.

Returns:: The exit delay when exiting an “away” alarm.

property exit_delay_home: int

Return the number of seconds to delay when exiting an “home” alarm.

Returns:: The exit delay when exiting a “home” alarm.

property gsm_strength: int

Return the signal strength of the cell antenna.

Returns:: The cell antenna strength.

property light: bool

Return whether the base station light is on.

Returns:: The light status.

property offline: bool

Return whether the system is offline.

Returns:: The offline status.

property power_outage: bool

Return whether the system is experiencing a power outage.

Returns:: The power outage status.

property rf_jamming: bool

Return whether the base station is noticing RF jamming.

Returns:: The RF jamming status.

property voice_prompt_volume: Volume

Return the volume level of the voice prompt.

Returns:: The voice prompt volume.

property wall_power_level: int

Return the power rating of the A/C outlet.

Returns:: The A/C power rating.

property wifi_ssid: str

Return the ssid of the base station.

Returns:: The connected SSID.

property wifi_strength: int

Return the signal strength of the wifi antenna.

Returns:: The WiFi strength.

as_dict() → dict[str, Any]

Return dictionary version of this device.

Returns:: A dict representation of this device.

generate_device_objects() → None: Generate device objects for this system.

async async_get_pins(cached: bool = True) → dict[str, str]

Return all of the set PINs, including master and duress.

The cached parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (True) or retrieves new data.

Parameters:: cached – Whether to update with cached data.
Returns:: A dictionary of PINs.

async async_set_properties(properties: dict[str, bool | int | Volume]) → None

Set various system properties.

Volume properties should take values from simplipy.system.v3.Volume().

The following properties can be set:

alarm_duration (in seconds): 30-480
alarm_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH
chime_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH
entry_delay_away (in seconds): 30-255
entry_delay_home (in seconds): 0-255
exit_delay_away (in seconds): 45-255
exit_delay_home (in seconds): 0-255
light: True or False
voice_prompt_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH

Parameters:: properties – The system properties to set.
Raises:: ValueError – Raised on invalid properties.

async async_update(*, include_subscription: bool = True, include_settings: bool = True, include_devices: bool = True, cached: bool = True) → None

Get the latest system data.

The cached parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (True) or retrieves new data.

Parameters:

include_subscription – Whether system state/properties should be updated.
include_settings – Whether system settings (like PINs) should be updated.
include_devices – whether sensors/locks/etc. should be updated.
cached – Whether to used cached data.

class simplipy.system.SystemNotification(notification_id: str, text: str, category: str, code: str, timestamp: float, link: str | None = None, link_label: str | None = None)

Define a representation of a system notification.

notification_id: str

text: str

category: str

code: str

timestamp: float

received_dt: datetime | None

link: str | None = None

link_label: str | None = None

class simplipy.system.SystemStates(value)

States that the system can be in.

ALARM = 1

ALARM_COUNT = 2

AWAY = 3

AWAY_COUNT = 4

ENTRY_DELAY = 5

ERROR = 6

EXIT_DELAY = 7

HOME = 8

HOME_COUNT = 9

OFF = 10

TEST = 11

UNKNOWN = 99

Utilities

Define utility modules.

simplipy.util.execute_callback(callback: Callable[[...], Awaitable[None] | None], *args: Any) → None

Schedule a callback to be called.

The callback is expected to be short-lived, as no sort of task management takes place – this is a fire-and-forget system.

Parameters:

callback – The callback to execute.
*args – Any arguments to pass to the callback.

`auth`

Define some utilities to work with SimpliSafe’s authentication mechanism.

simplipy.util.auth.get_auth_url(code_challenge: str, *, device_id: str | None = None) → str

Get a SimpliSafe authorization URL to visit in a browser.

Parameters:

code_challenge – A code challenge generated by simplipy.util.auth.get_auth0_code_challenge().
device_id – A UUID to identify the device getting the auth URL. If not provided, a random UUID will be generated.

Returns:

An authorization URL.

simplipy.util.auth.get_auth0_code_challenge(code_verifier: str) → str

Get an Auth0 code challenge from a code verifier.

Parameters:: code_verifier – A code challenge generated by simplipy.util.auth.get_auth0_code_verifier().
Returns:: A code challenge.

simplipy.util.auth.get_auth0_code_verifier() → str

Get an Auth0 code verifier.

Returns:: A code verifier.

`dt`

Define datetime utilities.

simplipy.util.dt.utcnow() → datetime

Return the current UTC time.

Returns:: A datetime.datetime object.

simplipy.util.dt.utc_from_timestamp(timestamp: float) → datetime

Return a UTC time from a timestamp.

Parameters:: timestamp – The epoch to convert.
Returns:: A parsed datetime.datetime object.

`string`

Define various string utilities.

simplipy.util.string.convert_to_underscore(string: str) → str

Convert thisString to this_string.

Parameters:: string – The string to convert.
Returns:: A converted string.

Errors

Define package errors.

exception simplipy.errors.SimplipyError: A base error.

exception simplipy.errors.EndpointUnavailableError: An error related to accessing an endpoint that isn’t available in the plan.

exception simplipy.errors.InvalidCredentialsError: An error related to invalid credentials.

exception simplipy.errors.MaxUserPinsExceededError: An error related to exceeding the maximum number of user PINs.

exception simplipy.errors.PinError: An error related to invalid PINs or PIN operations.

exception simplipy.errors.RequestError: An error related to invalid requests.

exception simplipy.errors.WebsocketError: An error related to generic websocket errors.

exception simplipy.errors.CannotConnectError: Define a error when the websocket can’t be connected to.

exception simplipy.errors.ConnectionClosedError: Define a error when the websocket closes unexpectedly.

exception simplipy.errors.ConnectionFailedError: Define a error when the websocket connection fails.

exception simplipy.errors.InvalidMessageError: Define a error related to an invalid message from the websocket server.

exception simplipy.errors.NotConnectedError: Define a error when the websocket isn’t properly connected to.

simplipy.errors.raise_on_data_error(data: dict[str, Any] | None) → None

Raise a specific error if the data payload suggests there is one.

Parameters:: data – An optional API response payload.
Raises:: error – A SimplipyError subclass.

API Reference

API

Websocket Communication

Devices

Lock

Sensors

Systems

Utilities

auth

dt

string

Errors

`auth`

`dt`

`string`