# Tutorial: Preparing your devices for the AWS IoT Device Client This tutorial walks you through the initialization of your Raspberry Pi to prepare it for the subsequent tutorials in this learning path. The goal of this tutorial is to install the current version of the device’s operating system and make sure that you can communicate with your device in the context of your development environment. **Prerequisites** Before you start this tutorial, make sure that you have the items listed in [Prerequisites to building demos with the AWS IoT Device Client](iot-tutorials-dc-intro.md#iot-dc-tutorial-overview) available and ready to use. This tutorial takes about 90 minutes to complete. **In this tutorial, you'll:** + Install and update the operating system of your device. + Install and verify any additional software needed to run the tutorials. + Test your device's connectivity and install the required certificates. After you complete this tutorial, the next tutorial prepares your device for the demos that use the AWS IoT Device Client. **Topics** + [Install and update the operating system of the device](iot-dc-prepare-device-sys.md) + [Install and verify required software on your device](iot-dc-prepare-device-sw.md) + [Test your device and save the Amazon CA cert](iot-dc-prepare-device-test.md) # Install and update the operating system of the device The procedures in this section describe how to initialize the microSD card that the Raspberry Pi uses for its system drive. The Raspberry Pi's microSD card contains its operating system (OS) software as well as space for its application file storage. If you're not using a Raspberry Pi, follow the device's instructions to install and update the device's operating system software. After you complete this section, you should be able to start your IoT device and connect to it from the terminal program on your local host computer. **Required equipment:** + Your local development and testing environment + A Raspberry Pi that or your IoT device, that can connect to the internet + A microSD memory card with at least 8 GB capacity or sufficient storage for the OS and required software. **Note** When selecting a microSD card for these exercises, choose one that is as large as necessary but, as small as possible. A small SD card will be faster to back up and update. On the Raspberry Pi, you won't need more than an 8-GB microSD card for these tutorials. If you need more space for your specific application, the smaller image files you save in these tutorials can resize the file system on a larger card to use all the supported space of the card you choose. **Optional equipment:** + A USB keyboard connected to the Raspberry Pi + An HDMI monitor and cable to connect the monitor to the Raspberry Pi **Topics** + [Load the device's operating system onto microSD card](#iot-dc-prepare-device-sys-step1) + [Start your IoT device with the new operating system](#iot-dc-prepare-device-sys-step2) + [Connect your local host computer to your device](#iot-dc-prepare-device-sys-step3) ## Load the device's operating system onto microSD card This procedure uses the local host computer to load the device's operating system onto a microSD card. **Note** If your device doesn't use a removable storage medium for its operating system, install the operating system using the procedure for that device and continue to [Start your IoT device with the new operating system](#iot-dc-prepare-device-sys-step2). **To install the operating system on your Raspberry Pi** 1. On your local host computer, download and unzip the Raspberry Pi operating system image that you want to use. The latest versions are available from [ https://www.raspberrypi.com/software/operating-systems/](https://www.raspberrypi.com/software/operating-systems/) **Choosing a version of Raspberry Pi OS** This tutorial uses the **Raspberry Pi OS Lite** version because it’s the smallest version that supports these the tutorials in this learning path. This version of the Raspberry Pi OS has only a command line interface and doesn't have a graphical user interface. A version of the latest Raspberry Pi OS with a graphical user interface will also work with these tutorials; however, the procedures described in this learning path use only the command line interface to perform operations on the Raspberry Pi. 1. Insert your microSD card into the local host computer. 1. Using an SD card imaging tool, write the unzipped OS image file to the microSD card. 1. After writing the Raspberry Pi OS image to the microSD card: 1. Open the BOOT partition on the microSD card in a command line window or file explorer window. 1. In the BOOT partition of the microSD card, in the root directory, create an empty file named `ssh` with no file extension and no content. This tells the Raspberry Pi to enable SSH communications the first time it starts. 1. Eject the microSD card and safely remove it from the local host computer. Your microSD card is ready to [Start your IoT device with the new operating system](#iot-dc-prepare-device-sys-step2). ## Start your IoT device with the new operating system This procedure installs the microSD card and starts your Raspberry Pi for the first time using the downloaded operating system. **To start your IoT device with the new operation system** 1. With the power disconnected from the device, insert the microSD card from the previous step, [Load the device's operating system onto microSD card](#iot-dc-prepare-device-sys-step1), into the Raspberry Pi. 1. Connect the device to a wired network. 1. These tutorials will interact with your Raspberry Pi from your local host computer using an SSH terminal. If you also want to interact with the device directly, you can: 1. Connect an HDMI monitor to it to watch the Raspberry Pi’s console messages before you can connect the terminal window on your local host computer to your Raspberry Pi. 1. Connect a USB keyboard to it if you want to interact directly with the Raspberry Pi. 1. Connect the power to the Raspberry Pi and wait about a minute for it to initialize. If you have a monitor connected to your Raspberry Pi, you can watch the start-up process on it. 1. Find out your device’s IP address: + If you connected an HDMI monitor to the Raspberry Pi, the IP address appears in the messages displayed on the monitor + If you have access to the router your Raspberry Pi is connects to, you can see its address in the router’s admin interface. After you have your Raspberry Pi's IP address, you're ready to [Connect your local host computer to your device](#iot-dc-prepare-device-sys-step3). ## Connect your local host computer to your device This procedure uses the terminal program on your local host computer to connect to your Raspberry Pi and change its default password. **To connect your local host computer to your device** 1. On your local host computer, open the SSH terminal program: + Windows: `PuTTY` + Linux/macOS: `Terminal` **Note** PuTTY isn't installed automatically on Windows. If it's not on your computer, you might need to download and install it. 1. Connect the terminal program to your Raspberry Pi’s IP address and log in using its default credentials. ``` username: pi password: raspberry ``` 1. After you log in to your Raspberry Pi, change the password for the `pi` user. ``` passwd ``` Follow the prompts to change the password. ``` Changing password for pi. Current password: raspberry New password: YourNewPassword Retype new password: YourNewPassword passwd: password updated successfully ``` After you have the Raspberry Pi's command line prompt in the terminal window and changed the password, you're ready to continue to [Install and verify required software on your device](iot-dc-prepare-device-sw.md). # Install and verify required software on your device The procedures in this section continue from [the previous section](iot-dc-prepare-device-sys.md) to bring your Raspberry Pi's operating system up to date and install the software on the Raspberry Pi that will be used in the next section to build and install the AWS IoT Device Client. After you complete this section, your Raspberry Pi will have an up-to-date operating system, the software required by the tutorials in this learning path, and it will be configured for your location. **Required equipment:** + Your local development and testing environment from [the previous section](iot-dc-prepare-device-sys.md) + The Raspberry Pi that you used in [the previous section](iot-dc-prepare-device-sys.md) + The microSD memory card from [the previous section](iot-dc-prepare-device-sys.md) **Note** The Raspberry Pi Model 3\$1 and Raspberry Pi Model 4 can perform all the commands described in this learning path. If your IoT device can't compile software or run the AWS Command Line Interface, you might need to install the required compilers on your local host computer to build the software and then transfer it to your IoT device. For more information about how to install and build software for your device, see the documentation for your device's software. **Topics** + [Update operating system software](#iot-dc-prepare-device-sw-step1) + [Install the required applications and libraries](#iot-dc-prepare-device-sw-step2) + [(Optional) Save the microSD card image](#iot-dc-prepare-device-sw-step3) ## Update operating system software This procedure updates the operating system software. **To update the operating system software on the Raspberry Pi** Perform these steps in the terminal window of your local host computer. 1. Enter these commands to update the system software on your Raspberry Pi. ``` sudo apt-get -y update sudo apt-get -y upgrade sudo apt-get -y autoremove ``` 1. Update the Raspberry Pi's locale and time zone settings (optional). Enter this command to update the device's locale and time zone settings. ``` sudo raspi-config ``` 1. To set the device's locale: 1. In the **Raspberry Pi Software Configuration Tool (raspi-config)** screen, choose option **5**. **`5 Localisation Options Configure language and regional settings`** Use the Tab key to move to **,** and then press the space bar. 1. In the list of locale options, choose the locales that you want to install on your Raspberry Pi by using the arrow keys to scroll and the space bar to mark those that you want. In the United States, **`en_US.UTF-8`** is a good one to choose. 1. After selecting the locales for your device, use the Tab key to choose ****, and then press the space bar to display the **Configuring locales** confirmation page. 1. To set the device’s time zone: 1. In the **raspi-config** screen, choose option **5**. **`5 Localisation Options Configure language and regional settings`** Use the Tab key to move to **,** and then press the space bar. 1. In the **Configuring tzdata** menu, choose your geographical area from the list. Use the Tab key to move to ****, and then press the space bar. 1. In the list of cities, use the arrow keys to choose a city in your time zone. To set the time zone, use the Tab key to move to ****, and then press the space bar. 1. When you’ve finished updating the settings, use the Tab key to move to ****, and then press the space bar to close the **raspi-config** app. 1. Enter this command to restart your Raspberry Pi. ``` sudo shutdown -r 0 ``` 1. Wait for your Raspberry Pi to restart. 1. After your Raspberry Pi has restarted, reconnect the terminal window on your local host computer to your Raspberry Pi. Your Raspberry Pi system software is now configured and you're ready to continue to [Install the required applications and libraries](#iot-dc-prepare-device-sw-step2). ## Install the required applications and libraries This procedure installs the application software and libraries that the subsequent tutorials use. If you are using a Raspberry Pi, or if you can compile the required software on your IoT device, perform these steps in the terminal window on your local host computer. If you must compile software for your IoT device on your local host computer, review the software documentation for your IoT device for information about how to do these steps on your device. **To install the application software and libraries on your Raspberry Pi** 1. Enter this command to install the application software and libraries. ``` sudo apt-get -y install build-essential libssl-dev cmake unzip git python3-pip ``` 1. Enter these commands to confirm that the correct version of the software was installed. ``` gcc --version cmake --version openssl version git --version ``` 1. Confirm that these versions of the application software are installed: + `gcc`: 9.3.0 or later + `cmake`: 3.10.x or later + `OpenSSL`: 1.1.1 or later + `git`: 2.20.1 or later If your Raspberry Pi has acceptable versions of the required application software, you're ready to continue to [(Optional) Save the microSD card image](#iot-dc-prepare-device-sw-step3). ## (Optional) Save the microSD card image Throughout the tutorials in this learning path, you'll encounter these procedures to save a copy of the Raspberry Pi's microSD card image to a file on your local host computer. While encouraged, they are not required tasks. By saving the microSD card image where suggested, you can skip the procedures that precede the save point in this learning path, which can save time if you find the need to retry something. The consequence of not saving the microSD card image periodically is that you might have to restart the tutorials in the learning path from the beginning if your microSD card is damaged or if you accidentally configure an app or its settings incorrectly. At this point, your Raspberry Pi's microSD card has an updated OS and the basic application software loaded. You can save the time it took you to complete the preceding steps by saving the contents of the microSD card to a file now. Having the current image of your device's microSD card image lets you start from this point to continue or retry a tutorial or procedure without the need to install and update the software from scratch. **To save the microSD card image to a file** 1. Enter this command to shut down the Raspberry Pi. ``` sudo shutdown -h 0 ``` 1. After the Raspberry Pi shuts down completely, remove its power. 1. Remove the microSD card from the Raspberry Pi. 1. On your local host computer: 1. Insert the microSD card. 1. Using your SD card imaging tool, save the microSD card’s image to a file. 1. After the microSD card’s image has been saved, eject the card from the local host computer. 1. With the power disconnected from the Raspberry Pi, insert the microSD card into the Raspberry Pi. 1. Apply power to the Raspberry Pi. 1. After waiting about a minute, on the local host computer, reconnect the terminal window on your local host computer that was connected to your Raspberry Pi., and then log in to the Raspberry Pi. # Test your device and save the Amazon CA cert The procedures in this section continue from [the previous section](iot-dc-prepare-device-sw.md) to install the AWS Command Line Interface and the Certificate Authority certificate used to authenticate your connections with AWS IoT Core. After you complete this section, you'll know that your Raspberry Pi has the necessary system software to install the AWS IoT Device Client and that it has a working connection to the internet. **Required equipment:** + Your local development and testing environment from [the previous section](iot-dc-prepare-device-sw.md) + The Raspberry Pi that you used in [the previous section](iot-dc-prepare-device-sw.md) + The microSD memory card from [the previous section](iot-dc-prepare-device-sw.md) **Topics** + [Install the AWS Command Line Interface](#iot-dc-prepare-device-test-step1) + [Configure your AWS account credentials](#iot-dc-prepare-device-test-step2) + [Download the Amazon Root CA certificate](#iot-dc-prepare-device-test-step3) + [(Optional) Save the microSD card image](#iot-dc-prepare-device-test-step4) ## Install the AWS Command Line Interface This procedure installs the AWS CLI onto your Raspberry Pi. If you are using a Raspberry Pi or if you can compile software on your IoT device, perform these steps in the terminal window on your local host computer. If you must compile software for your IoT device on your local host computer, review the software documentation for your IoT device for information about the libraries it requires. **To install the AWS CLI on your Raspberry Pi** 1. Run these commands to download and install the AWS CLI. ``` export PATH=$PATH:~/.local/bin # configures the path to include the directory with the AWS CLI git clone https://github.com/aws/aws-cli.git # download the AWS CLI code from GitHub cd aws-cli && git checkout v2 # go to the directory with the repo and checkout version 2 pip3 install -r requirements.txt # install the prerequisite software ``` 1. Run this command to install the AWS CLI. This command can take up to 15 minutes to complete. ``` pip3 install . # install the AWS CLI ``` 1. Run this command to confirm that the correct version of the AWS CLI was installed. ``` aws --version ``` The version of the AWS CLI should be 2.2 or later. If the AWS CLI displayed its current version, you're ready to continue to [Configure your AWS account credentials](#iot-dc-prepare-device-test-step2). ## Configure your AWS account credentials In this procedure, you'll obtain AWS account credentials and add them for use on your Raspberry Pi. **To add your AWS account credentials to your device** 1. Obtain an **Access Key ID** and **Secret Access Key** from your AWS account to authenticate the AWS CLI on your device. If you’re new to AWS IAM, [ https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/ ](https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/) describes the process to run in the AWS console to create AWS IAM credentials to use on your device. 1. In the terminal window on your local host computer that's connected to your Raspberry Pi. and with the **Access Key ID** and **Secret Access Key** credentials for your device: 1. Run the AWS configure app with this command: ``` aws configure ``` 1. Enter your credentials and configuration information when prompted: ``` AWS Access Key ID: your Access Key ID AWS Secret Access Key: your Secret Access Key Default region name: your AWS Region code Default output format: json ``` 1. Run this command to test your device's access to your AWS account and AWS IoT Core endpoint. ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` It should return your AWS account-specific AWS IoT data endpoint, such as this example: ``` { "endpointAddress": "a3EXAMPLEffp-ats.iot.us-west-2.amazonaws.com" } ``` If you see your AWS account-specific AWS IoT data endpoint, your Raspberry Pi has the connectivity and permissions to continue to [Download the Amazon Root CA certificate](#iot-dc-prepare-device-test-step3). **Important** Your AWS account credentials are now stored on the microSD card in your Raspberry Pi. While this makes future interactions with AWS easy for you and the software you’ll create in these tutorials, they will also be saved and duplicated in any microSD card images you make after this step by default. To protect the security of your AWS account credentials, before you save any more microSD card images, consider erasing the credentials by running `aws configure` again and entering random characters for the **Access Key ID** and **Secret Access Key** to prevent your AWS account credentials from compromised. If you find that you have saved your AWS account credentials inadvertently, you can deactivate them in the AWS IAM console. ## Download the Amazon Root CA certificate This procedure downloads and saves a copy of a certificate of the Amazon Root Certificate Authority (CA). Downloading this certificate saves it for use in the subsequent tutorials and it also tests your device's connectivity with AWS services. **To download and save the Amazon Root CA certificate** 1. Run this command to create a directory for the certificate. ``` mkdir ~/certs ``` 1. Run this command to download the Amazon Root CA certificate. ``` curl -o ~/certs/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem ``` 1. Run these commands to set the access to the certificate directory and its file. ``` chmod 745 ~ chmod 700 ~/certs chmod 644 ~/certs/AmazonRootCA1.pem ``` 1. Run this command to see the CA certificate file in the new directory. ``` ls -l ~/certs ``` You should see an entry like this. The date and time will be different; however, the file size and all other info should be the same as shown here. ``` -rw-r--r-- 1 pi pi 1188 Oct 28 13:02 AmazonRootCA1.pem ``` If the file size is not `1188`, check the **curl** command parameters. You might have downloaded an incorrect file. ## (Optional) Save the microSD card image At this point, your Raspberry Pi's microSD card has an updated OS and the basic application software loaded. **To save the microSD card image to a file** 1. In the terminal window on your local host computer, clear your AWS credentials. 1. Run the AWS configure app with this command: ``` aws configure ``` 1. Replace your credentials when prompted. You can leave **Default region name** and **Default output format** as they are by pressing **Enter**. ``` AWS Access Key ID [****************YT2H]: XYXYXYXYX AWS Secret Access Key [****************9plH]: XYXYXYXYX Default region name [us-west-2]: Default output format [json]: ``` 1. Enter this command to shut down the Raspberry Pi. ``` sudo shutdown -h 0 ``` 1. After the Raspberry Pi shuts down completely, remove its power connector. 1. Remove the microSD card from your device. 1. On your local host computer: 1. Insert the microSD card. 1. Using your SD card imaging tool, save the microSD card’s image to a file. 1. After the microSD card’s image has been saved, eject the card from the local host computer. 1. With the power disconnected from the Raspberry Pi, insert the microSD card into the Raspberry Pi. 1. Apply power to the device. 1. After about a minute, on the local host computer, restart the terminal window session and log in to the device. **Don't reenter your AWS account credentials yet.** After you have restarted and logged in to your Raspberry Pi, you're ready to continue to [Tutorial: Installing and configuring the AWS IoT Device Client](iot-dc-install-dc.md).