2  AWS Setup

We prepare what the virtual device needs to connect to AWS IoT Core. Four things are required.

Item Role
Thing Registration of the device. There is one Shadow per Thing
Certificate and private key The device’s identity. Used for the MQTT connection (TLS)
Policy What the certificate is allowed to do (which topics it may send to and receive from)
Endpoint Where to connect. A URL that differs for each account

2.1 Preparing Python and the AWS CLI

Work in code/, extracted from code.zip.

cd code
python3 -m venv .venv
source .venv/bin/activate          # on Windows: .venv\Scripts\activate
pip install -r requirements.txt    # paho-mqtt and boto3

aws sts get-caller-identity        # confirm the AWS CLI works

2.2 Running the creation script

bash setup/create_thing.sh                  # Thing name defaults to handson-aircon-01
bash setup/create_thing.sh my-aircon        # to specify a name

Resources are created in the Tokyo region (ap-northeast-1). For a different region, specify it like AWS_REGION=us-east-1 bash setup/create_thing.sh. When it finishes, the certificate and private key are in certs/ and the connection information is in device/config.json.

Let’s go through the script step by step.

2.2.1 Create the Thing

aws iot create-thing --thing-name "${THING}" --region "${REGION}"

2.2.2 Create the certificate and private key

aws iot create-keys-and-certificate --set-as-active --region "${REGION}" \
  --certificate-pem-outfile certs/device.pem.crt \
  --private-key-outfile certs/private.pem.key
WarningThe private key can be obtained only at this moment, and if it leaks anyone can impersonate the device
  • The private key can be downloaded only once, at creation time. If you lose it, recreate the certificate
  • Do not commit certs/ to Git (put it in .gitignore). On the ESP32, likewise keep it in a separate file such as secrets.h that is excluded from version control

We also download the root CA certificate (AmazonRootCA1.pem), used to verify that the AWS side is genuine.

2.2.3 Restrict “what is allowed” with a policy

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "iot:Connect",
      "Resource": "arn:aws:iot:<region>:<account>:client/<thing>*" },
    { "Effect": "Allow", "Action": ["iot:Publish", "iot:Receive"],
      "Resource": "arn:aws:iot:<region>:<account>:topic/$aws/things/<thing>/shadow/*" },
    { "Effect": "Allow", "Action": "iot:Subscribe",
      "Resource": "arn:aws:iot:<region>:<account>:topicfilter/$aws/things/<thing>/shadow/*" }
  ]
}
  • iot:Connect: only allow connections whose client ID starts with the Thing name
  • iot:Publish / iot:Receive: can send to and receive from only this Thing’s Shadow topics
  • iot:Subscribe: subscriptions are specified by a topic filter (topicfilter/), not a topic

Avoid "Action": "iot:*", "Resource": "*", which you often see in examples online: if the certificate leaks, every device in the same account can be operated.

TipA shell pitfall (one we actually fell into)

In zsh, writing "arn:aws:iot:$REGION:$ACCOUNT:client/..." causes $ACCOUNT:c to be interpreted as a zsh modifier, breaking the ARN (MalformedPolicyException). Either wrap variables in braces like ${ACCOUNT}, or run the script with bash.

2.2.4 Attach to the certificate

aws iot attach-policy --policy-name "${POLICY}" --target "${CERT_ARN}"
aws iot attach-thing-principal --thing-name "${THING}" --principal "${CERT_ARN}"

2.2.5 Look up the endpoint

aws iot describe-endpoint --endpoint-type iot:Data-ATS
# xxxxxxxxxxxxxx-ats.iot.ap-northeast-1.amazonaws.com

This endpoint is used for the device’s MQTT connection. The device must always specify it.

For SDKs that read and write the Shadow from the cloud side (send.py, or iot-data in Lambda), specifying it is optional. Current boto3, AWS CLI and JavaScript SDK v3 use the region-wide data-ats.iot.<region>.amazonaws.com if it is not specified, and that works as is (measured). send.py specifies the account-specific endpoint to make it clear that it connects to the same place as the device.

2.3 Cleaning up what you created

When you finish the hands-on, be sure to delete everything.

bash setup/cleanup.sh

Deletion proceeds in the order Shadow → detach the certificate → deactivate and delete the certificate → policy → Thing. A certificate cannot be deleted while it is active (ACTIVE), so it is first made inactive (INACTIVE).

ImportantSummary of this chapter
  • Connecting requires a Thing, a certificate and private key, a policy, and an endpoint
  • Restrict the policy to only that Thing’s Shadow topics
  • The private key can be obtained only once; do not commit it
  • When finished, delete everything with cleanup.sh