# Try the AWS IoT Core quick connect tutorial 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 Test connectivity 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.