Tunneling with ThingWorx and an Edge Device

[#1]

Setting up the ThingWorx Server RemoteThing, ApplicationKey, and TunnelSubsystem

Tunneling from the ThingWorx platform to an Edge Device can be easily done with a few preparation steps on the platform side:

1. Create an ApplicationKey entity on the ThingWorx server so that the EMS or SDK you are using can authenticate with the platform
2. Create a RemoteThingWithTunnels or RemoteThingWithTunnelsAndFileTransfer Thing for the remote device to bind to
   • Either ThingTemplate will work, the only difference is if you want to use any native file transfer capabilities that are provided by ThingWorx
1. In the newly created Thing, on the General Information page, click on the drop-down menu next to Enable Tunneling and select Override - Enabled
2. ​Go to the Configuration​ section under ​Entity Information ​on the right and click on the Add My Tunnel ​button
   • The Tunnel Name is used to identify what tunnel to use in the RemoteAccessWidget you will bind to the tunnel
   • The Host will remain 127.0.0.1 because this is from the perspective of where the vnc server is to the remote device
     • In my example they are on the same device
   • The Port value should be the Port that the server is listening on
     • This is typically 5900, but my vnc server is running on port 5901 for this example
   • The App URI can be cleared out because we do not need to reference that file
     • Here is a link to a further explanation on what the App URI is for: ThingWorx Tunneling App URI's
   • The # of Connections and Protocol can remain their default values unless you have a reason to change them
3. Navigate back to Home and look for the TunnelSubsystem under the Subsystems page
   1. Click on the TunnelSubsystem
   2. Click on the Configuration option on the left
   3. Modify the Public host name used for tunnels field and the Public port used for tunnels field to the host and port of your ThingWorx server
   4. Save and close the TunnelSubsystem

Configuring the Edge Device

For this example I'm going to keep it simple and set up an EMS (Edge MicroServer) instead of an SDK. This EMS will be on a totally separate device (an Ubuntu machine), while my ThingWorx server is on my local machine.

1. Download the latest EMS onto a separate machine
2. Configure the config.json file settings to match the server's host, port, and application key
   • The ​tunnel​ block will be necessary to add as well, see below for an example of a working config.json file:
3. Configure the config.lua file to match the name of the RemoteThingWithTunnels we created earlier; in this instance the name of my RemoteThing is ​EdgeThing​:
   
4. Run the EMS and LSR (Lua Script Resource)
   • The LSR EdgeThing​ will bind automatically to the RemoteThingWithTunnels we created earlier
5. To verify there is successful connection between the platform and EMS go to the ​EdgeThing​'s Properties page and check to see if the ​isConnected ​property is currently set to ​true​
   • If it's not, please refer to this Help Center section for further troubleshooting. There is a list of error codes here.

Installing a VNC Viewer and Server

The next series of steps talks about configuring a VNC Server on the EMS machine and a VNC Client on the computer you are using to connect to the server. For this example I will be using packages tightvncserver, xfce4, xfce4-goodies, and vnc4server on my Ubuntu machine that hosts the EMS, and I will be using the tightvnc viewer available for download here.

The following steps describe how to configure the Ubuntu machine so that it will be ready to accept vnc requests:

I want to note that I am specifically using a 64-bit Ubuntu 14.04 LTS OS

1. Run the following commands:
   1. sudo apt-get update
   2. sudo apt-get install xfce4 xfce4-goodies tightvncserver
2. Run the vncserver and you will be prompted to setup a password
   • I used password to keep it simple, but you will want to use something relatively secure
3. We will want to kill this instance right away so we can proceed with further configuration
   • vncserver -kill :1
4. ​Make a backup of the ​xstartup​ file in case things go awry
   • mv ~/.vnc/xstartup ~/.vnc/xstartup.bak
5. Create a new xstartup ​file to proceed with the setup
   • nano ~/.vnc/xstartup
6. Insert the following commands into the file, and they will be exercised every time the server starts or is restarted:
   • #!/bin/bash
     xrdb $HOME/.Xresources
     startxfce4 &
   • The first command in the file tells the VNC's GUI framework to reference the .Xresources file, which is where a user can change vnc settings
   • The second command launches the XFCE -- the graphical software
7. Ensure that the xstartup ​file has executable privileges:
   • sudo chmod +x ~/.vnc/xstartup
8. Start the server back up with vncserver

For the machine that is being used to view the Mashup, install the tightvnc server from the link mentioned above. You should double-click the tightvnc-jviewer.jar file to run the viewer application now so it is up and ready for the ​Establishing a Tunnel ​section​.

Creating the RemoteAccess Mashup

This next portion of the tutorial covers creating the Mashup that will be asked by any user who wants to remote into the Edge device.

1. Go to Composer Home and open the Mashup menu option on the left side of the screen
2. Add a new Static or Dynamic Mashup
3. Drag-and-drop a RemoteAccessWidget onto the Mashup
4. Click on the RemoteAccessWidget and modify the RemoteThingName, TunnelName, and AcceptSelfSignedCertificates ​properties for the connection
   • The RemoteThingName is the name of the Edge Thing the remote device is bound to
   • The TunnelName is the name of the tunnel we added to the Edge Thing in the Configuration screen
   • The AcceptSelfSignedCertificates is only used when using an SSL connection with self signed certs
5. View the Mashup and the RemoteAccess Widget should have a green plus sign on it if the connection from the EMS to platform is up and connected

Establishing a Tunnel

The following section is the last part of the process where we actually establish a tunnel between the client, platform, and remote device.

1. Open the Mashup with the RemoteAccess Widget if you closed it
2. Click on the RemoteAccess Widget to being the wsadapter.jnlp download
3. Once that has completed click on the wsadapter.jnlp file to run it
   
   • Keep in mind that there is a default 90 second timeout defined in the TunnelSubsystem that will render the wsadapter.jnlp file useless and you will have to download a new one if the connection is not established within that timeframe
   • If you receive the following error message you may need to reconfigure your TunnelSubsystem configuration options for your server because the thingworx-tunnel-launcher.jar was unable to be found at that address
     
   • If you receive the following error message after you will need to modify your security settings in your Java options. This is done by opening ​Configure Java​, navigating to the ​Security ​tab, and then adding your ThingWorx server's IP and port to the site list via the ​Edit Site List...​ button
4. You should have received a Security Warning message upon successfully finding the thingworx-tunnel-launcher.jar file that you will click the ​Run​ button on and check the I accept the risk and want to run this application​
   
5. A pop-up, like the following, will be seen and you know the tunnel is now open for tightvnc to connect through
   
   • Do not click ​OK​, instead, please proceed to the next step. Clicking OK will close the tunnel if you have not connected to the EMS via the VNC Viewer yet.
6. Open the tightvnc-jviewer.jar and type in the corresponding host and port that a vnc connection should be established to:
   • localhost ​ and port ​16345​ are used because we have already established a connection to the EMS and it is listening for a vnc connection on port 16345 -- per the ThingWorx pop-up we just saw
7. Click ​Connect​ and a new window should appear showing the GUI environment of your Ubuntu server like below
   
   

[ttielebein]

Hello,

This is phenomenal documentation, Meghan! Nice work!

I am having an issue with the final step (and I think I did everything right up until now). I see this error message when I try to connect to the server:

or this one when I use 127.0.0.1::16345 instead of localhost::16345:

I installed TightVNC on Windows just for local testing purposes, so hopefully that is not the issue (it should work this way, shouldn't it?)

Let me know your thoughts. Thanks!

Tori

[mhollenbach]

You are connecting from your local machine I'm assuming, Windows, and what are you connecting to? Whatever you are connecting to needs the TightVNC Server installed on it, and then your local machine has the TightVNC Viewer installed on it.

Meghan

[ttielebein]

Right, I am all on one host, and wondering if that is a problem. I am connecting to the EMS which is also running on localhost. TightVNC is running on localhost, also (like I can start and stop it in the Services windows application). Oh, wait do I need to connect the EMS to the VNC server in some way? I am a little confused about how this works conceptually, I suppose

[mhollenbach]

You are definitely going to need at least two separate devices (one to host the EMS and one to host ThingWorx).

To explain this a bit further, in a more real world example, you will have a ThingWorx server sitting somewhere on a machine, an EMS out in the field on another device, and then your client machine (laptop). The client machine is where tightVNC Viewer is installed and the EMS device is where the tightVNC server is hosted. Traffic is routed from client machine to the ThingWorx server then to the EMS device and back again, so trying to open a tunnel from a client machine that is hosting an EMS and the ThingWorx server is not an appropriate testing scenario because you are not tunneling outside of your localhost. This is why you are seeing the connection refused.

[ttielebein]

Ah, ok. I suspected as much. Now I just need to remember who borrowed my Raspberry Pi... thanks for your help clarifying this!

[DonnaHannemann]

Great documentation, thanks so much for your effort.

I am having an issue at Establishing a Tunnel.  When I click on wsadapter.jnlp I do get the error "Unable to launch the application", but is a different error then you describe.

I have been unable to find a resolution.  Do you have any ideas on what the issue could be?  I am using ThingWorx version 7.1.2-b6 on Windows 7.

Thanks, Donna

[rkandasamy]

Hi Meghan,

Greak work. But we would like to how to achieve the same with Edge SDKs like Dotnet, Java instead of EMS?

Can you share if you have any links for the same.?

[ttielebein]

This error often appears when the remote device isn't actually connected to the Platform.

[TomDecock]

Hi @mhollenbach,

In the marketplace there is also an SSH Extension, where one can use SSH from the platform, possibly together with the Terminal widget in the same extension.  This works easy for connecting from the Thingworx Server to SSH servers in the same network.  But do you know how to configure things to use the Terminal Widget and SSHServer Template to issue SSH commands from a mashup over a tunnel to an Edge Device ? Using the Remote Access Widget requires you to connect an SSH client like PuTTY to the listen port of the Java application launched by the Remote Access widget.  But it would be very nice if we could use the SSH Extension and Terminal Widget to send SSH commands to the Edge Device from a mashup.  Because if we use the built-in VNC client this also manipulates the visible UI on the Edge Device (e.g. a HMI), but with SSH we could manipulate the edge device without noticable visual effects.

Regards,

Tom

[posipova]

Tom,

Could you please open a separate thread on this in the ThingWorx Developer board? This would help bringing exposure for other users and not turn the "how-to-guide" into a troubleshooting thread.

Thanks.

[ShirishMorkhade]

Hi @mhollenbach,

This is really a great document/article.

I followed the document and after too many hiccups, I am able to establish the tunnel. However at step #7 instead of getting remote desktop GUI, I am getting blank/black screen. See below.

I have TWX on Windows machine, EMS and Ubuntu and VNC Viewer on on another Windows machine.

I would really appreciate if you can you please help me get this working the last piece of problem.

Thanks,

Shirish