Show Input form, default units (form_settings)

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

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

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

[
  {
    "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.

[
  {
	"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

[
  {
	"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:

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.

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.

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

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

The 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.

Note on priority matching:

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",

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

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

Support & QA