Community Tip - Need to share some code when posting a question or reply? Make sure to use the "Insert code sample" menu option. Learn more! X
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.
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": "\/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.
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.
3. Save and exit the file.
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" }
Copy and Paste the following code into the empty YourEdgeThingTemplate.lua file:
require "shapes.swupdate" module ("templates.YourEdgeThingTemplate", thingworx.template.extend)
In this step, you'll launch the EMS so that it can communicate with your ThingWorx Foundation platform.
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 .
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. |
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. |