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:
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:

  1. 401: We catch this, refresh the access token, and retry the original request.

  2. 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:

  1. 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:
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: dataclasses.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: dataclasses.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, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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:
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:

  1. alarm_duration (in seconds): 30-480

  2. alarm_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH

  3. chime_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH

  4. entry_delay_away (in seconds): 30-255

  5. entry_delay_home (in seconds): 0-255

  6. exit_delay_away (in seconds): 45-255

  7. exit_delay_home (in seconds): 0-255

  8. light: True or False

  9. 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
class simplipy.system.SystemStates(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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:
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.