AWS IoT Core Integration

How to integrate AWS IoT Core with Connectware, including X.509 mutual TLS authentication, the required IoT policy, publishing shop floor data, and receiving cloud-to-device messages.

This guide describes how to integrate AWS IoT Core with Connectware. You configure a service commissioning file that publishes shop floor data to the AWS IoT Core message broker over MQTT with X.509 mutual TLS and receives cloud-to-device messages in return. A complete example file is available at the end of this guide.

Objectives

• Establishing a mutual TLS (mTLS) authenticated MQTT connection between Connectware and AWS IoT Core.

• Creating an AWS IoT policy that authorizes the connection to connect, publish, subscribe, and receive.

• Publishing shop floor data from an ISA-95 topic hierarchy to AWS IoT Core topics.

• Receiving cloud-to-device commands from AWS IoT Core in Connectware.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware.

• An AWS account with access to the AWS IoT Core console or the AWS Command Line Interface (CLI).

• An AWS IoT thing with an activated X.509 device certificate and its private key. If you do not have one yet, follow Getting started with AWS IoT Core.

• Access to the Admin UI with sufficient user permissions.

• Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, endpoints, and mappings).

Connectware and AWS IoT Core Integration

AWS IoT Core provides a managed MQTT message broker. Connectware connects to it like any other device: over TLS on port 8883, authenticated with an X.509 client certificate. The MQTT connector handles the connection, and Cybus::Mapping and Cybus::Endpoint resources route data between the Connectware topic hierarchy and AWS IoT Core topics.

The broker is reachable at the device data endpoint of your AWS account, which has the form <account-specific-prefix>-ats.iot.<region>.amazonaws.com. You find it on the Settings page of the AWS IoT Core console, or with the AWS CLI:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

The AWS IoT Core broker differs from a generic MQTT broker in a few ways that matter for this integration (see AWS IoT Core MQTT documentation):

• AWS IoT Core supports MQTT Quality of Service (QoS) levels 0 and 1, but not QoS 2. Do not configure qos: 2 on endpoints or mappings that target AWS IoT Core.

• Every action requires authorization by an AWS IoT policy. Without the matching policy statement, a connect attempt is rejected, a publish is silently dropped, or a subscription is refused.

• Topic names that begin with $ are reserved for AWS IoT Core (for example, $aws/things/...). A topic can contain at most seven forward slashes, and the client ID can be at most 128 bytes.

• Retained messages are supported, but publishing them requires the additional iot:RetainPublish policy action.

• If a second client connects with the same client ID, AWS IoT Core disconnects the first client.

The MQTT topics on the Connectware side follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>). The mapping subscribes with wildcards across all levels, so any machine in the hierarchy is picked up without changing the integration. On the AWS side, this guide uses the dt/ prefix for device-to-cloud telemetry and the cmd/ prefix for cloud-to-device commands, following the AWS whitepaper Designing MQTT Topics for AWS IoT Core.

To connect through an AWS IoT Greengrass Core at the edge instead of connecting directly to the cloud, see AWS IoT Greengrass Integration.

AWS IoT Policy

AWS IoT Core authorizes every MQTT action against the AWS IoT policy that is attached to the device certificate. The policy must allow Connectware to connect with its client ID, publish to the telemetry topics, and subscribe to and receive from the command topic.

The following policy matches the topics used in this guide. Replace the region and the account ID with your own values.

connectware-policy.json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:eu-central-1:123456789012:client/connectware-shopfloor"
    },
    {
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": "arn:aws:iot:eu-central-1:123456789012:topic/dt/*"
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": "arn:aws:iot:eu-central-1:123456789012:topicfilter/cmd/connectware-shopfloor/commands"
    },
    {
      "Effect": "Allow",
      "Action": "iot:Receive",
      "Resource": "arn:aws:iot:eu-central-1:123456789012:topic/cmd/connectware-shopfloor/commands"
    }
  ]
}

iot:Publish and iot:Receive use topic/ resources, while iot:Subscribe uses topicfilter/ resources. AWS IoT policies use * as the wildcard character, not the MQTT wildcards + and #. For more policy variants, see the AWS IoT publish/subscribe policy examples.

AWS IoT Core Connection Parameters

The connection requires the device data endpoint, a client ID, and the certificate material. We add the endpoint, the client ID, and the topic root as parameters to the service commissioning file, so you can set them when you install the service.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

• awsIotEndpoint: The device data endpoint of your AWS account, as returned by describe-endpoint.

• clientId: The MQTT client ID. It must match the client resource in the iot:Connect policy statement and must be unique within your AWS account, because AWS IoT Core disconnects an existing connection that uses the same client ID.

• topicRoot: The root of the MQTT topic hierarchy on the Connectware side. Defaults to enterprise.

parameters:
  awsIotEndpoint:
    description: Device data endpoint (iot:Data-ATS) of your AWS account
    type: string
    default: a1b2c3d4e5f6g7-ats.iot.eu-central-1.amazonaws.com

  clientId:
    description: MQTT client ID, must match the client ARN in the AWS IoT policy
    type: string
    default: connectware-shopfloor

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

The MQTT connector expects the certificate material as string values containing the content of the PEM files, not as file paths (see MQTT Connection Properties). We add the three PEM blocks to the definitions section of the service commissioning file:

• caCert: The Amazon root CA certificate (AmazonRootCA1.pem) that Connectware uses to validate the broker certificate. Download it from the Amazon Trust Services repository listed under AWS IoT server authentication.

• clientCert: The device certificate that AWS IoT Core issued when you registered the thing.

• clientPrivateKey: The private key that belongs to the device certificate.

definitions:
  # The Amazon root CA certificate as PEM file content (AmazonRootCA1.pem)
  caCert: |
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----
  # The device certificate as PEM file content
  clientCert: |
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----
  # The device private key as PEM file content
  clientPrivateKey: |
    -----BEGIN RSA PRIVATE KEY-----
    -----END RSA PRIVATE KEY-----

The private key authenticates your Connectware instance against your AWS account. Treat the service commissioning file as a secret and restrict who can read it.

AWS IoT Core Connection

To connect to AWS IoT Core, we set up a Cybus::Connection resource that uses the MQTT connector with scheme: mqtts on port 8883 and mutualAuthentication: true, so Connectware presents the device certificate during the TLS handshake and validates the broker certificate against the Amazon root CA.

resources:
  awsIotConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref awsIotEndpoint
        port: 8883
        scheme: mqtts
        clientId: !ref clientId
        keepalive: 60
        mutualAuthentication: true
        caCert: !ref caCert
        clientCert: !ref clientCert
        clientPrivateKey: !ref clientPrivateKey

AWS IoT Core supports keep-alive intervals between 30 and 1200 seconds. The MQTT connector defaults to 0, which disables client-side keep-alive pings. AWS IoT Core then applies its server default of 1200 seconds and disconnects the client after prolonged inactivity. A value of 60 seconds keeps the connection alive even when no data flows.

Publishing Shop Floor Data to AWS IoT Core

A Cybus::Mapping resource forwards telemetry from the ISA-95 topic hierarchy to AWS IoT Core. The named wildcards +site, +area, +line, and +cell capture the levels of the source topic, and the publish side reuses them as $site, $area, $line, and $cell to mirror the hierarchy under the dt/ prefix.

telemetryMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/telemetry'
          qos: 1
        publish:
          connection: !ref awsIotConnection
          topic: dt/$site/$area/$line/$cell/telemetry
          qos: 1

A message published to enterprise/hamburg/assembly/line-1/press-01/telemetry now arrives on the AWS IoT Core topic dt/hamburg/assembly/line-1/press-01/telemetry. The payload is forwarded unchanged. To reshape it before it reaches the cloud, for example to add a timestamp or flatten a structure, add rules to the mapping (see Rule Engine).

QoS 1 on both sides gives at-least-once delivery from the internal broker to AWS IoT Core. Keep the AWS payload limit of 128 KB per publish in mind when you aggregate messages.

Receiving Commands from AWS IoT Core

For the opposite direction, a Cybus::Endpoint resource subscribes to the cloud-to-device command topic, and a mapping republishes every command to the Connectware topic hierarchy, where any other Connectware service can pick it up, for example to write a setpoint to a PLC.

commandEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Mqtt
    connection: !ref awsIotConnection
    subscribe:
      topic: !sub 'cmd/${clientId}/commands'
      qos: 1

commandMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref commandEndpoint
        publish:
          topic: !sub '${topicRoot}/cloud/aws-iot/commands'

Any application in your AWS account that is authorized to publish to cmd/connectware-shopfloor/commands, for example an AWS IoT rule or a Lambda function, can now send messages to the shop floor. Connectware republishes them to enterprise/cloud/aws-iot/commands.

Verifying the Integration

1. Install the service and set the parameters with the values from your AWS account.

2. Check that the connection is in the Connected state on the service details page in the Admin UI. If the certificate material is wrong or the policy lacks the iot:Connect statement, the connection does not reach the connected state.

3. In the AWS IoT Core console, open the MQTT test client and subscribe to dt/#.

4. Publish a test message to enterprise/hamburg/assembly/line-1/press-01/telemetry, for example with an MQTT client or the Admin UI. The message appears in the MQTT test client on dt/hamburg/assembly/line-1/press-01/telemetry.

5. In the MQTT test client, publish a message to cmd/connectware-shopfloor/commands. Use the Data Explorer to check that the message arrives on enterprise/cloud/aws-iot/commands.

If messages do not arrive in one direction, check the AWS IoT policy first. AWS IoT Core drops unauthorized publishes without disconnecting the client, so a missing iot:Publish or iot:Receive statement shows up as silently missing messages rather than as a connection error.

Service Commissioning File Example

aws-iot-core-example.yml

3KB

Open

aws-iot-core-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# AWS IoT Core Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for the bidirectional integration between
  Connectware and AWS IoT Core (Example)

metadata:
  name: AWS IoT Core Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  awsIotEndpoint:
    description: Device data endpoint (iot:Data-ATS) of your AWS account
    type: string
    default: a1b2c3d4e5f6g7-ats.iot.eu-central-1.amazonaws.com

  clientId:
    description: MQTT client ID, must match the client ARN in the AWS IoT policy
    type: string
    default: connectware-shopfloor

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

definitions:
  # The Amazon root CA certificate as PEM file content (AmazonRootCA1.pem)
  caCert: |
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----
  # The device certificate as PEM file content
  clientCert: |
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----
  # The device private key as PEM file content
  clientPrivateKey: |
    -----BEGIN RSA PRIVATE KEY-----
    -----END RSA PRIVATE KEY-----

resources:
  # Mutual TLS connection to the AWS IoT Core message broker
  awsIotConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref awsIotEndpoint
        port: 8883
        scheme: mqtts
        clientId: !ref clientId
        keepalive: 60
        mutualAuthentication: true
        caCert: !ref caCert
        clientCert: !ref clientCert
        clientPrivateKey: !ref clientPrivateKey

  # Publishes shop floor data from the ISA-95 topic hierarchy to AWS IoT Core
  telemetryMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/telemetry'
            qos: 1
          publish:
            connection: !ref awsIotConnection
            topic: dt/$site/$area/$line/$cell/telemetry
            qos: 1

  # Receives cloud-to-device commands from AWS IoT Core
  commandEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref awsIotConnection
      subscribe:
        topic: !sub 'cmd/${clientId}/commands'
        qos: 1

  commandMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref commandEndpoint
          publish:
            topic: !sub '${topicRoot}/cloud/aws-iot/commands'