Use the Edge MicroServer (EMS) to Connect to ThingWorx Part 2

[#1]

• Step 3: Configure EMS
• Step 4: Connect EMS

 

Step 3: Configure EMS

Now that you have "installed" (i.e. downloaded, unzipped, and moved to an appropriate location) the EMS on your Windows computer, it needs to be configured.

The primary method of doing so is via the config.json and config.lua files.

In this step, we'll create these files and paste some JSON / Lua configuration into them.

1. Navigate to the C:\CDEMO_EMS\etc directory.
   

   

2. Right-click inside the folder’s white-space and select New -> Text Document.
   

   

3. Change the name of New Text Document.txt to config.json.
   
   

   • Here are instructions on how to configure your computer to display file extensions if you are not currently doing so.
     
     

4. Click Yes in the Rename Popup to confirm the file extension change.

   
   

5. Open config.json in your preferred text editor.
   
   NOTE: You will need a text editor of some type to modify the config.json file. Notepad++ is one such editor. However, the default Windows text editor, Notepad, is sufficient.

   

6. Copy and Paste the following code into the empty config.json file:
   
   

    {
        "ws_servers": [{
            "host":    "YOUR_IP_ADDRESS_HERE",
            "port":    443
        }],
        "appKey": "YOUR_APP_KEY_HERE",
        "logger": {
            "level":             "INFO",
            "publish_directory": "C:\\CDEMO_EMS\\logs",
            "publish_level":     "INFO",
            "max_file_storage":  2000000,
            "auto_flush":        true
        },
        "http_server":  {
            "ssl": false,
            "authenticate": false
        },
        "ws_connection": {
            "encryption": "ssl"
        },
        "certificates": {
            "validate": false,
            "disable_hostname_validation": true
        },
        "tunnel": {
            "buffer_size":    8192,  
            "read_timeout":   10,  
            "idle_timeout":   300000,
            "max_concurrent": 4
        },
        "file": {
            "buffer_size": 8192, 
            "max_file_size": 8000000000,  
            "virtual_dirs": [   
                {"other":   "C:\\CDEMO_EMS\\other"},
                {"tw":      "C:\\CDEMO_EMS\\tw"},     
                {"updates": "C:\\CDEMO_EMS\\updates"}            
            ],
            "staging_dir":  "C:\\CDEMO_EMS\\staging" 
        }   
    }

When the EMS runs, the config.json file will answer the following questions:

Code Section	Question Answered
ws_servers	At what IP address / port is the ThingWorx Server located?
appKey	What is your Application Key?
logger	Where, and at what level, should we log errors?
http_server	What port should the WSEMS use to setup an HTTP server?
ws_connection	Should we use encryption?
certificates	Are we using Security Certificates?
tunnel	What are the configuration parameters for remote-tunneling?
file	What are the configuration parameters for file-transfer?

We pre-defined the parameters for everything that we could, but you will still need to tell the WSEMS the IP address where the ThingWorx instance is located and a valid Application Key you either created earlier or may create now.

TIP: You may have noticed the pre-existing config.json.complete and config.json.minimal files. These are example files that come with the WSEMS and are provided as an aid. The code above which you copied into your own config.json file is simply a customization of these aids. In particular, you may wish to look through the config.json.complete file, as it shows every available option which you might want to configure if you choose to make a custom application with the WSEMS. The config.json.complete file also contains comments for each of these options. However, a functional config.json file may NOT contain comments of any kind, so you would need to remove all comments if you choose to copy/paste some code from that file into a functional config.json of your own making.

Modify config.json to point to ThingWorx Foundation

1. Change YOUR_IP_ADDRESS_HERE to the IP address of your hosted ThingWorx instance.
   
   Note that you may use a URL, such as "pp-180207xx36jd.devportal.ptc.io". Either way, the IP or URL must be enclosed in quotation marks (""). Also, Port 443 is the appropriate port for the hosted ThingWorx trial. Other Ports may be needed for local installs.
   
   
   

2. Change YOUR_APP_KEY_HERE to an Application Key which you have previously created.
   
   

   • Or create a new Application Key now... and remember to set the Expiration Date far enough into the future.
     
     

3. Save and exit the file.

Create a config.lua file

1. Navigate to the C:\CDEMO_EMS\etc directory.
   
   
2. Right-click inside the folder’s white-space and select New -> Text Document.
   
   
3. Change the name of New Text Document.txt to config.lua
   .
   
   • Click Yes on whether you want to change the filename extension.
     
     
4. Open config.lua in your preferred text editor.
   
   

5. Copy and Paste the following code into the empty config.lua file:
   
   

    scripts.log_level = "WARN"
   
    scripts.script_resource_ssl = false
    scripts.script_resource_authenticate = false
   
    scripts.EdgeThing = {
            file = "thing.lua",
            template = "YourEdgeThingTemplate",
            scanRate = 120000,
            sw_update_dir = "C:\\CDEMO_EMS\\updates"
    }

6. Save and exit the file.

Create a Custom Template for the EdgeThing

1. Navigate to C:\CDEMO_EMS\etc\custom\templates.
   
   
2. Right-click inside the folder’s white-space and select New -> Text Document.
   
   
3. Change the name of New Text Document.txt to YourEdgeThingTemplate.lua.
   • Click Yes on whether you want to change the filename extension.
     
     
4. Open YourEdgeThingTemplate.lua in your preferred text editor.
   
   

5. Copy and Paste the following code into the empty YourEdgeThingTemplate.lua file:
   
   

    require "shapes.swupdate"
   
    module ("templates.YourEdgeThingTemplate", thingworx.template.extend)

6. Save and exit the file.

Step 4: Connect EMS

In this step, you'll launch the EMS so that it can communicate with your ThingWorx Foundation platform.

1. Navigate to the C:\CDEMO_EMS directory.
   
   
2. Hold Shift and right-click in the white space of the folder to open an options menu.
   

   

3. Click Open PowerShell window here.
   
   

   • Note that this guide assumes Windows 10, but older versions of Windows have similar command-line interfaces.

   

4. In the PowerShell window, enter the command .\wsems.exe and press the Enter key.
   
   Note: Do not close this window, or the connection to the ThingWorx platform will close. Also, please look through the output in the wsems.exe window. The final line should indicate Successfully connected. Saving .booted config file. If you do not see the Saving .booted comment, then you likely have an error in your config.json file. Close the wsems.exe application with a Ctrl+C and delete any .booted file before making further changes.

   

5. Open another PowerShell window as per the above instructions.
   
   

6. In the second PowerShell window, enter the command .\luaScriptResource.exe and press the Enter key.
   
   

   Note: Do not close this second PowerShell window, or the connection to the ThingWorx platform will close.
   
   

   NOTE: When the scripts start running, the WSEMS attempts to talk to the ThingWorx platform. However, at this point in the tutorial, ThingWorx does not have detailed information about the Edge device that is attempting to connect to it so you will see an error message. This is the expected behavior which we will resolve in the next step.

The wsems.exe program runs through the config.json file in order to extract the basic connectivity information to reach the ThingWorx platform. The luaScriptResource.exe runs through the config.lua file to extract to which Thing the WSEMS should be connecting. Both .exes must be running in order to achieve connectivity with ThingWorx.

Program	File Accessed	Purpose
wsems.exe	config.json	Extracts basic connectivity information to reach the ThingWorx platform.
luaScriptResource.exe	config.lua	Determines to which Thing the WSEMS should connect.

NOTE: Since the luaScriptResource.exe file which we created above has a reference to a custom template, it goes also accesses the YourEdgeThingTemplate.lua file to extend the base functionality. Both .exes must be running in order to achieve connectivity with ThingWorx.

Click here to view Part 3 of this guide.