API Reference

Main API

The main entry-point into pyschlage is through the pyschlage.Schlage object. From there you can access the locks associated with a Schlage account, and interact with them directly.

class pyschlage.Schlage(auth: Auth)

API for interacting with the Schlage WiFi cloud service.

__init__(auth: Auth) → None

Instantiates a Schlage API object.

Parameters:

auth (pyschlage.Auth) – Authentication and transport for the API.

locks(include_access_codes: bool = False) → list[Lock]

Retrieves all locks associated with this account.

Parameters:

include_access_codes – Whether to also refresh access codes.

Return type:

list[Lock]

Raises:
users() → list[User]

Retrieves all users associated with this account’s locks.

Return type:

list[User]

Raises:

Authentication

Creating a Schlage object first requires creating an authentication and transport object, which is encapsulated in the pyschlage.Auth object.

class pyschlage.Auth(username: str, password: str)

Handles authentication for the Schlage WiFi cloud service.

__init__(username: str, password: str) → None

Initializes an Auth object.

Parameters:

  • username (str) – The username associated with the Schlage account.

  • password (str) – The password for the account.

authenticate()

Performs authentication with AWS.

Raises:
property user_id: str

Returns the unique user id for the authenticated user.

Locks

The Schlage object provides access to Lock objects. Each instance of a Lock itself can fetch additional data such as access codes and log entries.

class pyschlage.lock.Lock(_auth: Auth | None = None, device_id: str = '', device_type: str = '', name: str = '', model_name: str = '', connected: bool = False, battery_level: int | None = None, battery_voltage: int | None = None, is_locked: bool | None = False, is_jammed: bool | None = False, lock_state_metadata: LockStateMetadata | None = None, beeper_enabled: bool = False, lock_and_leave_enabled: bool = False, auto_lock_time: int = 0, firmware_version: str | None = None, ble_firmware_version: str | None = None, wifi_firmware_version: str | None = None, keypad_firmware_version: str | None = None, mac_address: str | None = None, serial_number: str | None = None, manufacturer_name: str | None = None, access_code_length: int | None = None, max_user_codes: int | None = None, battery_low_state: BatteryState | None = None, door_state: DoorState | None = None, alarm_mode: AlarmMode | None = None, alarm_sensitivity: int | None = None, operating_mode: OperatingMode | None = None, users: dict[str, ~pyschlage.user.User]=<factory>, access_codes: dict[str, ~pyschlage.code.AccessCode] | None=None, _cat: str = '', _json: dict[~typing.Any, ~typing.Any]=<factory>)

A Schlage WiFi lock.

add_access_code(code: AccessCode)

Adds an access code to the lock.

Parameters:

code (pyschlage.code.AccessCode) – The access code to add.

Raises:
get_access_codes() → list[AccessCode]

Fetches the access codes for this lock.

Rtype list[pyschlage.code.AccessCode]:

Raises:

pyschlage.exceptions.NotAuthorizedError – When authentication fails.

get_diagnostics() → dict[Any, Any]

Returns a redacted dict of the raw JSON for diagnostics purposes.

keypad_disabled(logs: list[LockLog] | None = None) → bool

Returns True if the keypad is currently disabled.

Parameters:

logs (list[LockLog] or None) – Recent logs. If None, new logs will be fetched.

Return type:

bool

last_changed_by(logs: list[LockLog] | None = None) → str | None

Determines the last entity or user that changed the lock state.

Parameters:

logs – Unused. Kept for legacy reasons.

Return type:

str

lock()

Locks the device.

Raises:
logs(limit: int | None = None, sort_desc: bool = False) → list[LockLog]

Fetches activity logs for the lock.

Parameters:

  • limit (int | None) – The number of log entries to return.

  • sort_desc (bool (defaults to False)) – Whether to sort entries in descending order.

Return type:

list[pyschlage.log.LockLog]

Raises:
refresh(include_access_codes: bool = False) → None

Refreshes the Lock state.

Parameters:

include_access_codes – Whether to also refresh access codes. If False and access codes were previously fetched, they will be preserved from the last refresh.

Raises:
refresh_access_codes() → None

Fetches access codes for this lock.

Raises:
send_command(command: str, data: dict[Any, Any]) → Response

Sends a command to the device.

set_auto_lock_time(auto_lock_time: int)

Sets the auto_lock_time setting. Setting it to 0 turns off the auto-lock feature.

Parameters:

auto_lock_time (int) – Number of seconds of inactivity before the lock automatically locks itself. Must be one of AUTO_LOCK_TIMES.

Raises:
set_beeper(enabled: bool)

Sets the beeper_enabled setting.

Parameters:

enabled (bool) – Whether the keypress beep should be enabled.

Raises:
set_lock_and_leave(enabled: bool)

Sets the lock_and_leave setting.

Parameters:

enabled (bool) – Whether lock-and-leave should be enabled.

Raises:
unlock()

Unlocks the device.

Raises:
access_code_length: int | None = None

The number of digits in this lock’s access codes.

access_codes: dict[str, AccessCode] | None = None

Access codes for this lock, keyed by their ID.

alarm_mode: AlarmMode | None = None

The event the lock’s built-in alarm triggers on.

alarm_sensitivity: int | None = None

The sensitivity of the lock’s built-in alarm.

auto_lock_time: int = 0

Time (in seconds) after which the lock will automatically lock itself.

battery_level: int | None = None

The remaining battery level of the lock.

This is an integer between 0 and 100 or None if lock is unavailable.

battery_low_state: BatteryState | None = None

The coarse battery state reported by the lock.

This is independent of battery_level; locks may report a low battery before the level drops appreciably.

battery_voltage: int | None = None

The no-load battery voltage of the lock, in millivolts.

This is the reading taken with the motor idle, from the lock’s reported diagnostics. It is None if the lock does not report it.

beeper_enabled: bool = False

Whether the keypress beep is enabled.

ble_firmware_version: str | None = None

The firmware version of the lock’s Bluetooth radio.

connected: bool = False

Whether the lock is connected to WiFi.

device_id: str = ''

Schlage-generated unique device identifier.

device_type: str = ''

The device type of the lock.

door_state: DoorState | None = None

The state of the door, for locks with a door position sensor.

This is None for locks without one.

firmware_version: str | None = None

The firmware version installed on the lock or None if lock is unavailable.

is_jammed: bool | None = False

Whether the lock has identified itself as jammed.

This is True for both a jammed bolt and a jammed motor. Returns None if lock is unavailable.

is_locked: bool | None = False

Whether the device is currently locked or None if lock is unavailable.

Locks that support deadlocking report True while deadlocked. Locks in passage mode report False.

keypad_firmware_version: str | None = None

The firmware version of the lock’s keypad.

lock_and_leave_enabled: bool = False

Whether lock-and-leave (a.k.a. “1-Touch Locking) feature is enabled.

lock_state_metadata: LockStateMetadata | None = None

Metadata about the current lock state.

mac_address: str | None = None

The MAC address for the lock or None if lock is unavailable.

manufacturer_name: str | None = None

The manufacturer name reported by the lock.

max_user_codes: int | None = None

The maximum number of access codes this lock can store.

model_name: str = ''

The model name of the lock.

name: str = ''

User-specified name of the lock.

operating_mode: OperatingMode | None = None

Which protocol stack the lock is operating under.

serial_number: str | None = None

The serial number of the lock.

users: dict[str, User]

Users with access to this lock, keyed by their ID.

wifi_firmware_version: str | None = None

The firmware version of the lock’s WiFi radio.

This is None for locks without a WiFi radio.

class pyschlage.lock.LockStateMetadata(action_type: str, uuid: str | None = None, name: str | None = None)

Metadata about the current lock state.

action_type: str

The action type that last changed the lock state.

name: str | None = None

Human readable name of the access code that changed the lock state.

If the lock state was not changed by an access code, this will be None.

uuid: str | None = None

The UUID of the actor that changed the lock state.

class pyschlage.code.AccessCode(_auth: Auth | None = None, name: str = '', code: str = '', schedule: MultiRecurringSchedule | TemporarySchedule | RecurringSchedule | None = None, notify_on_use: bool = False, disabled: bool = False, device_id: str | None = None, access_code_id: str | None = None, _device: Device | None = None, _notification: Notification | None = None, _json: dict[~typing.Any, ~typing.Any]=<factory>)

An access code for a lock.

delete()

Deletes the access code.

Raises:
save()

Commits changes to the access code.

Raises:
access_code_id: str | None = None

Unique identifier for the access code.

code: str = ''

The access code.

Must be a string of 4 to 8 digits. Leading zeros are significant and must be included, since the code’s length is sent to the lock along with the code itself.

device_id: str | None = None

Unique identifier for the device the access code is associated with.

disabled: bool = False

Whether the code is disabled.

name: str = ''

User-specified name for the access code.

notify_on_use: bool = False

Whether to notify the user’s phone app when the code is used.

schedule: MultiRecurringSchedule | TemporarySchedule | RecurringSchedule | None = None

Optional schedule at which the code is enabled.

class pyschlage.code.RecurringSchedule(days_of_week: DaysOfWeek = <factory>, start_hour: int = 0, start_minute: int = 0, end_hour: int = 23, end_minute: int = 59)

A recurring schedule for when an AccessCode is enabled.

days_of_week: DaysOfWeek

Days of the week on which the access code is enabled.

end_hour: int = 23

Hour at which the access code is disabled.

end_minute: int = 59

Minute at which the access code is disabled.

start_hour: int = 0

Hour at which the access code is enabled.

start_minute: int = 0

Minute at which the access code is enabled.

class pyschlage.code.MultiRecurringSchedule(schedule1: RecurringSchedule | None, schedule2: RecurringSchedule | None)

A schedule consisting of at most two recurring schedules.

schedule1: RecurringSchedule | None

The first recurring schedule during which the access code is enabled.

schedule2: RecurringSchedule | None

The second recurring schedule during which the access code is enabled.

May only be set if schedule1 is also set.

class pyschlage.code.TemporarySchedule(start: datetime, end: datetime)

A temporary schedule for when an AccessCode is enabled.

end: datetime

The time at which the schedule should end.

start: datetime

The time at which the schedule should start.

class pyschlage.code.DaysOfWeek(sun: bool = True, mon: bool = True, tue: bool = True, wed: bool = True, thu: bool = True, fri: bool = True, sat: bool = True)

Enabled status for each day of the week.

fri: bool = True
mon: bool = True
sat: bool = True
sun: bool = True
thu: bool = True
tue: bool = True
wed: bool = True
class pyschlage.log.LockLog(created_at: datetime, message: str, accessor_id: str | None = None, access_code_id: str | None = None, event_code: int = -1)

A lock log entry.

access_code_id: str | None = None

Unique identifier for the access code that triggered the log entry.

accessor_id: str | None = None

Unique identifier for the user that triggered the log entry.

created_at: datetime

The UTC time at which the log entry was created.

event_code: int = -1

The raw event code reported by the lock.

See LOG_EVENT_TYPES for the known values.

message: str

The human-readable message associated with the log entry.

Device attributes

Several Lock attributes are reported as enumerations. Values the lock reports that are not listed here are mapped to UNKNOWN.

class pyschlage.device.DeviceType(*values)

Known device types.

Values are the devicetypeId prefix reported by the API. The full devicetypeId also carries a transport suffix (ble, wifi or wb) and, on later hardware revisions, a generation number, e.g. be489wifi2.

ARRIVE = 'be459'
BRIDGE = 'br400'
ENCODE = 'be489'
ENCODE_LEVER = 'fe789'
ENCODE_PLUS = 'be499'
GAINSBOROUGH_SELENE_ENTRANCE = 'gselent'
GAINSBOROUGH_SELENE_SECURE = 'gselsec'
SCHLAGE_SELENE_ENTRANCE = 'sselent'
SCHLAGE_SELENE_SECURE = 'sselsec'
SENSE = 'be479'
SENSE_PRO = 'be889'
class pyschlage.device.AlarmMode(*values)

The event an armed lock alarm triggers on.

DISABLED = 0
FORCED_ENTRY = 3
LOCK_UNLOCK = 1
TAMPER = 2
UNKNOWN = -1
class pyschlage.device.BatteryState(*values)

Coarse battery level reported by the lock.

CRITICALLY_LOW = 2
LOW = 1
NORMAL = 0
UNKNOWN = -1
class pyschlage.device.DoorState(*values)

State of the door, for locks with a door position sensor.

CLOSED = 2
FAULTY = 3
OPEN = 1
UNKNOWN = 0
class pyschlage.device.OperatingMode(*values)

Which protocol stack the lock is operating under.

HOMEKIT = 2
SCHLAGE = 1
SIMULTANEOUS = 3
UNKNOWN = 0

Users

The Schlage object’s users() method, as well as the Lock.users attribute, return User objects.

class pyschlage.user.User(name: str | None = None, email: str = '', user_id: str = '')

A Schlage API user account.

email: str = ''

The email associated with the account.

name: str | None = None

The username associated with the account.

user_id: str = ''

Unique identifier for the user.

Exceptions

Exceptions used in pyschlage.

exception pyschlage.exceptions.Error

Base error class.

exception pyschlage.exceptions.InvalidCodeError

Raised when an access code is not one the lock will accept.

Also a ValueError, since a non-numeric access code previously raised that from within a save operation.

exception pyschlage.exceptions.NotAuthenticatedError

Raised when a request is made to an unauthenticated object.

exception pyschlage.exceptions.NotAuthorizedError

Raised when invalid credentials are used.

exception pyschlage.exceptions.UnknownError

Raised when an unknown problem occurs.