Topic updated on September 17, 2021

thing_def.create

The thing_def.create command is used to create a new Thing Definition.

TR50 Request

{
  "cmd": {
    "command": "thing_def.create",
    "params": {
      "key": "sample_def",
      "name": "Sample Definition",
      "autoDefProps": false,
      "autoDefAttrs": false,
      "properties": {
        "temp": {
          "name": "Temperature",
          "suffix": "F",
	   "calcAggregates": false,
	   "deDuplicate": false,
	   "searchable": true,
          "unit": "F"
        }
      },
      "alarms": {
        "temp": {
          "name": "Temperature Alarm",
          "states": [
            {
              "name": "Too Cold",
              "color": "#0084FF"
            },
            {
              "name": "Just Right",
              "color": "#00D92B"
            },
            {
              "name": "Too Warm",
              "color": "#E07F00"
            },
            {
              "name": "Too Hot",
              "color": "#B80000"
            }
          ]
	"searchable": true
        }
      },
      "methods": {
        "test": {
          "name": "Test",
          "notificationVariables": {
            "test1": {
              "name": "Test1",
              "type": "int"
            }
          }
        }
      },
      "tunnels": {
        "workbench": {"name":"deviceWISE Workbench", "port":4012, "protocol": "other"},
        "ssh": {"name":"SSH", "port":22, "protocol": "ssh"},
        "rdp": {"name":"RDP", "port":3389, "protocol": "rdp"},
        "vnc": {"name":"VNC", "port":5900, "protocol": "vnc"}
      },
      "tunnelAdHoc": true,
      "locations": {
        "ignoreFixTypes": ["gps", "gnss"],
        "noDecode": true
      }
    }
  }
}

Request Parameters

Name Type Required Description
key String Yes The key of the new Thing Definition.
name String Yes The name of the Thing Definition.
autoDefAttrs Boolean Whether to automatically define attributes as they're published.
autoDefProps Boolean Whether to automatically define properties as they're published.
controlTags Array   An array of control tags associated with the Thing definition
alarms Object Key-value pairs where the key is the alarm key and the value is an alarm definition object.
attributes Object Key-value pairs where the key is the attribute key and the value is an attribute definition object.
methods Object Key-value pairs where the key is the method key and the value is a method definition object.
properties Object Key-value pairs where the key is the property key and the value is a property definition object.
tunnels Object Key-value pairs where the key is the tunnel key and the value is a tunnel definition object.
tunnelAdHoc Boolean Defines if things of this thing definition support ad hoc tunnels.
locations Object Key-value pairs of the location setting and value of the setting.
firmware Object A data structure of firmware versions (see firmware definition object) for things of this thing definition.

Alarm Definition Object

Name Type Required Description
name String Yes The name of the alarm.
states Array Array of alarm state objects, directly correlating with the array's indices.
viewTags Array Security "read" tags for this alarm.
updateTags Array Security "write" tags for this alarm
Alarm State Object
Name Type Required Description
name String Yes The state's name.
color String Color value used for UI display.

Attribute Definition Object

Name Type Required Description
name String Yes The name of the attribute.
default String The default value of the attribute when it is not set.
viewTags Array Security "read" tags for this attribute.
updateTags Array Security "write" tags for this attribute.

Method Definition Object

Name Type Required Description
name String Yes The name of the method.
tags String Array of tags by which the method is associated.
description String An optional description of the method.
notificationVariables Object Key-value pairs where the key is the variable key and the value is a method variable object.
completionVariables Object Key-value pairs where the key is the variable key and the value is a method variable object.
handler String The handler is set to either a method or a trigger.
  • A method handler will cause a method (with the same key) on the thing to execute.
  • However, if the trigger is set, a trigger (must have method.exec event containing the same Method key) will be executed. If not specified, the handler will default to a method.
defaultAckTimeout Integer The default acknowledge timeout (in seconds) to use when the method is executed. The maximum value is 300 seconds. Can be overridden by ackTimeout set while defining a method.
Method Variable Object
Name Type Required Description
name String Yes The variable's proper name.
type String Yes The variable's type. Must be one of: bool, float, int or string.
uiType String Type used for UI display only.
uiTypeOptions Object Unstructured params used for UI display only.
count Integer The variable value's count.
length Integer The variable value's length.

Property Definition Object

Name Type Required Description
name String Yes The name of the property.
prefix String The prefix used for displaying this property's values.
suffix String The suffix used for displaying this property's values.
unit String The unit used for displaying this property's values.
viewTags Array Security "read" tags for this property.
updateTags Array Security "write" tags for this property.
calcAggregates Bool If values of the property are to be aggregated. If set to True, all the seven types of aggregates (Average, Weighted Average, Non-zero time weighted average, Sum, Max, Min, and Count) are calculated.
deDuplicate Bool If a duplicate property is published (a newly published property value with the same timestamp as an existing property value), it is ignored when this parameter is set to true.

Tunnel Definition Object

Name Type Required Description
name String Yes The name of the tunnel.
desc String The description of the tunnel.
port Integer Yes The port that the service listens on.
tags Array Security "read" tags for this property.
protocol String A string describing the protocol of the tunnel. Valid values for this field can be acquired by calling the tunnel.protocol.list command.

Location Definition Object

Name Type Required Description
ignoreFixTypes Array An array of fix type strings to be ignored. Typically fix types include "gps", "gnss", "manual", and "m2m-locate"
noDecode Bool When set to true, the platform will not attempt to use reverse-geolocation to decode the lat/lng pair to an address when a lat/lng pair is supplied to the location.publish and location.batch commands. The noDecode setting will be overridden for a single location.publish if the decodeAddress parameter is set to true for the command.

Firmware Definition Object

Name Type Required Description
name String Yes The name of the firmware.
version String The version of the firmware.
fileName String The name of the firmware file.
url String The URL to the firmware file.
custom String A custom instruction to acquire the firmware file.
requires Array An array of versions required to be installed before this version can be installed.

TR50 Response

If the command is sent successfully a success message is returned. Otherwise, an error and error message will be returned.

{
  "cmd": {
    "success": true,
    "params": {
      "id": "537a3fa6d15a702de0000008"
    }
  }
}

Response Parameters

Name Type Description
id String The unique identifier of the new Thing Definition.