AWS IoT CLI on Raspberry Pi

Pradeep Singh | 28th Feb 2017

The AWS Command Line Interface (CLI) is a unified tool that allows you to control AWS services from the command line. If you are testing AWS IoT with Raspberry Pi and don’t want to create AWS IoT objects using GUI interface, give a try to AWS CLI. It’s simple and well documented.

Let’s explore how to install, configure and use AWS IoT CLI on Raspberry Pi.

1. AWS Account:

Before you begin make sure you have an AWS Account. If you don’t have one, register at this Link. I would recommend creating a separate user for CLI access from “Identity and Access Management” or “IAM” module of your AWS account.

The AWS CLI User must have “Programmatic access” (You will see this option while creating user) so that you can get hold of “Access Key ID” and “Secret Access Key“.

AWS CLI User must have “AWSIoTDataAccess” permission if you want to have read/write permission from CLI.

2. Install AWS CLI:

SSH into Raspberry Pi and install AWS CLI using following pip command –

sudo pip install awscli

3. CLI Command Completion:

AWS CLI includes command completion feature but it is not installed by default. Use following command to install command completion feature on Raspberry Pi’s CLI interface –

complete -C aws_completer aws

4. Configure AWS CLI with AWS Credentials:

You need to configure AWS CLI with Access Key ID,  Secret Access Key, AWS Region Name and Command Output format before getting started with it.

Refer to Step 1 (AWS Account) for your Access Key ID and  Secret Access Key.

For AWS Region Name Refer to following –

http://docs.aws.amazon.com/general/latest/gr/rande.html#iot_region

Select the AWS Region near to your geographic location. For example, if you are using Frankfurt DC you Region Name will be “eu-central-1“.

Select “json” as default output format, as it’s easier to parse compared to plain text.

Once you have this information execute “aws configure” command on your Raspberry Pi –

pi@raspberrypi:~ $ aws configure
AWS Access Key ID [None]: "Put your User's Access Key ID here"
AWS Secret Access Key [None]: "Put your User's Secret Access Key here"
Default region name [None]: eu-central-1
Default output format [None]: json
pi@raspberrypi:~ $

5. Test Connection with AWS:

To test the CLI connection, try to execute any aws list command. For example, to list all your IoT Things you can execute “aws iot list-things” command. If you have any IoT Thing configured on AWS, you should see something like following output –

pi@raspberrypi:~ $ aws iot list-things
{
    "things": [
        {
            "thingTypeName": "RaspberryPi", 
            "attributes": {}, 
            "version": 2, 
            "thingName": "Ra-Pi-3"
        }
    ]
}
pi@raspberrypi:~ $

If you don’t have any IoT Thing configured on AWS, you will see a blank json things list –

pi@raspberrypi:~ $ aws iot list-things
{
    "things": []
}

You can create a new Thing from AWS IoT GUI or using following command –

aws iot create-thing --thing-name "YourThingName" 

 6. Troubleshooting (Optional Step):

If you see following error, cross check Access Key ID and  Secret Access Key used in Step 4 (Configure AWS CLI with AWS Credentials).

pi@raspberrypi:~ $ aws iot list-things
An error occurred (UnrecognizedClientException) when calling the ListThings operation: The security token included in the request is invalid.
pi@raspberrypi:~ $

If you see following error, cross check the “Default region name” you used in Step 4 (Configure AWS CLI with AWS Credentials).

pi@raspberrypi:~ $ aws iot list-things
Could not connect to the endpoint URL: "https://iot.europe.amazonaws.com/things"
pi@raspberrypi:~ $

If you see following error, make sure you have assigned “AWSIoTDataAccess” or related permission to your CLI User.

pi@raspberrypi:~ $ aws iot create-thing --thing-name "MyRaspberry"
An error occurred (AccessDeniedException) when calling the CreateThing operation: User: arn:aws:iam::126003626:user/Code_Access is not authorized to perform: iot:CreateThing on resource: arn:aws:iot:eu-central-1:12600326:thing/MyRaspberry
pi@raspberrypi:~ $

In case you need to reconfigure any access parameter for AWS CLI, simply execute the “aws configure” command once again.

7. AWS IoT CLI Command Documentation:

For AWS IoT there are two command objects “iot” and “iot-data”.

• IoT command reference is available at following link –

http://docs.amazonaws.cn/cli/latest/reference/iot/index.html

• IoT-Data command reference is available at following link –

http://docs.aws.amazon.com/cli/latest/reference/iot-data/index.html

Conclusion:

You can use AWS CLI tool not only for AWS IoT but for any AWS Service. It could be really useful in case you want to auto deploy your solution on AWS Cloud using DevOps scripts.