Settings
Settings
A device's settings are its own configuration: a lock's auto-lock time, a motion sensor's sensitivity, how often a meter reports. Each device describes its own; the hub lists them as the device gives them.
Reading settings
curl https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/settings \ -H "Authorization: Bearer $ONEKEY_API_KEY"
{
"data": [
{
"id": "auto_lock",
"title": "Auto-lock",
"value": 0,
"min": 0,
"max": 300,
"unit": "s",
"default": 0,
"readonly": false,
"advanced": false
},
{
"id": "2",
"title": "Motion sensitivity",
"value": 8,
"min": 1,
"max": 10,
"default": 8,
"readonly": false,
"advanced": true
}
]
}
| Field | |
|---|---|
id |
Opaque. Use it as given to change the setting |
value |
What the device last reported |
pending |
A value sent and not yet reported by the device |
min, max, step, default, unit |
What the device accepts, when it says |
readonly |
Can't be changed |
advanced |
Rarely changed; a UI can tuck it away |
source |
For wakeup_interval: device (its own), quirk (the hub's correction for the product) or override (set through the API) |
Needs hubs:read.
Changing a setting
curl -X PATCH https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/settings/auto_lock \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"value": 30}'
{ "device_id": 7, "id": "auto_lock", "pending": 30 }
202 means the hub sent it. A device that sleeps takes it at its next wake-up; read the settings again to see the device's value. "value": null takes back a value set through the API, where the hub can. Needs hubs:write.
| Refusal | Why |
|---|---|
400 "that setting is read-only" |
readonly |
400 "that value is outside the range the device gave" |
outside min..max, or off step |
400 "that interval would drain the device's battery…" |
a wakeup_interval below what the hub allows |
422 command_refused |
a lock, keypad or garage door that did not join securely enough to be driven: its settings are read-only |
Settings every device of a kind has
| Setting | Devices | |
|---|---|---|
auto_lock |
Locks | Seconds after unlocking until it locks itself; 0 never. Many locks ship with it off |
wakeup_interval |
Battery devices that sleep | Seconds between check-ins. Shorter drains the battery; the hub's least is usually an hour |
Other settings are the device's own and differ by product; the device registry links each product's manual.