Running the ThingWorx EMS

ThingWorx Edge MicroServer (EMS) > Running the ThingWorx EMS

The ThingWorx EMS can be run either from a command line or as a Linux daemon or Windows service to establish a 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 directory, \microserver\etc.

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 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.

The configuration file must be named config.json and reside in the \microserver\etc directory.

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.

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.

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.

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:

1. Change into the \microserver\install_services\ directory.

2. 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]

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:

1. Change to the \microserver\install_services\ directory.

2. To make the install script executable, use the following command:

sudo chmod +x microserver/install_services/install

3. Run one of the following commands to install the EMS and LSR as daemons:

▪ Linux, using short names for the options

sudo ./microserver/install_services/install \
[-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 ./microserver/install_services/install \
[--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.

How the Startup Process Works and What May Happen

When the EMS starts, it attempts to read the config.json configuration file. If the configuration file is invalid, the EMS stops. The configuration file may be invalid because, for example, the fingerprint_allowlist property was added without any content. When the EMS fails to start, it writes a warning message to the log. By checking the log of the EMS, you can determine that this empty property group was the cause of the problem

The validation process is not necessarily done on every single configuration value in the file. Only certain explicit values are checked.

If the EMS can read the configuration file, it starts to process it. If it encounters a logical error, the EMS writers an error to the log and exits. For example, you enabled SSL on your HTTP server but did not provide a path to a certificates file.

If a connection to a server is rejected, you can determine the cause of the failure by looking in the EMS log. If a connection is rejected because of a mismatch in TLS host names or certificate fingerprint validation, a warning message is written to the log. For fingerprint validation, no message is written to the log if it succeeds.

The EMS uses XChaCha20-Poly1305 as its Encryption Cipher.