Modeling code for systems that can be used by ThingWorx things and mashups (Integration for PTC ThingWorx)
To see an example of how to set up a model to generate code that can be used by ThingWorx Things and Mashups, see the Electric Car Charger (Java) model that is provided in the Examples repository.
To model code for systems that can be used by ThingWorx things and mashups:
1. Set up your model as required to generate the system.
You must have a top-level class that represents the system
2. If you have not done so already, add the ThingWorx Profile to the model.
Note that the ThingWorx Profile is automatically added with the Java Profile or C++ Profile profiles.
Apply the ThingWorx Stereotypes to the items you want to expose:
1. To model a
ThingWorx Remote Thing
a. Locate the Class or Interface from which the ThingWorx Remote Thing will be generated.
b. Apply the «ThingWorx RemoteThing» stereotype to the Class or Interface.
c. Open the Property Pages of the Class or Interface.
d. On the ThingWorx RemoteThing tab, set the value of the Implementation tag definition to ThingShape or Thing Template depending on what you want to generate.
2. To model a ThingWorx Property:
a. Locate the Attribute or Operation from which the ThingWorx Property will be generated.
The Attribute or Operation must be a child of a Class or Interface that has the «ThingWorx RemoteThing» stereotype applied.
b. Apply the «ThingWorx Property» stereotype to the Attribute or Operation.
3. To model a ThingWorx Service (from an Operation):
a. Locate the Operation from which the ThingWorx Service will be generated.
The Operation must be a child of a Class or Interface that has the «ThingWorx RemoteThing» stereotype applied.
b. Apply the «ThingWorx Service» stereotype to the Operation.
4. To model a ThingWorx Service (from an Event):
a. Locate the Event from which the ThingWorx Service will be generated.
The Event must be used in a generated state machine.
b. Apply the «ThingWorx Service» stereotype to the Event.
5. To model a ThingWorx Event
a. Locate the Operation for which you want to generate code for a ThingWorx Event.
The Operation must be a child of a Class or Interface that has the «ThingWorx RemoteThing» stereotype applied.
b. Apply the «ThingWorx Event» stereotype to the Operation.
Create the ThingWorx connection port for the system Class:
1. Create a Composite Structure Diagram and add the system Class that represents the system to the diagram.
2. Create an untyped port on the top-class. This port will be the ThingWorx connection port.
To create an untyped port: click the Port toolbar button, click the Class, and then click Untyped.
3. Apply the «ThingWorx ConnectedClient» stereotype to the ThingWorx connection port.
4. Open the Property Pages of the ThingWorx connection port.
5. Click the ThingWorx ConnectedClient tab and set the values of the Tag Definitions as required:
◦ IncludesCommsBroker - When you are only modeling code for systems that can be used by ThingWorx things and mashups, set the IncludesCommsBroker value to FALSE
Binding the Remote Things classes to the ThingWorx connection port:
1. Drag each Class that has the «ThingWorx RemoteThing» stereotype applied to the system Class on the Composite Structure Diagram.
This creates a part on the system Class that uses the Class you dragged as its type.
2. For each Class you dragged to the diagram:
◦ On the Composite Structure Diagram toolbar, click the Bind button, click the part that was created for the dragged Class, and then click the ThingWorx connection port.
Configuring models to automatically upload ThingShapes, ThingTemplates, and DataShapes to a ThingWorx server
You can use the TWConfig.xml file in the %ProgramData% directory to configure models for automatic upload. The file is not installed by default. You should create it manually or generate it by running the Configuration Migration script in the ThingWorx Profile. We recommend using the Configuration Migration script.
When you run the script for the first time in a model with no «ThingWorx ConnectedClient» stereotyped ports, the file contents will be similar to the following:
<?xml version="1.0"?> <Config> <!-- Modify the default section to use your own default values if required. Add further sections for specific models. Model Directory and Client DottedName properties may be determined by use of the TellMe tool. The Model (Protocol, URI & AcceptSelfSigned) elements are used by the generator in order to export generated ThingShapes, ThingTemplates & DataShapes to a Thingworx server. The ConnectedClients element may have zero or more Client elements and is used to generate configuration files for specifying runtime client connections. --> <Model Directory='default'> <Protocol>http</Protocol> <URI>address:port</URI> <AcceptSelfSigned>false</AcceptSelfSigned> <ConnectedClients> <Client DottedName='MyDottedName'> <AppKey>MyAppKey</AppKey> <URI>protocol://address:port/Thingworx/WS</URI> </Client> </ConnectedClients> </Model> <!-- New Model --> <Model Directory='\\VLEWIS1L\ModelerATF\Models\79033b5f-e104-426e-ad40-1b01335def75\0\'> <Protocol>Protocol</Protocol> <URI>localhost:80</URI> <AcceptSelfSigned>false</AcceptSelfSigned> <ConnectedClients> </ConnectedClients> </Model> </Config>
Connected client ports, if they are any, appear as children of the ConnectedClients element. For example:
You should manually populate the Protocol, URI, and AcceptSelfSigned values of the model elements as appropriate. This allows you to automatically upload generated ThingShapes, ThingTemplates, DataShapes to your ThingWorx server.
If a model section is missing from TWConfig.xml when the generator is run, values from the 'default' section will be used instead. Therefore, you should consider populating the default section with fallback values.
In order to specify the runtime connection to a ThingWorx server or a microbridge, you should populate the AppKey and URI values of the Client element. The following values are required:
For AppKey—set the value to a valid application key for the ThingWorx server. For more information about application keys in ThingWorx, see the ThingWorx Help.
For URI—set the value by using the following syntax:
wss¦ws//<server name>:<port number>
Where:
• wss¦ws—is set to wss for a secure connection, or ws for a non-secure connection.
• <server name>—is the computer on which the ThingWorx server resides.
• <port number>—is the port number for the ThingWorx server.
Entering ThingWorx credentials to upload files to the ThingWorx server
A dialog box appears when the generator creates files that are ready to be uploaded to the ThingWorx server.
To upload the generated files:
• Enter your ThingWorx user credentials, and then click OK. Your credentials are stored until ACS is restarted.
If an upload fails, you must re-enter your ThingWorx credentials in order to upload the next file.
To skip any subsequent uploads of files in the current generation, click Cancel.
To skip any subsequent uploads of files in the current and in future generations, click Dismiss. Uploading is skipped until Force Generate is executed.
Migrating existing models to the new ThingWorx Profile configuration method
If you have existing models that use the ThingWorx Profile, you must update the models to the latest profile version.
To upgrade the ThingWorx profile, perform the following:
• Run the Configuration Migration script to create or amend the TWConfig.xml file.
The script extracts values that exist in profile tags and automatically populates the values in TWConfig.xml. For example:
Build the system as you normally would after generating the code using ACS. The ReadMe text diagram in the Electric Car Charger (Java) model provides information for building a system.
The ThingWorx Bridge must be running for the system to communicate through the ThingWorx AlwaysOn protocol.
Port toolbar button, click the Class, and then click Untyped.
Bind button, click the part that was created for the dragged Class, and then click the ThingWorx connection port.