End of support notice: On October 7th, 2026, AWS will discontinue support for AWS IoT Greengrass Version 1. After October 7th, 2026, you will no longer be able to access the AWS IoT Greengrass V1 resources. For more information, please visit [Migrate from AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html).
# Module 4: Interacting with client devices in an AWS IoT Greengrass group
This module shows you how local IoT devices, called *client devices* or *devices*, can connect to and communicate with an AWS IoT Greengrass core device. Client devices that connect to an AWS IoT Greengrass core are part of an AWS IoT Greengrass group and can participate in the AWS IoT Greengrass programming paradigm. In this module, one client device sends a Hello World message to another client device in the Greengrass group.
![\[AWS IoT connected to an AWS IoT Greengrass core, which is connected to client device #1 and client device #2.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-065.5.png)
Before you begin, run the [Greengrass device setup](quick-start.md) script or complete [Module 1](module1.md) and [Module 2](module2.md). This module creates two simulated client devices. You do not need other components or devices.
This module should take less than 30 minutes to complete.
**Topics**
+ [Create client devices in an AWS IoT Greengrass group](device-group.md)
+ [Configure subscriptions](config-subs.md)
+ [Install the AWS IoT Device SDK for Python](IoT-SDK.md)
+ [Test communications](test-comms.md)
# Create client devices in an AWS IoT Greengrass group
In this step, you add two client devices to your Greengrass group. This process includes registering the devices as AWS IoT things and configuring certificates and keys to allow them to connect to AWS IoT Greengrass.
1. In the AWS IoT console navigation pane, under **Manage**, expand **Greengrass devices**, and then choose **Groups (V1)**.
1. Choose the target group.
1. On the group configuration page, choose **Client devices**, and then choose **Associate**.
1. In the **Associate a client device with this group** modal, choose **Create new AWS IoT thing**.
The **Create things** page opens in a new tab.
1. On the **Create things** page, choose **Create single thing**, and then choose **Next**.
1. On the **Specify thing properties** page, register this client device as **HelloWorld\$1Publisher**, and then choose **Next**.
1. On the **Configure device certificate** page, choose **Next**.
1. On the **Attach policies to certificate** page, do one of the following:
+ Select an existing policy that grants permissions that client devices require, and then choose **Create thing**.
A modal opens where you can download the certificates and keys that the device uses to connect to the AWS Cloud and the core.
+ Create and attach a new policy that grants client device permissions. Do the following:
1. Choose **Create policy**.
The **Create policy** page opens in a new tab.
1. On the **Create policy** page, do the following:
1. For **Policy name**, enter a name that describes the policy, such as **GreengrassV1ClientDevicePolicy**.
1. On the **Policy statements** tab, under **Policy document**, choose **JSON**.
1. Enter the following policy document. This policy allows the client device to discover Greengrass cores and communicate on all MQTT topics. For information about how to restrict this policy's access, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Connect",
"iot:Receive"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"greengrass:*"
],
"Resource": [
"*"
]
}
]
}
```
------
1. Choose **Create** to create the policy.
1. Return to the browser tab with the **Attach policies to certificate** page open. Do the following:
1. In the **Policies** list, select the policy that you created, such as **GreengrassV1ClientDevicePolicy**.
If you don't see the policy, choose the refresh button.
1. Choose **Create thing**.
A modal opens where you can download the certificates and keys that the device uses to connect to the AWS Cloud and the core.
1. In the **Download certificates and keys** modal, download the device's certificates.
**Important**
Before you choose **Done**, download the security resources.
Do the following:
1. For **Device certificate**, choose **Download** to download the device certificate.
1. For **Public key file**, choose **Download** to download the public key for the certificate.
1. For **Private key file**, choose **Download** to download the private key file for the certificate.
1. Review [Server Authentication](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html) in the *AWS IoT Developer Guide* and choose the appropriate root CA certificate. We recommend that you use Amazon Trust Services (ATS) endpoints and ATS root CA certificates. Under **Root CA certificates**, choose **Download** for a root CA certificate.
1. Choose **Done**.
Make a note of the certificate ID that's common in the file names for the device certificate and keys. You need it later.
1. Return to the browser tab with the **Associate a client device with this group** modal open. Do the following:
1. For **AWS IoT thing name**, choose the **HelloWorld\$1Publisher** thing that you created.
If you don't see the thing, choose the refresh button.
1. Choose **Associate**.
1. Repeat steps 3 - 10 to add a second client device to the group.
Name this client device **HelloWorld\$1Subscriber**. Download the certificates and keys for this client device to your computer. Again, make a note of the certificate's ID that's common in the file names for the HelloWorld\$1Subscriber device.
You should now have two client devices in your Greengrass group:
+ HelloWorld\$1Publisher
+ HelloWorld\$1Subscriber
1. Create a folder on your computer for these client devices' security credentials. Copy the certificates and keys into this folder.
# Configure subscriptions
In this step, you enable the HelloWorld\$1Publisher client device to send MQTT messages to the HelloWorld\$1Subscriber client device.
1. On the group configuration page, choose the **Subscriptions** tab, and then choose **Add**.
1. On the **Create a subscription** page, do the following to configure the subscription:
1. For **Source type**, choose **Client device**, and then choose **HelloWorld\$1Publisher**.
1. Under **Target type**, choose **Client device**, and then choose **HelloWorld\$1Subscriber**.
1. For **Topic filter**, enter **hello/world/pubsub**.
**Note**
You can delete subscriptions from the previous modules. On the group's **Subscriptions** page, select the subscriptions to delete, and then choose **Delete**.
1. Choose **Create subscription**.
1. Make sure that automatic detection is enabled so the Greengrass core can publish a list of its IP addresses. Client devices use this information to discover the core. Do the following:
1. On the group configuration page, choose the **Lambda functions** tab.
1. Under **System Lambda functions**, choose **IP detector**, and then choose **Edit**.
1. In the **Edit IP detector settings**, choose **Automatically detect and override MQTT broker endpoints**, and then choose **Save**.
1. Make sure that the Greengrass daemon is running, as described in [Deploy cloud configurations to a core device](configs-core.md).
1. On the group configuration page, choose **Deploy**.
The deployment status is displayed below the group name on the page header. To see deployment details, choose the **Deployments** tab.
# Install the AWS IoT Device SDK for Python
Client devices can use the AWS IoT Device SDK for Python to communicate with AWS IoT and AWS IoT Greengrass core devices (using the Python programming language). For more information, including requirements, see the AWS IoT Device SDK for Python [ Readme](https://github.com/aws/aws-iot-device-sdk-python) on GitHub.
In this step, you install the SDK and get the `basicDiscovery.py` sample function used by the simulated client devices on your computer.
1. To install the SDK on your computer, with all required components, choose your operating system:
------
#### [ Windows ]
1. Open an [elevated command prompt](https://technet.microsoft.com/en-us/library/cc947813(v=ws.10).aspx) and run the following command:
```
python --version
```
If no version information is returned or if the version number is less than 2.7 for Python 2 or less than 3.3 for Python 3, follow the instructions in [Downloading Python](https://wiki.python.org/moin/BeginnersGuide/Download) to install Python 2.7\$1 or Python 3.3\$1. For more information, see [Using Python on Windows](https://docs.python.org/3.6/using/windows.html).
1. Download the [AWS IoT Device SDK for Python](https://github.com/aws/aws-iot-device-sdk-python) as a `zip` file and extract it to an appropriate location on your computer.
Make a note of the file path to the extracted `aws-iot-device-sdk-python-master` folder that contains the `setup.py` file. In the next step, this file path is indicated by *path-to-SDK-folder*.
1. From the elevated command prompt, run the following:
```
cd path-to-SDK-folder
python setup.py install
```
------
#### [ macOS ]
1. Open a Terminal window and run the following command:
```
python --version
```
If no version information is returned or if the version number is less than 2.7 for Python 2 or less than 3.3 for Python 3, follow the instructions in [Downloading Python](https://wiki.python.org/moin/BeginnersGuide/Download) to install Python 2.7\$1 or Python 3.3\$1. For more information, see [Using Python on a Macintosh](https://docs.python.org/3/using/mac.html).
1. In the Terminal window, run the following commands to determine the OpenSSL version:
```
python
>>>import ssl
>>>print ssl.OPENSSL_VERSION
```
Make a note of the OpenSSL version value.
**Note**
If you're running Python 3, use **print(ssl.OPENSSL\$1VERSION)**.
To close the Python shell, run the following command:
```
>>>exit()
```
If the OpenSSL version is 1.0.1 or later, skip to [step c](#step-c-install-python-sdk). Otherwise, follow these steps:
1. From the Terminal window, run the following command to determine if the computer is using Simple Python Version Management:
```
which pyenv
```
If a file path is returned, then choose the **Using `pyenv`** tab. If nothing is returned, choose the **Not using `pyenv`** tab.
------
#### [ Using pyenv ]
1. See [Python Releases for Mac OS X](https://www.python.org/downloads/mac-osx/) (or similar) to determine the latest stable Python version. In the following example, this value is indicated by *latest-Python-version*.
1. From the Terminal window, run the following commands:
```
pyenv install latest-Python-version
pyenv global latest-Python-version
```
For example, if the latest version for Python 2 is 2.7.14, then these commands are:
```
pyenv install 2.7.14
pyenv global 2.7.14
```
1. Close and then reopen the Terminal window and then run the following commands:
```
python
>>>import ssl
>>>print ssl.OPENSSL_VERSION
```
The OpenSSL version should be at least 1.0.1. If the version is less than 1.0.1, then the update failed. Check the Python version value used in the **pyenv install** and **pyenv global** commands and try again.
1. Run the following command to exit the Python shell:
```
exit()
```
------
#### [ Not using pyenv ]
1. From a Terminal window, run the following command to determine if [brew](https://brew.sh/) is installed:
```
which brew
```
If a file path is not returned, install `brew` as follows:
```
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
**Note**
Follow the installation prompts. The download for the Xcode command line tools can take some time.
1. Run the following commands:
```
brew update
brew install openssl
brew install python@2
```
The AWS IoT Device SDK for Python requires OpenSSL version 1.0.1 (or later) compiled with the Python executable. The **brew install python** command installs a `python2` executable that meets this requirement. The `python2` executable is installed in the `/usr/local/bin` directory, which should be part of the `PATH` environment variable. To confirm, run the following command:
```
python2 --version
```
If `python2` version information is provided, skip to the next step. Otherwise, permanently add the `/usr/local/bin` path to your `PATH` environment variable by appending the following line to your shell profile:
```
export PATH="/usr/local/bin:$PATH"
```
For example, if you're using `.bash_profile` or do not yet have a shell profile, run the following command from a Terminal window:
```
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
```
Next, [source](https://en.wikipedia.org/wiki/Source_(command)) your shell profile and confirm that `python2 --version` provides version information. For example, if you're using `.bash_profile`, run the following commands:
```
source ~/.bash_profile
python2 --version
```
`python2` version information should be returned.
1. Append the following line to your shell profile:
```
alias python="python2"
```
For example, if you're using `.bash_profile` or do not yet have a shell profile, run the following command:
```
echo 'alias python="python2"' >> ~/.bash_profile
```
1. Next, [source](https://en.wikipedia.org/wiki/Source_(command)) your shell profile. For example, if you're using `.bash_profile`, run the following command:
```
source ~/.bash_profile
```
Invoking the **python** command runs the Python executable that contains the required OpenSSL version (`python2`) .
1. Run the following commands:
```
python
import ssl
print ssl.OPENSSL_VERSION
```
The OpenSSL version should be 1.0.1 or later.
1. To exit the Python shell, run the following command:
```
exit()
```
------
1. Run the following commands to install the AWS IoT Device SDK for Python:
```
cd ~
git clone https://github.com/aws/aws-iot-device-sdk-python.git
cd aws-iot-device-sdk-python
sudo python setup.py install
```
------
#### [ UNIX-like system ]
1. From a terminal window, run the following command:
```
python --version
```
If no version information is returned or if the version number is less than 2.7 for Python 2 or less than 3.3 for Python 3, follow the instructions in [Downloading Python](https://wiki.python.org/moin/BeginnersGuide/Download) to install Python 2.7\$1 or Python 3.3\$1. For more information, see [Using Python on Unix platforms](https://docs.python.org/3.6/using/unix.html).
1. In the terminal, run the following commands to determine the OpenSSL version:
```
python
>>>import ssl
>>>print ssl.OPENSSL_VERSION
```
Make a note of the OpenSSL version value.
**Note**
If you're running Python 3, use **print(ssl.OPENSSL\$1VERSION)**.
To close the Python shell, run the following command:
```
exit()
```
If the OpenSSL version is 1.0.1 or later, skip to the next step. Otherwise, run the command(s) to update OpenSSL for your distribution (for example, `sudo yum update openssl`, `sudo apt-get update`, and so on).
Confirm that the OpenSSL version is 1.0.1 or later by running the following commands:
```
python
>>>import ssl
>>>print ssl.OPENSSL_VERSION
>>>exit()
```
1. Run the following commands to install the AWS IoT Device SDK for Python:
```
cd ~
git clone https://github.com/aws/aws-iot-device-sdk-python.git
cd aws-iot-device-sdk-python
sudo python setup.py install
```
------
1. After the AWS IoT Device SDK for Python is installed, navigate to the `samples` folder and open the `greengrass` folder.
For this tutorial, you copy the `basicDiscovery.py` sample function, which uses the certificates and keys that you downloaded in [Create client devices in an AWS IoT Greengrass group](device-group.md).
1. Copy `basicDiscovery.py` to the folder that contains the HelloWorld\$1Publisher and HelloWorld\$1Subscriber device certificates and keys.
# Test communications
1. Make sure that your computer and the AWS IoT Greengrass core device are connected to the internet using the same network.
1. On the AWS IoT Greengrass core device, run the following command to find its IP address.
```
hostname -I
```
1. On your computer, run the following command using the IP address of the core. You can use Ctrl \$1 C to stop the **ping** command.
```
ping IP-address
```
Output similar to the following indicates successful communication between the computer and the AWS IoT Greengrass core device (0% packet loss):
![\[Successful ping command output.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-075.5.png)
**Note**
If you're unable to ping an EC2 instance that's running AWS IoT Greengrass, make sure that the inbound security group rules for the instance allow ICMP traffic for [Echo request](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html#sg-rules-ping) messages. For more information, see [ Adding rules to a security group](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) in the *Amazon EC2 User Guide*.
On Windows host computers, in the Windows Firewall with Advanced Security app, you might also need to enable an inbound rule that allows inbound echo requests (for example, **File and Printer Sharing (Echo Request - ICMPv4-In)**), or create one.
1. Get your AWS IoT endpoint.
1. From the [AWS IoT console](https://console.aws.amazon.com/iot/) navigation pane, choose **Settings**.
1. Under **Device data endpoint**, make a note of the value of **Endpoint**. You use this value to replace the *AWS\$1IOT\$1ENDPOINT* placeholder in the commands in the following steps.
**Note**
Make sure that your [endpoints correspond to your certificate type](gg-core.md#certificate-endpoints).
1. On your computer (not the AWS IoT Greengrass core device), open two [command-line](https://en.wikipedia.org/wiki/Command-line_interface) (terminal or command prompt) windows. One window represents the HelloWorld\$1Publisher client device and the other represents the HelloWorld\$1Subscriber client device.
Upon execution, `basicDiscovery.py` attempts to collect information on the location of the AWS IoT Greengrass core at its endpoints. This information is stored after the client device has discovered and successfully connected to the core. This allows future messaging and operations to be executed locally (without the need for an internet connection).
**Note**
Client IDs used for MQTT connections must match the thing name of the client device. The `basicDiscovery.py` script sets the client ID for MQTT connections to the thing name that you specify when you run the script.
Run the following command from the folder that contains the `basicDiscovery.py` file for detailed script usage information:
```
python basicDiscovery.py --help
```
1. From the HelloWorld\$1Publisher client device window, run the following commands.
+ Replace *path-to-certs-folder* with the path to the folder that contains the certificates, keys, and `basicDiscovery.py`.
+ Replace *AWS\$1IOT\$1ENDPOINT* with your endpoint.
+ Replace the two *publisherCertId* instances with the certificate ID in the file name for your HelloWorld\$1Publisher client device.
```
cd path-to-certs-folder
python basicDiscovery.py --endpoint AWS_IOT_ENDPOINT --rootCA AmazonRootCA1.pem --cert publisherCertId-certificate.pem.crt --key publisherCertId-private.pem.key --thingName HelloWorld_Publisher --topic 'hello/world/pubsub' --mode publish --message 'Hello, World! Sent from HelloWorld_Publisher'
```
You should see output similar to the following, which includes entries such as `Published topic 'hello/world/pubsub': {"message": "Hello, World! Sent from HelloWorld_Publisher", "sequence": 1}`.
**Note**
If the script returns an `error: unrecognized arguments` message, change the single quotation marks to double quotation marks for the `--topic` and `--message` parameters and run the command again.
To troubleshoot a connection issue, you can try using [manual IP detection](#corp-network-manual-detection).
![\[Screenshot of the publisher output.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-076.png)
1. From the HelloWorld\$1Subscriber client device window, run the following commands.
+ Replace *path-to-certs-folder* with the path to the folder that contains the certificates, keys, and `basicDiscovery.py`.
+ Replace *AWS\$1IOT\$1ENDPOINT* with your endpoint.
+ Replace the two *subscriberCertId* instances with the certificate ID in the file name for your HelloWorld\$1Subscriber client device.
```
cd path-to-certs-folder
python basicDiscovery.py --endpoint AWS_IOT_ENDPOINT --rootCA AmazonRootCA1.pem --cert subscriberCertId-certificate.pem.crt --key subscriberCertId-private.pem.key --thingName HelloWorld_Subscriber --topic 'hello/world/pubsub' --mode subscribe
```
You should see the following output, which includes entries such as `Received message on topic hello/world/pubsub: {"message": "Hello, World! Sent from HelloWorld_Publisher", "sequence": 1}`.
![\[Screenshot of the subscriber output.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-077.png)
Close the HelloWorld\$1Publisher window to stop messages from accruing in the HelloWorld\$1Subscriber window.
Testing on a corporate network might interfere with connecting to the core. As a workaround, you can manually enter the endpoint. This ensures that the `basicDiscovery.py` script connects to the correct IP address of the AWS IoT Greengrass core device.
**To manually enter the endpoint**
1. In the AWS IoT console navigation pane, under **Manage**, expand **Greengrass devices**, and then choose **Groups (V1)**.
1. Under **Greengrass groups**, choose your group.
1. Configure the core to manually manage MQTT broker endpoints. Do the following:
1. On the group configuration page, choose the **Lambda functions** tab.
1. Under **System Lambda functions**, choose **IP detector**, and then choose **Edit**.
1. In the **Edit IP detector settings**, choose **Manually manage MQTT broker endpoints**, and then choose **Save**.
1. Enter the MQTT broker endpoint for the core. Do the following:
1. Under **Overview**, choose the **Greengrass core**.
1. Under **MQTT broker endpoints**, choose **Manage endpoints**.
1. Choose **Add endpoint** and make sure that you have only one endpoint value. This value must be the IP address endpoint for port 8883 of your AWS IoT Greengrass core device (for example, `192.168.1.4`).
1. Choose **Update**.