ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) > Configuring the WS EMS
Configuring the WS EMS
This topic takes you through the basic steps for a simple configuration that establishes a connection to your ThingWorx platform. First, you need to create the configuration file and then you configure the connection.
Create the WS EMS Configuration File
The configuration file of WS EMS is a text file that uses the JSON format. It is separated into multiple groups. Each group contains sets of name/value pairs (properties) that control different aspects of the configuration. To connect to a ThingWorx platform instance, only a few properties are required.
To view an example of a basic configuration file and create your own configuration file:
1. From the WS EMS installation directory, change to the directory, /etc. This directory contains the following configuration files for WS EMS:
config.json.complete — A valid JSON file, with no comments. If you want to use this file, you need to provide information relevant to your environment for such properties as the Application Key (appKey), and the and ws_servers.port for the instance of ThingWorx platform to which the WS EMS will connect.
config.json.documented — A copy of the config.json.complete file with many comments to explain the properties to set. This file is NOT a valid JSON file. Do NOT attempt to run the WS EMS with this configuration file.
config.json.minimal — A file that provides (in valid JSON) the essential properties that need to be set to communicate with a ThingWorx platform.
The fourth configuration file in this directory is a sample configuration file for the Lua Script Resource (config.lua.example). See Configuring a Lua Script Resource for more information.
2. To run the WS EMS, you need to create a separate configuration file, called config.json. To begin with a basic configuration, open config.json.minimal in a text editor. This file contains the minimum set of configuration settings required to connect to a ThingWorx platform.
3. Create a new file in your editor, and save it as config.json.
4. Copy the settings from config.json.minimal into your config.json file.
5. Follow the instructions in the next section to configure the connection between the WS EMS and an instance of ThingWorx platform.
Configure the Connection to ThingWorx Platform
To connect to a ThingWorx platform instance, you must configure the ws_servers group in the configuration file. This group contains the properties that define the connection between the WS EMS and a ThingWorx platform instance. You need to provide an IP address or host name and port for one instance of ThingWorx platform.
Previous releases of the WS EMS allowed you to configure an array that contained multiple addresses. However, the WS EMS no longer checks for another address if it fails to connect with the first address in the array. If you previously specified multiple addresses, you do NOT have to change your configuration file. The WS EMS will use the first address in the ws_servers array and ignore the rest.
As long as you have created your own config.json file, follow these steps to set up the connection:
1. Copy the first two lines from the config.json.minimal file and paste them in your file:
"ws_servers" : [{
You are ready to add the properties that define the connection.
2. Under "ws_servers", add the "host" and "port" properties. Then, for the "host" property, replace "localhost" with the URL of your ThingWorx platform instance. For the "port" property, enter the number of the port on the host to use for the connection. If the connection is to be secure, use port 443. For example:
"ws_servers": [{
"host" : "some_host_url",
"port": 443
"appKey" : "some_encrypted_application_key",
For development purposes, you may want to use a ThingWorx platform instance that is running on the same computer where you installed your WS EMS. "localhost" can be used as the value for "host" for these purposes only.
Next you will set the Application Key for the WS EMS to use to access the ThingWorx platform. A platform administrator can generate Application Keys using ThingWorx Composer. The Application Key is associated with a user account that determines the privileges that the WS EMS will have when accessing the instance. Once you have an Application Key for your WS EMS, you must encrypt it. Security best practices strongly advise encrypting the Application Key and any passwords that you may be using. For example, the password for a proxy server user name or the password for a certificate can be encrypted using the same command as for the Application Key..
3. To encrypt the Application Key, open a shell or command prompt, navigate to the WS EMS installation, and enter the following:
wsems.exe -encrypt myPasswordString
where myPasswordString is the Application Key that was generated in ThingWorx Composer for the WS EMS to use to access the ThingWorx platform.
4. Once the encryption generates output, copy the encrypted Application Key and paste it so that it replaces the current value of the "appKey" property. From the example above, replace "some_encrypted_application_key" with the encrypted key you just generated. Make sure that it is enclosed in the double quotation marks.
5. Save the configuration file.
If you want to try running the WS EMS to check the connection, see Running the ThingWorx WS EMS and then Verifying Your Connection.