4. (Optional) If you want to see the messages from your IoT client in the AWS IoT console, open the MQTT test client 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/1. For more information about topic subscription and publish, see the code example of your chosen SDK.
5. After you subscribe to the test topic, run ./start.sh on your device. For more information, see the section called “View MQTT messages with the AWS IoT MQTT client” (p. 65).
After you run ./start.sh, messages appear in the MQTT client, similar to the following:
{ "message": "Hello World!", "sequence": 10
}
The sequence number increments by one each time a new Hello World message is received and stops when you end the program.
6. To finish the tutorial and see a summary, in the AWS IoT console, choose Done.
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 client
From the AWS IoT console, you can open the MQTT client on the Test page of the AWS IoT console. In the MQTT client, subscribe to #, and then, on your device, run the program ./start.sh as described in
Testing connectivity with your device data endpoint
the previous step. For more information, see the section called “View MQTT messages with the AWS IoT MQTT client” (p. 65).
• Run tests on your devices with Device Advisor
Use Device Advisor to test if your devices can securely and reliably connect to, and interact with, AWS IoT.
• the section called “Try the AWS IoT Core interactive demo” (p. 19)
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 (p. 37)
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 services in hands-on tutorial (p. 37).
Testing 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.
To test a device's connectivity with your device data endpoint
• Find your device data endpoint (p. 33)
• Test the connection quickly (p. 33)
• Get the app to test the connection to your device data endpoint and port (p. 34)
• Test the connection to your device data endpoint and port (p. 36)
Find your device data endpoint
To find your device data endpoint
1. In the AWS IoT console, near the bottom of the navigation pane, chooseSettings.
2. In the Settings page, in the Device data endpoint container, locate the Endpoint value and copy it.
3. Your endpoint value is unique to your AWS account and is similar to this example:
a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com.
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 know 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 (p. 34).
Testing connectivity with your device data endpoint
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.
ping -c 5 a3qEXAMPLEsffp-ats.iot.eu-west-1.amazonaws.com
2. 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 (p. 34).
3. 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
2. If you see an output similar to the following, nmap is installed and you can continue to the section called “Test the connection to your device data endpoint and port” (p. 36).
Nmap version 6.40 ( http://nmap.org ) Platform: x86_64-koji-linux-gnu
Compiled with: 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
3. 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.
Testing connectivity with your device data endpoint
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.
a. Debian or Ubuntu:
sudo apt install nmap b. CentOS or RHEL:
sudo yum install nmap
2. Test the installation with this command:
nmap --version
3. If you see an output similar to the following, nmap is installed and you can continue to the section called “Test the connection to your device data endpoint and port” (p. 36).
Nmap version 6.40 ( http://nmap.org ) Platform: x86_64-koji-linux-gnu
Compiled with: 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#macosx and download the latest stable installer.
When prompted, select Open with DiskImageInstaller.
2. In the installation window, move the package to the Applications folder.
3. 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.
4. Review the security dialog box. If you are ready to install nmap, choose Open to install nmap.
5. In Terminal, test the installation with this command.
nmap --version
6. If you see an output similar to the following, nmap is installed and you can continue to the section called “Test the connection to your device data endpoint and port” (p. 36).
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:
Testing connectivity with your device data endpoint
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#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.
2. After the setup file finishes downloading, open downloaded nmap-xxxx-setup.exe to install the app.
3. 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.
4. In Command, test the installation with this command.
nmap --version
5. If you see an output similar to the following, nmap is installed and you can continue to the section called “Test the connection to your device data endpoint and port” (p. 36).
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
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
2. 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)
Explore AWS IoT Core services in hands-on tutorial
Nmap done: 1 IP address (1 host up) scanned in 0.91 seconds
3. 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 services in hands-on tutorial
In this tutorial, you'll install the software and create the AWS IoT resources necessary to connect a device to AWS IoT 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.
This tutorial is best for developers who want to get started with AWS IoT so they can continue to explore more advanced features, such as the rules engine and shadows. 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. If you are looking for just a quick, Hello World, experience, try the Try the AWS IoT quick connect (p. 23).
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.
Next steps
• Choose which device option is the best for you (p. 38)
• the section called “Create AWS IoT resources” (p. 38) if you are not going to create a virtual device with Amazon EC2.
• the section called “Configure your device” (p. 41)
• the section called “View MQTT messages with the AWS IoT MQTT client” (p. 65)
For more information about AWS IoT Core, see What Is AWS IoT Core (p. 1)?
Which device option is the best for you?
Which device option is the 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:
the section called “Create a virtual device with Amazon EC2” (p. 42)
• You don't have your own device to test.
• You don't want to install any software on your own system.
• You want to test on a Linux OS.
• You're not comfortable using command-line commands.
• You don't want to incur any additional AWS charges.
• You don't want to test on a Linux OS.
the section called “Use your Windows or Linux PC or Mac as an AWS IoT device” (p. 50)
• You don't want to incur any additional AWS charges.
• You don't want to configure any additional devices.
• You don't want to install any software on your personal computer.
• You want a more
representative test platform.
the section called “Connect a Raspberry Pi or another device” (p. 56)
• You want to test AWS IoT with an actual device.
• You already have a device to test with.
• You have experience integrating hardware into systems.
• You don't want to buy or configure a device just to try it out.
• You want to test AWS IoT as simply as possible, for now.
Create AWS IoT resources
In this tutorial, you'll create the AWS IoT resources that a device requires to connect to AWS IoT and exchange messages.
Create AWS IoT resources
1. Create an AWS IoT policy document, which will authorize your device to interact with AWS IoT services.
2. 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 the section called “Create a virtual device with Amazon EC2” (p. 42), you can skip this page and continue to the section called “Configure your device” (p. 41).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. On the left menu, choose Secure, and then choose Policies. On the You don't have a policy yet page, choose Create policy.
Create AWS IoT resources
If your account has existing policies, choose Create.
2. 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_Iot_Policy). Don't use personally identifiable information in your policy names.
2. 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 *. A * 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.
Note
In this quick start, the wildcard (*) 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.3. After you've entered the information for your policy, choose Create.
For more information, see IAM managed policies (p. 388).
Create a thing object
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. 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, in the left menu, choose Manage, then choose Things.
2. On the Things page, choose Create things.
3. On the Create things page, choose Create a single thing, then choose Next.
4. On the Specify thing properties page, for Thing name, enter a name for your thing, such as MyIotThing.
Configure your device
When naming things, choose the name carefully, because you can't change a thing name after you create it.
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.
5. Keep the rest of the fields on this page empty. Choose Next.
6. On the Configure device certificate - optional page, choose Auto-generate a new certificate (recommended). Choose Next.
7. 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_Iot_Policy. Choose Create thing.
8. 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
When you save your certificate files, give them the names in the following table. These are the file