Settings

You can let users choose device-specific settings, by defining them in your /app.json.

For example, take a look at the settings view and the JSON below.

/app.json.

{
    "id": "com.athom.hello",
    ...
    "drivers": [
        {
            "id": "my_driver",
            ...
            "settings": [
                {
                    "type": "group",
                    "label": {
                        "en": "General settings"
                    },
                    "children": [
                        {
                            "id": "text1",
                            "type": "text",
                            "label": {
                                "en": "Text label 1"
                            },
                            "value": "Text value 1",
                            "hint": {
                                "en": "If needed, add an additional description to explain this setting."
                            }
                        },
                        {
                            "id": "number1",
                            "type": "number",
                            "label": {
                                "en": "Number label 1"
                            },
                            "value": 3,
                            "attr": {
                                "min": 0,
                                "max": 5
                            }
                        },
                        {
                            "id": "radio1",
                            "type": "radio",
                            "label": {
                                "en": "Radio label 1"
                            },
                            "value": "choice1",
                            "values": [
                                {
                                    "id": "choice1",
                                    "label": {
                                        "en": "Radio choice 1"
                                    }
                                },
                                {
                                    "id": "choice2",
                                    "label": {
                                        "en": "Radio choice 2"
                                    }
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "group",
                    "label": {
                        "en": "Specific settings"
                    },
                    "children": [
                        {
                            "id": "checkbox1",
                            "type": "checkbox",
                            "value": true,
                            "label": {
                                "en": "Checkbox label 1"
                            }
                        },
                        {
                            "id": "dropdown1",
                            "type": "dropdown",
                            "value": "choice2",
                            "label": {
                                "en": "Dropdown label 1"
                            },
                            "values": [
                                {
                                    "id": "choice1",
                                    "label": {
                                        "en": "Dropdown choice 1"
                                    }
                                },
                                {
                                    "id": "choice2",
                                    "label": {
                                        "en": "Dropdown choice 2"
                                    }
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Settings types

Setting type Value type Description Notes
text string Text field Optionally validate input by Regex using pattern: "yourregex", e.g. pattern: "[a-zA-Z]"
password string Password field
textarea string Textarea field
number number Number field
checkbox boolean Multiple choice checkbox field
radio string Single choice radio field
dropdown string Single choice dropdown field
group - A group of settings Can be nested
label string Text field Read-only

Note that the value attribute is required for each settings in your app.json, as it will be the default value.

Accessing device settings programmatically

Get the device's settings as follows:

/drivers/my_driver/device.js

let settings = this.getSettings();

While these settings are meant for users to change, your driver can also change them programmatically:

/drivers/my_driver/device.js

this.setSettings({
    text1: "newValue",
    // only provide keys for the settings you want to change
})
    .then( this.log )
    .catch( this.error )

When settings are changed by a user through the front-end, the method onSettings() will be fired. Overwrite the method in your device.js to approve or reject the new settings.

/drivers/my_driver/device.js

onSettings( oldSettingsObj, newSettingsObj, changedKeysArr, callback ) {
    // run when the user has changed the device's settings in Homey.
    // changedKeysArr contains an array of keys that have been changed

    // always fire the callback, or the settings won't change!
    // if the settings must not be saved for whatever reason:
    // callback( "Your error message", null );
    // else
    callback( null, true );
}

When changing device settings programmatically using setSettings(), the onSettings() function is not fired.