[INFO] A step-by-step guide to connect ESP32-AT FW to PTC thingworx

[flosko]

Hi everyone,

I’ve evaluated for quite some while numerous larger IoT platforms to pick one for my projects. A hard requirement was to find one which allows me to use devices with the pre-compiled ESP32-AT firmware, so I ruled out all platforms which only use MQTT and/or proprietary interfaces; instead it should allow a connection via REST. Furthermore the platform must support parallel projects and management of hundreds+ devices. In that sense, the registration of devices during manufacturing and/or commissioning over a command line interface and/or scripts (and not via a “click-intensive” Web-based UI) was also a hard requirement. So, simple ones, such as thingspeak are not appropriate. A particularly interesting one is Thingworx from PTC https://www.ptc.com/en/products/iot/, which is also available as free evaluation version.

Since the initial setup is not straight forward and the learning curve quite steep, I like to drop a quick HOWTO here for everyone, who would like to try out the platform and get IoT devices connected in under 30 minutes.


HOW TO CREATE A BASIC THINGWORX SETUP:
1. register for the free (30 days) hosted foundation server, login and launch the server Thingworx Foundation (in my case Version 8.3)
2. create a project to associate all other entities with
3. create a device template with properties (e.g., a numeric property prop1), set persistent (to keep values after reboot) and is logged (to keep historic values in a value stream)
4. create value stream to automatically store historic values
5. create a user and set appropriate permissions (e.g., allow to read/write values)
6. create a thing (i.e., a shadow device) based on the initially created device template, associate with created value stream, and add the created user in the permissions tab
7. create an app key and associate it with the user; now the created user owns the set permissions to read/write properties of our thing using the created app key
8. create a mashup to visualize properties and their values in a dashboard
• set visibility to "everyone" in order to allow public dashboards, if preferred
• add visualization elements, such as Gauge, numeric displays, tables and time series charts
• add function data->QueryPropertyHistory and data->GetPropertyValues from our thing
• connect data to elements (drag and drop from data panel on the right to the mashup panel on the left); Notice: use QueryPropertyHistory to visualize historic values from the connected value stream (usually in a time series) and GetPropertyValues to get and render just the most recent value, e.g., in a gauge.


HOW TO COMMUNICATE WITH THE CREATED THING VIA ESP32-AT:
I assume the ESP32 is connected to a WiFi (AT+CWJAP) with Internet connectivity. All commands are terminated with CR+LF (0x13, 0x10)

Set up the connection to the server:

Code: Select all

// configure SSL connections – no client-side authentication used (in contrast to e.g., AWS)
AT+CIPSSLCCONF=0 

// create connection to the thingworx instance via SSL
AT+CIPSTART="SSL","pp-1532621669ia.devportal.ptc.io",443

Set some property of a thing to a specific value:

Code: Select all

// send a PUT request (to set “prop1” to value “7”) to push some data (209 bytes incl. *double* CR+LF; Notice the empty line between header and JSON body of the request!)
AT+CIPSEND=209

OK

> PUT /Thingworx/Things/thing001/Properties/* HTTP/1.1
Host: pp-1532621669ia.devportal.ptc.io
appKey: 12cf7151-be5e-4775-982a-b7a3e2f90bcd
Content-Type: application/json  
Content-Length: 11

{"prop1":7}

Recv 209 bytes
id:0,Len:209,dp:0x3ffc3b98

SEND OK

+IPD,372:HTTP/1.1 200 
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Content-Security-Policy: frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN
Expires: 0
Cache-Control: no-store, no-cache
Cache-Control: post-check=0, pre-check=0
Pragma: no-cache
Content-Type: text/html;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 20 Feb 2019 09:47:31 GMT

+IPD,5:0

Retrieve the last set value of a thing:

Code: Select all

// send a GET request to retrieve the previously pushed value (171 bytes incl. *double* CR+LF)
AT+CIPSEND=171

OK

> GET /Thingworx/Things/thing001/Properties/prop1 HTTP/1.1
Host: pp-1532621669ia.devportal.ptc.io
appKey: 12cf7151-be5e-4775-982a-b7a3e2f90bcd
Content: application/json

Recv 171 bytes
id:0,Len:171,dp:0x3ffc3b98

SEND OK

+IPD,952:HTTP/1.1 200 
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Content-Security-Policy: frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN
Expires: 0
Cache-Control: no-store, no-cache
Cache-Control: post-check=0, pre-check=0
Pragma: no-cache
Content-Type: text/html;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 20 Feb 2019 09:49:40 GMT

23d
<HTML><HEAD><TITLE>Property Value For thing001 &#x3a; prop1</TITLE><LINK rel='Stylesheet' href='/Thingworx/css/thingworxapi.css' type='text/css'></LINK><META http-equiv='Content-Type' content='text/html'></META><META http-equiv='cache-control' content='no-cache, no-store'></META><META http-equiv='expires' content='-1'></META><META http-equiv='pragma' content='no-cache, no-store'></META></HEAD><BODY><IMG SRC="/Thingworx/images/ThingworxLogo.png"/><BR/><H1>Property Value For thing001 &#x3a; prop1</H1><TABLE><TR><TH>prop1</TH></TR><TR><TD>7.0</TD></TR></TABLE></BODY></HTML>

+IPD,5:0

CLOSED
delete

That's it. There is of course much more to discover, but that's a solid starting point.
I'd be happy to get to know about your experience with this or a similar IoT platform used together with ESP32-AT FW.

cheers!

[flosko]

One small extension: In order to receive properties as JSON, you need to add "accept: application/json" to your GET request.

Code: Select all

AT+CIPSEND=197

OK

> GET /Thingworx/Things/thing001/Properties/prop1 HTTP/1.1
Host: pp-1532621669ia.devportal.ptc.io
appKey: 12cf7151-be5e-4775-982a-b7a3e2f90bcd
Content: application/json
accept: application/json

Recv 197 bytes
id:0,Len:197,dp:0x3ffc3b98

SEND OK

+IPD,591:HTTP/1.1 200 
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Content-Security-Policy: frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN
Expires: 0
Cache-Control: no-store, no-cache
Cache-Control: post-check=0, pre-check=0
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 22 Feb 2019 09:00:08 GMT

ce
{"dataShape":{"fieldDefinitions":{"prop1":{"name":"prop1","description":"","baseType":"NUMBER","ordinal":2,"aspects":{"isPersistent":true,"isLogged":true,"dataChangeType":"VALUE"}}}},"rows":[{"prop1":7.0}]}

+IPD,5:0

CLOSED
delete