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 before you continue.
In this tutorial, you'll:
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 to be more helpful.
To launch an instance
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/
. -
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.
-
In the Name and tags section, enter a name for the instance and optionally add tags.
-
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."
-
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. -
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.
-
In the Network settings section and the Configure storage section, you can keep the default settings. When you are ready, choose Launch instances.
-
A confirmation page lets you know that your instance is launching. Choose View Instances to close the confirmation page and return to the console.
-
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 torunning
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).) -
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.
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/
. -
On the left menu, choose Instances.
-
Select the instance and choose Connect.
-
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
-
In your Amazon EC2 Instance Connect window, update your instance by using the following command.
sudo yum update -y
-
In your Amazon EC2 Instance Connect window, install Git by using the following command.
sudo yum install git -y
-
To check if Git has been installed and the current version of Git, run the following command:
git --version
To install Node.js
-
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.
-
In your Amazon EC2 Instance Connect window, activate nvm by using this command.
. ~/.nvm/nvm.sh
-
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.
-
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.
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.
-
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
. 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
-
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.
-
In your Amazon EC2 Instance Connect window, run the following command to create your thing object.
aws iot create-thing --thing-name "MyIotThing"
-
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
-
In your Amazon EC2 Instance Connect window, create a directory to store your certificate and key files.
mkdir ~/certs
-
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
-
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" } } -
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
-
In your Amazon EC2 Instance Connect window, create the policy file by copying and pasting this policy document to a file named
~/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": [ "*" ] } ] }
-
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:
your-region
: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" } -
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
To install the AWS IoT Device SDK for JavaScript on your Linux instance
-
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
-
Navigate to the
aws-iot-device-sdk-js-v2
directory that you created in the preceding step.cd aws-iot-device-sdk-js-v2
-
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 |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Device certificate |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Root CA certificate |
|
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
-
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
-
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
-
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:
-
Connects to AWS IoT Core for your account.
-
Subscribes to the message topic, topic_1, and displays the messages it receives on that topic.
-
Publishes 10 messages to the topic, topic_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.
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
-
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.
-
Open the MQTT test client in the AWS IoT console.
-
In Subscribe to a topic, Subscribe to the topic, topic_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.