Sajith Abeywardhana

Connecting AWS IoT via the WSO2 ESB MQTT inbound endpoint, publishing events to the WSO2 DAS and analytics using WSO2 Siddhi — Part 1

In this technical guide we discuss how a typical IoT application scenario can be designed using AWS IoT, WSO2 ESB 5.0.0 and WSO2 DAS-3.1.0.

Aws-logo-white
Introduction

Today, a typical Internet of Things (IoT) related application will execute along the following steps of process:

  1. Connected devices publish their statuses to an IoT platform (e.g AWS IoT)
  2. device statuses are analysed via real-time analytical platforms according to predefined rules
  3. anomalies are published as notifications to connected systems and other users via channels such as email, SMS and push events.

 

In this technical guide I shall attempt to discuss how a typical IoT application scenario can be designed using AWS IoT, WSO2 ESB 5.0.0 and WSO2 DAS-3.1.0.

With relation to AWS IoT, we discuss how to:

  • configure an AWS IoT registry – by creating a ‘thing’
  • apply security to the ‘thing’ using ‘certificates’ and ‘policies’ to achieve authentication and authorisation
  • how to interact with the AWS IoT message broker via the ‘topic’

 

With relation to ‘WSO2 ESB’, we discuss how to:

  • implement MQTT inbound endpoint over the TLSv1.2
  • configure the event sink to the WSO2 DAS

 

With relation to the WSO2 DAS, we discuss how to

  • configure the WSO2 Event Receiver
  • use the Event Stream  and Event Store to capture and store device events
  • implement WSO2 Siddhi query to execute real-time analytics
  • publish notifications and events using the Email Publisher.

 

Please note that due to the lengthiness of the topic, I will be discussing the above mentioned topics in two separate parts.

This post – as a first one – contains the AWS IoT configuration, WSO2 ESB configurations, and implementation up to the MQTT message retrieval to the ESB from the IoT topic via the MQTT inbound endpoint.

The second story will contain the WSO2 ESB’s device event sink configuration and the WSO2 DAS side implementations.

 

High Level Architecture Diagram
High level architecture diagram

(Figure 1 – High level architecture diagram)

 

AWS IoT Configurations

Thing –  a ‘thing’ represents the actual hardware device. AWS IoT will provide the HTTPS endpoint to interact with the thing. In order to communicate with thing it is a necessary to have a secure connection using SSL certifications.

 

Configuring a thing in the AWS IoT
  • Log in to the AWS console and then navigate to the IoT Core dashboard. Now click on the Manage -> Things link
  • click on the create button to create a thing and follow the wizard
  • click on the “Create thing without certificate” button.

If done right, you should be able to view the newly created thing in the ‘things’ dashboard. Next steps are as follows:

  • Click on the particular thing and inspect the options which are associated with the thing
  • to interact with the thing there is an HTTPS endpoint under the interact link as illustrated in the below screenshot (see figure 2).
Configuring a thing’s HTTPS endpoint

(Figure 2 – Configuring a thing’s HTTPS endpoint)

 

Now we should facilitate the authentication and authorisation by associating the certificate and policy to the thing.

 

Security — Certificate and Policy

AWS IoT will not allow for any software component to publish or subscribe to MQTT messages to or from a topic without an SSL certification. In order to interact with the thing it is necessary to associate the certificate and policy to the thing.

Furthermore, the publisher or subscriber should also be configured with the certificate accordingly.

Certificates are used to authenticate requests and it is imperative to activate the certification before using it. Policies, on the other hand,  are used to check whether or not the requesting resources are authorised.

 

Creating an AWS sign certificate
  • click on the Secure -> Certificates link
  • click in the create button on the IoT Core dashboard
  • as we are using the AWS sign certificate, click on the “Create certificate” button
  • download the certificate, public key, private key and the root CA certificate by clicking each “Download” button in the new window
  • make sure to activate the certificate by clicking the “Activate” button.
Creating an AWS sign certificate

(Figure 3 – Creating an AWS sign certificate)

 

How to add a new Policy
  • Click on the Secure -> Policies link
  • click on the create button in the IoT Core dashboard
  • name the policy
  • add the below policy settings to it using the ‘advanced mode’ option.

(Please note that we are allowing all IoT permissions in this policy document but you may need to consider your security aspects accordingly.)

Creating a policy

(Figure 4 – Creating a policy)

Attaching a Thing and a Policy to a Certificate
  • Click on the Secure -> Certificates link to view the certificates list
  • click on the three dot mark on the relevant certificate
  • attach the thing and the policy to the given certificate.
Attaching a ‘thing’ and its ‘policy’ to the certificate

(Figure 5 – Attaching a ‘thing’ and ‘policy’ to the certificate)

 

Topics

Topics are not visible to the outside world. When you publish or subscribe to a topic you simply have to mention the relevant topic name.

Thus far we have covered configuring settings in the AWS IoT section. We have covered creating a thing, a certificate and a policy and then we attached the thing and policy to the certificate.


Implementations in the WSO2 ESB

In order to conduct implementation in the WSO2 ESB, you may have to download the WSO2 ESB-5.0.0 if it isn’t on your local machine.

Because AWS IoT will not allow – any software component without an SSL certification – to connect with a thing’s endpoint. It is mandatory to configure the SSL certification in the ESB. For the purpose of activating the inbound endpoint, the Java Key Store (JKS) requires configuring. This particular JKS should typically contain the SSL certification anlong with the private key which we downloaded earlier on.

 

Creating the new JKS using AWS IoT SSL certificate and the private key

Step 1. Create the PKCS 12 file using the private key and AWS signed certificate. OpenSSL command can be used for this purpose.

Note: p12 file password will be necessary when creating the JSK.

openssl pkcs12 -export -in iot-cert.crt -inkey private-key.pem.key -certfile iot-cert.crt -out testkeystore.p12

 

Step 2. Create the JKS using the keytool command.

Note: JKS password will be required when configuring the ESB MQTT inbound endpoint. Thus, make a note of the JKS password for your future reference.

keytool -importkeystore -srckeystore testkeystore.p12 -srcstoretype pkcs12 -destkeystore demo-aws-iot.jks -deststoretype JKS

 

Adding new JKS to the ESB and starting the ESB

Copy the newly created JKS file to the ESB’s security directory – which can be found as follows:  <ESB-HOME>/repository/resources/security/

cp cert/demo-aws-iot.jks wso2esb-5.0.0/repository/resources/security/

 

Starting the ESB

sh bin/wso2server.sh start

 

Implement a log-full Sequence to test the AWS IoT MQTT message
  • Log in to the ESB console using the default username and password
  • navigate to the Manage -> Service Bus -> Sequences
  • click on the “Add Sequence” button
  • switch to the source view in the “Design Sequence” page
  • paste the below code block to create a log-full sequence.

(note: this sequence will be used to print the MQTT message only. We need to implement a separate sequence to sink the device events to the DAS)

 

<?xml version=”1.0″ encoding=”UTF-8″?>

<sequence name=”LogFullMessageSequence” trace=”disable”

xmlns=”http://ws.apache.org/ns/synapse”>

<log level=”full”>

<property name=”[LogFullMessageSequence] Message” value=”LogFullMessageSequence” />

</log>

</sequence>

 

Configuring the MQTT Inbound Endpoint
  • To enable MQTT communication in the WSO2 ESB, we require a ‘paho client mqtt jar file’
  • download the jar file here and copy the jar file to the repository/components/lib/ directory.

Note: After you copied the jar file you will have to restart the EBS server.

  • Click on the Manage > Service Bus > Inbound Endpoints link
  • click on the “Add Inbound Endpoint”
  • provide  a name and select the type as MQTT in the next page
  • in the “New Inbound Endpoint” page you have to configure the MQTT connection properties as illustrated in the below screenshot
  • make sure to enter the thing HTTPS endpoint for the mqtt.server.host.name and the port as 8883.
Configuring the MQTT inbound endpoint basic properties

(Figure 6 – Configuring the MQTT inbound endpoint basic properties)

 

  • Under the advanced options menu tab, configure the SSL properties such as key-store and trust-store location
MQTT inbound endpoint advanced options

(Figure 7 – MQTT inbound endpoint advanced options)

 

For more details on the ESB MQTT inbound endpoint please refer the WSO2 ESB official documentation as follows: https://docs.wso2.com/display/ESB500/MQTT+Inbound+Protocol

 

Now, we are all set to receive MQTT messages which will publish to the demo-topic on the AWS IoT platform. Once the message is published to the topic the ESB’s carbon log will print the same message according to implementation.

 

Testing the MQTT Inbound Endpoint using IoT Test Service

To test the use case follow the below steps:

  • log in to the AWS IoT console
  • navigate to the IoT Core dashboard
  • click on the “Test” from the left-hand side menu
  • click on the “Publish to a topic” button
  • specify the topic name as demo-topic
  • use the below JSON sample message as a payload
  • click on the “Publish to topic” button.

 

{

“deviceId”:”d-1293″,

“eventTime”:”1522086271″,

“ambientTemperature”:50,

“lightValue”:150,

“soundValue”:254,

“motion”:1

}

(Code Snippet 1 –  JSON sample message as a payload)

 

(Figure 8 – Using AWS IoT Test service to publish a MQTT message)

 

If your configurations are perfect up to now, the ESB’s carbon log should print the MQTT message displayed in the below screenshot (see figure 9).

WSO2 ESB carbon log file output

(Figure 9 – WSO2 ESB carbon log file output)

Conclusion

In this article, we discussed how to create an AWS IoT thing with the association of necessary certificates and policies. We discussed how to interact with the thing using an HTPPS endpoint. We also discussed how to use the AWS IoT test service to test our scenario by publishing the JSON formatted MQTT message to the topic.

With relation to WSO2 ESB, we created a JKS using the AWS sign SSL certificate and using a private key, and then configured it to the ESB server. We implemented a test sequence which will be responsible for printing the MQTT message and then we configured the WSO2 ESB MQTT inbound endpoint to receive an MQTT message from the AWS IoT topic over the TLSv1.2.

Finally, we tested the scenario using the AWS IoT Test service.

As I mentioned in the introduction I will be discussing the rest of the topics using separate story soon.
Thank you for reading this Tech Guide. We hope you will also read our next tutorial so that we can help you solve some more interesting problems.

Sajith Abeywardhana - SSE

Sajith Abeywardhana

Senior Software Engineer | Mitra Innovation