RFC: Improve device configuration format

@LordMike I hope you don’t mind that I hijack your suggestions, but there are a couple of configuration file weirdnesses that I want to discuss.

More concise definition of partial parameters (#1436, proposed by @LordMike)

The current format looks like this:

"9[0x01]": {
	"label": "Alarm reaction to Access Control trigger state",
	"description": "React to access control triggers from other Z-Wave devices.",
	"valueSize": 2,
	"minValue": 0,
	"maxValue": 1,
	"defaultValue": 0,
	"readOnly": false,
	"writeOnly": false,
	"allowManualEntry": true
},
"9[0x0100]": {
	"label": "Alarm reaction to Smoke Alarms",
	"description": "React to Smoke Alarms from other Z-Wave devices.",
	"valueSize": 2,
	"minValue": 0,
	"maxValue": 1,
	"defaultValue": 0,
	"readOnly": false,
	"writeOnly": false,
	"allowManualEntry": true
},
...

It’s clunky, as we must repeat a number of values between settings - and come up with multiple labels and so on. I propose the following instead (edited by @AlCalzone):

"9": {
  "label": "Alarm reaction config",
  "description": "React to the following alarms from other Z-Wave devices.",
  // These stay out here and are shared by partial params:
  "valueSize": 2,
  "readOnly": false,
  "writeOnly": false,
  "allowManualEntry": true,
  "partials": {
    "0x01": {
      // Label is concatenated with the shared label of the param itself, e.g. "Alarm Reaction Config: Access Control Trigger State"
      "label": "CO2 Alarm",
      "minValue": 0,
      "maxValue": 1,
      "defaultValue": 0
    },
    "0x200": {
      "label": "CO Alarm",
      // Description overwrites the shared description
      "description": "Lalala",
      // if a bitmask only encompasses a single bit, min/max 0..1 could be implied
      "defaultValue": 0
    }
  }
}

Move manufacturer labels into devices array

We often have a situation where the same device is available under different brands. This leads to duplicated config files that might go out of sync because contributors only edit the one they know about. Or multiple brands share a manufacturer ID, because the same manufacturer made the device. I suggest we make it possible to move the manufacturer name (and potentially device label) into the devices array:

before:

// file 1:
{
	"manufacturer": "Brand A",
	"manufacturerId": "0x001f",
	"label": "Label A",
	"description": "Some Dimmer",
	"devices": [
		{
			"productType": "0x1234",
			"productId": "0x2345"
		}
	],
...
}

// file 2:
{
	"manufacturer": "Brand B",
	"manufacturerId": "0x001f",
	"label": "Label B",
	"description": "Some Dimmer",
	"devices": [
		{
			"productType": "0x0001",
			"productId": "0x0001"
		}
	],
... same as file 1
}

after

// single file:
{
	"label": "Label A",
	"description": "Some Dimmer",
	"devices": [
		{
			"manufacturer": "Brand A",
			"manufacturerId": "0x001a",
			"productType": "0x1234",
			"productId": "0x2345"
		},
		{
			"manufacturer": "Brand B",
			"manufacturerId": "0x001b",
			"productType": "0x0001",
			"productId": "0x0001"
		}
	],
...
}

In order to avoid repetition, having the manufacturer and label at the root level should still be allowed. The one in the devices array would have priority.

Conditional configuration parameters

==> Implemented in #1810

Templates/imports

=> Implemented in: #1687

[AlCalzone]

Updated the proposals after some discussion.

The only piece of work, that will come of it (looking at the current proposal), is digging deeper into the partials, when parsing the cfg file, to display its info.

You don’t have to do that - the API does that for you. You might only have to be able to display the additional “parent” param.

[marcus-j-davies]

my 2c,

Once upon a time, browser was reliant on manufacturers.json, as everything was traversed from that seed. Where-ever this ends up, as long as the index format doesn’t change, and it still has the properties, with their designated keys/location within the index (including the manufacture id/brand name, file location), it shouldn’t cause any issues.

Having just migrated browser to the index, id hate for that to be a lost cause.

The only piece of work, that will come of it (looking at the current proposal), is digging deeper into the partials, when parsing the cfg file, to display its info.

Edit: The version of browser that uses the index will drop after 6.1.4