Connecting Assets to Edge MicroServer (EMS)

Advanced Configurations and Integrations > Connecting Assets to Edge MicroServer (EMS)

The Edge MicroServer (EMS) is a stand-alone application that is installed on a remote device. It establishes always-on, bidirectional communications between the device and a ThingWorx host.

This section discusses how to connect asset properties in ThingWorx to a device using the Edge MicroServer (EMS), and the Lua Script Resource that is bundled with the EMS.

For information on connecting asset properties using the Edge SDK, refer to the ThingWorx Edge Java SDK Help Center.

Prerequisites

Ensure you have the following:

• Edge MicroServer (EMS) and the bundled Lua Script Resource (LSR).

• ThingWorx Composer 8.2.0 or higher with ThingWorx Apps installed.

• ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) Help Center. These instructions assume that you are familiar with the content of that help center.

Configuring ThingWorx

1. In ThingWorx Composer, create an application key to be used in your EMS.

a. From Security > Application Keys, click New.

b. Enter the appropriate values:

▪ Name—This value is needed when configuring the EMS.

▪ User Name Reference—Select a user who will use EMS. For example, Administrator.

▪ Expiration Date—Set an appropriate expiration date for the application key, based on your company policies. If left blank, it defaults to one day.

c. Click Save.

2. Create the asset (Thing) in ThingWorx to which you want to connect remote devices. Use one of the following base Thing Templates, or a Thing Template that implements one of the following Thing Templates:

◦ RemoteThing

◦ RemoteThingWithFileTransfer

◦ RemoteThingWithTunnels

◦ RemoteThingWithTunnelsAndFileTransfer

◦ PTC.ISA95.PhysicalAssetBaseThingTemplate

Regardless of the base Thing Template used, the asset must implement the RemoteAccessible Thing Shape.

As a best practice, implement Thing Shapes on Thing Templates, rather than on individual assets.

Configuring EMS

1. Download and install the EMS, following the directions in the ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) Help Center.

2. Navigate to the following file: <EMS installation location>/microserver/etc/config.json.

3. Edit the config.json file so that the host, port, and appKey all target your ThingWorx system. You can use the following example, or the config.json.minimal file.

{
"ws_servers": [{
"host": "localhost",
"port": 8080
}],
"appKey": "84fbd93b-1ca5-4057-be39-5a2b3bd1cf9e",
"ws_connection":{
"encryption":"none"
"http_server" : {
"host": "10.232.247.58",
"port": 8000,
"ssl" : false,
"certificate": "<absolute path to certificate file>",
"private_key": "<absolute path to private key>",
"passphrase": "password"
"authenticate": false,
"user": "johnsmith",
"password": "DP:AQABAKs1GFoUEW1XfDlwab4J4huKthm9GP3seM3PEjOMVoyFD3es2ZDtN2ngA99oLkcODQ",
"content_read_timeout": 20000,
"ports_to_try": 10,
"max_clients": 15,
"enable_csrf_tokens": true,
"csrf_token_rotation_period": 10
},

"logger":{
"level":"WARN",
"publish_directory":"<absolute path to \MicroServer\edge\logs>",
"publish_level":"INFO",
"max_file_storage":2000000,
"auto_flush":true
},

"certificates":{
"validate":false,
"allow_self_signed":true
},
"file":{
"buffer_size":32400,
"virtual_dirs":[{
"in":"<absolute path to \MicroServer\edge\in>"
}, {
"out":"<absolute path to \MicroServer\edge\out>"
},{
"staging":"<absolute path to \MicroServer\edge\staging>"
}],
"staging_dir":"staging"
}
}

4. Save the modified config.json file.

5. Run the <EMS installation location>/microserver/wsems.exe file as an option, or install it as a service.

Configuring the Lua Script Resource (LSR)

1. Locate the config.lua.example file in the <EMS installation location>/microserver/etc directory.

2. In the file, locate the Connection parameters section, and modify it according to your EMS settings. For example:

--
-- Connection parameters
--
scripts.rap_host = "EMS IP Address"
scripts.rap_port = "EMS Port"
scripts.rap_ssl = true
scripts.rap_userid = "EMS HTTP Server User ID"
scripts.rap_password = "password"
scripts.rap_server_authenticate = true
scripts.rap_cert_file = "Path to CA cert file."
scripts.rap_deny_selfsigned = true
scripts.rap_validate = true

3. Locate the HTTP Server Configuration section, and configure it for the Lua Script Resource. For example:

--
-- HTTP Server Configuration
--
scripts.script_resource_host = "localhost"
scripts.script_resource_port = "8001"
scripts.script_resource_ssl = "false"
scripts.script_resource_certificate_chain = "/path/to/lsr_http_server_certificate_chain/file"
scripts.script_resource_private_key = "/path/to/private/key"
scripts.script_resource_passphrase = "password"
scripts.script_resource_authenticate = "false"
scripts.script_resource_userid = "johnsmith"
scripts.script_resource_password = "AES:EncryptedPassword"
scripts.script_resource_enable_csrf_tokens = true
scripts.script_resource_csrf_token_rotation_period = 10
scripts.script_resource_enable_rest_services = false

4. Identify the asset to which you want to bind the properties. Find the following section in the config.lua.example file:

scripts.EdgeThing = {
file = "thing.lua",
template = "example",
}

◦ Replace EdgeThing with the actual asset Name value from ThingWorx.

◦ Alternatively, you can specify the identifier property here. After you run the Lua script later in this process, it will create an identifier in ThingWorx that you can then select for the Identifier on the General Information page for your asset in ThingWorx Composer.

A Remote Thing can be bound by name or by identifier, but not by both. When a Remote Thing that is bound by name also has an identifier, executing remote services or fetching remote properties for the Thing do not work as expected.

To bind a Remote Thing by name, do not specify an identifier. If an identifier is already specified, remove it.

◦ The template property represents the script identifying the information that you want to send from the device to your asset, such as remote properties or remote services. In the code example above, the example file shown can be found here: <EMS installation location>/microserver/etc/custom/templates/example.lua. The example.lua files contain examples for creating your own remote properties and remote services.

Running the EMS and Lua Script Resource (LSR)

After completing the configurations, run the EMS as a service or from the command line, then run the LSR as a service or from the command line. The following graphics show examples of running both from the command line.

• EMS:

• Lua script:

If there is an error in your configuration, the command line interface reports the error.

Binding Remote Properties

Once the LSR has run successfully, the remote properties defined in the script which you specified as the template are available to bind to your asset in ThingWorx.

1. In ThingWorx Composer, open your asset.

2. On the Properties and Alerts page, click Manage Bindings.

3. On the Manage Bindings window, click Remote. Drag and drop the remote properties which you want to bind to your asset from the left pane to the right pane.

4. Click Done.

5. Click Save to save the asset.

Was this helpful?