Versions Compared

Version Old Version 1 New Version Current
Changes made by

Brent Meriwether (Unlicensed)

Brent Meriwether (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

TODO - Info updated 4/13/2022

For the form settings you can save units to new keys.

...

Table of Contents

How to show form input during the Add process, in Device Settings

Certain devices require (or provide) additional options for setup or configuration. You can use form settings to expose these options to the customers during the Add Device process. These options are also available to the user post-install via the Settings screen for the device. The information shown in this section will help guide you in displaying custom input fields to the user.

💡 Note: If you do not customize the form settings, the options shown to the user will default to a core set of inputs based upon the device type. You can then override this behavior by customizing the form settings as detailed below.

...

Custom input fields are controlled by adding a list of setting objects as JSON objects. When building your own settings like this, there are a few things to consider:

  • JSON must be valid, so use a validator such as https://jsonformatter.org/ .

  • Ordering follows the order property (0,1,2,...).

  • Each “settings object” is separated with a comma, but you can’t have a dangling comma at the end.

To define settings for the device, on the Attributes tab, create a form_settings attribute and specify the settings you want displayed. To help you get started in crafting your form settings, below are some examples demonstrating common input fields.

Examples & basics for creating input fields

Info

The following is the overview & original examples for form_settings. Please note the updated format below that covers updates to the format and that newer style should be used going forward.

Basic Temperature selection

...

Code Block
[
  {
    "order": 0,
    "label": null,
    "variables": [
      {
        "order": 0,
        "label": "Unit",
        "type": "string",
        "min": null,
        "max": null,
        "form": "select",
        "key": "unit",
        "default_value": "f",
        "required": true,
        "values": [
          { "value": "f", "label": "°F", "short": "°F" },
          { "value": "c", "label": "°C", "short": "°C" }
        ]
      }
    ]
  }
]

Temperature and Offline Data Retrieval in minutes

Here’s an example that builds on basic Temperature by also adding the Offline Data Retrieval interval setting that is used by certain Laird Probe devices.

...

Code Block
[
  {
	"order": 0,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Unit",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "unit",
    	"default_value": "f",
    	"required": true,
    	"values": [
      	{
        	"value": "f",
        	"label": "°F",
        	"short": "°F"
      	},
      	{
        	"value": "c",
        	"label": "°C",
        	"short": "°C"
      	}
    	]
  	}
	]
  },
  {
	"order": 1,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Offline Data Retrieval",
    	"type": "number",
    	"min": 5,
    	"max": 1440,
    	"form": "input",
    	"key": "codec.offline_minutes",
    	"default_value": 10,
    	"required": true,
    	"values": null,
    	"help_texts": [
      	{
        	"order": 0,
        	"value": "Readings are stored locally for several days. If a device is offline, missing data is retrieved when the device comes back online."
      	},
      	{
        	"order": 1,
        	"value": "Set the amount of minutes a device has been offline before data retrieval is triggered."
      	}
    	]
  	}
	]
  }
]

Volumetric settings

Code Block
[
  {
	"order": 0,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Unit",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "unit",
    	"default_value": null,
    	"required": true,
    	"values": [
      	{
        	"value": "af",
        	"label": "Acre-foot (ac ft)",
        	"short": "ac ft"
      	},
      	{
        	"value": "ft3",
        	"label": "Cubic feet (ft³)",
        	"short": "ft³"
      	},
      	{
        	"value": "m3",
        	"label": "Cubic meter (m³)",
        	"short": "m³"
      	},
      	{
        	"value": "gal",
        	"label": "Gallon (gal)",
        	"short": "gal"
      	},
      	{
        	"value": "l",
        	"label": "Liter (L)",
        	"short": "L"
      	},
      	{
        	"value": "ml",
        	"label": "Milliliter (mL)",
        	"short": "mL"
      	}
    	]
  	}
	]
  },
  {
	"order": 1,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Interval",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "time_interval",
    	"default_value": null,
    	"required": true,
    	"values": [
      	{
        	"value": "latest",
        	"label": "Latest",
        	"short": null
      	},
      	{
        	"value": "hr",
        	"label": "Hour",
        	"short": "hr"
      	}
    	]
  	}
	]
  }
]

Example of All settings

Here is all settings all at once as JSON:

Code Block
[
  {
	"order": 0,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Unit",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "unit",
    	"default_value": "f",
    	"required": true,
    	"values": [
      	{ "value": "f", "label": "°F", "short": "°F" },
      	{ "value": "c", "label": "°C", "short": "°C" }
    	]
  	}
	]
  },

  {
	"order": 0,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Detection Threshold",
    	"type": "number",
    	"min": 0,
    	"max": 1000,
    	"form": "input",
    	"key": "codec.maxthreshold",
    	"default_value": 100,
    	"required": true,
    	"values": null
  	}
	]
  },

  {
	"order": 0,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Unit",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "unit",
    	"default_value": null,
    	"required": true,
    	"values": [
      	{
        	"value": "af",
        	"label": "Acre-foot (ac ft)",
        	"short": "ac ft"
      	},
      	{
        	"value": "ft3",
        	"label": "Cubic feet (ft³)",
        	"short": "ft³"
      	},
      	{
        	"value": "m3",
        	"label": "Cubic meter (m³)",
        	"short": "m³"
      	},
      	{
        	"value": "gal",
        	"label": "Gallon (gal)",
        	"short": "gal"
      	},
      	{
        	"value": "l",
        	"label": "Liter (L)",
        	"short": "L"
      	},
      	{
        	"value": "ml",
        	"label": "Milliliter (mL)",
        	"short": "mL"
      	}
    	]
  	}
	]
  },
  {
	"order": 1,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Interval",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "time_interval",
    	"default_value": null,
    	"required": true,
    	"values": [
      	{ "value": "latest", "label": "Latest", "short": null },
      	{ "value": "hr", "label": "Hour", "short": "hr" }
    	]
  	}
	]
  },

  {
	"order": 0,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Unit",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "unit",
    	"default_value": "ma",
    	"required": true,
    	"values": [
      	{
        	"value": "ma",
        	"label": "Milliampere (mA)",
        	"short": "mA"
      	},
      	{
        	"value": "a",
        	"label": "Ampere (A)",
        	"short": "A"
      	}
    	]
  	}
	]
  },

  {
	"order": 0,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Unit",
    	"type": "string",
    	"min": null,
    	"max": null,
    	"form": "select",
    	"key": "unit",
    	"default_value": "f",
    	"required": true,
    	"values": [
      	{ "value": "f", "label": "°F", "short": "°F" },
      	{ "value": "c", "label": "°C", "short": "°C" }
    	]
  	}
	]
  },
  {
	"order": 1,
	"label": null,
	"variables": [
  	{
    	"order": 0,
    	"label": "Offline Data Retrieval",
    	"type": "number",
    	"min": 5,
    	"max": 1440,
    	"form": "input",
    	"key": "codec.offline_minutes",
    	"default_value": 10,
    	"required": true,
    	"values": null,
    	"help_texts": [
      	{
        	"order": 0,
        	"value": "Readings are stored locally for several days. If a device is offline, missing data is retrieved when the device comes back online."
      	},
      	{
        	"order": 1,
        	"value": "Set the amount of minutes a device has been offline before data retrieval is triggered."
      	}
    	]
  	}
	]
  }
]

Special Case: Overriding input form for reserved device_type’s

Some of the existing (see Reserved) devices inherit some form_settings. If you are creating a new device type using the existing one as a copy, this may be undesirable. You can override these settings by either using a new device_type or by simply specifying an empty form_settings attribute.

...

Anchor
new_format
new_format
New format - support for multiple Input fields

This new format allows you to specify individual channels in the form_settings. Thus you can specify multiple input fields to be shown, their order, default units for each, etc.

  • Support added end of April 2022.

  • This new format is now what should be used for all new templates.

  • The Legacy form_settings format will still work in older templates.

  • Old templates can be updated to the new format by simply editing the template and re-saving with the newly changed form_settings.

    • Existing Paired devices will continue to use existing settings (e.g. it pulls the default units from template).

    • If you define new units in the form_settings, the user simply needs to Refresh their screen to see the new options - there’s no need to re-add device.

    • If form_settings are updated and a user with existing Paired device wants to take advantage without re-adding, they can simply open Settings for device, make selections in the new dropdowns and click Save.

form_settings with Individual channels format:

This is example of Milesight AM107 template which was updated so that now user can not only select Temperature channel units but also now can set Barometric Pressure units.

Code Block
[
  {
    "order": 0,
    "label": null,
    "variables": [
      {
        "order": 0,
        "label": "Temperature Unit",
        "type": "string",
        "min": null,
        "max": null,
        "form": "select",
        "key": "child.3.unit",
        "default_value": "f",
        "required": true,
        "values": [
          { "value": "f", "label": "°F", "short": "°F" },
          { "value": "c", "label": "°C", "short": "°C" }
        ]
      },
      {
        "order": 1,
        "label": "ProbeBarometric pressure Unit",
        "type": "string",
        "min": null,
        "max": null,
        "form": "select",
        "key": "child.713.unit",
        "default_value": "fhpa",
        "required": true,
        "values": [
          { "value": "fpa", "label": "°FPascal", "short": "°FPa" },
          { "value": "chpa", "label": "°CHectopascal", "short": "°ChPa" }
        ]
      }
    ]
  }
]

The Key should match the Channel as defined in the template.

For example Channel 3 (Temperature) from this template is matched with:

Code Block
"key": "child.3.unit"

where 3 is the channel

the priority isThe value in values definition should match the Payload from the template’s Units:

For example adding an entry to match “Hectopascals” would use "value": "hpa". The short and label can be used to display nice text to the user.

Code Block
"values": [
          { "value": "hpa", "label": "Hectopascal", "short": "hPa" }

...

Note on priority matching:

Code Block
1. properties.child.X.unit
2. properties.unit (if it is a valid unit for the sensor)
3. the unit marked as "default" for the capability if the sensor has console capability
4. sensor.unit, not sure where it is defined, but might be the standard unit API returns
5. no unit ("null" unit is also not shown)

Clone (using one key for multiple channels)

You can use cloning to show one input field that then gets used to set the units for multiple channels. You can either add a "clone_to_key": ”another_key” or you can use array support as well.

Example: Specifying one input that will also clone to one additional channel’s units

"clone_to_key": "child.502.unit",

Code Block
[
  {
    "order": 0,
    "label": null,
    "variables": [
      {
        "order": 0,
        "label": "Precipitation Unit",
        "type": "string",
        "min": null,
        "max": null,
        "form": "select",
        "key": "child.500.unit",
        "clone_to_key": "child.502.unit",
        "default_value": "in",
        "required": true,
        "values": [
          { "value": "in", "label": "Inches", "short": "in" },
          { "value": "mm", "label": "Millimeters", "short": "mm" }
        ]
      }
    ]
  }
]

Example: Specifying array so that the units will be cloned to multiple channels units

"clone_to_key": ["child.502.unit", "child.999.unit"],

Code Block
[
  {
    "order": 0,
    "label": null,
    "variables": [
      {
        "order": 0,
        "label": "Precipitation Unit",
        "type": "string",
        "min": null,
        "max": null,
        "form": "select",
        "key": "child.500.unit",
        "clone_to_key": ["child.502.unit", "child.999.unit"],
        "default_value": "in",
        "required": true,
        "values": [
          { "value": "in", "label": "Inches", "short": "in" },
          { "value": "mm", "label": "Millimeters", "short": "mm" }
        ]
      }
    ]
  }
]