cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

Community Tip - Want the oppurtunity to discuss enhancements to PTC products? Join a working group! X

Using the Edge MicroServer and LSR in a Gateway Scenario

No ratings

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.

config.json.png

  • 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:

config.lua.png

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

  1. Make sure the ThingWorx platform is running
  2. Create a RemoteThing with the name given in the auto_bind section for the LSR we are connecting
  3. Create an EMSGateway with the name given in the auto_bind section for the EMS as a Gateway to bind to
  4. 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
  5. 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
  6. 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
  7. 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.

Comments

Hi Meghan Hollenbach

Really great guide.

I have one question regarding the Gateway itself where the EMS is running on in the autobind section "EdgeGateway".

  • "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"

Does that mean that I need to model the Gateway as well as a thing on the platform? I'm asking because I can scale the Naming and registering of the "OtherEdgeThing", because the LSR is running on the equipment, which has a unique serial number.

But do all the gateways need to be modelled as a seperate thing?

Regards,

Pascal

Okay I googled this: Digital Media Publisher, and there it's explained that you can use always the same Thing EdgeGateway until an LSR has connected through the gateway on the plattform.

So, if you have 2000 things connected in the field with #2 each on #1 gateway, making it 2000 things and 1000 gateways, I only need to create 2001 things on the platform, 2000 things for LSR and 1 general EMSGateway thing, correct?

Does that make sense?

Thanks,

Pascal

Correct, you would only need 1 gateway for all your LSRs, but in a real world scenario you might want to scale that a bit differently. 2000 devices connecting to one gateway may have some performance issues.

Thanks Meghan Hollenbach​! 2000 things per device really do no not make sense - what I meant was on the platform - do I need to model each gateway as at thing as well?

Regards,

Pascal

You would want to model one Thing on the platform for each LSR to bind to, yes. The Gateway Thing will be ephemeral if you did not create one, so you really do not need to worry about creating a GatewayThing to bind with the EMS.

Meghan

In my situation, I have a seven smart, internet capable devices in a single building. However, I want all communication to the cloud to go through a local server within the building running the EMS in gateway mode. In this scenario, would my seven smart devices also contain the EMS application?

Version history
Last update:
‎May 16, 2016 12:23 PM
Updated by:
Labels (1)