Add on Configuration
The documentation below is focused on Node.js adapters, but other languages are supported as well.
The add-on can publish a configuration page on the gateway URL /settings/addons/config/youraddon, provided that it provides a JSON-schema in its manifest.
If the add-on provides configurable values, manifest.json should have an options field.
Example 1: JSON-schema for simple configuration.
{
"options": {
"schema": {
"type": "object",
"properties": {
"foo": {
"type": "string"
},
"bar": {
"type": "string"
}
}
}
}
}Configuration page for Example 1:
When the Apply button is pushed, the add-on is reloaded and can retrieve the user input with the Database class.
const {Database} = require('gateway-addon');
const manifest = require('./manifest.json');
loadMyAdapter(addonManager, _, errorCallback) {
const db = new Database(manifest.id);
db.open().then(() => {
return db.loadConfig();
}).then((config) => {
// config contains values which user input.
}).catch(console.error);
}If the add-on should have default values which are configurable in order to work without configuration, manifest.json should have a default field inside options.
Example 2: JSON-schema and default values for simple configuration.
{
"options": {
"default": {
"foo": "default value foo",
"bar": "default value bar"
},
"schema": {
"type": "object",
"properties": {
"foo": {
"type": "string"
},
"bar": {
"type": "string"
}
}
}
}
}Configuration page for Example 2:
The add-on can also provide descriptions about configurable values.
Example 3: JSON-schema for configuration with description.
{
"options": {
"schema": {
"type": "object",
"description": "this is description",
"properties": {
"foo": {
"type": "string",
"description": "this is description for foo"
},
"bar": {
"type": "string",
"description": "this is description for bar"
}
}
}
}
}Configuration page for Example 3:
If the add-on provides configurable values which are variable length, JSON-schema should have array field.
Example 4: JSON-schema for configuration which have variable length values.
{
"options": {
"schema": {
"type": "array",
"title": "addable field",
"items": {
"type": "string"
}
}
}
}Configuration page for Example 4:
+ button clicked:
If the add-on provides a dynamic form which is related with some configurable values, JSON-schema should have oneOf field and dependencies field.
Example 5: JSON-schema for configuration with dynamic form.
{
"options": {
"schema": {
"title": "Device",
"type": "object",
"properties": {
"deviceType": {
"type": "string",
"enum": [
"light",
"dimmingLight",
"colorLight"
],
"default": "light"
}
},
"required": [
"deviceType"
],
"dependencies": {
"deviceType": {
"oneOf": [
{
"properties": {
"deviceType": {
"enum": [
"light"
]
}
}
},
{
"properties": {
"deviceType": {
"enum": [
"dimmingLight"
]
},
"recommendBrightness": {
"type": "number"
}
},
"required": [
"recommendBrightness"
]
},
{
"properties": {
"deviceType": {
"enum": [
"colorLight"
]
},
"recommendColor": {
"type": "string"
}
},
"required": [
"recommendColor"
]
}
]
}
}
}
}
}Configuration page for Example 5:
Change deviceType to dimmingLight:
Change deviceType to colorLight:
If you need more information about generating configuration with JSON-schema, see here.
The gateway has jsonschema-form which is ported without uiSchema and customForm.
The use case is based on this question.
If the add-on provides some device-specific information in order to help a user input configuration values,"e.g. How many devices should be configured?", the add-on can add information to the config.
Example 6: JSON-schema for helping a user input values
{
"options": {
"schema": {
"type": "object",
"properties": {
"WiFiAccessPoint": {
"type": "object",
"properties": {
"SSID": {
"type": "string"
},
"password": {
"type": "string"
}
},
"required": [
"SSID",
"password"
]
},
"discoveredDevices": {
"type": "array",
"description": "Dont add or delete discoveredDevices.",
"items":{
"type": "object",
"properties": {
"name":{
"type": "string"
},
"pin1": {
"type": "string"
},
"pin2": {
"type": "string"
}
}
}
}
}
}
}
}The add-on code for helping a user input values:
const {Adapter, Database} = require('gateway-addon');
class SettingsTestAdapter extends Adapter {
constructor(addonManager, packageName) {
super(addonManager, packageName, packageName);
addonManager.addAdapter(this);
// if discovered dvices, add to config.
const discoveredDevices = [
{name: 'device1'},
{name: 'device2'},
{name: 'device3'},
];
const db = new Database(packageName);
db.open().then(async () => {
const config = await db.loadConfig();
config.discoveredDevices = discoveredDevices;
db.saveConfig(config);
});
}
}Configuration page for Example 6:
First step, the user input WiFi configuration for connecting an router and devices.
Second step, the user input the device configuration for using the device.
