Settings Locking
Overview
Settings locking prevents conflicts when both the web dashboard and the device itself try to configure settings at the same time. Without locking, one side's changes could silently overwrite the other, leading to unexpected behavior.
When either side acquires a lock, the other side is blocked from saving settings until the lock is released.
How It Works
When you edit a device on the web dashboard, a web lock is automatically acquired. While the web lock is active, the device cannot overwrite any configuration settings. When you save or leave the edit page, the lock is released.
The same works in reverse: if the device acquires a device lock (by setting is_settings_locked_device: true via the device API), the web dashboard will show a warning and block saves until the device releases the lock or the lock expires.
Status fields such as battery percentage, version numbers, and connection state are exempt from locking and can always be reported by the device.
Lock Types
| Lock | Set By | Meaning |
|---|---|---|
Web lock (is_settings_locked_web) |
Web dashboard | A user is editing settings from the web dashboard |
Device lock (is_settings_locked_device) |
Device API | The device is configuring its own settings (e.g. writing encrypted credentials) |
Initial setup (waiting_for_configuration_from_web) |
System | The device has not been fully configured yet |
A device is considered locked (is_settings_locked = true) if any of the three conditions above are active.
Auto-Expiry
Locks automatically expire after 15 minutes. This prevents stale locks caused by browser crashes, device disconnects, or other unexpected interruptions.
If a lock has been held for longer than 15 minutes, it is treated as expired and the other side can save freely.
Force Unlock
If a device is stuck in a locked state, you can force unlock it from the web dashboard:
- Navigate to the device detail page
- If the device is locked, a yellow banner will appear at the top
- Click Force Unlock to clear all locks (both web and device)
Force unlock clears all lock fields immediately, allowing both sides to save again.
API: Device-Side Locking
Devices can acquire and release locks when updating settings via the device API (PUT /device).
Lock Check Behavior
If a device tries to save protected settings while the web dashboard holds a lock, the API will return a 422 error:
{
"error": "Settings are locked. The web dashboard is currently configuring this device.",
"is_settings_locked": true
}
Status fields (battery, version, connection state, etc.) are exempt from the lock check and can always be updated.