ThingWorx Remote Access Client (RAC)
The Remote Access Client (RAC) is provided as a mechanism for using the ThingWorx Remote Access features from a custom mashup or from the Remote Access and Control module of ThingWorx Asset Advisor. For any end user to connect to a remote device, the user needs to have a tunnel created between the local machine and the remote device. The RAC enables that tunnel. You can download the RAC from the ThingWorx Remote Access Client Downloads page.
 |
For secure connections, the RAC supports TLS with certificates from well-known CAs only.
|
This topic contains the following sections:
1. Quick Start
Quick Start
1. From ThingWorx Composer, set up a Thing and then connect it to your ThingWorx Platform. When setting up a Thing, make sure that it meets the following criteria for remote access:
a. The Thing must have the RemoteAccessible Thing Shape applied. Axeda eMessage Agent Things have this shape applied automatically.
b. The Thing must have the appropriate RemoteAccessProvider configured in the RemoteAccessProvider property.
c. The Thing must be reporting. That is, the value of the isReporting property must be true, which is indicated by a check mark icon. A "reporting" Thing Typically is a remote device bound into the ThingWorx Platform.
d. The Thing must have a tunnel endpoint configured. Good candidates for testing are protocols such as:
▪ SSH — for a machine without desktop components, TCP port 22
▪ VNC — for a machine with desktop, TCP port 5900
 |
By design, the tunnel created by RAC remains active as long as neither side breaks the connection. For this reason, ThingWorx edge tunneling does not support protocols that make multiple connections to and disconnections from the Edge, such as using a browser to access an HTTP server. For example, RDP triggers disconnects when you use the wrong credentials and when you are connecting to an RDP server that is not trusted by your computer. To be most effective, make sure you understand the connection and disconnection behavior of the protocol you are trying to forward.
|
2. Download the ThingWorx Remote Access Client (RAC) from the ThingWorx Remote Access Client Downloads page.
3. Navigate to the location where you saved the package, and run it to install the RAC. For example, on Windows run the .exe file. On Linux and OS X, install the package.
5. Using your mashup, start a Remote Session with the Edge Thing that you set up and connected in step 1. The following sequence takes place:
a. A remote session is requested for the selected Thing in ThingWorx Platform by invoking the StartSession service on the Thing.
b. The RAC application (tw-ra-client) is launched.
c. The RAC application establishes a connection with the Remote Access Server and displays the session information.
|
|
The RAC application connects by default to WebSocket Secure (WSS). If you must access the mashup through a clear-text HTTP endpoint (not recommended), the RAC client must be configured to allow a connection to an un-encrypted WebSocket (WS). To do this, modify the config.json file to contain the { "secure": false } element. Refer to the bulleted list in Step 10 in the topic, Administrator Setup Tasks for Remote Access for the location of the file on your operating system. Disabling encryption is an insecure and bad practice, so do not use this unless absolutely necessary. Keep in mind that the RAC application can connect to either WSS or WS endpoints, but not to both of them at the same time.
|
6. Connect your client application to the local port. The RAC application forwards client data to the Remote Access Server (and on to the remote device), and vice versa.
Exploring the ThingWorx Remote Access Client (RAC)
The client that can be launched is called the ThingWorx Remote Access Client (RAC). This client will launch when you invoke the LaunchClient service on the RAClientLinker Widget. The rest of this section explains the user interface of this client.
When launched from a mashup, the RAC user interface may look like this upon session startup:
The name of the Thing that the RAC is connecting to in the above screenshot is ra-test-agent. The message window displays the current status, which in the example above is Server ready: connect client to <localhost:38367. The icons that appear on the right, above the message window, are described as follows:
• 
— An indicator of the connection status. The color yellow means that it is connecting. The indicator animates to indicate that the client is doing something.
— An indicator of the connection status. The color yellow means that it is connecting. The indicator animates to indicate that the client is doing something.The list of parameters below the status message include:
◦ Remote Entity — The name of the Thing that represents the remote device in ThingWorx. In the example above, the Thing name is ra-test-agent.
◦ Remote Server — The name of the RemoteAccessProvider that is used to establish the remote session. In the example above, the remote server is an Axeda Global Access Server (GAS), with the name, gas.ptciot.io.
◦ Remote Endpoint — The type of remote interface for this remote session. In the example above, the type of remote interface is TERMINAL, which refers to SSH or Telnet interfaces.
◦ Created By — The name of the user who started this remote session. In the example above, the user name is Administrator.
◦ Start Time — The day of the week, date, time, and timezone that the remote session was initiated by the remote server. In the example above, the session was started on Monday, November 5, 2018, at 17:13:14 (5:13:14 PM) in the GMT time zone.
◦ Duration — The number of hours, minutes, and seconds that the remote session lasted, from initialization to disconnection. In the example above, the session has been established for six seconds.
◦ Bytes Transferred — The number of bytes exchanged between the remote device and the computer from which the RAC was started. For ThingWorxInternal tunnels, the value is initially a non-zero value once the device-side server is ready. In the example above, the remote device is running an Axeda eMessage Agent. The session is ready but has not been fully established with the Axeda eMessage Agent, so this number is 0.
When the session is ready, this indicator changes to display the port number in use on a green background and the message that the remote access server is ready to connect to the device:
 | You can click the port number to copy it to paste into your client application. |
• 
— Click the black square icon if you want to stop the current session.
— Click the black square icon if you want to stop the current session.• 
— Click this icon to remove the session from the screen. If you have not already stopped the session, clicking this icon stops the session and then removes it from the screen.
— Click this icon to remove the session from the screen. If you have not already stopped the session, clicking this icon stops the session and then removes it from the screen.On the right side of the top bar are the following:
• 
— This icon indicates the status of your connection to ThingWorx Platform. When a check mark appears in the green cloud, you are connected.
— This icon indicates the status of your connection to ThingWorx Platform. When a check mark appears in the green cloud, you are connected.• 
— Click this icon to display the menu for the RAC:
— Click this icon to display the menu for the RAC:
To stop all of the sessions, select the Stop All Sessions option from the menu. Note that the information for each session remains visible until you click to remove it.
to remove it.If you must use a proxy server between your computer and the remote device, you can specify the host name and port number to use by selecting the Proxy Settings option from the menu:
| | It's important to note that the RAC can be launched with no arguments for the purpose of setting up the proxy settings. Once the settings are saved, the RAC will continue to use the proxy settings that were configured when launched by a ThingWorx Mashup. |
To display version information about the RAC, select the About option on the menu:
When you are ready to close the client, select the Exit option on the menu. Exiting prompts you to end all active sessions, if there are any.
Configuring Proxy Settings through the UI
The ThingWorx Remote Access Client (RAC) supports modifying and saving the proxy settings if the proxy configuration is NOT specified as a query parameter.
| | The RAC does not support authenticated proxies at this time. |
You can configure the settings through the RAC user interface, as follows:
1. Launch the RAC locally or from ThingWorx.
| | If launched locally, it does not connect to ThingWorx, but you can still configure proxy settings and save them. |
2. Select the menu icon (three dots): 
3. From the menu, select Proxy Settings.
4. When the window for the settings appears, specify the Host name and Port number to use:
5. Click Save.
Connections Proxied by the RAC
If the proxy configuration is specified in RAC, the following outbound connections are tunneled through the proxy server:
• ThingWorx Platform, using the AlwaysOn protocol.
• Axeda Global Access Server (GAS), using TCP.
• ThingWorx Internal Remote Access Provider, using the AlwaysOn protocol.
Status of Remote Sessions
The Remote Access Client (RAC) can detect a change to CLOSE_REQUESTED in the status of a remote session. This change occurs when the RemoteAccessSubsystem determines that a remote session has exceeded the maximum time that it can remain active.
To refresh the lastActivityTime for a remote session, the RAC periodically (every 20 seconds) updates the session to refresh the bytesTransferred for any sessions that meet the following conditions:
• The bytes transferred tracked by the RAC are greater than 0
• The bytes transferred tracked by the RAC has changed since the last update for the session
• The session status is not TERMINATED.
If the session update fails due to the session no longer existing, the session status is forced to the TERMINATED state. This change effectively stops the refresh bytes processing.
| | This timer is only enabled/required for the clients of the ThingWorxInternalRemoteAccessProvider. Since the Axeda Global Access Server (GAS) sends a periodic status update to the ThingWorx eMessage Connector, this timer is not required for a client of a GASRemoteAccessProvider. The lastActivityTime for GAS client sessions is refreshed automatically. |