Sending SMS and E-Mail notifications

Many machine applications use SMS and email notifications to send status information and alarms. This documentation describes a cloud-based approach to sending text and email messages. With this approach, the communication channel is derived from the actual message type (text, email), and the decision whether an incoming message from the machine is to be treated as text or email (or both) is made in the cloud.

History

Classically, either a telephone dial-up (via a connected USB or serial modem) or an SMTP connection to a mail server directly from the machine control was used to send SMS or email messages. Although this may have worked very well, the disadvantages of this approach are quickly apparent:

• Special modem hardware and a contract with a cellular provider are required, resulting in additional costs.
• Another communication channel to a mail server is needed.

On the TwinCAT side, the TwinCAT3 Function TF6350 TC3 SMS/SMTP supports the PLC programmer in sending SMS and email messages. To send text messages, the supplement product communicates with a GSM modem connected to the controller via an RS232 serial port. For email messages, the supplement product establishes an SMTP connection to a mail server on the network. After that, the mail server is responsible for message delivery.

Requirements

Please ensure that the following requirements are met before you continue with this documentation.

• Make sure that you have created an AWS account and that you can access the AWS management console using the account credentials.
• Install TwinCAT 3.1 Build 4022.0 or higher, so that the product TF6701 IoT Communication is available. We recommend updating to the latest TwinCAT version if possible.
• To understand how TwinCAT is linked to AWS IoT Core, please refer to the TF6701 documentation.

Other TwinCAT IoT products and protocols In this tutorial we will use TF6701 IoT Communication to connect to AWS IoT Core via MQTT. Please note that other products from the TwinCAT IoT product range can also connect to AWS IoT Core and that the same principles apply for these products. Also note that MQTT is not the only transport channel that can be used to connect to AWS IoT Core. Another transport option is HTTPS, which can be implemented with the TwinCAT IoT product TF6760 IoT HTTPS/REST.

We particularly recommend the following articles about getting started with AWS. We will point out when it is important to read any of these articles before proceeding to the next step.

AWS IoT Core: https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html

Amazon SNS: https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html

Using Amazon SNS in an AWS IoT Core Rule: https://docs.aws.amazon.com/iot/latest/developerguide/config-and-test-rules.html

Architecture

Cloud systems provide the technical infrastructure that makes the Internet of Things (IoT) possible. They also provide the scalability needed to support millions of connected devices. Cloud service providers like Microsoft Azure and Amazon Web Services (AWS) offer hundreds of services to support different use cases: virtual machines, message brokers, databases, serverless functions, etc. Their product portfolio also includes various functions for processing messages from connected devices. A central message broker (sometimes referred to as an "IoT Hub") provides a single, secure endpoint for devices to communicate with other services in the Ecosystem. Using so-called "rules", the user can then filter messages and easily forward them to other services. Because the message broker is treated as the single endpoint for all data connectivity scenarios, the firewall attack surface is minimized.

The following diagram illustrates this concept. It is based on services offered by AWS as an example. Other cloud platforms such as Microsoft Azure offer similar services.

Focusing on our use case (text messages and emails), the relevant services are:

• AWS IoT Core (message broker) for a single, secure endpoint in the cloud
• Amazon SNS for sending text messages and emails

Compared to a traditional setup, a cloud-based solution has the following advantages:

1. The message type (email, text, ...) is transparent for the device that issues the message. The device simply sends the message, while the decision whether it is sent in the form of an email or text message is made in the cloud.
2. Address changes do not have to be forwarded to the device that issues a message. All relevant contact data (email addresses, phone numbers, ...) are managed in the cloud.
3. Secure transport between the device that issues a message and the cloud. Each message of the device is sent to AWS IoT Core over a secure communication channel, either MQTT or HTTPS.
4. The required internet connectivity is based on TCP/IP. No additional modem hardware is required for sending text messages.
5. No contract with a mobile phone provider is required. AWS manages the text message transmission. Charges are based on usage (pay-per-use).

TwinCAT IoT supports MQTT and HTTPS connectivity with AWS IoT Core. The following pages of the documentation provide a more detailed configuration description for the components involved in this use case.

Setup of AWS IoT Core

AWS IoT Core is a scalable and managed message broker service in the AWS Eco system. It enables you to securely connect devices and manage their data ingest. To use AWS IoT Core, you need:

• An AWS account for logging into the AWS web-based management console. All required AWS IoT Core features are automatically implemented when the account is created, so service provisioning is not necessary.
• Device credentials (certificates) and security policies for each connected device. The certificates must be transferred to the device and used by the device while connecting to the AWS IoT Core service. In other words, the certificates are always used by TwinCAT IoT when the connection is established. This is described in a later chapter.

The setup of AWS IoT Core includes the following topics:

1. Logging into the AWS IoT console
2. Creating an object
3. Registering a device
4. Configuring your machine
5. Viewing the MQTT messages issued by the device with the AWS IoT MQTT client
6. Configuring and testing rules (next chapter)

These steps are described in detail in the tutorial Getting Started with AWS IoT Core. This tutorial is a good source of information and describes the above steps in detail. We recommend that you read this tutorial and work through the step-by-step instructions before proceeding to the next chapter in this documentation.

Step 6 of the tutorial describes exactly the use case we are trying to solve: Configuring an AWS IoT Core rule that uses Amazon SNS to send an email or text message.

Setup of Amazon SNS

Amazon SNS allows you to send push notifications to mobile apps, text messages to mobile numbers, and plain text emails to email addresses. Step 6 ("Configuring and testing rules") of the official "Getting started with AWS IoT Core" guide describes in detail how Amazon SNS must be prepared for an AWS IoT rule to forward a device message to an SNS topic. If you want to learn more about Amazon SNS, we recommend the tutorial Getting started with Amazon SNS.

In this official graphic, AWS IoT Core acts as an intermediate station between the publisher of a message (the "device") and Amazon SNS.

Simply follow the steps described in the official "Getting started guide" to

• create an Amazon SNS topic and a subscription (use email as "protocol")
• create an AWS IoT Core rule
• test the rule

Please note the following: when using "email" as protocol, a one-off message will be sent to the email address entered by the user to confirm the subscription. This email must be acknowledged before messages can be sent to this email address. This procedure is similar to that for e-newsletters.

Note on service limits: note that for regular AWS accounts there may be a limit for text messages. This limit can be increased by calling AWS support. For more information, visit the Amazon SNS service limit web page.

Once the Amazon SNS Topic/Subscription and the AWS IoT rule have been created, the setup can be tested using the MQTT client integrated into the AWS management console. To do this, simply send a test message to topic "my/topic" topic specified as a filter in the AWS IoT rule and use the following JSON content:

{
  "default": "Hello, from AWS IoT console",
  "email": "Hello, from AWS IoT console"
}

All available properties are documented in the Amazon SNS documentation.

The notification email should arrive at the email address used for the Amazon SNS subscription after a few seconds.

In the next step we want to enable TwinCAT to send messages to AWS IoT Core.

Setup of TwinCAT

The TwinCAT IoT Supplement products facilitate cloud connectivity for different use cases. One of their main advantages is that they use standard communication protocols to provide connectivity to cloud systems from different vendors, such as Microsoft Azure, Amazon Web Services, IBM, Google, etc.

In this documentation, we use TF6701 IoT Communication to connect to AWS IoT Core and publish a message for the topic "my/topic" that has been set as a filter in the AWS IoT rule to forward the messages that arrive at Amazon SNS for that particular topic, in order to send a notification email.

Requirements

This chapter is based on the regular TF6701 sample IotMqttSampleAwsIoT, which illustrates the general procedure for connecting to AWS IoT Core. Download this sample to establish a common starting point. For more detailed information about how the sample code works, please refer to the corresponding Infosys website for this particular sample.

Important Before you continue please ensure you have completed all the steps described in chapter Setup of AWS IoT Core.

Establishment of a connection

All certificates created with the AWS Management Console must be referenced in the FB_IotMqttClient.stTLS data structure (sCA, sCert and sKeyFile). Use the URL of the AWS IoT Core instance as the sHostName, as shown on the AWS Management Console. Since the connection is a secure MQTT connection, use 8883 as nHostPort. The MQTT client ID (sClientId) is the object name (ThingName) that was used when the object was created according to the chapter Setup of AWS IoT Core.

(* TLS settings for AWS IoT connection *)
fbMqttClient.stTLS.sCA := 'c:\certs\AmazonRootCA1.pem';
fbMqttClient.stTLS.sCert := 'c:\certs\6a1ba937cb-certificate.pem.crt';
fbMqttClient.stTLS.sKeyFile := 'c:\certs\6a1ba937cb-private.pem.key';

(* Broker settings für AWS IoT *)
fbMqttClient.sHostName:= 'aXX-ats.iot.eu-central-1.amazonaws.com';
fbMqttClient.nHostPort:= 8883;
fbMqttClient.sClientId:= 'ThingName';

Defining appropriate topics

The standard sample illustrates how to connect to AWS IoT Core for exchange data with this message broker. It publishes messages for a topic and subscribes to a topic to receive messages. In the sample both topics are identical, so that TwinCAT receives the same message that it sent to the broker.

In addition to this regular sample behavior, we will now write new code to make the sample send a message for the topic "my/topic" so that an email is sent. For this purpose we first declare some new variables:

sTopicEmail : STRING(255) := 'my/topic';
bSendEmail : BOOL;
sPayloadEmail : STRING(255) := '{"default": "Hello from TwinCAT","message": "Hello from TwinCAT"}';

Then we will add the following lines of code after the IF query for the timer execution:

IF fbTimer.Q THEN
  ...
END_IF
IF bSendEmail THEN
  bSendEmail := FALSE;
  fbMqttClient.Publish(sTopic:= sTopicEmail, pPayload:= ADR(sPayloadEmail), nPayloadSize:= LEN2(ADR(sPayloadEmail)), eQoS:= TcIotMqttQos.AtMostOnceDelivery, bRetain:= FALSE, bQueue:= FALSE);
END_IF

After activating the project, first validate whether the connection with AWS IoT Core was successful by checking the parameter eConnectionState (must be and remain "MQTT_ERR_SUCCESS"). If the connection status appears to fluctuate or if an TLS error is reported (e.g. "MQTT_ERR_TLS_VERIFICATIONFAILED"), double-check the steps described in chapter "Setup of AWS IoT Core" and make sure that the device certificate has been activated and the security policy allows the device to publish data for the topics used.

If the connection is successful, try setting bSendEmail to TRUE. After a few seconds, an email should appear in the inbox of the email address that was used for the Amazon SNS subscription.