ThingWorx Remote Access Client
To fully migrate Axeda customers to ThingWorx, the ThingWorx Remote Access Client (RAC) is provided as a mechanism for using the ThingWorx remote access features, including the ThingWorx Asset Advisor, Remote Access and Control module, and Axeda Desktop Viewer. 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 Remote Access Client enables that tunnel. You can download the RAC from the ThingWorx Remote Access Client Downloads page.
The RAC connection to a ThingWorx Platform is called a command channel. In a single node ThingWorx Platform installation, the command channel goes directly to the platform from a RAC instance. In a high availability (HA) environment, the RAC connection requires a ThingWorx Connection Server to establish the command channel to an available ThingWorx Platform server in the cluster. For more information on using remote access in an HA environment, refer to .
The following sections provide details about the RAC, including administrator setup tasks and a quick start for using it, followed by more detailed steps. Click a section title to display the content. Click the title again to hide the content.
Administrator Setup Tasks
Remote sessions are supported for devices that are running Axeda eMessage agents (Axeda Gateway or Axeda Connector) Agents. Administrators need to ensure that the requirements are met. For details, refer to Requirements for Remote Sessions.
Security
By default, the ThingWorx Remote Access Client (RAC) is configured to use TLS for network connections. The use of TLS is a security best practice and should be used, especially in production deployments.
Quick Start
1. From ThingWorx Composer, set up a Thing and then connect it to your ThingWorx Platform. The Thing must meet the following criteria:
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. A reporting Thing typically is a remote device bound into the ThingWorx Platform. In the case of Axeda eMessage Agent devices, a remote device that regularly polls the eMessage Connector should show as reporting if the AxedaPollingTimer is running and correctly configured with an AxedaPollingStrategy. To determine if the device is reporting, check the value of the isReporting property of the Thing. It should be true, which is indicated by a dimmed check mark as the value of the property
d. You must configure a tunnel endpoint for each Thing that represents an eMessage Agent device.
Good candidates for testing remote sessions with devices 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 from https://free-dl.ptc.com/thingworx/remote-access/client/inventory.html.
3. Navigate to the location where you saved the package and run it to install the Remote Access Client For example, on Windows run the .exe file. On Linux and OS X, install the package.
4. From ThingWorx Mashup Builder, add the RAClientLinker widget to a mashup and set the properties described in the following table:
Property | Description |
|---|---|
ThingName | The name of the Thing that represents the asset with which you want to establish a remote session. |
RemoteEndpoint | You need to bind this property to a row returned by the GetRemoteAccessibleEndpoints service, This service is provided on the RemoteAccessible Thing Shape and therefore to each eMessage Agent device with which you conduct remote sessions. |
ProviderConfig | This property is JSON that is specifically formatted to the type of RemoteAccessProvider being used, either the ThingWorxInternalRemoteAccessProvider Thing for ThingWorx AlwaysOn agents such as the Edge MicroServer or the GASRemoteAccessProvider Thing for Axeda eMessage Agents. You can bind this property to a row returned by the GetRemoteServerConfiguration service. For details about this service, refer to its description in the topic, RemoteAccessProvider Thing Shape. |
SessionDescription | The JSON-formatted metadata field from the RemoteSessionParameters Data Shape supports this property. When the widget calls the StartSession service, it adds the content of this field with the key description and the vavlue of the SessionDescription property. |
Refer to Using the RAClientLinker Widget for details about using the widget in a mashup.
5. Using your mashup, start a Remote Session with the Thing that you connected in Step 1. The following sequence takes place:
a. A remote session is requested for the selected Thing in the ThingWorx Platform by invoking the StartSession service on the Thing.
b. The Remote Access Client (RAC) application (tw-ra-client) is then launched.
c. The RAC 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 (strongly discouraged), the RAC must be configured to allow a connection to an unencrypted WebSocket (WS). To do this, create or modify the config.json file to contain the { "secure": false } element. Depending on your operating system, the config.json file is located in one of the following directories: • Linux: ~/.config/tw-ra-client. • Windows: %USER_HOME%\AppData\Roaming\tw-ra-client. • OS X/Mac: ~/Library/Application Support/tw-ra-client. 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. |
WARNING Disabling TLS can leave your network communication open to security breaches and is, therefore, strongly discouraged. Do so at your own risk.
6. Connect your client application to the local port. The RAC forwards client data to the Remote Access Server (and on to the remote device), and vice versa.
The RAC uses port cycling when attempting to establish a session. During port cycling, the RAC tries to connect using the connect port defined at the Agent. Failing that, it uses a random port.
The RAC always shows the IP address and actual port used and an arrow pointing to the Agent's connect port. Showing the Agent's connect port as well as the port actually used enables you to identify any ports that have been aliased. For example, in the green oval and in the grey text area in the following figure, RAC displays "localhost" with the local random TCP port used, 43267. The grey text area also includes an arrow pointing to the Agent's configured connect port, 22:
For detailed instructions and illustrated usage information for the widget and the Remote Access Client, refer to Using the RAClientLinker Widget.
Exploring the ThingWorx Remote Access Client (RAC)
The ThingWorx Remote Access Client launches when the LaunchClient service is invoked on the RAClientLinker widget. The rest of this section explains the user interface of this client.
Upon session startup, the Remote Access Client user interface looks similar to this:
The name of the Thing that the RAClient is connecting to in the above screenshot is ra-test-agent. The message window displays the current status, which in the example above is Awaiting session readiness.... The icons that may 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 RemoteAccessServer Thing used to establish the remote session. In this example the name of the Thing is gas.ptciot.io.
◦ Remote Endpoint — The type of remote interface for this remote session. In the example above, the type of remote interface is ssh-app, 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 March 17, 2021, at 09:43:36.
◦ Duration — The number of hours, minutes, and seconds that the remote session lasted, from initialization to disconnection. In the example above, the session has not been started yet, so this field shows a zero in every time field.
◦ Bytes Transferred — The number of bytes exchanged between the remote device and the computer from which the RAC was started. In the example above, the remote device is running an Axeda eMessage Agent. The RAC is waiting to connect, so the value is 0.
When the session is ready, this indicator changes to display localhost: and the port number used on a green background and on the background, as well as the message that the remote access server is ready to connect to the device on localhost, port 43267, which is mapped to the Agent's connect port, 22:
 | 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 RA Client:
— Click this icon to display the menu for the RA Client:
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 is 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 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 UI, 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, arranged in a vertical line): 
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 AlwaysOn protocol
• Axeda Global Access Server (GAS) or ThingWorx Global Access Server (GAS) , using TCP
• ThingWorx Internal Remote Access Provider, using WebSocket 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 Global Access Server (GAS) sends a periodic status update to the eMessage Connector, this timer is not required for a client of a GASRemoteAccessProvider. The lastActivityTime for GAS client sessions is refreshed automatically. |