Skip to main content
Feb 16, 2017 7:06 PM UTC
Question

Help Center Excerpt - ThingWorx Edge / Connection Services (incl AWS IoT Connector)

The detailed Help Center table of contents for the ThingWorx Edge / Connection Services Help Center is extensive, ranging from Release Notes on the ThingWorx AWS IoT Connector to info on Edge SDKs for C, Java, Android and IoS to ADO and OPC-DA services.  To use your company's credentials, register as a Partner and get access to the entire Help Center library, please reach out to your partner manager.

 

Welcome to ThingWorx Edge / Connection Services Help Center

This Help Center provides information on ThingWorx WebSocket-based Edge MicroServer (WS EMS), the ThingWorx Edge SDKs, and the ThingWorx Connection Services. For information on the ThingWorx Core, see the ThingWorx Core Help Center, at http://support.ptc.com/help/thingworx_hc/thingworx_7_hc/.

Note:

The release notes for each product are cumulative, so that you can find information about a prior release of a product in the release notes topic for that product. For example, the release notes for the C SDK contain information for releases 1.1.0 through 1.3.2. For the Edge SDKs, the content of each release is provided in a table.

The main sections for each product in this Help Center address the current release of the product.

ThingWorx WebSocket-based Edge MicroServer (WS EMS)

The ThingWorx WebSocket-based Edge MicroServer works with edge devices or data stores that need to connect to the ThingWorx Core over the Internet. WS EMS also supports edge devices or data stores that are behind firewalls at a remote site, allowing secure, efficient communication back to the ThingWorx Core.

ThingWorx Edge SDKs

The ThingWorx Edge SDKs are collections of classes, objects, functions, methods, and variables that provide a framework that you can use to develop applications easily. Your applications can send data securely from your edge devices to the ThingWorx Core.

ThingWorx Connection Services

This ThingWorx Edge Help Center contains the latest content for the ThingWorx Connection Services, which consist of the following products:

• ThingWorx Connection Server, v.7.2, with its AlwaysOn Adapter. This next generation ThingWorx Connection Server implements a new framework for connections to the ThingWorx Core, separating the core services of a connection server from the adapter that translates messages from devices to a format that the ThingWorx Core understands. This new version of the Connection Server offloads the processing of AlwaysOn connections from the ThingWorx Core.

• ThingWorx AWS IoT Connector, v.1.1.0, which integrates the Amazon Web Services (AWS) IoT device cloud with ThingWorx Core. This package includes the core connection server, the AWS IoT Adapter to translate messages, and the AWS IoT Adapter Extension.

• ThingWorx Azure IoT Hub Connector, v.1.0, which integrates the Microsoft Azure IoT Hub cloud with ThingWorx Core.

Legacy Support

The Legacy Support section contains information about the original ThingWorx Connection Server (versions 1.0.0 through 7.0.0) and the original ThingWorx Edge XMPP MicroServer.

ThingWorx Edge / Connectivity Help Center Documentation

This ThingWorx Edge / Connectivity Help Center contains the latest content for the ThingWorx WebSocket-based Edge MicroServer and the ThingWorx Edge SDKs. PDF documents for these products are available in their distribution packages. These PDF documents and the ThingWorx Edge Requirements and Compatibility Matrix document are also available from the Reference Documentation page on the PTC Support site.

ThingWorx AWS IoT Connector Release Notes, v. 1.1.1

ThingWorx AWS IoT Connector, v.1.1.1, is part of the next generation of the ThingWorx connection servers. The next generation connection server is an architectural foundation that enables an expansion of the types of protocols that edge devices can use to communicate with the ThingWorx Core. Currently, the following products are available:

• ThingWorx AWS IoT Connector, v.1.1.1, which provides the core connection server and the ThingWorx AWS IoT Adapter

• ThingWorx Azure IoT Hub Connector, v.1.0, which provides the core connection server and the ThingWorx Azure IoT Hub Adapter

• ThingWorx Connection Server, v.7.2, which includes the core connection server and the ThingWorx AlwaysOn Adapter

The AWS IoT Connector provides the following basic features:

• Scalable connectivity between the ThingWorx Core and devices that use the AWS IoT SDK.

• Efficient translation between AWS IoT and ThingWorx Core.

• Horizontal scaling, by adding instances to handle increased load.

• Health check service, logging, and metrics collection features that enable system administrators to monitor the health of the connection to the ThingWorx Core as well as the traffic that it is handling. It can also provide detailed logs to help in troubleshooting.

• Customizable configuration.

Components of the AWS IoT Connector

The ThingWorx AWS IoT Connector enables devices that use the AWS IoT SDK to interact with ThingWorx Core. The ThingWorx AWS IoT Connector is comprised of the following components:

• The core, next-generation, connection server with the AWS IoT protocol adapter, that is installed and then configured to support AWS IoT devices.

• The ThingWorx Connection Services Extension (CSE), v. 1.1.1. Previously distributed in a separate bundle, this extension is now part of the distribution bundle for the Connector. You must import this extension into ThingWorx Core before importing the AWS IoT extension.

• An AWS IoT extension that must be imported into ThingWorx Core to support AWS IoT entities.

What’s New in Release 1.1.1?

The following table lists and describes the issue fixed in release 1.1.1:

Issue

Description

AWS-322

Current Drone Demo Import File Causes Failures

The Drone_AllEntities.xml file contained old service interface definitions and referenced an older version of the Connection Services Extension (CSE). Critical services in the Connector could not be called.

This release resolves this issue. A new version of the Drone_AllEntities.xml file is provided in this release.

The following table describes a Known Issue found in release 1.1.0:

Issue

Description

AWS-226

Long thing names cause the AwsIotThing’s GenerateDevicePolicy service to fail.

The GenerateDevicePolicy service on an AwsIotThing attempts to create a device-specific policy if no policyName parameter is specified. The device-specific policy includes a bunch of statements to allow some IoT actions against the device-specific resources. However, the AWS IoT policy has a character limit of 2048 bytes (see http://docs.aws.amazon.com/iot/latest/developerguide/iot-limits.html#security-limits).

If a thing name (including tenant) has more than 113 characters, the creation of the IoT Policy in AWS fails with an Exception:

{{An error occurred (InvalidRequestException) when calling the
CreatePolicy operation: Policy cannot be created - size exceeds
hard limit (2048)}}

What's New in Release 1.1.0?

Release 1.1.0 of ThingWorx AWS IoT Connector adds the following features:

• Initialization script that you run to generate a file containing the property/value pairs that configure the Connector to communicate with AWS IoT. If you have multiple tenants, run the initialization script for each tenant.

• Support for multi-tenancy. This feature enables support for multiple tenants within the AWS IoT Broker for a single AWS IoT account and region. The Connector applies the tenant name as a prefix to the names of AWS IoT things. When you have multiple tenants, rules and streams are created by the initialization script that you run for each tenant.

• Support for importing things and their data from AWS IoT into ThingWorx Core. The import process fits AWS IoT data into any ThingWorx template that is derived from the AwsIotThing template. If desired, you can add data shapes to a template that match property names as they exist in AWS IoT.

• The code and configuration that were previously part of the AwsIotAdapter extension is now part of the AWS IoT Connector. The configuration information is generated when you run the initialization script. All communication with AWS IoT to import/update things is handled by the Connector. Instead of calling AWS services directly from ThingWorx Core (the extension), the Connector calls them.

• Default device policy now restricted to a single device.

• Presence is a concept that is native to ThingWorx. It provides information about the connection from the device to ThingWorx Core. The properties that indicate that a device is “present” are isConnected and lastConnection (on the AwsIotTemplate), which inform a user whether a device is currently connected to the Core and the date/time that the device most recently connected. Presence is provided as a BETA component of the AWS IoT Connector because it can be used only with edge applications that implement the BETA version of the ThingWorx Javascript SDK for AWS IoT that is included in the distribution bundle for the ThingWorx AWS IoT Connector.

Caution:

Version 1.1.0 provides a BETA version of the Presence stream and a BETA version of the ThingWorx Javascript SDK for AWS IoT for example purposes only. As such, the Presence stream and SDK are not supported by your ThingWorx Support agreement and are not guaranteed to work with future versions of the ThingWorx AWS IoT Connector and the SDK.

• Support for customer-generated certificates for device identity. Typically, AWS supplies private keys and related certificates for things. With this release of the Connector, you can add certificates for keys that are generated externally. The Connector attaches a thing-specific policy to a new certificate when it is generated by default. The Connector provides a service to create a thing-specific policy.

Note:

When using externally generated keys and certificates, only the certificate is sent to AWS and therefore, only the certificate can be retrieved. Private keys remain private.

• This release requires version 1.1.1 (latest) of the Connection Services Extension (CSE). This extension is now distributed in the bundle for the Connector (in the extensions subdirectory). You do not need to download it separately from the PTC Support site. Note that only one version of the CSE can be installed at a time.

AWS Resource Changes

With the previous version of the AWS IoT Connector, most of the required AWS resources were created when the AwsIotSubsystem started. The only exception was the IAM User(s) that the AWS IoT Connector and AwsIotSubsystem used to connect to AWS; they had to be pre-created and configured on the respective components.

With AWS IoT Connector 1.1.0, an initialization script (aws_init.py) is provided for the Connector. This script creates all of the required AWS resources, including a new IAM User that is configured with the permissions required by the AWS IoT Connector.

Kinesis Stream Split

In AWS IoT Connector 1.0.0 there was only one Kinesis Stream to handle the data from things. All of the AWS IoT resources created to support this were given generic names, such as twx_iot_stream and twx_kinesis_rule. In A new stream was added in AWS IoT Connector 1.1.0 to handle thing presence. To support the new stream, the existing resources were named to be data specific and the new resources were named to be presence specific. The following table maps the release 1.1.0 Kinesis resource types to those in the release 1.0.0.

Resource Type

AWS IoT 1.0.0 Name

AWS IoT 1.1.0 Name

Kinesis Stream

twx_iot_stream

twx_data_stream

IoT Rule

twx_kinesis_rule

twx_data_rule

IAM Role for IoT Rule

twx_kinesis

twx_data

IAM Policy for Assume IoT Role

tws_iot_assume_kinesis_role

twx_iot_assume_data_role

IAM Policy for IAM Role for Kinesis Publishing

twx_kinesis_putrecord

twx_data_putrecord

The following table lists the resource types for thing presence in this release:

Resource Type

Name in 1.1.0

Kinesis Stream

twx_presence_stream

IoT Rule

twx_presence_rule

IAM Role for IoT Rule

twx_presence

IAM Policy for Assume IoT Role

twx_iot_assume_presence_role

IAM Policy for IAM Role for Kinesis Publishing

twx_presence_putrecord

Known Issues

This release of the AWS IoT Connector does not support migration. Instead, follow the instructions in the ThingWorx AWS IoT Connector Installation and Operations Guide, v.1.1.0, to perform a fresh installation of the Connector. If you require migration, contact PTC Technical Support to request assistance. The AWS IoT Connector guide provides information about contacting Technical Support in the section, “About This Guide”. In addition, this release has the following known issues:

ID

Description

VOL-226

The maximum size of a policy in AWS IoT is 2048 bytes. Since the thing name is part of the policy name, make sure you limit thing name to 113 characters, including the name of the tenant and the separator between the tenant name and the thing name. For example, ACME.thingOne, where ACME is the tenant name, a dot (.) is the separator, and thingOne is the name of the thing.

VOL-223

The AwsIotDisableThing service on the Connection Services Hub is invoked when an AwsIotThing is deleted from ThingWorx Core. The Hub routes the AwsIotDisableThing service invocation to an available AWS IoT Connector. The service handler on the Connector detaches the thing from all certificates, detaches the default thing policy from each certificate, and deactivates each certificate once no other policies are attached. If the thing being deleted was added to a lot of certificates, it is possible for the service to time out, thereby causing the deletion to fail. As much as possible, do NOT add a thing to multiple certificates.

You can find additional information in the ThingWorx Community forum.

We want your feedback

As you use this Help Center, we are interested in your feedback. Please contact us at documentation@ptc.com if you want to provide suggestions or comments about the Help Center, or examples of your use of the ThingWorx WebSocket-based Edge MicroServer or the ThingWorx Edge SDKs.

This Help Center was last updated November 2016.