Setup a Raspberry Pi as an IoT Device Part 3

Yes

Step 6: Configure EMS
Step 7: Connect EMS

Step 6: Configure EMS

The EMS consists of two distinct components that perform slightly different operations and communicate with each other.

The first is the EMS itself which creates an AlwaysOn™ connection to ThingWorx Foundation. It binds Things to the platform and automatically provides features like file transfer and tunneling.

The second is the Lua Script Resource (LSR). It is used as a scripting language so that you can add Properties, Services, and Events to the Things that you create in the EMS.

Now that you have "installed" (i.e. downloaded, unzipped, and moved to an appropriate location) the EMS on your Raspberry Pi, 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.

Navigate to the /etc directory.
Right-click inside the folder’s white-space and select New File....
Enter config.json and click OK.
Right-click on the new config.json file and select Text Editor.

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

Note that the backslashes (\) in the JSON below are escape characters necessary to properly address special characters, such as the forward-slashes (/) indicating path directories.

{
    "ws_servers": [{
        "host": "YOUR_IP_ADDRESS_HERE",
        "port": 443
    }],
    "appKey": "YOUR_APP_KEY_HERE",
    "logger": {
        "level":             "INFO",
        "publish_directory": "\/home\/pi\/Downloads\/microserver\/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":   "\/home\/pi\/Downloads\/microserver\/other"},
            {"tw":      "\/home\/pi\/Downloads\/microserver\/tw"},     
            {"updates": "\/home\/pi\/Downloads\/microserver\/updates"}          
        ],
        "staging_dir":  "\/home\/pi\/Downloads\/microserver\/staging" 
    }   
}

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

Code Section	Questions 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

Change YOUR_IP_ADDRESS_HERE to the IP address of your hosted ThingWorx instance.

You may wish to e-mail yourself the Foundation IP address using a web-mail account so that you can copy/paste on the Pi from your e-mail to the config.json file.

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 ThingWorx hosted server. Ports for local-install may vary.

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

Or create a new Application Key now.
You may wish to e-mail yourself the Application Key using a web-mail account so that you can copy/paste on the Pi from your e-mail to the config.json file.

3. Save and exit the file.

Create a config.lua file

Navigate to the /etc directory.
Right-click inside the folder’s white-space and select New File....
Enter config.lua and click OK.
Right-click on the new config.lua file and select Text Editor.

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.PiThing = {
        file = "thing.lua",
        template = "YourEdgeThingTemplate",
        scanRate = 120000,
        sw_update_dir = "\/home\/pi\/Downloads\/microserver\/updates"
}

Save and exit the file.

Create a Custom Template for the EdgeThing

Navigate to /etc/custom/templates.
Right-click inside the folder’s white-space and select New File....
Enter YourEdgeThingTemplate.lua and click OK.
Right-click on the new YourEdgeThingTemplate.lua file and select Text Editor.

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

require "shapes.swupdate"

module ("templates.YourEdgeThingTemplate", thingworx.template.extend)

Save and exit the file.

Step 7: Connect EMS

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

On the Raspberry Pi , open a Terminal by clicking the Terminal icon in the top-left.
Navigate to the EMS's root folder, i.e. /home/pi/Downloads/microserver , by issuing the following command and then pressing Enter : cd /home/pi/Downloads/microserver
In the Terminal window, enter the command sudo ./wsems and press Enter .

Note: Do not close this window, or the connection to the ThingWorx platform will close. Also, look through the output in the wsems window. Near the end, you should see 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... especially with either the address or Application Key .
Open another Terminal window as per the above instructions.
In this second Terminal window, Navigate to the EMS's root directory, i.e. /home/pi/Downloads/microserver , by issuing the following command and pressing Enter : cd /home/pi/Downloads/microserver
In the second Terminal window, enter the command sudo ./luaScriptResource and press Enter .

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

NOTE: When the scripts start running, the EMS 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 program runs through the config.json file in order to extract the basic connectivity information to reach the ThingWorx platform. The luaScriptResource program runs through the config.lua file to extract to which Thing the WSEMS should be connecting. Both programs must be running in order to achieve connectivity with ThingWorx.

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

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

Troubleshoot Connectivity Issues

If the websocket does not connect successfully, check the following:

Issue	Solution
WEBSOCKET CLOSED - Warning seen immediately after Websocket gets connected.	Ensure that the host IP address, port, and appKey of the ThingWorx composer instance are accurately set. If, in config.json, you have selected the option to validate certification, then make sure the path to the certificate file is correctly set.
twWs_Connect - Error trying to connect.	Ensure that the host IP address and port running the ThingWorx Composer is accurately set. Check if the certification parameter is set or not. By default, the WS EMS validates certificates. To ensure that the validation is performed correctly without errors, ensure that the certificates configuration parameters are set accurately with the correct path to the certificate file. If you do not wish to validate the certificate, you may explicitly set the validate parameter in certificates parameter set to false.
twTlsClient_Connect - Error intializing TLS connection. Invalid certificate.	Check if the ws_encryption parameter is present in your config.json file. By default, WS EMS enables TLS connection to the ThingWorx Platform. Ensure that the certificate file mentioned in config.json is valid and stored in the path specified. For debugging purposes, you can set the ssl parameter to none in ws_encryption configuration parameter.
[WARN ] ... Main - Unable to connect to server. Trying .booted config file.	Ensure that the host is up and running at the IP address and port number mentioned in the config.json file. Ensure that ThingWorx is running on the host address at the correct port number. Ensure that all necessary ports are open for communication.

Click here to view Part 4 of this guide.