Device and Feature templates explained

[stefxx]

MAIN PRINCIPLE OF THIS PLUGIN

I am using many IoT devices using MQTT, currently over 120. I have tried several existing MQTT plugins, and they are all great except for one thing; reusability. I found myself spending many hours configuring the same device type over and over, and depending on how precisely I duplicated all steps I would get more or less the same results. When adding functionality or improving existing functions, I needed to redo that again to many devices. So instead of making MQTT Topics the basis for this plugin, I choose the actual device as a starting point.

It is probably not the most flexible MQTT plugin looking at the numbers of features. But it is simple, predictable, stable and extremely fast. And keeps maintaining my devices to a minimum. Also, since Device and Feature templates are reusable, it would be great if we could create a community where we share our templates for others as well.

DEVICE AND FEATURES TEMPLATES

Simply put, a Device template is a reference to a MQTT device type. For instance, a Shelly 2.5. If defines basic characteristics like name and the features it holds. The definition of the features are in a separate template called Feature template. There all characteristics of that specific feature is defined. A feature often refers to a single MQTT topic, but it can also be used to listen to multiple topics, each holding multiple value and status information. If a MQTT device can also be controlled, it can also be configured in the Feature template, using multiple controls like buttons and sliders, and can use multiple MQTT commands.

When assigning a Device template to an actual device, a HS4 device will be created. The Device template should have one or more Feature templates assigned to it, and for each Feature template a HS4 feature (child device) below the HS4 device will be created as well.

You can use the "Device templates" and "Feature templates" tabs in the MQTT IoT setup for easy editing. You can also edit the JSON files directly if you prefer. Make sure to adhere to the JSON standards when editing JSON files, so either use a good JSON editor or an online one like this: https://jsonformatter.org/json-editor. The plugin also allows for direct editing the JSON (raw) templates, and basic JSON formatting checking will be performed before it can be saved.

[stefxx]

DEVICE TEMPLATES

Device templates are located in the <HomeSeer root>\data\MQTT_IoT directory. For Windows, that should be something like “C:\Program Files (x86)\HomeSeer HS4\data\MQTT_IoT”. After initial installation, no templates will exist so I recommend installing some templates from the “Install Templates” tab. Copy and modify an existing template will help setting up your first custom template.

The device layout is quite simple. Start by opening the "Device templates" tab in the setup or open the JSON file in your editor.

Using the plugin setup, select the file to edit from the dropdown list. Or select "Create a new device template" if you want to start from scratch. The first field will be to (re-)name the file. Make sure to give it a ".json" extension, otherwise the name will be ignored. For existing files, there is also a "Delete" button to delete the file.

Then we can start editing the JSON, using the following fields:

• Template: Used to name this device. It is recommended to keep this in line with the filename for easy reference. But you can use anything you like to identify this device type.
• Note: Free text to be displayed when you configure this device. I use it often as a reminder to configure a device with specific settings.
• Param 1..3: Optional variables that can hold any values, and be used as string replacements in the Feature templates. I use this for Zigbee devices, as I need the name of the Zigbee coordinator in order to control a Zigbee device. In this case you would assign one of the parameters "Zigbee coordinator".
• Features: Unlimited number of features assigned to this device. For each feature, you can select any Feature template from both the Default and Custom folder.
  • Feature x: The first three options are to remove or move the feature up or down. Below you'll find all Feature templates to choose from. Select the appropriate features from the list until you have selected all required features.
  • Name: You can overrule the feature name here. When left blank, it will use the name as defined in the Feature template. The name will be used to create the HS4 feature. For instance, "Power", "Light", "Watts", "Temperature" etc.

Here is an example of a Shelly 2.5 Device template running Tasmota firmware:

{
  "template": "Shelly 2.5 (Tasmota)",
  "note": "\"SetOption 59 1\" and \"SetOption90 1\" is recommended",
  "features": [
    {
      "template": "Tasmota Power 1"
    },
    {
      "template": "Tasmota Power 2"
    },
    {
      "template": "Tasmota Watts 1"
    },
    {
      "template": "Tasmota Watts 2"
    },
    {
      "template": "Tasmota Temperature",
      "name": "Temperatuur"
    },
    {
      "template": "Tasmota IP Address"
    },
    {
      "template": "Tasmota LWT"
    }
  ]
}

[stefxx]

FEATURE TEMPLATES

Standard feature templates are located in the <HomeSeer root>\data\MQTT_IoT directory\<DeviceName>. For Windows, that should be something like “C:\Program Files (x86)\HomeSeer HS4\data\MQTT_IoT\Shelly Plug S”.


The feature layout is a bit more complicated than the device layout (see above), but still easy to understand. Start by opening the "Feature templates" tab in the setup or open the JSON file in your editor.

Using the plugin setup, select first the device and than the feature to edit from the dropdown list. Or select "Create a new feature template" if you want to start from scratch. The first field will be to (re-)name the file. Make sure to give it a ".json" extension, otherwise the name will be ignored. For existing files, there is also a "Delete" button to delete the file.

Then we can start editing the JSON, using the following fields:

• Template: Used to name this feature. It is recommended to keep this in line with the filename for easy reference. But you can use anything you like to identify this Feature type.
• Name: Name of this feature, used to create the HS4 feature.
• Address: Address of this feature, used to create the HS4 feature. Make sure it is unique for each device, keep it short and without special characters and spaces.
• Status sets: Unlimited number of Status sets. Create a Status set for each MQTT Topic the feature supports.
  • Topic: Full topic(s) to listen to. Use #TOPIC# to replace the topic name from the device, and : to indicate a JSON value. If a colon is being used in a JSON field, use \:.
  • Value sets: Unlimited number of value sets. Create a Value set for each value or value range the above MQTT Topic(s) can receive.
    • Payload: The action Payload being received. Note that this is case sensitive.
    • Array index: If the value received is an array, indicate the index of the value required. Leave 0 for non-array fields. The index starts at 1.
    • Value: The received value to match. Set to 0 if a range is used (see below)
    • Range start: Start range, or 0 for a fixed value
    • Range end: End range, or 0 for a fixed value
    • Status: The HS4 display status. Use #PAYLOAD# to include the payload.
    • Image: The feature image
    • Prefix: Prefix to use when displaying the value
    • Suffix: Suffix to use when displaying the value
    • Decimals: Number of decimals to use when displaying the value
    • Factor: The value shown will be multiplied with this factor. To divide, use fractional numbers.
    • Dimmer status: Used to ensure proper dimmer operations. Empty = no dimmer, on = set to last value, off = off, level = set to specific dim level.
    • Should this value always be set when received, even if unchanged?: Set to true or false to indicate the feature should update, even if the received value is unchanged. Useful for buttons that might update to the same value when pressed repeatedly.
• Control sets: Unlimited number of Control sets. Create a Control set for every possible control the feature supports.
  • Topic: Full topic to send. Use #TOPIC# to replace the topic name from the device, and : to indicate a JSON value. If a colon is being used in a JSON field, use \:.
  • Value sets: Unlimited number of value sets. Create a Value set for each value or value range to be send to the device.
    • Payload: The action Payload to send. Note that this is case sensitive. You can use #NUMBER# and status# to use the actual Value or Label fields below. Especially useful for ranges. HS4 Replacement Variables are supported. For variables that use a feature reference, you can use reference 0 for the current feature. Also calculations are supported. Can also be used for step-up or step-down. Ie “$$DVR: (0):+.5)“ will set the payload to the current feature value + 0.5.
    • Type: button/slider/dropdown. Use button for single values, slider or dropdown for ranges.
    • Label for button/slider/dropdown: The label to be used for the button.
    • Column for button/slider/dropdown: If you want to control the position of the button on the HS4 device page, you can set the column here. 0 for default.
    • Row for button/slider/dropdown: If you want to control the position of the button on the HS4 device page, you can set the row here. 0 for default.
    • Button value: The value to send. Set to 0 if a range is used (see below)
    • Slider/dropdown range start: Start range, or 0 for a fixed value
    • Value range end: End range, or 0 for a fixed value
    • Prefix: Prefix to use when displaying the value
    • Suffix: Suffix to use when displaying the value
    • Control use: Used by other apps like HSTouch to give context on the status.

Here is an example of the "Tasmota Power 1" template, used by the Shelly 2.5:

{
  "template": "Tasmota Power 1",
  "name": "Power 1",
  "address": "Power1",
  "status": [
    {
      "topics": [
        "tele/#TOPIC#/STATE:POWER1"
      ],
      "values": [
        {
          "payload": "OFF",
          "value": 0,
          "status": "Off",
          "image": "off.gif"
        },
        {
          "payload": "ON",
          "value": 100,
          "status": "On",
          "image": "on.gif"
        }
      ]
    }
  ],
  "control": [
    {
      "topic": "cmnd/#TOPIC#/POWER1",
      "values": [
        {
          "payload": "OFF",
          "type": "button",
          "value": 0,
          "label": "Off",
          "controluse": "off"
        },
        {
          "payload": "ON",
          "type": "button",
          "value": 100,
          "label": "On",
          "controluse": "on"
        }
      ]
    }
  ]
}