AWS IoT Core bridge tutorials

Connect FairCom Edge to AWS IoT Core bridge

The purpose of this tutorial is to demonstrate and describe how to use FairCom APIs and services to forward (bridge) messages from the FairCom broker to an AWS IoT Core broker.

Requirements:
 
  1. Ensure the FairCom server is installed and running.
  2. Confirm server access by running the FairCom API Explorer. The typical URL is https://localhost:8443/ .

 

Access the AWS IoT Core console

Establish access to the AWS IoT Core console:
 
  1. Create an AWS account.
  2. Log into your AWS account.
  3. Navigate to the IoT core management center.
  4. Create required AWS service endpoints.
  5. Create AWS IoT client certificates.
  6. Make sure to attach a policy with the required permissions to the certificate from the previous step.

 

Access an AWS IoT Core MQTT client

 
  1. Navigate to the AWS IoT Core MQTT test client in the AWS core console as seen above.
  2. Observe that your location is set to the correct region referred to in AWS Endpoint in the console header.
  3. Use this console to see forwarded messages from the FairCom broker, published messages, the topics you are subscribed to, and more.

Learn more about features of the MQTT test client at View MQTT messages with the AWS IoT Core MQTT client below.

 

Configure a broker connection

Configure the FairCom MQ broker to forward to newly started MQTT broker from the AWS IoT Core instance:

In this procedure, the FairCom Control Center is used to configure a broker connection.

  1. Navigate to the Code tab.
  2. Select API Console from the Code menu.
  3. Paste this code into the API Console and click the Run button:
    1. {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "action": "configureBrokerConnection",
        "params": {
          "brokerConnectionName": "AWS_Broker",
          "brokerHostname": "a3cuvixbm02nv9-ats.iot.us-east-2.amazonaws.com",
          "tls": {
            "certificateFilename": "C:/certificates/aws/c5e615c86ae33b44a60c56cad557be7ad6c754952836906f9132d410e271d716-certificate.pem.crt",
            "privateKeyFilename": "C:/certificates/aws/c5e615c86ae33b44a60c56cad557be7ad6c754952836906f9132d410e271d716-private.pem.key",
            "certificateAuthoritiesFilename": "C:/certificates/aws/AmazonRootCA1.pem"
          },
          "brokerPort": 8883
        }
      }
      
    2. Replace the "brokerHostname" property value with the applicable values in the following format from the AWS instance endpoint.
    3. "brokerHostname": "<uniqueID>-<location>.amazonaws.com",
    4. Download the certificate from the AWS instance and set the "tls" configuration accordingly.
  4. Observe the response and ensure the action completed successfully. An "errorCode" with a value of 0 indicates success. An "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.
    1. {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "result": {},
        "requestId": "00000015",
        "debugInfo": {
          "request": {
            "authToken": "replaceWithAuthTokenFromCreateSession",
            "api": "mq",
            "action": "configureBrokerConnection",
            "params": {
          "brokerConnectionName": "AWS_Broker",
          "brokerHostname": "a3cuvixbm02nv9-ats.iot.us-east-2.amazonaws.com",
          "tls": {
            "certificateFilename": "C:/certificates/aws/c5e615c86ae33b44a60c56cad557be7ad6c754952836906f9132d410e271d716-certificate.pem.crt",
            "privateKeyFilename": "C:/certificates/aws/c5e615c86ae33b44a60c56cad557be7ad6c754952836906f9132d410e271d716-private.pem.key",
            "certificateAuthoritiesFilename": "C:/certificates/aws/AmazonRootCA1.pem"
            },
            "apiVersion": "1.0",
            "requestId": "00000016",
            "debug": "max"
          },
          "executionMicroseconds": 1951,
          "totalMicroseconds": 5263
        },
        "errorCode": 0,
        "errorMessage": ""
      }
      
  5. Run the minimal example of the "listBrokerConnections" action from the JSON Actions dropdown menu.
  6. Observe the list of broker connections in the response to verify that "AWS_Broker" was created.
    1. {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "result": {
          "brokerConnectionNames": [
            "AWS_Broker"
          ]
        },
        "requestId": "00000018",
        "errorCode": 0,
        "errorMessage": ""
      }
      

 

Forward to AWS IoT Core MQTT

This quick tutorial shows you how to configure FairCom's MQTT broker to forward messages to a AWS IoT Core MQTT broker.

Configure topic "acmefactory/line1/station1/acidbath/telemetry" to be forwarded to the AWS external broker:

  1. Navigate to the Code tab.
  2. Select API Console from the Code menu.
  3. Paste this code into the API Console and click the Run button:
    1. The "params.topic" value is the MQTT topic that receives inbound messages.
    2. The "params.forwardToExternalBroker.[].topic" value is the topic on the target broker that will receive the MQTT topic messages.
    3. {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "action": "configureTopic",
        "params": {
          "topic": "acmefactory/line1/station1/acidbath/telemetry",
          "forwardToExternalBrokers": [
            {
              "brokerConnectionName": "AWS_Broker",
              "topic": "acmefactory/line1/station1/acidbath/telemetry"
            }
          ]
        },
        "debug": "max"
      }
      
  4. Observe the response and ensure the action completed successfully.
    1. An "errorCode" with a value of 0 indicates success. An "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.
    2. {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "result": {},
        "requestId": "00000019",
        "debugInfo": {
          "request": {
            "authToken": "replaceWithAuthTokenFromCreateSession",
            "api": "mq",
            "action": "configureTopic",
            "params": {
              "topic": "acmefactory/line1/station1/acidbath/telemetry",
              "forwardToExternalBrokers": [
                {
                  "brokerConnectionName": "AWS_Broker",
                  "topic": "acmefactory/line1/station1/acidbath/telemetry"
                }
              ]
            },
            "apiVersion": "1.0",
            "requestId": "00000019",
            "debug": "max"
          },
          "executionMicroseconds": 263214,
          "totalMicroseconds": 263414
        },
        "errorCode": 0,
        "errorMessage": ""
      }
      
      
      
      
      
      
      
      

 

Publish a message to the FairCom MQ broker

Publish a message to the FairCom MQ broker, to verify that the message is forwarded to the AWS IoT Core instance, and then received by the subscriber:

  1. In the FairCom Control Center, go to the MQ tab.
  2. Click on the Publish button.
  3. Select "acmefactory/line1/station1/acidbath/telemetry" from the Topic.
  4. Enter a message like {"temp":25}.
  5. Click on the Publish button.

 

View messages on the AWS MQTT test client

Subscribe to a topic in the test client to see messages published from the FairCom broker to the AWS MQTT test client.

Subscribing to # in the test client, will result in you seeing messages from every topic.

  1. Subscribe to all topics.
    1. In the Topic Filter textbox type #.
    2. Click Subscribe ().
    3. Observe # listed under Subscriptions.
  2. Observe that the message is from the acmefactory/line1/station1/acidbath/telemetry topic which was specified during the Configure a broker connection step above.
  3. Observe test message here in the message body from the data.json file that was edited in Create a client and publish to the FairCom broker step above.