Release Notes > ThingWorx Protocol Adapter Toolkit Release Notes, November 2019, updated for v.1.5.1
ThingWorx Protocol Adapter Toolkit Release Notes, November 2019, updated for v.1.5.1
IMPORTANT! With release 1.5.1, the ThingWorx Protocol Adapter Toolkit (PAT) has been certified to work with ThingWorx Platform v.8.5.0. In addition, as part of PTC's ongoing efforts to improve security, this release of the PAT includes software fixes for potential security issues, as well as additional issues proactively identified by vulnerability scanning software or PTC QA testing. PTC strongly recommends upgrading to the latest versioornn of the PAT as soon as possible to take advantage of security enhancements.
Versions 8.2.15, 8.3.10, 8.4.6, 8.5.0 or later of the ThingWorx Platform contain a fix that requires a user to have EventSubscribe permissions to trigger a subscription associated with an event. A user must have EventInvoke and EventSubscribe permissions on an event and associated subscriptions in order to trigger them. If you are using any of these versions of ThingWorx Platform, make sure that you use the version of the ThingWorx Connection Services Extension (CSE) provided with the PAT, which is 1.5.6. This version of the CSE includes an update to the GrantThingTemplatePermissions service such that the service grants Execute permission to use the EventSubscribe service to the Connector user.
Previous Releases
The initial release of the ThingWorx Protocol Adapter Toolkit provided support for HTTP and WebSockets channels. Release 1.1.2 added support for MQTT and custom channels. The Connection Services Extension (CSE), v.1.5.1, added a Protocol Adapter Subsystem and a ProtocolAdapterWithAvailability Thing Template that is created in ThingWorx when you import version 1.5.1 or later of the Connection Services Extension.
This Toolkit supports creation of the three primary components of a Connector:
A Channel for sending and receiving messages between your edge devices and your Codec. You can implement your own custom channel or use one of the standard, supported channels (WebSocket, HTTP, or MQTT).
A Codec that translates messages from your edge devices into messages that ThingWorx Platform can process (your protocol to ThingWorx AlwaysOn protocol). You must implement the Codec.
A Platform Connection for sending messages to and receiving messages from ThingWorx Platform.
As of release 1.5.0, the PAT supports the ability to run a Connector using an encrypted configuration file. Refer to the topic, Setting Up an Encrypted Configuration File for a Connector in the ThingWorx Protocol Adapter Toolkit Developer's Guide or in the ThingWorx Connection Services Help Center.
Requirements and Compatibility
The following table lists the requirements and compatibility for the releases of the toolkit:
Protocol Adapter Toolkit, v.1.5.1
JDK 1.8.0_u161 or later
Linux 64-bit operating system
ThingWorx Platform v.8.1.x or later
Connection Services Extension (CSE), v.1.5.1 or later
Connector Feature Summary
The following table lists features of a typical Connector and the channels that the current version of the ThingWorx Protocol Adapter Toolkit support. For features such as a property read or a service invocation, the table breaks down the support of that feature into “Edge Initiated” and “Platform Initiated” (that is, initiated by ThingWorx Platform). The columns for the supported channels show whether that feature is supported for the channel in the toolkit. The footnote markers in this table indicate which item in the list of Footnotes that follows this table describes a limitation for the feature in this release of the Toolkit.
Channel Features
The footnote markers in the preceding table correspond to each entry in the numbered list below:
1. The Protocol Adapter Toolkit does not enable synchronous messaging when the request is initiated by ThingWorx Platform to an edge device. Remote property reads can be approximated by creating a custom service on the edge device. When invoked by a remote service call, the custom service would initiate a property write on ThingWorx Platform.
2. The Protocol Adapter Toolkit does not support the File Transfer SubSystem (FTSS). File transfers can be accomplished by chunking the file into multiple messages and writing a custom service backed by a file repository on ThingWorx Platform. The Protocol Adapter Toolkit ships with example applications that show how to chunk a file and write a custom service, using HTTP and WebSocket Channels.
3. Devices using a polling channel, such as HTTP, are not always connected to ThingWorx Platform. Users may see a message like the one below when manually testing unconnected devices using ThingWorx Composer. Remote operations will be queued and delivered to the device when the device asks for them. Refer to the Edge-Requested Egress section of the Protocol Adapter Toolkit section of the ThingWorx Connection Services Help Center. If you have upgraded to ThingWorx Platform 8.4.0, a new feature called Thing Presence can facilitate knowing when polling devices are connected. Refer to the Tip that follows this error message image:
The Thing Presence feature of the ThingWorx Platform (new as of v.8.4.0) can help you better determine when polling devices are connected. The new isReporting property is updated to show whether a device is online. The samples provided with this version of the toolkit show how to use Thing Presence for various channels. For details about Thing Presence see the section on Thing Presence in the ThingWorx Platform Help Center.
Issues Fixed in v.1.5.0
The following table lists and briefly describes issues fixed in release 1.5.0:
The documentation has been updated to include using blocking vs. non-blocking options. Refer to the table of Optional Configuration Properties for All Types of Channels, in the ThingWorx Connection Services Help Center..
User context for reporting strategy added to the samples that accompany the Protocol Adapter Toolkit.
A new configuration element is available for reporting strategies that sets the user context in which they execute. For details see Thing Presence Reporting Strategy: Security Setup).
The Protocol Adapter Toolkit now supports running your connector with an encrypted configuration file to provide improved security for your IoT solution. Refer to the topic, "Setting Up an Encrypted Configuration File for Your Connector" in the ThingWorx Protocol Adapter Toolkit Developer's Guide, v.1.5.0.
Issue Fixed in v.1.1.2
The following issue is fixed by the changes made to the documentation:
XSDK-723 (14177951)
PAT Compatibility with ThingWorx 8.3 is not documented.
This issue is fixed in this documentation update . Refer to XSDK-724 in the table of Known Issues above..
Known Issues
The following table lists and briefly describes Known Issues.
Known Issues
The Protocol Adapter Toolkit distribution does not build with Java 9 or later.
The Protocol Adapter Toolkit distribution ships with an older version of Gradle that prevents PAT from compiling with Java 9 or later out of the box.
The ReadPropertyMessage, WritePropertyMessage, and WritePropertiesMessage classes of PAT do not support properties that use the PASSWORD base type. If your model includes properties that use the PASSWORD base type and you need to read or write to these properties from your PAT Connector, you can accomplish this by writing services on the ThingWorx Platform.