Overview of modeling code for systems that communicate through the ThingWorx AlwaysOn protocol (Integration for PTC ThingWorx)
When you use ACS to generate Java and C++ code for systems from Modeler, you can set up those models so that the generated systems can communicate through the ThingWorx AlwaysOn protocol.
For systems to communicate through the AlwaysOn protocol, you must configure and run the ThingWorx Bridge, which is installed with Modeler. For more information, see the ThingWorx Bridge section that follows.
To set up a model that can communicate through the ThingWorx AlwaysOn protocol, you use the Stereotypes and Tag Definitions that are provided in the ThingWorx profile.
The Electric Car Charger (Java) model that is provided in the Examples database demonstrates how to use the ThingWorx profile in a model. The ReadMe text diagram in the model provides information for generating and building the code, and simulating the system.
Setting up a model to generate code for systems that communicate through the ThingWorx AlwaysOn protocol
To define how the system communicates through the ThingWorx Bridge you must make the following changes to a model:
• On the top-level Class for the system, create an untyped port that is stereotyped by the «ThingWorx ConnectedClient» stereotype.
• Through the Tag Definitions of the «ThingWorx ConnectedClient» stereotype specify the following information for the ThingWorx Bridge: its server, port, application key, and whether it is a secure or non-secure connection.
The IncludesCommsBroker tag definition specifies whether a COMMS_BROKER Thing is generated for the system. When two or more systems are connected through the ThingWorx AlwaysOn protocol, the COMMS_BROKER Thing must be generated for one system only.
• For each Class that needs to communicate through the ThingWorx AlwaysOn protocol, create a Part on the system Class that uses the Class as its type. You can do this by dragging the Classes to the system Class on a Composite Structure Diagram.
• For each Class that needs to communicate through the ThingWorx AlwaysOn protocol, create an untyped port on the part that uses it as a type. For each of these ports create the following items:
◦ A shallow Association link between the port and the «ThingWorx ConnectedClient» stereotyped port.
◦ Provided Interface links to provided Interfaces, and Required Interface links to the required Interfaces.
• Create EstablishConnection and CloseConnection calls to enable and disable the connection. These calls must be made through Event Action Block Actions on generated State Diagrams.
• On the State Diagrams, create the required code for working with the connection.
You will find it useful to see how the preceding items have been implemented in the Electric Car Charger (Java) model that is provided in the Examples database.
Seeing how the Electric Car Charger (Java) model has been set up to communicate through the ThingWorx AlwaysOn protocol
Open the Electric Car Charger (Java) model from the provided Examples database.
In the Packages pane expand the Software package, and then open the Composite Structure Diagram.
On the top-level CarSystem class you can see the untyped port that has been stereotyped by the «ThingWorx ConnectedClient» stereotype. The port is named ChargingPort.
Open the Property Pages of the ChargingPort port, and click the ThingWorx Connected Client tab.
You can see that the values of the tag definitions have been set up to match the configuration of the ThingWorx Bridge:
• The applicationKey property value matches the appkey value in the configuration file.
• The uri property value specifies the following information:
◦ wss, which means it is a secure connection. This matches the tls value of true in the configuration file.
Note that when it is a non-secure connection, the uri property value would specify ws, and the tls value would be set to false.
◦ localhost for the server, which means that the ThingWorx Bridge is on the same computer as the system.
◦ 811 for the port, which matches the port specified in uri value in the configuration file.
For a secure connection to a ThingWorx server, the default port number is 8080. For a non-secure connection to a ThingWorx server, the default port number is 8443.
Notice that the IncludesCommsBroker property is set to FALSE for the CarSystem, but is set to TRUE for the ChargeSystem. When the IncludesCommsBroker is set to TRUE a COMMS_BROKER Thing is generated. When two or more systems are connected through the ThingWorx AlwaysOn protocol, the COMMS_BROKER Thing must be generated for one system only.
On the Composite Structure Diagram you can see a part named m_Car that uses the Car class as its type. Through this part, the Car class can communicate with the ThingWorx connection port.
On the Composite Structure Diagram you can see that an untyped port named Plug has been created on the m_Car part. The Icar interface is set up as a provided Interface for the Plug port, and the ICharger interface is set up as a required Interface for the Plug port.
The Plug port on the m_Car part is linked to the ChargingPort port using a shallow Association link.
In the Packages pane open the State Diagram for the Car class, which is named Car.
You can see the EstablishConnection() and CloseConnection() calls on the Plug port, which enable and disable the connection.
ThingWorx Bridge
Modeler provides a ThingWorx Bridge that must be configured and running to allow communication between systems using the ThingWorx AlwaysOn protocol.
The ThingWorx Bridge launcher (TWBridgeLauncher.exe) and its configuration file (TWBridgeConfig.xml) are installed to the following folder:
C:\ProgramData\PTC Integrity Modeler\TWComms
You can create copies of the two files to use on your system's computer.
In the configuration file, you must specify the port to use, the application key to use and whether the connection is secure or non-secure.
The LocalServer settings are mandatory and they are for the ThingWorx Bridge. The UpperServer settings are optional and can be used to pass on communications to or from a ThingWorx server or another ThingWorx Bridge:
• uri - specifies the port to use. Do not change the '0.0.0.0:' part of the value.
• appkey - specifies a key to use for the communication.
• tls - specifies whether to use a secure or non-secure connection. Set to true for a secure connection, or false for a non-secure connection.
After the ThingWorx Bridge has been configured, the model for a system can be set up to work that ThingWorx Bridge.
For systems to communicate through the ThingWorx AlwaysOn protocol, a ThingWorx Bridge must be running and the system must be set up to use that ThingWorx Bridge.
