Getting Started

Pilot Version 1.8.0

Copyright 2017 PTC Inc. and/or Its Subsidiary Companies. All

Rights Reserved.
User and training guides and related documentation from PTC Inc. and its
subsidiary companies (collectively "PTC") are subject to the copyright laws of the
United States and other countries and are provided under a license agreement that
restricts copying, disclosure, and use of such documentation. PTC hereby grants to
the licensed software user the right to make copies in printed form of this
documentation if provided on software media, but only for internal/personal use
and in accordance with the license agreement under which the applicable software
is licensed. Any copy made shall include the PTC copyright notice and any other
proprietary notice provided by PTC. Training materials may not be copied without
the express written consent of PTC. This documentation may not be disclosed,
transferred, modified, or reduced to any form, including electronic media, or
transmitted or made publicly available by any means without the prior written
consent of PTC and no authorization is granted to make copies for such purposes.
Information described herein is furnished for general information only, is subject
to change without notice, and should not be construed as a warranty or
commitment by PTC. PTC assumes no responsibility or liability for any errors or
inaccuracies that may appear in this document.
The software described in this document is provided under written license
agreement, contains valuable trade secrets and proprietary information, and is
protected by the copyright laws of the United States and other countries. It may
not be copied or distributed in any form or medium, disclosed to third parties, or
used in any manner not provided for in the software licenses agreement except
with written prior approval from PTC.
UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN
RESULT IN CIVIL DAMAGES AND CRIMINAL PROSECUTION.
PTC regards software piracy as the crime it is, and we view offenders accordingly.
We do not tolerate the piracy of PTC software products, and we pursue (both
civilly and criminally) those who do so using all legal means available, including
public and private surveillance resources. As part of these efforts, PTC uses data
monitoring and scouring technologies to obtain and transmit data on users of
illegal copies of our software. This data collection is not performed on users of
legally licensed software from PTC and its authorized distributors. If you are
using an illegal copy of our software and do not consent to the collection and
transmission of such data (including to the United States), cease using the illegal
version, and contact PTC to obtain a legally licensed copy.
Important Copyright, Trademark, Patent, and Licensing Information: See
the About Box, or copyright notice, of your PTC software.

UNITED STATES GOVERNMENT RIGHTS

PTC software products and software documentation are commercial items as
that term is defined at 48 C.F.R. 2.101. Pursuant to Federal Acquisition Regulation
(FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014) for civilian agencies or
the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1
(a) (Policy) and 227.7202-3 (a) (Rights in commercial computer software or
commercial computer software documentation) (FEB 2014) for the Department of
Defense, PTC software products and software documentation are provided to the
U.S. Government under the PTC commercial license agreement. Use, duplication
or disclosure by the U.S. Government is subject solely to the terms and conditions
set forth in the applicable PTC software license agreement.
PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA

Contents

Introduction.................................................................................................................7
Core Components ................................................................................................8
ThingWorx Experience Service Architecture Overview.............................................9
Supported Devices, Operating Systems, and Browsers ................................................ 11
Installing ThingWorx Studio........................................................................................13
Updating ThingWorx Studio to the Latest Version ..................................................14
Installing on Windows .........................................................................................15
Installing on Mac.................................................................................................18
Installing ThingWorx View ..........................................................................................21
Obtaining and Installing PTC Creo Illustrate ................................................................23
ThingWorx Authorization............................................................................................31
Global Experience Index (GXI) ...................................................................................33
Generating ThingMarks in Specific Sizes ....................................................................35

1
Introduction
Core Components .......................................................................................................8
ThingWorx Experience Service Architecture Overview ...................................................9

This guide provides the information needed to install and deploy the following
components:

ThingWorx Studio
ThingWorx View

Core Components
ThingWorx Studio
ThingWorx Studio is a web-native, easy-to-use tool for authoring domain and
task-specific Experiences that provide an integrated view of digital and physical
product data, dashboards, and alerts with 2D, 3D, and augmented reality.
ThingWorx Experience Service
ThingWorx Experience Service is an enterprise-class, secure and scalable server
used by both ThingWorx Studio and ThingWorx View. The following table lists
simple use cases for Experience Service.
ThingWorx Component
ThingWorx Studio
ThingWorx View

ThingWorx Core

Use Case
Published Experiences are stored on
ThingWorx Experience Service.
Once a ThingMark is scanned,
ThingWorx View searches ThingWorx
Experience Service for all relevant
Experiences. Once search results are
returned and a user selects an
Experience, the Experience is loaded in
ThingWorx View.
Used to serve data from Edge devices.
Optionally, it can delegate
authentication.

For more information on ThingWorx Experience Service , see Architecture

Overview on page 9.

Note
ThingWorx Experience Service is a fully standalone node application and does
not have any dependencies on ThingWorx Core.
ThingWorx View
ThingWorx View delivers Experiences rich with 2D and 3D graphics, augmented
reality, and real-time product data. ThingWorx View uses specialized markers
called ThingMarks, that once scanned, immediately deliver relevant 2D, 3D, and
AR Experiences. Experiences augment the view of your immediate surroundings
with context-sensitive information and graphics, enabling you to interact directly
with the things around you.

Getting Started

ThingWorx Experience Service

Architecture Overview
ThingWorx Experience Service is an enterprise-class, secure and scalable server
used by both ThingWorx Studio and ThingWorx View.
ThingWorx Experience Service acts as a transparent proxy to ThingWorx Core,
allowing both ThingWorx Studio Experiences and the relevant thing data to come
from the same domain.

Note
Edge devices should not be connected using ThingWorx Experience Service.
Instead, they should be accessed directly through ThingWorx Core using
alternative ports, Enterprise Load Balancer (ELB), etc.
A ThingWorx Experience Service extension is available that provides the ability
to automatically register ThingMarks with a ThingWorx Experience Service
directly from ThingWorx Core. The extension can be configured either in
ThingWorx Composer or can be automated using REST APIs; services are
available to validate configuration.

Introduction

Communication Protocols
ThingWorx Studio leverages web-based protocols for communication with clients.
These protocols are primarily HTTP(S) over standard web ports.

The following table lists the protocols and communication paths used within the
ThingWorx Studio architecture.
Software Component
ThingWorx Experience
Service
ThingWorx Studio
ThingWorx View
ThingWorx Core

10

Default Port
443

Protocol
HTTPS

443
443
8080

HTTPS
HTTPS
HTTP

Getting Started

2
Supported Devices, Operating
Systems, and Browsers
ThingWorx View iOS Supported Devices (iOS 9.0 or later)
Device
iPhone
iPad

Supported Versions
5s, 6, 6 Plus, 6s, 6s Plus, SE
Air, Air 2, Mini 4, Pro, Pro 9.7

ThingWorx View Android Supported Operating Systems

ThingWorx View is supported on Android operating systems version 5.0 and
newer.
ThingWorx Studio Supported Operating Systems and Browsers
Operating System
Mac
Windows

Supported Versions
El Capitan
7, 10 (64-bit only)

Supported Browsers
Chrome
Chrome

Note
The screen resolution minimum is 1280.

11

3
Installing ThingWorx Studio
Updating ThingWorx Studio to the Latest Version.........................................................14
Installing on Windows ................................................................................................15
Installing on Mac .......................................................................................................18

Download ThingWorx Studio from the ThingWorx Studio Portal.

Select the appropriate install option according to your OS:

Installing on Windows on page 15

Installing on Mac on page 18

13

Updating ThingWorx Studio to the Latest

Version
Use the following procedure to update ThingWorx Studio.
Windows
1. From your Task Bar, right-click the ThingWorx Studio icon and select Exit and
ensure that you have closed out of ThingWorx Studio from your browser.

2. Uninstall the previous version of ThingWorx Studio by navigating to Control

Panel Uninstall a program.
3. From the list of programs, select ThingWorx Studio, and then click Uninstall/
Change.
4. Select Remove the application from this computer., and click OK.
5. Install the latest version of ThingWorx Studio. For more information, see
Installing on Windows on page 15.
Mac
Quit any running instances of ThingWorx Studio. Locate the ThingWorx Studio
file in your Applications folder and drag the icon to the Trash can in the dock.
Install the latest version of ThingWorx Studio. For more information, see
Installing on Mac on page 18

Manually Moving ThingWorx Studio Projects

ThingWorx Studio automatically moves your projects and extensions directories
under a new ThingWorxStudio directory on startup of ThingWorx Studio 1.6.
However, if there are a large number of projects to be moved, the process may
take a while. Also, if the move fails, ThingWorx Studio will not start, and will
continue to keep trying to complete the move on subsequent startups until it
succeeds. While it is recommended that you let ThingWorx Studio move your
projects for you, it is possible to manually move them using the following process.
1. Create a ThingWorxStudio folder under <Home Directory>/
Documents.
2. Move the <Home Directory>/Documents/
VuforiaStudioEnterpriseProjects/buildersettings.json file to Documents/ThingWorxStudio.

14

Getting Started

3. Move the contents of <Home Directory>/Documents/

VuforiaStudioEnterpriseProjects/ to <Home Directory>/
Documents/ThingWorxStudio/Projects and delete the
VuforiaStudioEnterpriseProjects folder.
4. Move the contents of <Home Directory>/Documents/
VuforiaStudioEnterpriseExtensions/ to <Home Directory>/
Documents/ThingWorxStudio/Extensions, and delete the
VuforiaStudioEnterpriseExtensions folder.

Note
The Home Directory that ThingWorx Studio uses is controlled by HOME
environment variable, or if that doesn't exist the USERPROFILE environment
variable is used. For example, on Windows the home directory could be D:\
Users\jdoe\, or on OS X, ~/.

Installing on Windows
1.
2.
3.
4.
5.
6.

Go to the ThingWorx Studio Portal.

Click DASHBOARD at the top of the page.
Click Download for Windows.
Double-click the setup.exe file once it downloads.
Click Run when asked if you want to run the file.
On the Application Install - Security Warning window, click Install.

Installing ThingWorx Studio

15

7. Once the install has completed, the ThingWorx Studio window appears. Click
Open.

8. A Windows Security Alert appears. Click Allow Access.

16

Getting Started

9. The home screen appears. Click

and select Settings.

10. Enter your ThingWorx Experience Service URL. This will configure
ThingWorx Studio to use your Experience Service.

Installing ThingWorx Studio

17

Installing on Mac
1.
2.
3.
4.
5.
6.

18

Go to the ThingWorx Studio Portal.

Click DASHBOARD at the top of the page.
Click Download for Mac, and wait for the .dmg to download.
Drag-and-drop the .dmg file onto the Applications folder.
In the Applications folder, click the ThingWorx Studio application.
Once startup has completed, click Open.

Getting Started

7. The home screen appears. Click

and select Settings.

8. Enter your ThingWorx Experience Service URL. This will configure

ThingWorx Studio to use your Experience Service.

Installing ThingWorx Studio

19

4
Installing ThingWorx View
The latest version of ThingWorx View is available in the Apple App Store or
Google Play for your supported mobile devices and operating systems. Check
your App updates and install the latest version or, if you are installing for the first
time, search for ThingWorx View.

21

5
Obtaining and Installing PTC Creo
Illustrate
The ThingWorx Studio Pilot Program includes access to Creo Illustrate for
preparing your 3D models and creating animation sequences.
Obtaining PTC Creo Illustrate Licenses
1. If you do not already have a ptc.com account, you will need to register for one
at: https://support.ptc.com/appserver/common/account/createAccount.jsp
2. Use the PTC Installation Assistant to retrieve and install a license by
downloading and running https://free-dl.ptc.com/install/setup.exe.

Note
You will only install the license through this tool, not the actual software.

23

3. For Select a task, select Setup license and click Next.

4. On the Software License Agreement screen, select I accept the software license
agreement. and select the Export Agreement checkbox, and click Next.

24

Getting Started

5. Under Simple License Entry, enter the following Product Code:

VS420607ED1040-YJWM-KD98

6. Click Install Licensing. When prompted, enter your ptc.com account

credentials. It may take a few moments for the license to process.

Obtaining and Installing PTC Creo Illustrate

25

Caution
Do NOT make any changes to the list of license sources in the License
Summary section.
7. Once the license installation has finished processing, click Finish to exit the
PTC Installation Assistant.
8. You will receive an email that includes your license pack. Save the .dat file
in the email to the following location on your system if it is not already there:
C:\ProgramData\PTC\Licensing\VS420607ED1040-YJWMKD98_license.dat

26

Getting Started

Note
Alternatively, you can generate a Creo Illustrate license through the PTC
Licensing request form using the following procedure:
1. Find the host ID for your machine by executing the ipconfig/all
command from a command prompt window.
2. Find and note the Physical Address.

3. From the link below, complete and submit the License Request form. You
will be asked to enter your PTC user name and password.
http://www.ptc.com/appserver/lm/programs/licensing_programs_v.jsp

Enter your Physical Address in the Host ID field.

Enter the following in the Product Code field: VS420607ED1040YJWM-KD98

4. After you successfully submit the request form, you will receive an email
that includes your license pack. Save the .dat file to the following
location on your system:
C:\ProgramData\PTC\Licensing

Downloading and Installing PTC Creo Illustrate

Complete the following steps to download and install Creo Illustrate.
1. Click the link below to download the .zip file:
https://free-dl.ptc.com/creo/CreoIllustrate_031_M010.zip

Obtaining and Installing PTC Creo Illustrate

27

If prompted with a Windows security warning, click OK.

Note
Downloading the .zip may take a moment.
2. Once the .zip has finished loading, extract the contents into a new, empty
directory, and then double-click the setup.vbs file.
3. If a Windows User Account Control warning appears, click Yes.
4. Select a language and click OK.
5. On the Before You Begin page, read the information and click Next.
6. Click I Accept on the PTC Customer Agreement page. Click Next. The Select
Directory page appears.
7. Under Installation Directory, accept the default directory, or browse to a new
path and click Select. The Review Settings page appears.
8. Review the settings and click Install.
9. Once installation is complete, click Done.
10. PTC Creo Illustrate is now installed.

28

Getting Started

Starting PTC Creo Illustrate

Once you have successfully installed Creo Illustrate, you will need to configure
your license.
1. Open PTC Creo Illustrate.
2. The PTC Creo Illustrate Startup window appears.

3. Enter the following path to your license file in the License Server field:
C:\ProgramData\PTC\Licensing\VS420607ED1040-YJWM-KD98_license.dat
4. Click Start.
5. You can now begin using Creo Illustrate.

Obtaining and Installing PTC Creo Illustrate

29

6
ThingWorx Authorization
An Experience can display data from ThingWorx in widgets such as sensors and
labels. In order for the ThingWorx data to be displayed in the Experience, the user
viewing the Experience must have the necessary ThingWorx permissions to access
the data. Each user that uses an Experience that access data in ThingWorx must be
granted the following run time permissions in ThingWorx.

Property Readpermission for any property whose value is displayed in the

Experience
Service Executepermission for any service used by the Experience

If web sockets are used to push property values to the Experience, then each user
that uses the experience must be granted the following additional run time
permissions.

Event Subscribepermission for the DataChange event on any thing whose

property values are pushed to the Experience through a web socket
Execute Servicepermission on the GetClientApplicationKey service on the
EntityServices resource
Service Executepermission on the SDKGateway thing template

31

7
Global Experience Index (GXI)
GXI eliminates the need for you to manually configure ThingWorx View to point
to your ThingWorx Experience Service and processes queries for any ThingMark.
When the GXI receives a ThingMark query, it identifies the ThingWorx
Experience Service that hosts Experiences for that ThingMark and redirects the
query to that specific ThingWorx Experience Service.
By default, ThingWorx View uses the GXI but can also be manually configured to
use a different Experience Service.

33

8
Generating ThingMarks in Specific
Sizes
This topic provides the steps required to generate ThingMarks of specific sizes for
printing and subsequent use with ThingWorx View.
Prerequisites
Before you can generate ThingMarks in different sizes, you must install imageediting software such as GIMP (GNU Image Manipulation Program), that
supports the Scalable Vector Graphics format (.svg files). You can download
GIMP from the following link:
https://www.gimp.org/downloads/

35

Selecting a ThingMark Size

1. Open a .svg file using GIMP.
2. The Render Scalable Vector Graphics window appears.

3. Select the appropriate unit of measurement from the drop-down menu next to
the Height field.
4. Enter the desired Width of the ThingMark.

Note
To preserve correct proportions, the Height property is adjusted
automatically.
5. Set the desired Resolution.

Tip
Setting the Resolution to 120 pixels/in displays the best with Microsoftbased tools, including Microsoft Office. Other resolutions can result in
incorrect printed sizes.

36

Getting Started

Printing or Exporting a ThingMark

You can print directly from GIMP. Alternatively, if you are printing multiple
ThingMarks or multiple sizes, you can perform the Select All action (Ctrl+A) and
copy/paste the ThingMarks into Microsoft Word.

Note
When printing ThingMarks from Microsoft Word or Adobe Acrobat/Reader,
ensure that you do not to select printing options such as Shrink to fit. These
options could adversely affect the size of the printed ThingMark.
You can also export the ThingMarks for later use using the following steps.
1.
2.
3.
4.

From GIMP, select File Export As.

Enter a filename in the Name field.
Select the desired location path using the Save in folder field.
Select PNG image (*.png) as the file format.

Note
Saving the ThingMark in other formats, such as a JPEG, can result in the
loss of quality due to compression.
5. Click Export.

Generating ThingMarks in Specific Sizes

37