[RFC] Thing configuration

[spacemanspiff2007]

trafficstars

Currently a thing is used to represent an (to openHAB) external device (at least most of the time). However the current data and configuration structure does not properly represent this situation leading to all different kind of issues. With this issue(s) I'll try to create an overview how a thing can be used and I'd like to make a suggestion how to change it (hopefully for the better 😉 )

Configuration

1. Thing interaction

Configuration of the thing on the openHAB side. This defines how openHAB interacts with the device. Example:

• IP Address of an external Device
• Poll period
• authentication information
• location (Astro binding)

This configuration can be validated and directly set by the binding on the thing creation

2. Device configuration

Configuration of the represented device. This changes settings/parameters on the represented device and thus device behavior. Example:

• Selecting Venetian/ Rollershutter - Mode for a Rollershutter
• Fade-In time on physical connected button press for a dimmer
• Report time interval for a sensor

Since this configuration is done on the device it's possible that the device rejects the sent configuration e.g. if it's invalid. Battery powered devices are asleep most of the time so it's possible that the configuration is only applied when the device wakes up the next time.

3. Current implementation

All configuration options are mixed together

  "configuration": {
    "pollingInterval": 300,
    "venetianMode": true
  },

Shortcomings:

• There is no way to provide feedback to the user if and why e.g. a parameter has been rejected by the device.
• Additionally the parameter status is misleading: Changing a value and immediately changing it back for a battery powered device will show the parameter as "PENDING" even though it's correct.
• Changing device configuration through UI can not be done together with textual configuration (Sometimes the device is not in the zwave database yet)

4. Improvements

4.1 Separate device and thing configuration

Strictly separate the configuration of the openHAB side and the device side. The Example from 3. becomes this:

  "thingConfiguration": {
    "pollingInterval": 300
  },
  "deviceConfiguration": {
    "venetianMode": true
  },

4.2 Model remote parameter for device configuration

Since the device can reject the configuration or it might take some time to update it the device configuration should represent that. Something like:

"deviceConfiguration": [ {
    "name": "config_42",
    "value": 15,
    "newValue": 16,
    "newValueStatus": "PENDING",
}]

4.4 Add a way to model referencing parameters for device

Devices (especially cheap micro controller devices) often use bitfields to enable/disable functionality. Multiple bits can be used to enable/disable certain functionality but the value transmitted to the device is always the complete byte (or multiple bytes). The user does not want to calculate the the binary representation of the bits so the goal is that the GUI provides a drop down for each bit with a description.

The Z-Wave binding uses the following naming mechanism to model this: Each bitfield parameter hat at least two config options: config_5_1 : Whole parameter config_5_1_00000002: Bitfield parameter

config_5: Parameter 5 (Z-Wave Parameters are identified by number) 1: Size 1 Byte 00000002: Bitmask which identifies which bits to set in the parameter

It would be nice if this functionality would be available consistently for all bindings. A way this could be implemented is to add a new virtual parameter to the config description

{
    "type": "VIRTUAL_INTEGER",
    "parent": "config_5",
    "bitmask": "00000002",
    "name": "config_5__1"
    "...": "rest of ConfigDescriptionDTO"
}

Note:

• Instead of bitmask it would be nicer to use both bitPos and bitWidth.
• instead of "VIRTUAL_INTEGER" a flag isVirtual: true would also be a good way

[spacemanspiff2007]

5. Thing actions

Some devices hide actions behind the configuration. E.g. it's possible to put the z-wave stick into inclusion mode for 30s/60s by changing a configuration value (which automatically changes back after the time). In the GUI these actions are displayed using config-descriptions

    {
      "default": "false",
      "description": "Puts the controller into Exclusion mode.",
      "label": "Exclude Devices",
      "name": "controller_exclude",
      "required": false,
      "type": "BOOLEAN",
      "readOnly": false,
      "multiple": false,
      "groupName": "actions",
      "advanced": true,
      "verify": false,
      "limitToOptions": true,
      "options": [],
      "filterCriteria": []
    },

It's very confusing that configuration values are misused to trigger temporary actions of a device. Additionally when using textual configuration it's not possible to use these actions because it's not possible to change the properties.

Improvement

A dedicated thing action rest endpoint is the proper and clean solution. There the description and required parameters can be queried and the execution triggered. This overlaps with /actions/{thingUID} which probably should have been /things/{thingUID}/actions

[J-N-K]

Regarding 5: This should be fixed in the binding by implementing a proper thing action. This should be available from the REST API without modifications.

[spacemanspiff2007]

The action is only triggered by the user and not by rules. So the user has to have the availability to click a button in the GUI. I'm guessing that's the reason it's implemented the way it is. Everything except View Network Map triggers an action on the device and it's all done through configuration.