Introduction
The Edge MicroServer (EMS) and Lua Script Resource (LSR) are Edge software that can be used to connect remote devices to the ThingWorx platform. Using a Gateway is beneficial because, this will allow you to run one instance of the EMS on a server and then many instances of the LSR on different devices all over the world. All communication to the platform will be handled by this one EMS Gateway server. The EMS Gateway can be set up in two different types of scenarios: Self-Identifying Remote Things and Explicitly defined Remote Things.
The scenario I'm going to discuss below will involve explicitly defined Remote Things, a ThingWorx server, an EMS, and a LSR. We will need at least 1 server to run the ThingWorx platform and EMS, but these can always be on separate servers as well. We will also need some other machine or device that will run the LSR.
Visit the support downloads page to find the latest EMS releases. The LSR is contained within the EMS download.
You can also navigate to the Edge Support site to read more about the EMS and LSR oif this is the first time you have ever configured one. The "ThingWorx WebSocket-based Edge MicroServer Developer's Guide" is also provided inside of the zip file that contains the EMS for further information.
Setting up the EMS
Once we have obtained the EMS download from the support site (see the section above for links) we can begin creating our config.json file.
The image below is a working config.json file for using the EMS as a Gateway. The settings in here are particular to my personal IP addresses and Application Key, but the concept remains the same, and I will go into further detail on the necessary sections, below the image.
- ws_servers
- The host and port parameters are always set to the IP address and port that the ThingWorx platform is being hosted on
- When the EMS and ThingWorx platform are on the same server, "localhost" can be used instead of an IP address
- appKey
- The appKey section is the value of an Application Key in the ThingWorx platform that should be used for the authentication of the EMS to the platform
- An Application Key will need to be created and assigned a user with proper priveledges prior to authenticating
- certificates
- The certificates section should be validating and pointing to proper certificates, but in the example above I am not validating any certificates for the sake of simplicity
- More can be read about the certificates sections here
- logger
- The logging section is out of scope of this article, but further reading on logger configurations can be found here
- The section in the example above will work for basic logging needs
- http_server
- The http_server section configuration parameters will tell the EMS what host and port to spin up a server on and if there is authentication necessary by any LSRs trying to connect
- The LSR has settings that will explicitly call out whatever value is set to the host and port in this section, so make sure to set these to an open port that is not in use or blocked behind a firewall
- Further reading on the http_server section can be found here
- auto_bind
- You can see above that there are two objects defined in the auto_bind section. One of these is binding the EMS to an EMSGateway Thing in the platform called "EdgeGateway" and the other is defined in the config.lua file for the LSR
- The gateway parameter is set to true only in the object, "EdgeGateway", that is being used for the EMS to bind to
- The host and port defined for the "OtherEdgeThing" should point to the port and IP address that the LSR is running on in the other device
- By default, the LSR runs on port 8001, but you can always double check the listening port by finding the Process Identification (PID) number of the luaScriptResource.exe and then matching the PID to the corresponding line item in the output of netstat -ao command in a console window
- The protocol can be set to "http" in an example application, but make sure to use "https" when security is of concern
All further reading on the sections of the config.json file can be found in the config.json.complete file included with the EMS download and on the Edge Help Center under the "Creating a Configuration File" section and the "Viewing All Options" section.
Setting up the LSR
In this example, the LSR is going to run on a separate server and point to the EMS server. Below is a screenshot of two very important additions (rap_host and rap_port) to the default config.lua file:
- rap_host
- The rap_host field should be set to the IP address where the EMS is hosted
- rap_port
- The rap_port field should be set to the port parameter defined in the config.json http_server section
- script_resource_host
- The script_resource_host field must be set to ensure that the EMS will know what IP address to communicate with the LSR at
- scripts.OtherEdgeThing
- This line is necessary to identify what the name of the LSR is that will register with the EMS to bind to the platform
- "OtherEdgeThing" can be changed to anything, but make sure that the auto_bind section in the config.json aligns with what you've defined in the config.lua file at this line
Running the EMS and LSR
Now that we have configured the LSR and EMS to point to each other and the platform we can try running both of these applications to make sure we are successful.
- Make sure the ThingWorx platform is running
- Create a RemoteThing with the name given in the auto_bind section for the LSR we are connecting
- Create an EMSGateway with the name given in the auto_bind section for the EMS as a Gateway to bind to
- Start the EMS
- This can be done by double clicking the wsems.exe when in Windows, running it as a service, or running it directly from the command line
- Start the LSR
- This can be done by double clicking the luaScriptResource.exe when in Windows, running it as a service, or running it directly from the command line
- Navigate to the ThingWorx platform and make sure that the Things you have created are connected
- Do this by navigating to the Properties menu option and refreshing the isConnected property
- You should be able to browse remote properties and services for each bound RemoteThing, and this means you have successfully setup the EMS as a Gateway device to external LSR applications running on remote devices
Any further questions about browsing remote properties or other configuration settings in the .config files is most likely addressed in the Edge Help Center under the EMS section, and if not, feel free to comment directly on this document.
