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, which installs all software on a virtual machine.

In this tutorial, you'll:

• Set up your personal computer
• Install Git, Python, and the AWS IoT Device SDK for Python
• Set up the policy and run the sample application
• View messages from the sample app in the AWS IoT console
• Run the Shared Subscription example in Python

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

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

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.

python -V

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

cd ~ git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git

echo %USERPROFILE% cd %USERPROFILE% git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git

Note

 echo $home

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. 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.

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.

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:

Where to find the value

1. In the AWS IoT console , in the left menu, choose Settings.
2. On the Settings page, 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 .

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 , in the Things list, find the thing resource that represents your device.
2. Choose the Name link of the thing resource that represents your device to open the Thing details page.
3. 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.
4. In the Policy overview page, find the JSON editor and choose Edit policy document to review and edit the policy document as required.
5. 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:region:account:topic/test/topic" ] >,  "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/test/topic" ] >,  "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "arn:aws:iot:region:account:client/test-*" ] > ] >

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

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

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

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.
2. Subscribes to the message topic, test/topic, and displays the messages it receives on that topic.
3. Publishes 10 messages to the topic, test/topic.
4. 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 Troubleshooting problems with the sample app.

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. 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.
2. Open the MQTT test client in the AWS IoT console.
3. In Subscribe to a topic, subscribe to the topic, test/topic.
4. 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

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.

Run the Shared Subscription example in Python

AWS IoT Core supports Shared Subscriptions 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: $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 .
2. 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

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

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

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.

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!