Export to AWS IoT Core

Overview

The following example describes how to configure an application service to publish Edge Xpert events to the AWS IoT Core over MQTT by using proprietary built-in function XpertMQTTExport. For further information on AWS IoT Core, refer to the AWS IoT Core.

Note

In Edge Xpert V2, AWSIoTCoreMQTTSend function is replaced by XpertMQTTExport function.

When designing your AWS IoT application, please note the following limitations of the AWS IoT message broker.

Sample Configuration

The following code defines the pipeline function:

[Writable.Pipeline.Functions.XpertMQTTExport]
  [Writable.Pipeline.Functions.XpertMQTTExport.Parameters]
    ExportMode = "AWSIoTCore"
    BrokerAddress = "tls://{identifier}.iot.{region}.amazonaws.com:8883"
    # For further information on AWS Device Shadaow MQTT topics, refer to https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#get-pub-sub-topic.
    Topic = "$aws/things/{ThingName}/shadow/update"
    ClientID = "{ThingName}"
    SecretPath = "aws"
    Qos = "0"
    AutoReconnect = "true"
    SkipVerify = "false"
    PersistOnError = "false"

The following table describes the configuration parameters used to define the pipeline function:

Configuration	Mandatory	Description
BrokerAddress	Yes	Specifies the MQTT broker address on the AWS IoT Core. At the time of publication,AWS allowed users to access the AWS IoT Core using the MQTT protocol by using a broker address in the following format, where is the endpoint that allows you to connect to AWS IoT Core: tls://{AWSCustomEndpoint}:8883 For further information on port mappings,refer to the [AWS IoT Developer Guide].
Topic	Yes	Specifies the MQTT topic on the AWS IoT MQTT broker to which to publish the message to. Note: Topics that begin with a dollar sign ($) are reserved for use by AWS IoT. You can publish to these reserved topics as they allow; however, you can't create new topics that begin with a dollar sign. Unsupported publish operations to reserved topics can result in a terminated connection. For further information on the reserved topics, refer to [AWS IoT Developer Guide].
ClientID	Yes	Specifies an MQTT client ID.
SecretPath		The path in the secret provider from which to retrieve the certificate and private key of your AWS IoT Thing.
Qos		Specifies the Quality of Service (QoS) levels for theAWS IoT Core MQTT connection. The AWS IoT Core MQTT broker accepts only QoS 0 and 1. For further information on the MQTT QoS,refer to the MQTT specification.
AutoReconnect		Specifies whether the connection is to be automatically reconnected if it is lost.
SkipVerify		Specifies whether the Edge Xpert Application Service verifies the server's certificate chain and host name. If set to true, TLS accepts any certificate presented by the server and any host name in that certificated. This means that TLS is susceptible to man-in-themiddle attacks. Use this setting for testing purposes only.
PersistOnError		Specifies whether the events are stored for further attempts if any error is encountered during the message publication. Note: To use persistOnError, Store and Forward must be enabled in the Application Service configuration file. For further information on Store and Forward, refer to the Advanced Topics under the Application Functions SDK section of the EdgeX Foundry documentation. Set to true to enable Set to false to disable

Example

This example shows how the Application Service can be configured to use the AWSIoTCoreMQTTSend function. This function exports data to the AWS IoT Core.

Before starting this example, you must have the following:

Note

Make a note of the Thing Name, Certificate and Private Key. This information is needed when authenticating with the AWS IoT Core.

Note

You can also create application services with EdgeXpert Manager, which is the graphical user interface (GUI) of EdgeXpert. Refer to Edge Xpert Manager UI - App Services for the details.

To configure an Application Service to export events to the AWS IoT Core, complete the following steps:

Find the AWS Custom Endpoint in the Settings page of the AWS IoT Core console.
Copy the /usr/share/edgexpert/examples/app-configurable/awsiotcore-mqtt-export/configuration-insecure.toml sample configuration file to your local config directory.
Open the copied configuration-insecure.toml file in an editor and update the details for the AWS Custom Endpoint, which you located in step 1, and the Thing Name.
Configure certificate and private key
- To launch the application service under insecure mode, copy and paste your certificate and private key to Writable.InsecureSecrets.aws.Secrets configuration as shown below:
```
[Writable.InsecureSecrets.aws]
path = "aws"
  [Writable.InsecureSecrets.aws.Secrets]
    # When using XpertMQTTExport and ExportMode="AWSIoTCore", clientcert and clientkey are mandatory secrets.
    clientcert = '''
{X509_PEM_certificate}
'''
    clientkey = '''
 {X509_PEM_private_key}
'''
```
- To launch the application service under secure mode, please refer to EdgeX FoundryStoring Secrets for details about getting app service client token and adding authentication token value into secret store.
Specify the execution order of the pipeline function, as shown in the following example:
```
[Writable.Pipeline]
 ExecutionOrder = "XpertMQTTExport"
```

Start the Application Service, and the Virtual Device Service to simulate device data to send to the AWS IoT Core, as follows:

# Under secure mode
edgexpert up --secret device-virtual app-service --path=<path of your confgiuration file>

# Under insecure mode
edgexpert up device-virtual app-service --path=<path of your confgiuration file>

Monitor the events on the AWS IoT Core Console. To display the dashboard, select Test and then subscribe to the topic to which the function XpertMQTTExport publishes to. The console is similar to the following:

AWS IoT Core, MQTT test client