Set up and troubleshoot AWS IoT Greengrass with client devices - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsBest practicesEpicsTroubleshootingRelated resourcesAdditional information

Set up and troubleshoot AWS IoT Greengrass with client devices

Created by Marouane Sefiani and Akalanka De Silva (AWS)

Environment: PoC or pilot

Technologies: IoT

AWS services: AWS IoT Greengrass; AWS IoT Core

Summary

AWS IoT Greengrass is an open-source edge runtime and cloud service for building, deploying, and managing Internet of Things (IoT) software on edge devices. Use cases for AWS IoT Greengrass include:

  • Smart homes where an AWS IoT Greengrass gateway is used as a hub for home automation

  • Smart factories where AWS IoT Greengrass can facilitate ingestion and local processing of data from the shop floor

AWS IoT Greengrass can act as a secure, authenticated, MQTT connection endpoint for other edge devices (also known as client devices), which otherwise would typically connect directly to AWS IoT Core. This capability is useful when client devices do not have direct network access to the AWS IoT Core endpoint.

You can set up AWS IoT Greengrass for use with client devices for the following use cases:

  • For client devices to send data to AWS IoT Greengrass

  • For AWS IoT Greengrass to forward data to AWS IoT Core

  • To take advantage of advanced AWS IoT Core rules engine features

These capabilities require installing and configuring the following components on the AWS IoT Greengrass device:

  • MQTT broker

  • MQTT bridge

  • Client device authentication

  • IP detector

In addition, published messages from client devices must be in JSON format or Protocol Buffers (protobuf) format.

This pattern describes how to install and configure these required components, and provides troubleshooting tips and best practices.

Prerequisites and limitations

Prerequisites

Limitations

  • You must choose an AWS Region where AWS IoT Core is available. For the current list of Regions for AWS IoT Core, see AWS Services by Region.

  • The core device must have at least 172 MB RAM and 512 MB of disk space.

Architecture

The following diagram shows the solution architecture for this pattern.

Solution architecture for setting up AWS IoT Greengrass with client devices

The architecture includes:

  • Two client devices. Each device contains a private key, a device certificate, and a root certificate authority (CA) certificate. The AWS IoT Device SDK, which contains an MQTT client, is also installed on each client device.

  • A core device that has AWS IoT Greengrass deployed with the following components:

    • MQTT broker

    • MQTT bridge

    • Client device authentication

    • IP detector

This architecture supports the following scenarios:

  • Client devices can use their MQTT client to communicate with one another through the core device’s MQTT broker.

  • Client devices can also communicate with AWS IoT Core in the cloud through the core device’s MQTT broker and the MQTT bridge.

  • AWS IoT Core in the cloud can send messages to client devices through the MQTT test client and the core device’s MQTT bridge and MQTT broker.

For more information about the communications between client devices and the core device, see the Additional information section.

Tools

AWS services

  • AWS IoT Greengrass is an open source Internet of Things (IoT) edge runtime and cloud service that helps you build, deploy, and manage IoT applications on your devices.

  • AWS IoT Core provides secure, bidirectional communication for internet-connected devices to connect to the AWS Cloud.

  • AWS IoT Device SDK is a software development kit that includes open-source libraries, developer guides with samples, and porting guides so that you can build innovative IoT products or solutions on your choice of hardware platforms.

  • AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.

Best practices

  • The payload of the messages from client devices should be in either JSON or Protobuf format in order to take advantage of the advanced features of the AWS IoT Core rules engine, such as transformation and conditional actions.

  • Configure the MQTT bridge to allow bidirectional communication.

  • Configure and deploy the IP detector component in AWS IoT Greengrass to ensure that the core device’s IP addresses are included in the subject alternative name (SAN) field of the MQTT broker certificate.

Epics

TaskDescriptionSkills required

Set up AWS IoT Greengrass on your core device.

Install the AWS IoT Greengrass Core software by following the instructions in the developer guide.

AWS IoT Greengrass

Check the status of your installation.

Use the following command to check the status of the AWS IoT Greengrass service on your core device:

sudo systemctl status greengrass.service

The expected output of the command is:

Launched Nucleus successfully
General AWS

Set up an IAM policy and attach it to the Greengrass service role.

  1. Create an IAM policy to allow communications to and from the MQTT bridge. Here’s an example policy:

    {
    "Version": "2012-10-17",
    "Statement": [

        {
            "Effect": "Allow",
            "Action": [
                "iot:*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "GreengrassActions",
            "Effect": "Allow",
            "Action": [
                "greengrass:*"
            ],
            "Resource": "*"
        }
    ]
}

  2. Attach the policy to the Greengrass service role. To get the service role, use the command:

    aws greengrassv2 get-service-role-for-account --region <region>

    where <region> refers to your AWS Region.

General AWS

Configure and deploy required components in the AWS IoT Greengrass core device.

Configure and deploy the following components:

AWS IoT Greengrass

Confirm that the MQTT bridge allows bidirectional communication.

To relay MQTT messages between client devices and AWS IoT Core, configure and deploy the MQTT bridge component and specify the topics to relay. Here’s an example:

{
  "mqttTopicMapping": {
    "ClientDevicesToCloud": {
      "topic": "dt/#",
      "source": "LocalMqtt",
      "target": "IotCore"
    },
    "CloudToClientDevices": {
      "topic": "cmd/#",
      "source": "IotCore",
      "target": "LocalMqtt"
    }
  }
}
AWS IoT Greengrass

Confirm that the auth component allows client devices to connect and publish or subscribe to topics.

The following aws.greengrass.clientdevices.Auth configuration allows all client devices to connect, publish messages, and subscribe to all topics.

{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
AWS IoT Greengrass
TaskDescriptionSkills required

Install the AWS IoT Device SDK.

Install the AWS IoT Device SDK on client devices. For a full list of supported languages and the associated SDKs, see the AWS IoT Core documentation.

For example, the AWS IoT Device SDK for Python SDK is located on GitHub. To install this SDK:

  1. Confirm that Python 3.7 or later is installed, as instructed on the Prerequisites page of the GitHub repository.

  2. Use the pip command to install the SDK.

    For MacOS and Linux::

    python3 -m pip install awsiotsdk

    For Windows:

    python -m pip install awsiotsdk

Alternatively, you can install the SDK from the source repository:

# Create a workspace directory to hold all the SDK files
mkdir sdk-workspace
cd sdk-workspace
# Clone the repository
git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git
# Install using Pip (use 'python' instead of 'python3' on Windows)
python3 -m pip install ./aws-iot-device-sdk-python-v2
General AWS IoT

Create a thing.

  1. In the AWS IoT console, if a Get started button appears, choose it. Otherwise, in the navigation pane, choose Security, Policies.

  2. If the You don't have any policies yet dialog box appears, choose Create a policy. Otherwise, choose Create.

  3. Enter a name for the AWS IoT policy (for example, ClientDevicePolicy).

  4. In the Add statements section, replace the existing policy with the following JSON code. Replace <region> and <account> with your AWS Region and AWS account number.

    {
   "Version": "2012-10-17",
   "Statement": [{
         "Effect": "Allow",
         "Action": "iot:Connect",
         "Resource": "arn:aws:iot:region:account:client/*"
      },
      {
         "Effect": "Allow",
         "Action": "iot:Publish",
         "Resource": "*"
      },
      {
         "Effect": "Allow",
         "Action": "iot:Receive",
         "Resource": "*"
      },
      {
         "Effect": "Allow",
         "Action": "iot:Subscribe",
         "Resource": "*"
      },
      {
         "Effect": "Allow",
         "Action": [
            "iot:GetThingShadow",
            "iot:UpdateThingShadow",
            "iot:DeleteThingShadow"
         ],
         "Resource": "arn:aws:iot:region:account:thing/*"

      }
   ]
}

  5. Choose Create.

  6. On the AWS IoT console, in the navigation pane, choose Manage, Things.

  7. If the You don't have any things yet dialog box is displayed, choose Register a thing. Otherwise, choose Create.

  8. On the Creating AWS IoT things page, choose Create a single thing.

  9. On the Add your device to the device registry page, enter a name for your IoT thing (for example, ClientDevice1), and then choose Next.

    Note: You can't change the name of a thing after you create it. To change the name, you must create a new thing, give it the new name, and then delete the old thing.

  10. On the Add a certificate for your thing page, choose Create certificate.

  11. Choose the Download links to download the certificate, private key, and root CA certificate.

    Important: This is your only opportunity to download your certificate and private key.

  12. To activate the certificate, choose Activate. The certificate must be active for a device to connect to AWS IoT.

  13. Choose Attach a policy.

  14. For Add a policy for your thing, choose ClientDevicePolicy, Register Thing.

AWS IoT Core

Download the CA certificate from the Greengrass core device.

If you expect the Greengrass core device to work in offline environments, you have to make the Greengrass core CA certificate available to the client device so it can verify the MQTT broker’s certificate (which is issued by the Greengrass core CA). Therefore, it is important to obtain a copy of this certificate. Use one of the following approaches to download the CA certificate:

  • If you have network access to the AWS IoT Greengrass device from your PC, enter https://<device IP>:8883 in your web browser and view the MQTT broker certificate and the CA certificate. You can also save the CA certificate to the client device.

  • Alternatively, you can use the OpenSSL command line:

    openssl s_client -showcerts -connect <device IP>:8883
General AWS

Copy credentials in the client devices.

Copy the Greengrass core CA certificate, the device certificate, and the private key in the client devices.

General AWS

Associate client devices with the core device.

Associate client devices with a core device so that they can discover the core device. The client devices can then use the Greengrass discovery API to retrieve connectivity information and certificates for their associated core devices. For more information, see Associate client devices in the AWS IoT Greengrass documentation.

  1. On the AWS IoT Greengrass console, choose Core devices.

  2. Choose the core device to manage.

  3. On the core device's details page, choose the Client devices tab.

  4. In the Associated client devices section, choose Associate client devices.

  5. In the Associate client devices with core device modal, do the following for each client device to associate:

    1. Enter the name of the AWS IoT thing to associate as a client device.

    2. Choose Add.

  6. Choose Associate.

The client devices that you associated can now use the Greengrass discovery API to discover this core device.

AWS IoT Greengrass
TaskDescriptionSkills required

Send data from one client device to another client device.

Use the MQTT client in your device to publish a message on the dt/client1/sensor topic.

General AWS

Send data from the client device to AWS IoT Core.

Use the MQTT client in your device to publish a message on the dt/client1/sensor topic.

In the MQTT test client, subscribe to the topic that the device is sending messages on, or subscribe to # for all topics (see details).

General AWS

Send messages from AWS IoT Core to client devices.

On the MQTT test client page, in the Publish to a topic tab, in the Topic name field, enter the topic name of your message. In this example, use cmd/client1 for the topic.

General AWS

Troubleshooting

IssueSolution

Unable to verify server certificate error

This error occurs when the MQTT client cannot verify the certificate that’s presented by the MQTT broker during the TLS handshake. The most common reason is that the MQTT client doesn’t have the CA certificate. Follow these steps to make sure that the CA certificate is provided to the MQTT client.

  1. If you have network access to the AWS IoT Greengrass device from your PC, enter https://<device IP>:8883 in a browser window to view the MQTT broker certificate and the CA certificate. You can also save the CA certificate to the client device.

    Alternatively use the OpenSSL command line:

    openssl s_client -showcerts -connect <device IP>:8883

  2. Save the contents of the Moquette CA and Greengrass Core CA certificates into files, and then view the decoded contents by using the command:

    openssl x509 -in <Name of CA>.pem -text

    The Moquette CA certificate should show the SAN field as in this example:

     X509v3 Subject Alternative Name:  IP Address:XXX.XXX.XXX.XXX, IP Address:127.0.0.1, DNS:localhost

Unable to verify server name error

This errors occurs when the MQTT client can’t verify that it’s connecting to the correct server. The most common reason is that the IP address of the Greengrass device isn’t listed in the SAN field of the certificate.

Follow the instructions in the previous solution to obtain the MQTT broker certificate and verify that the SAN field contains the IP address of the AWS IoT Greengrass device, as explained in the Additional information section. If not, confirm that the IP detector component is installed correctly and restart the core device.

Unable to verify server name only when connecting from an embedded client device

Mbed TLS, which is a popular TLS library used in embedded devices, currently supports DNS name verification only in the SAN field of the certificate, as shown in the Mbed TLS library code. Because the core device doesn’t have its own domain name and depends on the IP address, TLS clients that use Mbed TLS will fail the server name verification during the TLS handshake, causing a connection failure. We recommend that you add the SAN IP address verification to your Mbed TLS library at the x509_crt_check_san function.

Related resources

Additional information

This section provides additional information about the communications between the client devices and the core device.

The MQTT broker listens on port 8883 in the core device for a TLS client connection attempt. The following illustration shows an example MQTT broker’s server certificate.

Example of MQTT broker server certificate

The example certificate displays the following details:

  • The certificate is issued by the AWS IoT Greengrass Core CA, which is local and specific to the core device; that is, it acts as a local CA.

  • This certificate is automatically rotated every week by the client auth component as shown in the following illustration. You can set this interval in the client auth component configuration.

Rotating the MQTT broker's server certificate

  • The subject alternative name (SAN) plays a critical role in the server name verification on the TLS client end. It helps the TLS client ensure that it connects to the correct server and helps avoid man-in-the-middle attacks during TLS session setup. In the example certificate, the SAN field indicates that this server is listening on localhost (the local Unix domain socket), and the network interface has the IP address 192.168.1.12.

The TLS client uses the SAN field in the certificate to verify that it’s connecting to a legitimate server during server verification. In contrast, during a typical TLS handshake between an HTTP server and a browser, the domain name in the common name (CN) field or SAN field is used to cross-check the domain that the browser is actually connecting to during the server verification process. If the core device doesn’t have a domain name, the IP address included in the SAN field serves the same purpose. For more information, see the Subject Alternative Name section of RFC 5280 – Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

Th IP detector component in AWS IoT Greengrass ensures that the correct IP addresses are included in the SAN field of the certificate.

The certificate in the example is signed by the AWS IoT Greengrass device acting as a local CA. The TLS client (MQTT client) isn’t aware of this CA, so we must provide a CA certificate that looks like the following.

Example CA certificate