# Getting started with AWS IoT Core tutorials
Whether you're new to IoT or you have years of experience, these resources present the AWS IoT concepts and terms that will help you start using AWS IoT.
+ **Look** inside AWS IoT and its components in [How AWS IoT works](aws-iot-how-it-works.md).
+ [**Learn** more about AWS IoT](aws-iot-learn-more.md) from our collection of training materials and videos. This topic also includes a list of services that AWS IoT can connect to, social media links, and links to communication protocol specifications.
+ **[Connect your first device to AWS IoT Core](#aws-iot-get-started)**.
+ **Develop** your IoT solutions by [Connect to AWS IoT Core](connect-to-iot.md) and exploring the [AWS IoT tutorials](iot-tutorials.md).
+ **Test and validate** your IoT devices for secure and reliable communication by using the [Device Advisor](device-advisor.md).
+ **Manage** your solution by using AWS IoT Core management services such as [Fleet indexing](iot-indexing.md), [AWS IoT Jobs](iot-jobs.md), and [AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/what-is-device-defender.html).
+ **Analyze** the data from your devices by using the [AWS IoT data services](aws-iot-how-it-works.md#aws-iot-components-data).
## Connect your first device to AWS IoT Core
AWS IoT Core services connect IoT devices to AWS IoT services and other AWS services. AWS IoT Core includes the device gateway and the message broker, which connect and process messages between your IoT devices and the cloud.
Here's how you can get started with AWS IoT Core and AWS IoT.
![\[AWS IoT Core getting started tour map.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/iot-gs-tour-map.png)
This section presents a tour of the AWS IoT Core to introduce its key services and provides several examples of how to connect a device to AWS IoT Core and pass messages between them. Passing messages between devices and the cloud is fundamental to every IoT solution and is how your devices can interact with other AWS services.
+
**[Set up AWS account](setting-up.md)**
Before you can use AWS IoT services, you must set up an AWS account. If you already have an AWS account and an IAM user for yourself, you can use them and skip this step.
+
**[Try the quick connect tutorial](iot-quick-start.md)**
This tutorial is best if you want to quickly get started with AWS IoT and see how it works in a limited scenario. In this tutorial, you'll need a device and you'll install some AWS IoT software on it. If you don't have an IoT device, you can use your Windows, Linux, or macOS personal computer as a device for this tutorial. If you want to try AWS IoT, but you don't have a device, try the next option.
+
**[Try the interactive tutorial](interactive-demo.md)**
This demo is best if you want to see what a basic AWS IoT solution can do without connecting a device or downloading any software. The interactive tutorial presents a simulated solution built on AWS IoT Core services that illustrates how they interact.
+
**[Explore AWS IoT Core services with a hands-on tutorial](iot-gs-first-thing.md)**
This tutorial is best for developers who want to get started with AWS IoT so they can continue to explore other AWS IoT Core features such as the rules engine and shadows. This tutorial follows a process similar to the quick connect tutorial, but provides more details on each step to enable a smoother transition to the more advanced tutorials.
+
**[View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md)**
Learn how to use the MQTT test client to watch your first device publish MQTT messages to AWS IoT. The MQTT test client is a useful tool to monitor and troubleshoot device connections.
**Note**
If you want to try more than one of these getting started tutorials or repeat the same tutorial, you should delete the thing object that you created from an earlier tutorial before you start another one. If you don't delete the thing object from an earlier tutorial, you will need to use a different thing name for subsequent tutorials. This is because the thing name must be unique in your account and AWS Region.
For more information about AWS IoT Core, see [What Is AWS IoT Core](what-is-aws-iot.md)?
# Set up AWS account
Before you use AWS IoT Core for the first time, complete the following tasks:
**Topics**
+ [
## Sign up for an AWS account
](#sign-up-for-aws)
+ [
## Create a user with administrative access
](#create-an-admin)
+ [
## Open the AWS IoT console
](#iot-console-signin)
## Sign up for an AWS account
If you do not have an AWS account, complete the following steps to create one.
**To sign up for an AWS account**
1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).
1. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.
When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).
AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**.
## Create a user with administrative access
After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.
**Secure your AWS account root user**
1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password.
For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*.
1. Turn on multi-factor authentication (MFA) for your root user.
For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*.
**Create a user with administrative access**
1. Enable IAM Identity Center.
For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*.
1. In IAM Identity Center, grant administrative access to a user.
For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*.
**Sign in as the user with administrative access**
+ To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.
For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*.
**Assign access to additional users**
1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.
For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*.
1. Assign users to a group, and then assign single sign-on access to the group.
For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*.
+ [Open the AWS IoT console](#iot-console-signin)
If you already have an AWS account and a user for yourself, you can use them and skip ahead to [Open the AWS IoT console](#iot-console-signin).
## Open the AWS IoT console
Most of the console-oriented topics in this section start from the AWS IoT console. If you aren't already signed in to your AWS account, sign in, then open the [AWS IoT console](https://console.aws.amazon.com//iot/home) and continue to the next section to continue getting started with AWS IoT.
# Interactive tutorial
The interactive tutorial shows the components of a simple IoT solution built on AWS IoT. The tutorial shows how IoT devices interact with AWS IoT Core services. This topic provides a preview of the AWS IoT Core interactive tutorial.
**Note**
The images in the console include animations that don't appear in the images in this tutorial.
To run the demo, you must first [Set up AWS account](setting-up.md). The tutorial, however, doesn't require any AWS IoT resources, additional software, or any coding.
Expect to spend approximately 5-10 minutes on this demo. Giving yourself 10 minutes will allow more time to comprehend each of the steps.
**To run the AWS IoT Core interactive tutorial**
1. Open the [AWS IoT home page](https://console.aws.amazon.com//iot/home#/home) in the AWS IoT console.
On the **AWS IoT home page**, in the **Learning resources** window pane, choose **Start tutorial**.
![\[This is the AWS IoT console home page.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-home-demo.png)
1. In the **AWS IoT Console Tutorial** page, review the tutorial sections and choose **Start section** when you're ready to continue.
**The following sections describe how the **AWS IoT Console Tutorial** presents these AWS IoT Core features:**
+ [
## Connecting IoT devices
](#interactive-demo-part1)
+ [
## Saving offline device state
](#interactive-demo-part2)
+ [
## Routing device data to services
](#interactive-demo-part3)
## Connecting IoT devices
Learn how IoT devices communicate with AWS IoT Core.
![\[This is the first step of the AWS IoT interactive tutorial.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-demo-step-1.png)
The animation in this step shows how two devices, the control device on the left and a smart lamp in the house on the right, connect and communicate with AWS IoT Core in the cloud. The animation shows the devices communicating with AWS IoT Core and reacting to the messages they receive.
For more information about connecting devices to AWS IoT Core, see [Connect to AWS IoT Core](connect-to-iot.md).
## Saving offline device state
Learn how AWS IoT Core saves device state for while a device or app is offline.
![\[This is the second step of the AWS IoT interactive tutorial.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-demo-step-2.png)
The animation in this step shows how the Device Shadow service in AWS IoT Core saves device state information for the control device and the smart lamp. While the smart lamp is offline, the Device Shadow saves commands from the control device.
When the smart lamp reconnects to AWS IoT Core, it retrieves those commands. When the control device is offline, the Device Shadow saves state information from the smart lamp. When the control device reconnects, it retrieves the current state of the smart lamp to update its display.
For more information about Device Shadows, see [AWS IoT Device Shadow service](iot-device-shadows.md).
## Routing device data to services
Learn how AWS IoT Core sends device state to other AWS services.
![\[This is the third step of the AWS IoT interactive tutorial.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-demo-step-3.png)
The animation in this step shows how AWS IoT Core sends data from the devices to other AWS services by using AWS IoT rules. AWS IoT rules subscribe to specific messages from the devices, interpret the data in those messages, and route the interpreted data to other services. In this example, an AWS IoT rule interprets data from a motion sensor and sends commands to a Device Shadow, which then sends them to the smart bulb. As in the previous example, the Device Shadow stores the device-state info for the control device.
For more information about AWS IoT rules, see [Rules for AWS IoT](iot-rules.md).
# Try the AWS IoT Core quick connect tutorial
In this tutorial, you'll create your first thing object, connect a device to it, and watch it send MQTT messages.
You can expect to spend 15-20 minutes on this tutorial.
This tutorial is best for people who want to quickly get started with AWS IoT to see how it works in a limited scenario. If you're looking for an example that will get you started so that you can explore more features and services, try [Explore AWS IoT Core in hands-on tutorials](iot-gs-first-thing.md).
In this tutorial, you'll download and run software on a device that connects to a *thing resource* in AWS IoT Core as part of a very small IoT solution. The device can be an IoT device, such as a Raspberry Pi, or it can also be a computer that is running Linux, OS and OSX, or Windows. If you're looking to connect a Long Range WAN (LoRaWAN) device to AWS IoT, refer to the tutorial [>Connecting devices and gateways to AWS IoT Core for LoRaWAN](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/lorawan-getting-started.html).
If your device supports a browser that can run the [AWS IoT console](https://console.aws.amazon.com//iot/home), we recommend you complete this tutorial on that device.
**Note**
If your device doesn't have a compatible browser, follow this tutorial on a computer. When the procedure asks you to download the file, download it to your computer, and then transfer the downloaded file to your device by using Secure Copy (SCP) or a similar process.
The tutorial requires your IoT device to communicate with port 8443 on your AWS account's device data endpoint. To test whether it can access that port, try the procedures in [Test connectivity with your device data endpoint](iot-quick-start-test-connection.md).
## Step 1. Start the tutorial
If possible, complete this procedure on your device; otherwise, be ready to transfer a file to your device later in this procedure.
To start the tutorial, sign in to the [AWS IoT console](https://console.aws.amazon.com//iot/home). In the AWS IoT console home page, on the left, choose **Connect** and then choose **Connect one device**.
![\[This AWS IoT console home page shows how to connect one device.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-quick-connect.PNG)
## Step 2. Create a thing object
1. In the **Prepare your device** section, follow the on-screen instructions to prepare your device for connecting to AWS IoT.
![\[How to prepare device in AWS IoT console.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-prepare-device.png)
1. In the **Register and secure your device** section, choose **Create a new thing** or **Choose an existing thing**. In the **Thing name** field, enter the name for your thing object. The thing name used in this example is **TutorialTestThing**
**Important**
Double-check your thing name before you continue.
A thing name can't be changed after the thing object is created. If you want to change a thing name, you must create a new thing object with the correct thing name and then delete the one with the incorrect name.
In the **Additional configurations** section, customize your thing resource further using the optional configurations listed.
After you provide your thing object a name and select any additional configurations, choose **Next**.
![\[Use AWS IoT console to register and secure your device.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-register-and-secure-your-device.png)
1. In the **Choose platform and SDK** section, choose the platform and the language of the AWS IoT Device SDK that you want to use. This example uses the Linux/OSX platform and the Python SDK. Make sure that you have python3 and pip3 installed on your target device before you continue to the next step.
**Note**
Be sure to check the list of prerequisite software required by your chosen SDK at the bottom of the console page.
You must have the required software installed on your target computer before you continue to the next step.
After you choose the platform and device SDK language, choose **Next**.
![\[Use AWS IoT console to choose platform and SDK.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-choose-platform-and-SDK.png)
## Step 3. Download files to your device
This page appears after AWS IoT has created the connection kit, which includes the following files and resources that your device requires:
+ The thing's certificate files used to authenticate the device
+ A policy resource to authorize your thing object to interact with AWS IoT
+ The script to download the AWS Device SDK and run the sample program on your device
1. When you're ready to continue, choose the **Download connection kit for** button to download the connection kit for the platform that you chose earlier.
![\[This is the page of AWS IoT console to download certificate file.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-download-connection-kit_1.png)
1. If you're running this procedure on your device, save the connection kit file to a directory from which you can run command line commands.
If you're not running this procedure on your device, save the connection kit file to a local directory and then transfer the file to your device.
1. In the **Unzip connection kit on your device** section, enter **unzip connect\$1device\$1package.zip** in the directory where the connection kit files are located.
If you're using a Windows PowerShell command window and the **unzip** command doesn't work, replace **unzip** with **expand-archive**, and try the command line again.
1. After you have the connection kit file on the device, continue the tutorial by choosing **Next**.
![\[AWS IoT console certificate file download page after connection kit download.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-download-connection-kit_2.png)
## Step 4. Run the sample
You do this procedure in a terminal or command window on your device while you follow the directions displayed in the console. The commands you see in the console are for the operating system you chose in [Step 2. Create a thing object](#iot-quick-start-configure). Those shown here are for the Linux/OSX operating systems.
1. In a terminal or command window on your device, in the directory with the connection kit file, perform the steps shown in the AWS IoT console.
![\[AWS IoT console quick start install and run page.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-run-connection-kit.png)
1. After you enter the command from **Step 2** in the console, you should see an output in the device's terminal or command window that is similar to the following. This output is from the messages the program is sending to and then receiving back from AWS IoT Core.
![\[AWS IoT console quick start example program output.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-connect-console-output-python_updated.png)
While the sample program is running, the test message `Hello World!` will appear as well. The test message appears in the terminal or command window on your device.
**Note**
For more information about topic subscription and publish, see the example code of your chosen SDK.
1. To run the sample program again, you can repeat the commands from **Step 2** in the console of this procedure.
1. (Optional) If you want to see the messages from your IoT client in the [AWS IoT console](https://console.aws.amazon.com//iot/home), open the [MQTT test client](https://console.aws.amazon.com//iot/home#/test) on the **Test** page of the AWS IoT console. If you chose Python SDK, then in the **MQTT test client**, in **Topic filter**, enter the topic, such as **sdk/test/*python*** to subscribe to the messages from your device. The topic filters are case sensitive and depend on the programming language of the SDK you chose in **Step 1**. For more information about topic subscription and publish, see the code example of your chosen SDK.
1. After you subscribe to the test topic, run **./start.sh** on your device. For more information, see [View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md).
After you run **./start.sh**, messages appear in the MQTT client, similar to the following:
```
{
"message": "Hello World!" [1]
}
```
The `sequence` number encased in `[]` increments by one each time a new `Hello World!` message is received and stops when you end the program.
1. To finish the tutorial and see a summary, in the AWS IoT console, choose **Continue**.
![\[AWS IoT console quick start completion page.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-connect-complete_updated1.png)
1. A summary of your AWS IoT quick connect tutorial will now appear.
![\[AWS IoT console quick start summary page.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/aws-iot-learn-device-is-connected.png)
## Step 5. Explore further
Here are some ideas to explore AWS IoT further after you complete the quick start.
+
**[View MQTT messages in the MQTT test client](https://console.aws.amazon.com/iot/home#/test)**
From the [AWS IoT console](https://console.aws.amazon.com//iot/home), you can open the [MQTT client](https://console.aws.amazon.com//iot/home#/test) on the **Test** page of the AWS IoT console. In the **MQTT test client**, subscribe to **\$1**, and then, on your device, run the program **./start.sh** as described in the previous step. For more information, see [View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md).
+
**Run tests on your devices with [Device Advisor](https://docs.aws.amazon.com//iot/latest/developerguide/device-advisor.html)**
Use Device Advisor to test if your devices can securely and reliably connect to, and interact with, AWS IoT.
+
**[Interactive tutorial](interactive-demo.md)**
To start the interactive tutorial, from the **Learn** page of the AWS IoT console, in the **See how AWS IoT works** tile, choose **Start the tutorial**.
+
**[Get ready to explore more tutorials](iot-gs-first-thing.md)**
This quick start gives you just a sample of AWS IoT. If you want to explore AWS IoT further and learn about the features that make it a powerful IoT solution platform, start preparing your development platform by [Explore AWS IoT Core in hands-on tutorials](iot-gs-first-thing.md).
# Test connectivity with your device data endpoint
This topic describes how to test a device's connection with your account's *device data endpoint*, the endpoint that your IoT devices use to connect to AWS IoT.
Perform these procedures on the device that you want to test or by using an SSH terminal session connected to the device you want to test.
**Topics**
+ [
## Find your device data endpoint
](#iot-quick-start-test-connection-endpoint)
+ [
## Test the connection quickly
](#iot-quick-start-test-connection-ping)
+ [
## Get the app to test the connection to your device data endpoint and port
](#iot-quick-start-test-connection-app)
+ [
## Test the connection to your device data endpoint and port
](#iot-quick-start-test-connection-test)
## Find your device data endpoint
This procedure explains how to find your device data endpoint in the [AWS IoT console](https://console.aws.amazon.com//iot/home) for testing the connection to your IoT device.
**To find your device data endpoint**
1. In the [AWS IoT console](https://console.aws.amazon.com//iot/home), in the **Connect** section, go to **Domain Configurations**.
1. In the **Domain Configurations** page, go to the **Domain configurations** container, and copy the **Domain name**. Your endpoint value is unique to your AWS account and is similar to this example: `a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com`.
1.
Save your device data endpoint to use in the following procedures.
## Test the connection quickly
This procedure tests general connectivity with your device data endpoint, but it doesn't test the specific port that your devices will use. This test uses a common program and is usually sufficient to find out if your devices can connect to AWS IoT.
If you want to test connectivity with the specific port that your devices will use, skip this procedure and continue to [Get the app to test the connection to your device data endpoint and port](#iot-quick-start-test-connection-app).
**To test the device data endpoint quickly**
1. In a terminal or command line window on your device, replace the sample device data endpoint (`a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com`) with the device data endpoint for your account, and then enter this command.
------
#### [ Linux ]
```
ping -c 5 a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com
```
------
#### [ Windows ]
```
ping -n 5 a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com
```
------
1. If `ping` displays an output similar to the following, it connected to your device data endpoint successfully. While it didn't communicate with AWS IoT directly, it did find the server and it's likely that AWS IoT is available through this endpoint.
```
PING a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com (xx.xx.xxx.xxx) 56(84) bytes of data.
64 bytes from ec2-EXAMPLE-218.eu-west-1.compute.amazonaws.com (xx.xx.xxx.xxx): icmp_seq=1 ttl=231 time=127 ms
64 bytes from ec2-EXAMPLE-218.eu-west-1.compute.amazonaws.com (xx.xx.xxx.xxx): icmp_seq=2 ttl=231 time=127 ms
64 bytes from ec2-EXAMPLE-218.eu-west-1.compute.amazonaws.com (xx.xx.xxx.xxx): icmp_seq=3 ttl=231 time=127 ms
64 bytes from ec2-EXAMPLE-218.eu-west-1.compute.amazonaws.com (xx.xx.xxx.xxx): icmp_seq=4 ttl=231 time=127 ms
64 bytes from ec2-EXAMPLE-218.eu-west-1.compute.amazonaws.com (xx.xx.xxx.xxx): icmp_seq=5 ttl=231 time=127 ms
```
If you are satisfied with this result, you can stop testing here.
If you want to test the connectivity with the specific port used by AWS IoT, continue to [Get the app to test the connection to your device data endpoint and port](#iot-quick-start-test-connection-app).
1. If `ping` didn't return a successful output, check the endpoint value to make sure you have the correct endpoint and check the device's connection with the internet.
## Get the app to test the connection to your device data endpoint and port
A more thorough connectivity test can be performed by using `nmap`. This procedure tests to see if `nmap` is installed on your device.
**To check for `nmap` on the device**
1. In a terminal or command line window on the device you want to test, enter this command to see if `nmap` is installed.
```
nmap --version
```
1. If you see an output similar to the following, `nmap` is installed and you can continue to [Test the connection to your device data endpoint and port](#iot-quick-start-test-connection-test).
```
Nmap version 6.40 ( http://nmap.org )
Platform: x86_64-koji-linux-gnu
Compiled with: nmap-liblua-5.2.2 openssl-1.0.2k libpcre-8.32 libpcap-1.5.3 nmap-libdnet-1.12 ipv6
Compiled without:
Available nsock engines: epoll poll select
```
1. If you don't see a response similar to the one shown in the preceding step, you must install `nmap` on the device. Choose the procedure for your device's operating system.
------
#### [ Linux ]
This procedure requires that you have permission to install software on the computer.
**To install nmap on your Linux computer**
1. In a terminal or command line window on your device, enter the command that corresponds to the version of Linux it's running.
1. Debian or Ubuntu:
```
sudo apt install nmap
```
1. CentOS or RHEL:
```
sudo yum install nmap
```
1. Test the installation with this command:
```
nmap --version
```
1. If you see an output similar to the following, `nmap` is installed and you can continue to [Test the connection to your device data endpoint and port](#iot-quick-start-test-connection-test).
```
Nmap version 6.40 ( http://nmap.org )
Platform: x86_64-koji-linux-gnu
Compiled with: nmap-liblua-5.2.2 openssl-1.0.2k libpcre-8.32 libpcap-1.5.3 nmap-libdnet-1.12 ipv6
Compiled without:
Available nsock engines: epoll poll select
```
------
#### [ macOS ]
This procedure requires that you have permission to install software on the computer.
**To install nmap on your macOS computer**
1. In a browser, open [https://nmap.org/download\$1macosx](https://nmap.org/download#macosx) and download the **latest stable** installer.
When prompted, select **Open with DiskImageInstaller**.
1. In the installation window, move the package to the **Applications** folder.
1. In the **Finder**, locate the `nmap-xxxx-mpkg` package in the **Applications** folder. **Ctrl-click** the on package and select **Open** to open the package.
1. Review the security dialog box. If you are ready to install **nmap**, choose **Open** to install **nmap**.
1. In **Terminal**, test the installation with this command.
```
nmap --version
```
1. If you see an output similar to the following, `nmap` is installed and you can continue to [Test the connection to your device data endpoint and port](#iot-quick-start-test-connection-test).
```
Nmap version 7.92 ( https://nmap.org )
Platform: x86_64-apple-darwin17.7.0
Compiled with: nmap-liblua-5.3.5 openssl-1.1.1k nmap-libssh2-1.9.0 libz-1.2.11 nmap-libpcre-7.6 nmap-libpcap-1.9.1 nmap-libdnet-1.12 ipv6 Compiled without:
Available nsock engines: kqueue poll select
```
------
#### [ Windows ]
This procedure requires that you have permission to install software on the computer.
**To install nmap on your Windows computer**
1. In a browser, open [https://nmap.org/download\$1windows](https://nmap.org/download#windows) and download the **latest stable** release of the setup program.
If prompted, choose **Save file**. After the file is downloaded, open it from the downloads folder.
1. After the setup file finishes downloading, open downloaded **nmap-xxxx-setup.exe** to install the app.
1. Accept the default settings as the program installs.
You don't need the Npcap app for this test. You can deselect that option if you don't want to install it.
1. In **Command**, test the installation with this command.
```
nmap --version
```
1. If you see an output similar to the following, `nmap` is installed and you can continue to [Test the connection to your device data endpoint and port](#iot-quick-start-test-connection-test).
```
Nmap version 7.92 ( https://nmap.org )
Platform: i686-pc-windows-windows
Compiled with: nmap-liblua-5.3.5 openssl-1.1.1k nmap-libssh2-1.9.0 nmap-libz-1.2.11 nmap-libpcre-7.6 Npcap-1.50 nmap-libdnet-1.12 ipv6
Compiled without:
Available nsock engines: iocp poll select
```
------
## Test the connection to your device data endpoint and port
This procedure tests your IoT device's connection to your device data endpoint using your selected port.
**To test your device data endpoint and port**
1. In a terminal or command line window on your device, replace the sample device data endpoint (`a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com`) with the device data endpoint for your account, and then enter this command.
```
nmap -p 8443 a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com
```
1. If `nmap` displays an output similar to the following, `nmap` was able to connect successfully to your device data endpoint at the selected port.
```
Starting Nmap 7.92 ( https://nmap.org ) at 2022-02-18 16:23 Pacific Standard Time
Nmap scan report for a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com (xx.xxx.147.160)
Host is up (0.036s latency).
Other addresses for a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com (not scanned): xx.xxx.134.144 xx.xxx.55.139 xx.xxx.110.235 xx.xxx.174.233 xx.xxx.74.65 xx.xxx.122.179 xx.xxx.127.126
rDNS record for xx.xxx.147.160: ec2-EXAMPLE-160.eu-west-1.compute.amazonaws.com
PORT STATE SERVICE
8443/tcp open https-alt
MAC Address: 00:11:22:33:44:55 (Cimsys)
Nmap done: 1 IP address (1 host up) scanned in 0.91 seconds
```
1. If `nmap` didn't return a successful output, check the endpoint value to make sure you have the correct endpoint and check your device's connection with the internet.
You can test other ports on your device data endpoint, such as port 443, the primary HTTPS port, by replacing the port used in step 1, `8443`, with the port that you want to test.
# Explore AWS IoT Core in hands-on tutorials
In this tutorial, you'll install the software and create the AWS IoT resources necessary to connect a device to AWS IoT Core so that it can send and receive MQTT messages with AWS IoT Core. You'll see the messages in the MQTT client in the AWS IoT console.
You can expect to spend 20-30 minutes on this tutorial. If you are using an IoT device or a Raspberry Pi, this tutorial might take longer if, for example, you need to install the operating system and configure the device.
![\[Getting started with AWS IoT Core page.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/iot-getting-started.png)
This tutorial is best for developers who want to get started with AWS IoT Core so they can continue to explore more advanced features, such as the [rules engine](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rules.html) and [shadows](https://docs.aws.amazon.com//iot/latest/developerguide/iot-device-shadows.html). This tutorial prepares you to continue learning about AWS IoT Core and how it interacts with other AWS services by explaining the steps in greater detail than [the quick start tutorial](iot-quick-start.md). If you are looking for just a quick, *Hello World*, experience, try the [Try the AWS IoT Core quick connect tutorial](iot-quick-start.md).
After setting up your AWS account and AWS IoT console, you'll follow these steps to see how to connect a device and have it send messages to AWS IoT Core.
**Next steps**
+ [Choose which device option is the best for you](#choosing-a-gs-system)
+ [Create AWS IoT resources](create-iot-resources.md) if you are not going to create a virtual device with Amazon EC2
+ [Configure your device](configure-device.md)
+ [View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md)
For more information about AWS IoT Core, see [What Is AWS IoT Core](what-is-aws-iot.md)?
## Which device option is best for you?
If you're not sure which option to pick, use the following list of each option's advantages and disadvantages to help you decide which one is best for you.
| Option | This might be a good option if: | This might not be a good option if: |
| --- | --- | --- |
| [Create a virtual device with Amazon EC2](creating-a-virtual-thing.md) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs-first-thing.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs-first-thing.html) |
| [Use your Windows or Linux PC or Mac as an AWS IoT device](using-laptop-as-device.md) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs-first-thing.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs-first-thing.html) |
| [Connect a Raspberry Pi or other device](connecting-to-existing-device.md) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs-first-thing.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs-first-thing.html) |
# Create AWS IoT resources
In this tutorial, you'll create the AWS IoT resources that a device requires to connect to AWS IoT Core and exchange messages.
![\[Create AWS IoT resources page.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/iot-gs-create-resources.png)
1. Create an AWS IoT policy document, which will authorize your device to interact with AWS IoT services.
1. Create a thing object in AWS IoT and its X.509 device certificate, and then attach the policy document. The thing object is the virtual representation of your device in the AWS IoT registry. The certificate authenticates your device to AWS IoT Core, and the policy document authorizes your device to interact with AWS IoT.
**Note**
If you are planning to [Create a virtual device with Amazon EC2](creating-a-virtual-thing.md), you can skip this page and continue to [Configure your device](configure-device.md). You will create these resources when you create your virtual thing.
This tutorial uses the AWS IoT console to create the AWS IoT resources. If your device supports a web browser, it might be easier to run this procedure on the device's web browser because you will be able to download the certificate files directly to your device. If you run this procedure on another computer, you will need to copy the certificate files to your device before they can be used by the sample app.
## Create an AWS IoT policy
Devices use an X.509 certificate to authenticate with AWS IoT Core. The certificate has AWS IoT policies attached to it. These policies determine which AWS IoT operations, such as subscribing or publishing to MQTT topics, the device is permitted to perform. Your device presents its certificate when it connects and sends messages to AWS IoT Core.
Follow the steps to create a policy that allows your device to perform the AWS IoT operations necessary to run the example program. You must create the AWS IoT policy before you can attach it to the device certificate, which you'll create later.
**To create an AWS IoT policy**
1. In the [AWS IoT console](https://console.aws.amazon.com//iot/home), in the left menu, choose **Security** and then choose **Policies**.
1. On the **You don't have a policy yet** page, choose **Create policy**.
If your account has existing policies, choose **Create policy**.
1. On the **Create policy** page:
1. In the **Policy properties** section, in the **Policy name** field, enter a name for the policy (for example, **My\$1Iot\$1Policy**). Don't use personally identifiable information in your policy names.
1. In the **Policy document** section, create the policy statements that grant or deny resources access to AWS IoT Core operations. To create a policy statement that grants all clients to perform ****iot:Connect****, follow these steps:
+ In the **Policy effect** field, choose **Allow**. This allows all clients that have this policy attached to their certificate to perform the action listed in the **Policy action** field.
+ In the **Policy action** field, choose a policy action such as ****iot:Connect****. Policy actions are the actions that your device needs permission to perform when it runs the example program from the Device SDK.
+ In the **Policy resource** field, enter a resource Amazon Resource Name (ARN) or **\$1**. A **\$1** to select any client (device).
To create the policy statements for ****iot:Receive****, ****iot:Publish****, and ****iot:Subscribe****, choose **Add new statement** and repeat the steps.
![\[The page to create a policy.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/gs-create-policy-new.png)
**Note**
In this quick start, the wildcard (\$1) character is used for simplicity. For higher security, you should restrict which clients (devices) can connect and publish messages by specifying a client ARN instead of the wildcard character as the resource. Client ARNs follow this format: `arn:aws:iot:your-region:your-aws-account:client/my-client-id`.
However, you must first create the resource (such as a client device or thing shadow) before you can assign its ARN to a policy. For more information, see [AWS IoT Core action resources](https://docs.aws.amazon.com//iot/latest/developerguide/iot-action-resources.html).
1. After you've entered the information for your policy, choose **Create**.
For more information, see [How AWS IoT works with IAM](security_iam_service-with-iam.md).
## Create a thing object
Devices connected to AWS IoT Core are represented by *thing objects* in the AWS IoT registry. A *thing object* represents a specific device or logical entity. It can be a physical device or sensor (for example, a light bulb or a light switch on the wall). It can also be a logical entity, like an instance of an application or physical entity that doesn't connect to AWS IoT, but is related to other devices that do (for example, a car that has engine sensors or a control panel).
**To create a thing in the AWS IoT console**
1. In the [AWS IoT console](https://console.aws.amazon.com/iot/home), in the left menu, choose **All devices** and then choose **Things**.
1. On the **Things** page, choose **Create things**.
1. On the **Create things** page, choose **Create a single thing**, then choose **Next**.
1. On the **Specify thing properties** page, for **Thing name**, enter a name for your thing, such as **MyIotThing**.
Choose thing names carefully, because you can't change a thing name later.
To change a thing's name, you must create a new thing, give it the new name, and then delete the old thing.
**Note**
Do not use personally identifiable information in your thing name. The thing name can appear in unencrypted communications and reports.
1. Keep the rest of the fields on this page empty. Choose **Next**.
1. On the **Configure device certificate - *optional*** page, choose **Auto-generate a new certificate (recommended)**. Choose **Next**.
1. On the **Attach policies to certificate - *optional*** page, select the policy you created in the previous section. In that section, the policy was named, **My\$1Iot\$1Policy**. Choose **Create thing**.
1. On the **Download certificates and keys** page:
1. Download each of the certificate and key files and save them for later. You'll need to install these files on your device.
When you save your certificate files, give them the names in the following table. These are the file names used in later examples.
**Certificate file names**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html)
1. To download the root CA file for these files, choose the **Download** link of the root CA certificate file that corresponds to the type of data endpoint and cipher suite you're using. In this tutorial, choose **Download** to the right of **RSA 2048 bit key: Amazon Root CA 1** and download the **RSA 2048 bit key: Amazon Root CA 1** certificate file.
**Important**
You must save the certificate files before you leave this page. After you leave this page in the console, you will no longer have access to the certificate files.
If you forgot to download the certificate files that you created in this step, you must exit this console screen, go to the list of things in the console, delete the thing object you created, and then restart this procedure from the beginning.
1. Choose **Done**.
After you complete this procedure, you should see the new thing object in your list of things.
# Configure your device
This section describes how to configure your device to connect to AWS IoT Core. If you'd like to get started with AWS IoT Core but don't have a device yet, you can create a virtual device by using Amazon EC2 or you can use your Windows PC or Mac as an IoT device.
Select the best device option for you to try AWS IoT Core. Of course, you can try all of them, but try only one at a time. If you're not sure which device option is best for you, read about how to choose [which device option is the best](iot-gs-first-thing.md#choosing-a-gs-system), and then return to this page.
**Device options**
+ [Create a virtual device with Amazon EC2](creating-a-virtual-thing.md)
+ [Use your Windows or Linux PC or Mac as an AWS IoT device](using-laptop-as-device.md)
+ [Connect a Raspberry Pi or other device](connecting-to-existing-device.md)
# Create a virtual device with Amazon EC2
In this tutorial, you'll create an Amazon EC2 instance to serve as your virtual device in the cloud.
To complete this tutorial, you need an AWS account. If you don't have one, complete the steps described in [Set up AWS account](setting-up.md) before you continue.
**Topics**
+ [
## Set up an Amazon EC2 instance
](#set-up-ec2)
+ [
## Install Git, Node.js and configure the AWS CLI
](#install-git-node)
+ [
## Create AWS IoT resources for your virtual device
](#ec2-create-certificate)
+ [
## Install the AWS IoT Device SDK for JavaScript
](#ec2-sdk)
+ [
## Run the sample application
](#ec2-run-app)
+ [
## View messages from the sample app in the AWS IoT console
](#ec2-view-msg)
## Set up an Amazon EC2 instance
The following steps show you how to create an Amazon EC2 instance that will act as your virtual device in place of a physical device.
If this is the first time you've created an Amazon EC2 instance, you might find the instructions in [Get started with Amazon EC2Linux instances](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/EC2_GetStarted.html) to be more helpful.
**To launch an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. From the console menu on the left, expand **Instances** section and choose **Instances**. From the **Instances** dashboard, choose **Launch instances** on the right to display a list of basic configurations.
1. In the **Name and tags** section, enter a name for the instance and optionally add tags.
1. In the **Application and OS Images (Amazon Machine Image)** section, choose an AMI template for your instance, such as *Amazon Linux 2 AMI (HVM)*. Notice that this AMI is marked "Free tier eligible."
1. In the **Instance type** section, you can select the hardware configuration of your instance. Select the `t2.micro` type, which is selected by default. Notice that this instance type is eligible for the free tier.
1. In the **Key pair (login)** section, choose a key pair name from the drop-down list or choose **Create a new key pair** to create a new one. When creating a new key pair, make sure you download the private key file and save it in a safe place, because this is your only chance to download and save it. You'll need to provide the name of your key pair when you launch an instance and the corresponding private key each time you connect to the instance.
**Warning**
Don't choose the **Proceed without a key pair** option. If you launch your instance without a key pair, then you can't connect to it.
1. In the **Network settings** section and the **Configure storage** section, you can keep the default settings. When you are ready, choose **Launch instances**.
1. A confirmation page lets you know that your instance is launching. Choose **View Instances** to close the confirmation page and return to the console.
1. On the **Instances** screen, you can view the status of the launch. It takes a short time for an instance to launch. When you launch an instance, its initial state is `pending`. After the instance starts, its state changes to `running` and it receives a public DNS name. (If the **Public DNS (IPv4)** column is hidden, choose **Show/Hide Columns** (the gear-shaped icon) in the top right corner of the page and then select **Public DNS (IPv4)**.)
1. It can take a few minutes for the instance to be ready so that you can connect to it. Check that your instance has passed its status checks; you can view this information in the **Status Checks** column.
After your new instance has passed its status checks, continue to the next procedure and connect to it.
**To connect to your instance**
You can connect to an instance using the browser-based client by selecting the instance from the Amazon EC2 console and choosing to connect using Amazon EC2 Instance Connect. Instance Connect handles the permissions and provides a successful connection.
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. On the left menu, choose **Instances**.
1. Select the instance and choose **Connect**.
1. Choose **Amazon EC2 Instance Connect **, **Connect**.
You should now have an **Amazon EC2 Instance Connect** window that is logged into your new Amazon EC2 instance.
## Install Git, Node.js and configure the AWS CLI
In this section, you'll install Git and Node.js on your Linux instance.
**To install Git**
1. In your **Amazon EC2 Instance Connect** window, update your instance by using the following command.
```
sudo yum update -y
```
1. In your **Amazon EC2 Instance Connect** window, install Git by using the following command.
```
sudo yum install git -y
```
1. To check if Git has been installed and the current version of Git, run the following command:
```
git --version
```
**To install Node.js**
1. In your **Amazon EC2 Instance Connect** window, install node version manager (nvm) by using the following command.
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
```
We will use nvm to install Node.js because nvm can install multiple versions of Node.js and allow you to switch between them.
1. In your **Amazon EC2 Instance Connect** window, activate nvm by using this command.
```
. ~/.nvm/nvm.sh
```
1. In your **Amazon EC2 Instance Connect** window, use nvm to install the latest version of Node.js by using this command.
```
nvm install 16
```
**Note**
This installs the latest LTS release of Node.js.
Installing Node.js also installs the Node Package Manager (npm) so you can install additional modules as needed.
1. In your **Amazon EC2 Instance Connect** window, test that Node.js is installed and running correctly by using this command.
```
node -e "console.log('Running Node.js ' + process.version)"
```
This tutorial requires Node v10.0 or later. For more information, see [Tutorial: Setting Up Node.js on an Amazon EC2 Instance](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-up-node-on-ec2-instance.html).
**To configure AWS CLI**
Your Amazon EC2 instance comes preloaded with the AWS CLI. However, you must complete your AWS CLI profile. For more information on how to configure your CLI, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
1. The following example shows sample values. Replace them with your own values. You can find these values in your [AWS console in your account info under **Security credentials**](https://console.aws.amazon.com//iam/home#/security_credentials).
In your **Amazon EC2 Instance Connect** window, enter this command:
```
aws configure
```
Then enter the values from your account at the prompts displayed.
```
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json
```
1. You can test your AWS CLI configuration with this command:
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
If your AWS CLI is configured correctly, the command should return an endpoint address from your AWS account.
## Create AWS IoT resources for your virtual device
This section describes how to use the AWS CLI to create the thing object and its certificate files directly on the virtual device. This is done directly on the device to avoid the potential complication that might arise from copying them to the device from another computer. In this section, you will create the following resources for your virtual device:
+ A thing object to represent your virtual device in AWS IoT.
+ A certificate to authenticate your virtual device.
+ A policy document to authorize your virtual device to connect to AWS IoT, and to publish, receive, and subscribe to messages.
**To create an AWS IoT thing object in your Linux instance**
Devices connected to AWS IoT are represented by *thing objects* in the AWS IoT registry. A *thing object* represents a specific device or logical entity. In this case, your *thing object* will represent your virtual device, this Amazon EC2 instance.
1. In your **Amazon EC2 Instance Connect** window, run the following command to create your thing object.
```
aws iot create-thing --thing-name "MyIotThing"
```
1. The JSON response should look like this:
```
{
"thingArn": "arn:aws:iot:your-region:your-aws-account:thing/MyIotThing",
"thingName": "MyIotThing",
"thingId": "6cf922a8-d8ea-4136-f3401EXAMPLE"
}
```
**To create and attach AWS IoT keys and certificates in your Linux instance**
The **[create-keys-and-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-keys-and-certificate.html)** command creates client certificates signed by the Amazon Root certificate authority. This certificate is used to authenticate the identity of your virtual device.
1. In your **Amazon EC2 Instance Connect** window, create a directory to store your certificate and key files.
```
mkdir ~/certs
```
1. In your **Amazon EC2 Instance Connect** window, download a copy of the Amazon certificate authority (CA) certificate by using this command.
```
curl -o ~/certs/Amazon-root-CA-1.pem \
https://www.amazontrust.com/repository/AmazonRootCA1.pem
```
1. In your **Amazon EC2 Instance Connect** window, run the following command to create your private key, public key, and X.509 certificate files. This command also registers and activates the certificate with AWS IoT.
```
aws iot create-keys-and-certificate \
--set-as-active \
--certificate-pem-outfile "~/certs/device.pem.crt" \
--public-key-outfile "~/certs/public.pem.key" \
--private-key-outfile "~/certs/private.pem.key"
```
The response looks like the following. Save the `certificateArn` so that you can use it in subsequent commands. You'll need it to attach your certificate to your thing and to attach the policy to the certificate in a later steps.
```
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/9894ba17925e663f1d29c23af4582b8e3b7619c31f3fbd93adcb51ae54b83dc2",
"certificateId": "9894ba17925e663f1d29c23af4582b8e3b7619c31f3fbd93adcb51ae54b83dc2",
"certificatePem": "
-----BEGIN CERTIFICATE-----
MIICiTCCEXAMPLE6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgEXAMPLEAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSEXAMPLE2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYEXAMPLEb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCEXAMPLEJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDAEXAMPLEsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEXAMPLE25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+aEXAMPLE
EXAMPLEfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZEXAMPLELG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAEXAMPLEWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9qEXAMPLEyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDEXAMPLEBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE=
-----END CERTIFICATE-----\n",
"keyPair": {
"PublicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkEXAMPLEQEFAAOCAQ8AMIIBCgKCAQEAEXAMPLE1nnyJwKSMHw4h\nMMEXAMPLEuuN/dMAS3fyce8DW/4+EXAMPLEyjmoF/YVF/gHr99VEEXAMPLE5VF13\n59VK7cEXAMPLE67GK+y+jikqXOgHh/xJTwo+sGpWEXAMPLEDz18xOd2ka4tCzuWEXAMPLEahJbYkCPUBSU8opVkR7qkEXAMPLE1DR6sx2HocliOOLtu6Fkw91swQWEXAMPLE\GB3ZPrNh0PzQYvjUStZeccyNCx2EXAMPLEvp9mQOUXP6plfgxwKRX2fEXAMPLEDa\nhJLXkX3rHU2xbxJSq7D+XEXAMPLEcw+LyFhI5mgFRl88eGdsAEXAMPLElnI9EesG\nFQIDAQAB\n-----END PUBLIC KEY-----\n",
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nkey omitted for security reasons\n-----END RSA PRIVATE KEY-----\n"
}
}
```
1. In your **Amazon EC2 Instance Connect** window, attach your thing object to the certificate you just created by using the following command and the *certificateArn* in the response from the previous command.
```
aws iot attach-thing-principal \
--thing-name "MyIotThing" \
--principal "certificateArn"
```
If successful, this command does not display any output.
**To create and attach a policy**
1. In your **Amazon EC2 Instance Connect** window, create the policy file by copying and pasting this policy document to a file named **\$1/policy.json**.
If you don't have a favorite Linux editor, you can open **nano**, by using this command.
```
nano ~/policy.json
```
Paste the policy document for `policy.json` into it. Enter ctrl-x to exit the **nano** editor and save the file.
Contents of the policy document for `policy.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:Connect"
],
"Resource": [
"*"
]
}
]
}
```
1. In your **Amazon EC2 Instance Connect** window, create your policy by using the following command.
```
aws iot create-policy \
--policy-name "MyIotThingPolicy" \
--policy-document "file://~/policy.json"
```
Output:
****
```
{
"policyName": "MyIotThingPolicy",
"policyArn": "arn:aws:iot:us-east-1:your-aws-account:policy/MyIotThingPolicy",
"policyDocument": "{
\"Version\": \"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": [
\"iot:Publish\",
\"iot:Receive\",
\"iot:Subscribe\",
\"iot:Connect\"
],
\"Resource\": [
\"*\"
]
}
]
}",
"policyVersionId": "1"
}
```
1. In your **Amazon EC2 Instance Connect** window, attach the policy to your virtual device's certificate by using the following command.
```
aws iot attach-policy \
--policy-name "MyIotThingPolicy" \
--target "certificateArn"
```
If successful, this command does not display any output.
## Install the AWS IoT Device SDK for JavaScript
In this section, you'll install the AWS IoT Device SDK for JavaScript, which contains the code that applications can use to communicate with AWS IoT and the sample programs. For more information, see the [AWS IoT Device SDK for JavaScript GitHub repository](https://github.com/aws/aws-iot-device-sdk-js-v2).
**To install the AWS IoT Device SDK for JavaScript on your Linux instance**
1. In your **Amazon EC2 Instance Connect** window, clone the AWS IoT Device SDK for JavaScript repository into the `aws-iot-device-sdk-js-v2` directory of your home directory by using this command.
```
cd ~
git clone https://github.com/aws/aws-iot-device-sdk-js-v2.git
```
1. Navigate to the `aws-iot-device-sdk-js-v2` directory that you created in the preceding step.
```
cd aws-iot-device-sdk-js-v2
```
1. Use npm to install the SDK.
```
npm install
```
## Run the sample application
The commands in the next sections assume that your key and certificate files are stored on your virtual device as shown in this table.
**Certificate file names**
| File | File path |
| --- | --- |
| Private key | `~/certs/private.pem.key` |
| Device certificate | `~/certs/device.pem.crt` |
| Root CA certificate | `~/certs/Amazon-root-CA-1.pem` |
In this section, you'll install and run the `pub-sub.js` sample app found in the `aws-iot-device-sdk-js-v2/samples/node` directory of the AWS IoT Device SDK for JavaScript. This app shows how a device, your Amazon EC2 instance, uses the MQTT library to publish and subscribe to MQTT messages. The `pub-sub.js` sample app subscribes to a topic, `topic_1`, publishes 10 messages to that topic and displays the messages as they're received from the message broker.
**To install and run the sample app**
1. In your **Amazon EC2 Instance Connect** window, navigate to the `aws-iot-device-sdk-js-v2/samples/node/pub_sub` directory that the SDK created and install the sample app by using these commands.
```
cd ~/aws-iot-device-sdk-js-v2/samples/node/pub_sub
npm install
```
1. In your **Amazon EC2 Instance Connect** window, get *your-iot-endpoint* from AWS IoT by using this command.
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
1. In your **Amazon EC2 Instance Connect** window, insert *your-iot-endpoint* as indicated and run this command.
```
node dist/index.js --topic topic_1 --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
```
The sample app:
1. Connects to AWS IoT Core for your account.
1. Subscribes to the message topic, **topic\$11**, and displays the messages it receives on that topic.
1. Publishes 10 messages to the topic, **topic\$11**.
1. Displays output similar to the following:
```
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":1}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":2}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":3}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":4}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":5}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":6}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":7}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":8}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":9}
Publish received. topic:"topic_1" dup:false qos:1 retain:false
{"message":"Hello world!","sequence":10}
```
If you're having trouble running the sample app, review [Troubleshoot problems with the sample application](gs-device-troubleshoot.md).
You can also add the `--verbosity debug` parameter to the command line so the sample app displays detailed messages about what it’s doing. That information might provide you the help you need to correct the problem.
## View messages from the sample app in the AWS IoT console
You can see the sample app's messages as they pass through the message broker by using the **MQTT test client** in the **AWS IoT console**.
**To view the MQTT messages published by the sample app**
1. Review [View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md). This helps you learn how to use the **MQTT test client** in the **AWS IoT console** to view MQTT messages as they pass through the message broker.
1. Open the **MQTT test client** in the **AWS IoT console**.
1. In **Subscribe to a topic**, Subscribe to the topic, **topic\$11**.
1. In your **Amazon EC2 Instance Connect** window, run the sample app again and watch the messages in the **MQTT test client** in the **AWS IoT console**.
```
cd ~/aws-iot-device-sdk-js-v2/samples/node/pub_sub
node dist/index.js --topic topic_1 --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
```
For more information about MQTT and how AWS IoT Core supports the protocol, see [MQTT](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html).
# Use your Windows or Linux PC or Mac as an AWS IoT device
In this tutorial, you'll configure a personal computer for use with AWS IoT. These instructions support Windows and Linux PCs and Macs. To accomplish this, you need to install some software on your computer. If you don't want to install software on your computer, you might try [Create a virtual device with Amazon EC2](creating-a-virtual-thing.md), which installs all software on a virtual machine.
**Topics**
+ [
## Set up your personal computer
](#gs-pc-prereqs)
+ [
## Install Git, Python, and the AWS IoT Device SDK for Python
](#gs-pc-sdk-node)
+ [
## Set up the policy and run the sample application
](#gs-pc-python-app-run)
+ [
## View messages from the sample app in the AWS IoT console
](#gs-pc-view-msg)
+ [
## Run the Shared Subscription example in Python
](#gs-pc-shared-subscription-example)
## Set up your personal computer
To complete this tutorial, you need a Windows or Linux PC or a Mac with a connection to the internet.
Before you continue to the next step, make sure you can open a command line window on your computer. Use **cmd.exe** on a Windows PC. On a Linux PC or a Mac, use **Terminal**.
## Install Git, Python, and the AWS IoT Device SDK for Python
In this section, you'll install Python, and the AWS IoT Device SDK for Python on your computer.
### Install the latest version of Git and Python
This procedure explains how to install the latest version of Git and Python on your personal computer.
**To download and install Git and Python on your computer**
1. Check to see if you have Git installed on your computer. Enter this command in the command line.
```
git --version
```
If the command displays the Git version, Git is installed and you can continue to the next step.
If the command displays an error, open [https://git-scm.com/download](https://git-scm.com/download) and install Git for your computer.
1. Check to see if you have already installed Python. Enter the command in the command line.
```
python -V
```
**Note**
If this command gives an error: `Python was not found`, it might be because your operating system calls the Python v3.x executable as `Python3`. In that case, replace all instances of `python` with `python3` and continue the remainder of this tutorial.
If the command displays the Python version, Python is already installed. This tutorial requires Python v3.7 or later.
1. If Python is installed, you can skip the rest of the steps in this section. If not, continue.
1. Open [https://www.python.org/downloads/](https://www.python.org/downloads/) and download the installer for your computer.
1. If the download didn't automatically start to install, run the downloaded program to install Python.
1. Verify the installation of Python.
```
python -V
```
Confirm that the command displays the Python version. If the Python version isn't displayed, try downloading and installing Python again.
### Install the AWS IoT Device SDK for Python
**To install the AWS IoT Device SDK for Python on your computer**
1. Install v2 of the AWS IoT Device SDK for Python.
```
python3 -m pip install awsiotsdk
```
1. Clone the AWS IoT Device SDK for Python repository into the aws-iot-device-sdk-python-v2 directory of your home directory. This procedure refers to the base directory for the files you're installing as *home*.
The actual location of the *home* directory depends on your operating system.
------
#### [ Linux/macOS ]
In macOS and Linux, the *home* directory is `~`.
```
cd ~
git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git
```
------
#### [ Windows ]
In Windows, you can find the *home* directory path by running this command in the `cmd` window.
```
echo %USERPROFILE%
cd %USERPROFILE%
git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git
```
------
**Note**
If you're using Windows PowerShell as opposed to **cmd.exe**, then use the following command.
```
echo $home
```
For more information, see the [AWS IoT Device SDK for Python GitHub repository](https://github.com/aws/aws-iot-device-sdk-python-v2).
### Prepare to run the sample applications
**To prepare your system to run the sample application**
+ Create the `certs` directory. Into the `certs` directory, copy the private key, device certificate, and root CA certificate files you saved when you created and registered the thing object in [Create AWS IoT resources](create-iot-resources.md). The file names of each file in the destination directory should match those in the table.
The commands in the next section assume that your key and certificate files are stored on your device as shown in this table.
------
#### [ Linux/macOS ]
Run this command to create the `certs` subdirectory that you'll use when you run the sample applications.
```
mkdir ~/certs
```
Into the new subdirectory, copy the files to the destination file paths shown in the following table.
**Certificate file names**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/using-laptop-as-device.html)
Run this command to list the files in the `certs` directory and compare them to those listed in the table.
```
ls -l ~/certs
```
------
#### [ Windows ]
Run this command to create the `certs` subdirectory that you'll use when you run the sample applications.
```
mkdir %USERPROFILE%\certs
```
Into the new subdirectory, copy the files to the destination file paths shown in the following table.
**Certificate file names**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/using-laptop-as-device.html)
Run this command to list the files in the `certs` directory and compare them to those listed in the table.
```
dir %USERPROFILE%\certs
```
------
## Set up the policy and run the sample application
In this section, you'll set up your policy and run the `pubsub.py` sample script found in the `aws-iot-device-sdk-python-v2/samples` directory of the AWS IoT Device SDK for Python. This script shows how your device uses the MQTT library to publish and subscribe to MQTT messages.
The `pubsub.py` sample app subscribes to a topic, `test/topic`, publishes 10 messages to that topic, and displays the messages as they're received from the message broker.
To run the `pubsub.py` sample script, you need the following information:
**Application parameter values**
| Parameter | Where to find the value |
| --- | --- |
| your-iot-endpoint | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/using-laptop-as-device.html) |
The *your-iot-endpoint* value has a format of: `endpoint_id-ats.iot.region.amazonaws.com`, for example, `a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`.
Before running the script, make sure your thing's policy provides permissions for the sample script to connect, subscribe, publish, and receive.
**To find and review the policy document for a thing resource**
1. In the [AWS IoT console](https://console.aws.amazon.com//iot/home#/thinghub), in the **Things** list, find the thing resource that represents your device.
1. Choose the **Name** link of the thing resource that represents your device to open the **Thing details** page.
1. In the **Thing details** page, in the **Certificates** tab, choose the certificate that is attached to the thing resource. There should only be one certificate in the list. If there is more than one, choose the certificate whose files are installed on your device and that will be used to connect to AWS IoT Core.
In the **Certificate** details page, in the **Policies** tab, choose the policy that's attached to the certificate. There should only be one. If there is more than one, repeat the next step for each to make sure that at least one policy grants the required access.
1. In the **Policy** overview page, find the JSON editor and choose **Edit policy document** to review and edit the policy document as required.
1. The policy JSON is displayed in the following example. In the `"Resource"` element, replace `region:account` with your AWS Region and AWS account in each of the `Resource` values.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/test/topic"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/test/topic"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/test-*"
]
}
]
}
```
------
#### [ Linux/macOS ]
**To run the sample script on Linux/macOS**
1. In your command line window, navigate to the `~/aws-iot-device-sdk-python-v2/samples/node/pub_sub` directory that the SDK created by using these commands.
```
cd ~/aws-iot-device-sdk-python-v2/samples
```
1. In your command line window, replace *your-iot-endpoint* as indicated and run this command.
```
python3 pubsub.py --endpoint your-iot-endpoint --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key
```
------
#### [ Windows ]
**To run the sample app on a Windows PC**
1. In your command line window, navigate to the `%USERPROFILE%\aws-iot-device-sdk-python-v2\samples` directory that the SDK created and install the sample app by using these commands.
```
cd %USERPROFILE%\aws-iot-device-sdk-python-v2\samples
```
1. In your command line window, replace *your-iot-endpoint* as indicated and run this command.
```
python3 pubsub.py --endpoint your-iot-endpoint --ca_file %USERPROFILE%\certs\Amazon-root-CA-1.pem --cert %USERPROFILE%\certs\device.pem.crt --key %USERPROFILE%\certs\private.pem.key
```
------
The sample script:
1. Connects to the AWS IoT Core for your account.
1. Subscribes to the message topic, **test/topic**, and displays the messages it receives on that topic.
1. Publishes 10 messages to the topic, **test/topic**.
1. Displays output similar to the following:
```
Connected!
Subscribing to topic 'test/topic'...
Subscribed with QoS.AT_LEAST_ONCE
Sending 10 message(s)
Publishing message to topic 'test/topic': Hello World! [1]
Received message from topic 'test/topic': b'"Hello World! [1]"'
Publishing message to topic 'test/topic': Hello World! [2]
Received message from topic 'test/topic': b'"Hello World! [2]"'
Publishing message to topic 'test/topic': Hello World! [3]
Received message from topic 'test/topic': b'"Hello World! [3]"'
Publishing message to topic 'test/topic': Hello World! [4]
Received message from topic 'test/topic': b'"Hello World! [4]"'
Publishing message to topic 'test/topic': Hello World! [5]
Received message from topic 'test/topic': b'"Hello World! [5]"'
Publishing message to topic 'test/topic': Hello World! [6]
Received message from topic 'test/topic': b'"Hello World! [6]"'
Publishing message to topic 'test/topic': Hello World! [7]
Received message from topic 'test/topic': b'"Hello World! [7]"'
Publishing message to topic 'test/topic': Hello World! [8]
Received message from topic 'test/topic': b'"Hello World! [8]"'
Publishing message to topic 'test/topic': Hello World! [9]
Received message from topic 'test/topic': b'"Hello World! [9]"'
Publishing message to topic 'test/topic': Hello World! [10]
Received message from topic 'test/topic': b'"Hello World! [10]"'
10 message(s) received.
Disconnecting...
Disconnected!
```
If you're having trouble running the sample app, review [Troubleshoot problems with the sample application](gs-device-troubleshoot.md).
You can also add the `--verbosity Debug` parameter to the command line so the sample app displays detailed messages about what it’s doing. That information might help you correct the problem.
## View messages from the sample app in the AWS IoT console
You can see the sample app's messages as they pass through the message broker by using the **MQTT test client** in the **AWS IoT console**.
**To view the MQTT messages published by the sample app**
1. Review [View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md). This helps you learn how to use the **MQTT test client** in the **AWS IoT console** to view MQTT messages as they pass through the message broker.
1. Open the **MQTT test client** in the **AWS IoT console**.
1. In **Subscribe to a topic**, subscribe to the topic, **test/topic**.
1. In your command line window, run the sample app again and watch the messages in the **MQTT client** in the **AWS IoT console**.
------
#### [ Linux/macOS ]
```
cd ~/aws-iot-device-sdk-python-v2/samples
python3 pubsub.py --topic test/topic --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
```
------
#### [ Windows ]
```
cd %USERPROFILE%\aws-iot-device-sdk-python-v2\samples
python3 pubsub.py --topic test/topic --ca_file %USERPROFILE%\certs\Amazon-root-CA-1.pem --cert %USERPROFILE%\certs\device.pem.crt --key %USERPROFILE%\certs\private.pem.key --endpoint your-iot-endpoint
```
------
For more information about MQTT and how AWS IoT Core supports the protocol, see [MQTT](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html).
## Run the Shared Subscription example in Python
AWS IoT Core supports [Shared Subscriptions](mqtt.md#mqtt5-shared-subscription) for both MQTT 3 and MQTT 5. Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. To use Shared Subscriptions, clients subscribe to a Shared Subscription's [topic filter](https://docs.aws.amazon.com//iot/latest/developerguide/topics.html#topicfilters): `$share/{ShareName}/{TopicFilter}`.
**To set up the policy and run the Shared Subscription example**
1. To run the Shared Subscription example, you must set up your thing's policy as documented in [MQTT 5 Shared Subscription](https://github.com/aws/aws-iot-device-sdk-python-v2/blob/main/samples/mqtt5_shared_subscription.md#mqtt5-shared-subscription).
1. To run the Shared Subscription example, run the following commands.
------
#### [ Linux/macOS ]
**To run the sample script on Linux/macOS**
1. In your command line window, navigate to the `~/aws-iot-device-sdk-python-v2/samples` directory that the SDK created by using these commands.
```
cd ~/aws-iot-device-sdk-python-v2/samples
```
1. In your command line window, replace *your-iot-endpoint* as indicated and run this command.
```
python3 mqtt5_shared_subscription.py --endpoint your-iot-endpoint --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --group_identifier consumer
```
------
#### [ Windows ]
**To run the sample app on a Windows PC**
1. In your command line window, navigate to the `%USERPROFILE%\aws-iot-device-sdk-python-v2\samples` directory that the SDK created and install the sample app by using these commands.
```
cd %USERPROFILE%\aws-iot-device-sdk-python-v2\samples
```
1. In your command line window, replace *your-iot-endpoint* as indicated and run this command.
```
python3 mqtt5_shared_subscription.py --endpoint your-iot-endpoint --ca_file %USERPROFILE%\certs\Amazon-root-CA-1.pem --cert %USERPROFILE%\certs\device.pem.crt --key %USERPROFILE%\certs\private.pem.key --group_identifier consumer
```
------
**Note**
You can optionally specify a group identifier based on your needs when you run the sample (e.g., `--group_identifier consumer`). If you don't specify one, `python-sample` is the default group identifier.
1. The output in your command line can look like the following:
```
Publisher]: Lifecycle Connection Success
[Publisher]: Connected
Subscriber One]: Lifecycle Connection Success
[Subscriber One]: Connected
Subscriber Two]: Lifecycle Connection Success
[Subscriber Two]: Connected
[Subscriber One]: Subscribed to topic 'test/topic' in shared subscription group 'consumer'.
[Subscriber One]: Full subscribed topic is: '$share/consumer/test/topic' with SubAck code: []
[Subscriber Two]: Subscribed to topic 'test/topic' in shared subscription group 'consumer'.
[Subscriber Two]: Full subscribed topic is: '$share/consumer/test/topic' with SubAck code: []
[Publisher]: Sent publish and got PubAck code:
[Subscriber Two] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [1]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber One] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [2]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber Two] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [3]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber One] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [4]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber Two] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [5]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber One] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [6]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber Two] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [7]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber One] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [8]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber Two] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [9]"'
[Publisher]: Sent publish and got PubAck code:
[Subscriber One] Received a publish
Publish received message on topic: test/topic
Message: b'"Hello World! [10]"'
[Subscriber One]: Unsubscribed to topic 'test/topic' in shared subscription group 'consumer'.
[Subscriber One]: Full unsubscribed topic is: '$share/consumer/test/topic' with UnsubAck code: []
[Subscriber Two]: Unsubscribed to topic 'test/topic' in shared subscription group 'consumer'.
[Subscriber Two]: Full unsubscribed topic is: '$share/consumer/test/topic' with UnsubAck code []
Publisher]: Lifecycle Disconnected
[Publisher]: Lifecycle Stopped
[Publisher]: Fully stopped
Subscriber One]: Lifecycle Disconnected
[Subscriber One]: Lifecycle Stopped
[Subscriber One]: Fully stopped
Subscriber Two]: Lifecycle Disconnected
[Subscriber Two]: Lifecycle Stopped
[Subscriber Two]: Fully stopped
Complete!
```
1. Open **MQTT test client** in the **AWS IoT console**. In **Subscribe to a topic**, subscribe to the Shared Subscription’s topic such as: `$share/consumer/test/topic`. You can specify a group identifier based on your needs when you run the sample (e.g., `--group_identifier consumer`). If you don't specify a group identifier, the default value is `python-sample`. For more information, see [MQTT 5 Shared Subscription Python example](https://github.com/aws/aws-iot-device-sdk-python-v2/blob/main/samples/mqtt5_shared_subscription.md#mqtt5-shared-subscription) and [Shared Subscriptions](mqtt.md#mqtt5-shared-subscription) from *AWS IoT Core Developer Guide*.
In your command line window, run the sample app again and watch the distribution of messages in your **MQTT test client** of the **AWS IoT console** and the command line.
![\[The shared subscriptions output page.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/shared-subscription-output.png)
# Connect a Raspberry Pi or other device
In this section, we'll configure a Raspberry Pi for use with AWS IoT. If you have another device that you'd like to connect, the instructions for the Raspberry Pi include references that can help you adapt these instructions to your device.
This normally takes about 20 minutes, but it can take longer if you have many system software upgrades to install.
**Topics**
+ [
## Set up your device
](#gs-device-prereqs)
+ [
## Install the required tools and libraries for the AWS IoT Device SDK
](#gs-device-sdk-tools)
+ [
## Install AWS IoT Device SDK
](#gs-device-install-sdk)
+ [
## Install and run the sample app
](#gs-device-node-app-run)
+ [
## View messages from the sample app in the AWS IoT console
](#gs-device-view-msg)
**Important**
Adapting these instructions to other devices and operating systems can be challenging. You'll need to understand your device well enough to be able to interpret these instructions and apply them to your device.
If you encounter difficulties while configuring your device for AWS IoT, you might try one of the other device options as an alternative, such as [Create a virtual device with Amazon EC2](creating-a-virtual-thing.md) or [Use your Windows or Linux PC or Mac as an AWS IoT device](using-laptop-as-device.md).
## Set up your device
The goal of this step is to collect what you'll need to configure your device so that it can start the operating system (OS), connect to the internet, and allow you to interact with it at a command line interface.
To complete this tutorial, you need the following:
+ An AWS account. If you don't have one, complete the steps described in [Set up AWS account](setting-up.md) before you continue.
+ A [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/) or more recent model. This might work on earlier versions of the Raspberry Pi, but they have not been tested.
+ [Raspberry Pi OS (32-bit)](https://www.raspberrypi.com/software/operating-systems/) or later. We recommend using the latest version of the Raspberry Pi OS. Earlier versions of the OS might work, but they have not been tested.
To run this example, you do not need to install the desktop with the graphical user interface (GUI); however, if you're new to the Raspberry Pi and your Raspberry Pi hardware supports it, using the desktop with the GUI might be easier.
+ An Ethernet or WiFi connection.
+ Keyboard, mouse, monitor, cables, power supplies, and other hardware required by your device.
**Important**
Before you continue to the next step, your device must have its operating system installed, configured, and running. The device must be connected to the internet and you will need to be able to access the device by using its command line interface. Command line access can be through a directly-connected keyboard, mouse, and monitor, or by using an SSH terminal remote interface.
If you are running an operating system on your Raspberry Pi that has a graphical user interface (GUI), open a terminal window on the device and perform the following instructions in that window. Otherwise, if you are connecting to your device by using a remote terminal, such as PuTTY, open a remote terminal to your device and use that.
## Install the required tools and libraries for the AWS IoT Device SDK
Before you install the AWS IoT Device SDK and sample code, make sure your system is up to date and has the required tools and libraries to install the SDKs.
1.
**Update the operating system and install required libraries**
Before you install an AWS IoT Device SDK, run these commands in a terminal window on your device to update the operating system and install the required libraries.
```
sudo apt-get update
```
```
sudo apt-get upgrade
```
```
sudo apt-get install cmake
```
```
sudo apt-get install libssl-dev
```
1.
**Install Git**
If your device's operating system doesn't come with Git installed, you must install it to install the AWS IoT Device SDK for JavaScript.
1. Test to see if Git is already installed by running this command.
```
git --version
```
1. If the previous command returns the Git version, Git is already installed and you can skip to Step 3.
1. If an error is displayed when you run the **git** command, install Git by running this command.
```
sudo apt-get install git
```
1. Test again to see if Git is installed by running this command.
```
git --version
```
1. If Git is installed, continue to the next section. If not, troubleshoot and correct the error before continuing. You need Git to install the AWS IoT Device SDK for JavaScript.
## Install AWS IoT Device SDK
Install the AWS IoT Device SDK.
------
#### [ Python ]
In this section, you'll install Python, its development tools, and the AWS IoT Device SDK for Python on your device. These instructions are for a Raspberry Pi running the latest Raspberry Pi OS. If you have another device or are using another operating system, you might need to adapt these instructions for your device.
1.
**Install Python and its development tools**
The AWS IoT Device SDK for Python requires Python v3.5 or later to be installed on your Raspberry Pi.
In a terminal window to your device, run these commands.
1. Run this command to determine the version of Python installed on your device.
```
python3 --version
```
If Python is installed, it will display its version.
1. If the version displayed is `Python 3.5` or greater, you can skip to Step 2.
1. If the version displayed is less than `Python 3.5`, you can install the correct version by running this command.
```
sudo apt install python3
```
1. Run this command to confirm that the correct version of Python is now installed.
```
python3 --version
```
1.
**Test for pip3**
In a terminal window to your device, run these commands.
1. Run this command to see if **pip3** is installed.
```
pip3 --version
```
1. If the command returns a version number, **pip3** is installed and you can skip to Step 3.
1. If the previous command returns an error, run this command to install **pip3**.
```
sudo apt install python3-pip
```
1. Run this command to see if **pip3** is installed.
```
pip3 --version
```
1.
**Install the current AWS IoT Device SDK for Python**
Install the AWS IoT Device SDK for Python and download the sample apps to your device.
On your device, run these commands.
```
cd ~
python3 -m pip install awsiotsdk
```
```
git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git
```
------
#### [ JavaScript ]
In this section, you'll install Node.js, the npm package manager, and the AWS IoT Device SDK for JavaScript on your device. These instructions are for a Raspberry Pi running the Raspberry Pi OS. If you have another device or are using another operating system, you might need to adapt these instructions for your device.
1.
**Install the latest version of Node.js**
The AWS IoT Device SDK for JavaScript requires Node.js and the npm package manager to be installed on your Raspberry Pi.
1. Download the latest version of the Node repository by entering this command.
```
cd ~
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
```
1. Install Node and npm.
```
sudo apt-get install -y nodejs
```
1. Verify the installation of Node.
```
node -v
```
Confirm that the command displays the Node version. This tutorial requires Node v10.0 or later. If the Node version isn't displayed, try downloading the Node repository again.
1. Verify the installation of npm.
```
npm -v
```
Confirm that the command displays the npm version. If the npm version isn't displayed, try installing Node and npm again.
1. Restart the device.
```
sudo shutdown -r 0
```
Continue after the device restarts.
1.
**Install the AWS IoT Device SDK for JavaScript**
Install the AWS IoT Device SDK for JavaScript on your Raspberry Pi.
1. Clone the AWS IoT Device SDK for JavaScript repository into the `aws-iot-device-sdk-js-v2` directory of your *home* directory. On the Raspberry Pi, the *home* directory is `~/`, which is used as the *home* directory in the following commands. If your device uses a different path for the *home* directory, you must replace `~/` with the correct path for your device in the following commands.
These commands create the `~/aws-iot-device-sdk-js-v2` directory and copy the SDK code into it.
```
cd ~
git clone https://github.com/aws/aws-iot-device-sdk-js-v2.git
```
1. Change to the `aws-iot-device-sdk-js-v2` directory that you created in the preceding step and run `npm install` to install the SDK. The command `npm install` will invoke the `aws-crt` library build that can take a few minutes to complete.
```
cd ~/aws-iot-device-sdk-js-v2
npm install
```
------
## Install and run the sample app
In this section, you'll install and run the `pubsub` sample app found in the AWS IoT Device SDK. This app shows how your device uses the MQTT library to publish and subscribe to MQTT messages. The sample app subscribes to a topic, `topic_1`, publishes 10 messages to that topic, and displays the messages as they're received from the message broker.
**Install the certificate files**
The sample app requires the certificate files that authenticate the device to be installed on the device.
**To install the device certificate files for the sample app**
1. Create a `certs` subdirectory in your *home* directory by running these commands.
```
cd ~
mkdir certs
```
1. Into the `~/certs` directory, copy the private key, device certificate, and root CA certificate that you created earlier in [Create AWS IoT resources](create-iot-resources.md).
How you copy the certificate files to your device depends on the device and operating system and isn't described here. However, if your device supports a graphical user interface (GUI) and has a web browser, you can perform the procedure described in [Create AWS IoT resources](create-iot-resources.md) from your device's web browser to download the resulting files directly to your device.
The commands in the next section assume that your key and certificate files are stored on the device as shown in this table.
**Certificate file names**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/connecting-to-existing-device.html)
To run the sample app, you need the following information:
**Application parameter values**
| Parameter | Where to find the value |
| --- | --- |
| your-iot-endpoint | In the [AWS IoT console](https://console.aws.amazon.com/iot/home), choose **All devices**, and then choose **Things**. On the **Settings** page in the AWS IoT menu. Your endpoint is displayed in the **Device data endpoint** section. |
The *your-iot-endpoint* value has a format of: `endpoint_id-ats.iot.region.amazonaws.com`, for example, `a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`.
------
#### [ Python ]
**To install and run the sample app**
1. Navigate to the sample app directory.
```
cd ~/aws-iot-device-sdk-python-v2/samples
```
1. In the command line window, replace *your-iot-endpoint* as indicated and run this command.
```
python3 pubsub.py --topic topic_1 --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
```
1. Observe that the sample app:
1. Connects to the AWS IoT service for your account.
1. Subscribes to the message topic, **topic\$11**, and displays the messages it receives on that topic.
1. Publishes 10 messages to the topic, **topic\$11**.
1. Displays output similar to the following:
```
Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'...
Connected!
Subscribing to topic 'topic_1'...
Subscribed with QoS.AT_LEAST_ONCE
Sending 10 message(s)
Publishing message to topic 'topic_1': Hello World! [1]
Received message from topic 'topic_1': b'Hello World! [1]'
Publishing message to topic 'topic_1': Hello World! [2]
Received message from topic 'topic_1': b'Hello World! [2]'
Publishing message to topic 'topic_1': Hello World! [3]
Received message from topic 'topic_1': b'Hello World! [3]'
Publishing message to topic 'topic_1': Hello World! [4]
Received message from topic 'topic_1': b'Hello World! [4]'
Publishing message to topic 'topic_1': Hello World! [5]
Received message from topic 'topic_1': b'Hello World! [5]'
Publishing message to topic 'topic_1': Hello World! [6]
Received message from topic 'topic_1': b'Hello World! [6]'
Publishing message to topic 'topic_1': Hello World! [7]
Received message from topic 'topic_1': b'Hello World! [7]'
Publishing message to topic 'topic_1': Hello World! [8]
Received message from topic 'topic_1': b'Hello World! [8]'
Publishing message to topic 'topic_1': Hello World! [9]
Received message from topic 'topic_1': b'Hello World! [9]'
Publishing message to topic 'topic_1': Hello World! [10]
Received message from topic 'topic_1': b'Hello World! [10]'
10 message(s) received.
Disconnecting...
Disconnected!
```
If you're having trouble running the sample app, review [Troubleshoot problems with the sample application](gs-device-troubleshoot.md).
You can also add the `--verbosity Debug` parameter to the command line so the sample app displays detailed messages about what it’s doing. That information might provide you the help you need to correct the problem.
------
#### [ JavaScript ]
**To install and run the sample app**
1. In your command line window, navigate to the `~/aws-iot-device-sdk-js-v2/samples/node/pub_sub` directory that the SDK created and install the sample app by using these commands. The command `npm install` will invoke the `aws-crt` library build that can take a few minutes to complete.
```
cd ~/aws-iot-device-sdk-js-v2/samples/node/pub_sub
npm install
```
1. In the command line window, replace *your-iot-endpoint* as indicated and run this command.
```
node dist/index.js --topic topic_1 --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
```
1. Observe that the sample app:
1. Connects to the AWS IoT service for your account.
1. Subscribes to the message topic, **topic\$11**, and displays the messages it receives on that topic.
1. Publishes 10 messages to the topic, **topic\$11**.
1. Displays output similar to the following:
```
Publish received on topic topic_1
{"message":"Hello world!","sequence":1}
Publish received on topic topic_1
{"message":"Hello world!","sequence":2}
Publish received on topic topic_1
{"message":"Hello world!","sequence":3}
Publish received on topic topic_1
{"message":"Hello world!","sequence":4}
Publish received on topic topic_1
{"message":"Hello world!","sequence":5}
Publish received on topic topic_1
{"message":"Hello world!","sequence":6}
Publish received on topic topic_1
{"message":"Hello world!","sequence":7}
Publish received on topic topic_1
{"message":"Hello world!","sequence":8}
Publish received on topic topic_1
{"message":"Hello world!","sequence":9}
Publish received on topic topic_1
{"message":"Hello world!","sequence":10}
```
If you're having trouble running the sample app, review [Troubleshoot problems with the sample application](gs-device-troubleshoot.md).
You can also add the `--verbosity Debug` parameter to the command line so the sample app displays detailed messages about what it’s doing. That information might provide you the help you need to correct the problem.
------
## View messages from the sample app in the AWS IoT console
You can see the sample app's messages as they pass through the message broker by using the **MQTT test client** in the **AWS IoT console**.
**To view the MQTT messages published by the sample app**
1. Review [View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md). This helps you learn how to use the **MQTT test client** in the **AWS IoT console** to view MQTT messages as they pass through the message broker.
1. Open the **MQTT test client** in the **AWS IoT console**.
1. Subscribe to the topic, **topic\$11**.
1. In your command line window, run the sample app again and watch the messages in the **MQTT client** in the **AWS IoT console**.
------
#### [ Python ]
```
cd ~/aws-iot-device-sdk-python-v2/samples
python3 pubsub.py --topic topic_1 --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
```
------
#### [ JavaScript ]
```
cd ~/aws-iot-device-sdk-js-v2/samples/node/pub_sub
node dist/index.js --topic topic_1 --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
```
------
# Troubleshoot problems with the sample application
If you encounter an error when you try to run the sample app, here are some things to check.
## Check the certificate
If the certificate is not active, AWS IoT will not accept any connection attempts that use it for authorization. When creating your certificate, it's easy to overlook the **Activate** button. Fortunately, you can activate your certificate from the [AWS IoT console](https://console.aws.amazon.com/iot/home).
**To check your certificate's activation**
1. In the [AWS IoT console](https://console.aws.amazon.com/iot/home), in the left menu, choose **Secure**, and then choose **Certificates**.
1. In the list of certificates, find the certificate you created for the exercise and check its status in the **Status** column.
If you don't remember the certificate's name, check for any that are **Inactive** to see if they might be the one you're using.
Choose the certificate in the list to open its detail page. In the detail page, you can see its **Create date** to help you identify the certificate.
1. **To activate an inactive certificate**, from the certificate's detail page, choose **Actions** and then choose **Activate**.
If you found the correct certificate and it's active, but you're still having problems running the sample app, check its policy as the next step describes.
You can also try to create a new thing and a new certificate by following the steps in [Create a thing object](create-iot-resources.md#create-aws-thing). If you create a new thing, you will need to give it a new thing name and download the new certificate files to your device.
## Check the policy attached to the certificate
Policies authorize actions in AWS IoT. If the certificate used to connect to AWS IoT does not have a policy, or does not have a policy that allows it to connect, the connection will be refused, even if the certificate is active.
**To check the policies attached to a certificate**
1. Find the certificate as described in the previous item and open its details page.
1. In the left menu of the certificate's details page, choose **Policies** to see the policies attached to the certificate.
1. If there are no policies attached to the certificate, add one by choosing the **Actions** menu, and then choosing **Attach policy**.
Choose the policy that you created earlier in [Create AWS IoT resources](create-iot-resources.md).
1. If there is a policy attached, choose the policy tile to open its details page.
In the details page, review the **Policy document** to make sure it contains the same information as the one you created in [Create an AWS IoT policy](create-iot-resources.md#create-iot-policy).
## Check the command line
Make sure you used the correct command line for your system. The commands used on Linux and macOS systems are often different from those used on Windows systems.
## Check the endpoint address
Review the command you entered and double-check the endpoint address in your command to the one in your [AWS IoT console](https://console.aws.amazon.com/iot/home).
## Check the file names of the certificate files
Compare the file names in the command you entered to the file names of the certificate files in the `certs` directory.
Some systems might require the file names to be in quotes to work correctly.
## Check the SDK installation
Make sure that your SDK installation is complete and correct.
If in doubt, reinstall the SDK on your device. In most cases, that's a matter of finding the section of the tutorial titled **Install the AWS IoT Device SDK for **SDK language**** and following the procedure again.
If you are using the **AWS IoT Device SDK for JavaScript**, remember to install the sample apps before you try to run them. Installing the SDK doesn't automatically install the sample apps. The sample apps must be installed manually after the SDK has been installed.
# View MQTT messages with the AWS IoT MQTT client
This section describes how to use the AWS IoT MQTT test client in the [AWS IoT console](https://console.aws.amazon.com/iot/home) to watch the MQTT messages sent and received by AWS IoT. The example used in this section relates to the examples used in [Getting started with AWS IoT Core tutorials](iot-gs.md); however, you can replace the *topicName* used in the examples with any [topic name or topic filter](topics.md) used by your IoT solution.
Devices publish MQTT messages that are identified by [topics](topics.md) to communicate their state to AWS IoT, and AWS IoT publishes MQTT messages to inform the devices and apps of changes and events. You can use the MQTT client to subscribe to these topics and watch the messages as they occur. You can also use the MQTT test client to publish MQTT messages to subscribed devices and services in your AWS account.
**Topics**
+ [
## Viewing MQTT messages in the MQTT client
](#view-mqtt-subscribe)
+ [
## Publishing MQTT messages from the MQTT client
](#view-mqtt-publish)
+ [
## Testing Shared Subscriptions in the MQTT client
](#view-mqtt-shared-subscriptions)
## Viewing MQTT messages in the MQTT client
The following procedure explains how to subscribe to a specific MQTT topic that your device publishes messages to and view those messages in the [AWS IoT console](https://console.aws.amazon.com/iot/home).
**To view MQTT messages in the MQTT test client**
1. In the [AWS IoT console](https://console.aws.amazon.com/iot/home), in the left menu, choose **Test** and then choose **MQTT test client**.
![\[Choose MQTT test client from the console menu on the left navigation.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/choose-test.png)
1. In the **Subscribe to a topic** tab, enter the *topicName* to subscribe to the topic on which your device publishes. For the getting started sample app, subscribe to **\$1**, which subscribes to all message topics.
Continuing with the getting started example, on the **Subscribe to a topic** tab, in the **Topic filter** field, enter **\$1**, and then choose **Subscribe**.
![\[The subscribe to a topic tab.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/subscribe-button-topic.png)
The topic message log page, **\$1** opens and **\$1** appears in the **Subscriptions** list. If the device that you configured in [Configure your device](configure-device.md) is running the example program, you should see the messages it sends to AWS IoT in the **\$1** message log. The message log entries will appear below the **Publish** section when messages with the subscribed topic are received by AWS IoT.
![\[The section to show the topic has been subscribed successfully.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/subscribed-button-topic.png)
1. On the **\$1** message log page, you can also publish messages to a topic, but you'll need to specify the topic name. You cannot publish to the **\$1** topic.
Messages published to subscribed topics appear in the message log as they are received, with the most recent message first.
### Troubleshooting MQTT messages
**Use the wild card topic filter**
If your messages are not showing up in the message log as you expect, try subscribing to a wild card topic filter as described in [Topic name filters](topics.md#topicfilters). The MQTT multi-level wild card topic filter is the hash or pound sign ( `#` ) and can be used as the topic filter in the **Subscription topic** field.
Subscribing to the `#` topic filter subscribes to every topic received by the message broker. You can narrow the filter down by replacing elements of the topic filter path with a `#` multi-level wild card character or the '\$1' single-level wild-card character.
**When using wild cards in a topic filter**
+ The multi-level wild card character must be the last character in the topic filter.
+ The topic filter path can have only one single-level wild card character per topic level.
For example:
| Topic filter | Displays messages with |
| --- | --- |
| `#` | Any topic name |
| `topic_1/#` | A topic name that starts with `topic_1/` |
| `topic_1/level_2/#` | A topic name that starts with `topic_1/level_2/` |
| `topic_1/+/level_3` | A topic name that starts with `topic_1/`, ends with `/level_3`, and has one element of any value in between. |
For more information on topic filters, see [Topic name filters](topics.md#topicfilters).
**Check for topic name errors**
MQTT topic names and topic filters are case sensitive. If, for example, your device is publishing messages to `Topic_1` (with a capital *T*) instead of `topic_1`, the topic to which you subscribed, its messages would not appear in the MQTT test client. Subscribing to the wild card topic filter, however would show that the device is publishing messages and you could see that it was using a topic name that was not the one you expected.
## Publishing MQTT messages from the MQTT client
**To publish a message to an MQTT topic**
1. On the MQTT test client page, in the **Publish to a topic** tab, in the **Topic name** field, enter the *topicName* of your message. In this example, use **my/topic**.
**Note**
Do not use personally identifiable information in topic names, whether using them in the MQTT test client or in your system implementation. Topic names can appear in unencrypted communications and reports.
1. In the message payload window, enter the following JSON:
```
{
"message": "Hello, world",
"clientType": "MQTT test client"
}
```
1. Choose **Publish** to publish your message to AWS IoT.
**Note**
Make sure you are subscribed to the **my/topic** topic before publishing your message.
![\[The publish to a topic tab.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/publish-to-topic.png)
1. In the **Subscriptions** list, choose **my/topic** to see the message. You should see the message appear in the MQTT test client below the publish message payload window.
![\[The screen that shows the published topic has been received.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/publish-to-topic-received.png)
You can publish MQTT messages to other topics by changing the *topicName* in the **Topic name** field and choosing the **Publish** button.
**Important**
When you create multiple subscriptions with overlapping topics (e.g., probe1/temperature and probe1/\$1), there is a possibility that a single message published to a topic matching both subscriptions will be delivered multiple times, once for each overlapping subscription.
## Testing Shared Subscriptions in the MQTT client
This section describes how to use the AWS IoT MQTT client in the [AWS IoT console](https://console.aws.amazon.com/iot/home) to watch the MQTT messages sent and received by AWS IoT using Shared Subscriptions. [Shared subscriptions](mqtt.md#mqtt5-shared-subscription) allow multiple clients to share a subscription to a topic with only one client receiving messages published to that topic using a random distribution. To simulate multiple MQTT clients (in this example, two MQTT clients) sharing the same subscription, you open the AWS IoT MQTT client in the [AWS IoT console](https://console.aws.amazon.com/iot/home) from multiple web browsers. The example used in this section doesn't relate to the examples used in [Getting started with AWS IoT Core tutorials](iot-gs.md). For more information, see [Shared Subscriptions](mqtt.md#mqtt5-shared-subscription).
**To share a subscription to an MQTT topic**
1. In the [AWS IoT console](https://console.aws.amazon.com/iot/home), in the navigation pane, choose **Test** and then choose **MQTT test client**.
1. In the **Subscribe to a topic** tab, enter the *topicName* to subscribe to the topic on which your device publishes. To use Shared Subscriptions, subscribe to a Shared Subscription's topic filter as follows:
```
$share/{ShareName}/{TopicFilter}
```
An example topic filter can be **\$1share/group1/topic1**, which subscribes to the message topic **topic1**.
![\[The tab that shows how to specify a topic filter for shared subscriptions.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/shared-subscription-topicfilter.png)
1. Open another web browser and repeat step1 and step2. In this way, you are simulating two different MQTT clients that share the same subscription **\$1share/group1/topic1**.
1. Choose one MQTT client, in the **Publish to a topic** tab, in the **Topic name** field, enter the *topicName* of your message. In this example, use **topic1**. Try publishing the message a few times. From the **Subscriptions** list of both MQTT clients, you should be able to see that the clients receive the message using a random distribution. In this example, we publish the same message "Hello from AWS IoT console" three times. The MQTT client on the left received the message twice and the MQTT client on the right received the message once.
![\[The shared subscriptions flow with two clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/shared_subscriptions_test.gif)