Configuring Automatic Binding for EMS
The EMS features some basic edge functionality such as file transfer and tunneling without the need for the LSR. The automatic binding feature for the EMS provides a way of letting the EMS talk to HTTP servers at the Edge that you want to represent as Things in ThingWorx. When you configure auto_bind, you must supply a REST endpoint for the EMS to communicate with. If the ThingWorx Platform makes a request down to that device, the EMS makes an HTTPS connection to the server defined in the auto_bind configuration.
The auto_bind group in the config.json file of an EMS is used to:
• Define specific local Things that are always expected to be bound through this EMS to a ThingWorx Platform.
• Define an EMS as a gateway.
For more information about configuring EMS as a gateway, refer to Auto-bound Gateways.
The auto_bind property is an array, allowing you to statically define more than one device or machine Thing.
 |
The code sample below is provided for example purposes only.
|
"auto_bind": [{
"name" : "EdgeThing001",
"host" : "localhost",
"port" : 8001,
"path" : "/",
"timeout" : 30000,
"protocol" : "http",
"user" : "username",
"password" : "some_encrypted_password",
"gateway" : false
}],
Best Practices
When configuring a host and a port for automatic binding, always use the same host and port as for the http_server configuration. This best practice prevents failure of a file transfer between the ThingWorx Platform and an EMS. This includes transfers of file-based SCM packages. Refer to Troubleshooting File Transfers When Using Automatic Binding.
When using SSL/TLS between this device and the EMS, ensure optimal security by adding certificate fingerprint validation to the EMS configuration file. For details, refer to Certificate Fingerprint Validation for EMS and LSR.
The following sections provide additional information about automatic binding. Click the title of a section to display the content. Click the title again to hide the content.
Properties for Automatic Binding
The following table describes the properties for automatic binding:
Property | Description |
|---|---|
name | REQUIRED. This property specifies the Thing Name of the entity as it exists on the configured ThingWorx Platform instance. If an identifier is configured for the Thing on the platform instance, you must specify that identifier here. For more information, refer to the section, “Identifiers”, below. |
host | This property specifies the name of the host machine for the Thing. The default value is localhost, but this likely means IPV6, and not 127.0.0.1. If you are using IPV4, use the 127.0.0.1 IP address instead of localhost. |
port | This property specifies the port number used by the Thing/device for communications. The default value is 8001. |
path | This property specifies the path to prepend to the path received in the request from the ThingWorx Platform instance. |
timeout | This property specifies the maximum amount of time to wait for a response from the target, in milliseconds. The default value is 30000 milliseconds (30 seconds). |
protocol | This property specifies whether the protocol to use for communications is HTTP or HTTPS. The default value is https. |
user | This property specifies the name of the user account to use for authentication when connecting. In general, do not use the colon (:) character in user names. |
password | This property specifies the password for the user account specified for the user property. If you specify a user name and password, it is recommended that you encrypt the password. For details, refer to Encrypting Application Keys, Passwords, and Passphrases. |
gateway | This property specifies whether this automatically bound Thing is a gateway or non-gateway Thing. By default, this property is set to false. To understand the differences between these two settings, refer to Auto-bound Gateways. |
Identifiers
Identifiers provide a way to specify an alternate name for a given Thing. An identifier can be set for a Thing on the General Information tab of the Thing in ThingWorx Composer. If a Thing has an identifier set, the ThingWorx Platform must bind the Thing using the identifier. A typical use case for an identifier is the serial number for a device, as opposed to an intuitive name.
You can use an identifier when dynamically registering a Thing or when configuring the auto_bind group. To use an identifier, prepend an asterisk (*) to the identifier and specify it as the value for the "name" property, as follows:
{
"name" : "*SN0012",
"host" : "localhost",
"port" : 9000,
"path" : "/"
}