Running the ThingWorx EMS
The ThingWorx EMS can be run manually from a command line, as a Linux daemon, or as a Windows service to establish a connection to ThingWorx Platform.
Running EMS from a Command Line
The EMS can be run from a command line as follows:
1. Open a command window or terminal session on the system or device that is hosting the EMS.
2. Change to the \microserver\etc directory.
3. For a basic configuration, copy the config.json.minimal file and rename it to config.json. For a complex configuration, start with your basic config.json file to ensure first that you can run the EMS.
 |
Do not attempt to use config.json.documented as is to run your EMS. It is intended as a reference, not as a valid JSON file that you can use to run EMS. Instead, use config.json.complete to run EMS using all available properties. Make sure that you save config.json.complete as config.json, and set all of the minimally required properties (refer to the next step).
|
4. Set the configuration properties:
◦ For a simple configuration that establishes a connection to ThingWorx Platform, refer to the section, Creating a Configuration File.
◦ For a more complex configuration, start with the section, Creating a Configuration File, and then continue to the section, Viewing All Configuration Options.
5. Save the configuration file as config.json.
6. Change directories back to the top-level directory, \microserver.
You are ready to run the EMS, as follows:
1. To run the EMS, enter the command, wsems.
 |
When starting, the EMS looks for a configuration file named config.json in the \microserver\etc directory by default.
You can specify the path to the configuration file when running the EMS using a command similar to the following:
wsems -cfg /path/to/my/configuration_file.json
|
As part of initialization, the EMS checks the configuration file settings. Once initialized, the EMS prints its version number to the console and log file, attempts to connect to ThingWorx Platform, and returns a message that the connection was successful to the console. You can tell that EMS is running and connected to ThingWorx Platform by looking at the console prompt—two plus signs (++) indicate that it is running and connected.
For example, if the ThingWorx Platform resides at 10.9.8.7 and is listening on port 8443, the console prompt appears as follows when it is running and connected:
10.9.8.7:8443++>
2. Should you need to shut down the EMS, press ENTER to display the console prompt and type q.
|
|
The Windows-based operating systems have a tick resolution (15ms) that is higher than the tick resolutions requested by the C SDK (5ms). For information about achieving the best performance in a Windows-based operating system, refer to Running on a Windows-based Operating System.
|
Running EMS as a Daemon (Linux) or as a Windows Service
To run EMS and the LSR as daemons or services, you first need to "install" them and then you can start them as you would any other daemon or service. Follow these steps:
1. Open a command window or terminal session on the system or device that is hosting the EMS.
2. Change to the \microserver\etc directory.
3. For a basic configuration, copy the file, config.json.minimal, and rename it to config.json. Even for a complex configuration, start with your basic config.json file to ensure that you can run EMS.
|
|
Do not attempt to use config.json.documented as is to run your EMS. It is intended as a reference, not as a valid JSON file that you can use to run EMS. Instead, use config.json.complete to run EMS using all available properties. Make sure that you save config.json.complete as config.json, and set at least all of the minimally required properties (refer to the next step).
|
4. Set the configuration properties:
◦ For a simple configuration that establishes a connection to ThingWorx Platform, refer to Create the EMS Configuration File and Configure the Connection to ThingWorx Platform.
◦ For a more complex configuration, start with the section, Create the EMS Configuration File, and then continue to the section, Additional Configuration Options.
5. Save the configuration file as config.json.
|
|
The configuration file must be named config.json and reside in the \microserver\etc directory.
|
6. Follow the steps for your operating system:
◦ For Windows:
a. Change to the \microserver\install_services\ directory by running a command similar to the following:
cd microserver\install_services
b. As an Administrator, run the following command to install EMS and LSR as Windows services, with or without the options to create custom names:
install.bat [-wsems your_name_for_wsems_service_here]
[-lsr your_name_for_lsr_service_here]
[-lsr your_name_for_lsr_service_here]
Use only one hyphen (-) for the options. There is a space between the option and the argument, but for Windows, you must use the full option name.
◦ For Linux:
a. Change to the /microserver/install_services/ directory by running a command similar to the following:
cd ./microserver/install_services
b. Make the install script executable by running the following command:
sudo chmod +x install
c. Run one of the following commands to install the EMS and LSR as daemons:
▪ Linux, using short names for the options:
sudo ./install \
[-w your_name_for_ws_ems_service_here] \
[-l your_name_for_lsr_service_here]
[-w your_name_for_ws_ems_service_here] \
[-l your_name_for_lsr_service_here]
Use only one hyphen (-) for the options. There is a space between the option and the argument.
▪ Linux, using long names for the options:
sudo ./install \
[--wsems=your_name_for_ws_ems_service_here] \
[--lsr=your_name_for_lsr_service_here]
[--wsems=your_name_for_ws_ems_service_here] \
[--lsr=your_name_for_lsr_service_here]
Note that the long options require two hyphens (--) before the option name, an equal sign following the name, and no space between the equal sign and the argument (your name for the service).
|
|
To uninstall the service, remove the service from /etc/init.d/<Service Name>.
|
As part of initialization, the EMS checks the configuration file settings. Once initialized, the EMS prints its version number to the console and log file, attempts to connect to EMS, and returns a message that the connection was successful to the console. You can tell that EMS is running and connected to ThingWorx Platform by looking at the console prompt—two plus signs (++) indicate that it is running and connected.
For example, if the ThingWorx Platform resides at 10.9.8.7 and is listening on port 8443, the console prompt appears as follows when it is running and connected:
10.9.8.7:8443++>
Startup Process
When the EMS starts, it attempts to read the config.json configuration file. If the configuration file is invalid, the EMS stops. When the EMS fails to start, it writes a warning message to the log. The configuration file may be invalid because, for example, the fingerprint_allowlist property was added without any content. Check the EMS log to verify that this empty property group was the cause of the problem.
|
|
Not every configuration value in the config.json file is validated. Only certain explicit values are checked.
|
If the configuration file can be read, the EMS starts to process the file. If it encounters a logical error, the EMS writes an error to the log and exits. An example of a logical error is enabling SSL on your HTTP server without providing a path to a certificates file.
When a connection to a server is rejected, the cause of the failure is written to the EMS log. For example, a mismatch in TLS host names or certificate fingerprint validation will results in a rejected connection and a warning message is written to the log. If fingerprint validation succeeds, no message is written to the log.
|
|
The EMS uses XChaCha20-Poly1305 as its Encryption Cipher.
|