Settings
Device settings allow users to customize the behaviour of their devices from Homey.
Devices can have settings that can be changed by the user. These are presented to the user as Advanced settings. The device settings are defined in the /drivers/<driver_id>/driver.settings.compose.json
file.
Defining settings
Every setting has a type
property that determines what values it can have and how it is presented to the user. The value
property of each setting is the initial value of the setting, this property is required for all settings. The following setting types are supported:
Text
This is a single line text input whose value is a string
. You can optionally validate the value using a regex pattern by adding a pattern
property. For example adding "pattern": "[a-zA-Z]"
to the setting definition will make sure the user can only input letters.
Password
Settings with the type password
behave the same as text
but the input is visually hidden.
Text area
textarea
type settings behave the same as text
but allow multi-line input.
Number
The number
type settings can only contain numbers, this means that the value
must also be a number. Number settings also support min
max
and step
properties. You can also optionally provide the unit of the setting by setting the units
property.
Checkbox
checkbox
settings can be true
or false
.
Dropdown
Settings with the type dropdown
allow the user to pick a value from a predefined set of choices. The values of the checkbox must be strings.
Group
You can add a type
group to your settings to group multiple settings together with a label.
Label
You can add additional explanation or headings to the device settings page by adding a setting with the type label
. This acts as a read-only text field and can only be updated by your app.
Highlighted settings
In an app with an extensive list of settings, it can be challenging for users to locate the most important ones. To address this, there's an option to display key settings in a separate list during the pairing of a new device. This feature, called "Highlighted Settings," helps users quickly find the most essential settings.
To highlight a settings item, simply add "highlight": true
to the item in your settings JSON file.
Be selective when choosing highlighted settings. The goal is to feature a few frequently used items. Highlighting too many settings can make the highlighted list just as difficult to navigate as the full list of settings.
Using settings
Once you have defined what settings your device has you can read the settings in from your Device
class. You can retrieve the current values of all settings as follows:
When settings are changed by a user, Device#onSettings()
will be called. You can overwrite the method in your device.js
to react to changes to the settings. It is also possible to throw an error from this method if the settings are invalid. The thrown error will be shown to the user and they be asked to change their settings in order to store them.
It is also possible to update the settings from your Device
by calling Device#setSetting()
.
When changing device settings programmatically using Device#setSettings()
, the Device#onSettings()
function is not fired.
Last updated