Settings

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.
/drivers/<driver_id>/driver.settings.compose.json
[
  {
    "id": "username",
    "type": "text",
    "label": { "en": "Username" },
    "value": "John Doe",
    "hint": { "en": "The name of the user." }
  },
  {
    "id": "password",
    "type": "password",
    "label": { "en": "Password" },
    "value": "Secret",
    "hint": { "en": "The password of the user." }
  }
]
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.
{
  "id": "username",
  "type": "text",
  "label": { "en": "Username" },
  "value": "John Doe",
  "hint": { "en": "The name of the user." }
}
Password
Settings with the type password behave the same as text but the input is visually hidden.
{
  "id": "password",
  "type": "password",
  "label": { "en": "Password" },
  "value": "Secret",
  "hint": { "en": "The password of the user." }
}
Text area
textarea type settings behave the same as text but allow multi-line input.
{
  "id": "description",
  "type": "textarea",
  "label": { "en": "Description" },
  "value": "Initial description",
  "hint": { "en": "A custom device description." }
}
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.
{
  "id": "duration",
  "type": "number",
  "label": { "en": "Duration" },
  "value": 3,
  "min": 0,
  "max": 5,
  "units": { "en": "minutes" }
}
Checkbox
checkbox settings can be true or false.
{
  "id": "allow_override",
  "type": "checkbox",
  "value": true,
  "label": { "en": "Allow override" }
}
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.
{
  "id": "mode",
  "type": "dropdown",
  "value": "heating",
  "label": { "en": "Default mode" },
  "values": [
    {
      "id": "heating",
      "label": { "en": "Heating" }
    },
    {
      "id": "cooling",
      "label": { "en": "Cooling" }
    }
  ]
}
Group
You can add a type group to your settings to group multiple settings together with a label.
{
  "type": "group",
  "label": { "en": "Login details" },
  "children": [
    {
      "id": "username",
      "type": "text",
      "label": { "en": "Username" },
      "value": "John Doe",
      "hint": { "en": "The name of the user." }
    },
    {
      "id": "password",
      "type": "password",
      "label": { "en": "Password" },
      "value": "Secret",
      "hint": { "en": "The password of the user." }
    }
  ]
}
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.
{
  "id": "label",
  "type": "label",
  "label": { "en": "IP address" },
  "value": "192.168.0.10",
  "hint": { "en": "The IP address of the device." }
}
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:
/drivers/<driver_id>/device.js
const Homey = require('homey');
​
class Device extends Homey.Device {
  async onInit() {
    const settings = this.getSettings();
    console.log(settings.username);
  }
}
​
module.exports = Device;
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.
/drivers/<driver_id>/device.js
const Homey = require('homey');
​
class Device extends Homey.Device {
  async onSettings({ oldSettings, newSettings, changedKeys }) {
    // run when the user has changed the device's settings in Homey.
    // changedKeysArr contains an array of keys that have been changed
    // if the settings must not be saved for whatever reason:
    // throw new Error('Your error message');
  }
}
​
module.exports = Device;
It is also possible to update the settings from your Device by calling Device#setSetting().
/drivers/<driver_id>/device.js
const Homey = require('homey');
​
class Device extends Homey.Device {
  async onInit() {
    await this.setSettings({
      // only provide keys for the settings you want to change
      username: "Jane Doe",
    });
  }
}
​
module.exports = Device;
When changing device settings programmatically using Device#setSettings(), the Device#onSettings() function is not fired.

Energy

Best practices

Last modified 4mo ago

Copy link

Outline

Defining settings

Text

Password

Text area

Number

Checkbox

Dropdown

Group

Label

Using settings