AWS IoT Workshop Created by: Josh Sohn, Cedrus Digital, 2018

Overview: In this workshop, we will create a back end IoT solution using AWS. This workshop uses a DevOps approach to integrate the following AWS services:

- IoT Core - Greengrass - Lambda - API Gateway - EC2 (mocking an edge device)

To deploy this solution, we will use the following AWS services:

- CloudFormation - CodePipeline - CodeBuild - AWS SAM - S3

Prerequisites: - AWS Account - Admin Privileges

Notes: It is advisable that you do NOT use an AWS account with important

development/production assets. It is recommended that you use a personal account where you are the administrator.

Everything should be done in ‘us-east-1’.

ACTIVITY ONE: INITIAL SET-UP Section 1: Create Key Pair

Our first step is creating a Key Pair so we can connect to our EC2 instance via SSH. In this workshop, our EC2 instance will be acting as a mock gateway/edge device running Greengrass.

Step 1: Navigate to EC2 in AWS console.

Step 2: Select ‘Key Pairs’ under ‘Network & Security’ in side navigation menu.

Step 3: Click ‘Create Key Pair’.

Step 4: Name your Key Pair and click ‘Create’.

‘<KEY_NAME>.pem` will automatically download. Move this file to an appropriate

folder for later use.

Section 2: Create Resources

Next, we will use CloudFormation to create the resources needed to deploy our solution. Our initial CloudFormation stack will create the following resources:

- CodePipeline • Pipeline named ‘IoT-Workshop-Pipeline’ • Associated IAM Role/Policy

- CodeBuild • Project named ‘IoT-Workshop’ • Associated IAM Role/Policy

- S3 • Bucket used for CodePipeline/CodeBuild/AWS SAM artifacts

- EC2 • Instance named ‘IoT-Workshop’ • Associated Role/Policy, Profile, and Security Group

Step 1: Create Stack. Launch CloudFormation Stack

Step 2: Enter parameters and create stack. Enter name of Key Pair created in Section 1.

Enter a unique name for an S3 bucket. Note: Bucket name must be globally unique and follow naming rules (lowercase letters, numbers, and hyphens), so be specific and add some random characters. e.g. iot-workshop-3dr4.

Tick box acknowledging that CloudFormation will create IAM resources. Click ‘Create’.

Step 3: Navigate to S3 in AWS Console.

Step 4: Navigate to the bucket you named in Step 2.

Step 5: Download the zip file below.

https://s3.amazonaws.com/sohnbucket/iotworkshopsource.zip

Step 6: Upload the zip file to your S3 Bucket.

Click Upload. (There is no need to change any of the default settings.) Once you’ve uploaded the file ‘iotworkshopsource.zip’, a pipeline revision will be

triggered. CodePipeline will use the code as the source for our CodeBuild project. Our CodeBuild project will use AWS SAM to create several more CloudFormation stacks. These stacks will create several Lambda functions and an API Gateway. This source code can be found at the following link:

https://github.com/retrofuturejosh/aws-iot-workshop

ACTIVITY TWO: GREENGRASS SETUP For this activity, we will get a look at how Greengrass works on a mock edge device and

make deployments from the AWS console. NOTE: This section can only be completed when the EC2 instance has finished initializing

and creating necessary IoT assets. When there is a Greengrass group named ‘demoGroup’ in the AWS console under IoT Core > Greengrass > Groups, set up has successfully completed.

Section 1: Start Greengrass In section one, we will start Greengrass on our EC2 instance.

Step 1: Navigate to EC2 in AWS console.

Step 2: Select ‘Instances’ in side navigation menu.

Step 3: Select the instance named ‘IoT-Workshop’ and click ‘Connect’.

Step 4: Follow directions to connect via a standalone SSH client.

Step 5: Start Greengrass. Enter the following commands to start Greengrass on your EC2 instance. You should see an output similar to the following:

Section 2: Deploy a Test ‘Hello World’ Lambda In this section, we will test our Greengrass connection with a simple ‘Hello World’ lambda function, provided by AWS.

Step 1: Navigate to IoT Core in AWS Console.

Step 2: Find and select Greengrass Group named ‘demoGroup’.

Yo

u

ur

Ke

y

Your Key.

cd /greengrass/ggc/core

sudo ./greengrassd start

Your Key.

Instance DNS

Instance DNS

Step 3: Click on ‘Lambdas’ and ‘Add your first Lambda’.

Step 4: Select ‘Use Existing Lambda’.

Step 5: Select ‘helloGreengrass’ Lambda.

Step 6: Select ‘Alias: greengrass’ version.

Step 7: Select ‘Edit Configuration’ from the Lambda’s dropdown menu.

Step 8: Change the Memory limit to 32 MB and select ‘Make this function long-lived and keep it running indefinitely’. Click ‘Update’.

Step 9: Navigate back to the group’s main page. Click on ‘Subscriptions and ‘Add your first Subscription’.

Step 10: Select ‘helloGreengrass’ Lambda as source and ‘IoT Cloud’ as target. Click Next.

Step 11: Enter ‘hello/world’ as topic filter, click ‘Next’ and then ‘Finish’

Step 12: Click on ‘Actions’ and then select ‘Deploy’

Step 13: Select ‘Automatic Detection’

Step 14: After deployment is successful, navigate to ‘Test’ on the sidebar of the main IoT page.

Step 15: Subscribe to the topic ‘hello/world’.

Step 16: You should see a message arriving every 5 seconds.

Section 3: Deploy Device Control Lambda In this section, we will add a mock ‘Light’ device and deploy a long-lived device control Lambda to our Greengrass group.

Step 1: In terminal, connect to EC2 instance (as we did in section 1) and enter following commands.

This will create a device named ‘myLight’ in the Greengrass group. After creation, you should see a new device called ‘myLight’ in the AWS console.

Step 2: Add Device control Lambda.

Navigate to the Lambda section of the Greengrass group. Add an existing Lambda named ‘resolveDeltas’. Choose the version named ‘Alias: greengrass’. Edit Lambda Configuration so that the memory limit is 64 MB and the function is long lived. Add an environment variable with key ‘DEVICE_NAME’ and value ‘myLight’.

cd /iot-workshop/greengrass-node-toolkit

sudo DEVICE_NAME=myLight npm run add-device

Step 3: Add Local Resource Navigate to ‘Resources’ section of Greengrass group and select ‘Add a local resource’.

Step 3: Configure Local Resource Give the resource a logical name.

e.g. ‘lambdaCerts’. Change the resource type to ‘Volume’. Enter the source path: ‘/greengrass/certs’ Enter the destination path: ‘/lambdacerts’ Choose ‘Automatically add OS group permissions…’

Affiliate the lambda function named ‘resolveDeltas’ with read-only access. Save the resource.

Step 4: Deploy to your Greengrass instance.

Section 4: Test Device Control In this section, we will test if we can issue commands to our new mock light device. Our

edge device (EC2 instance) is running a long-lived lambda function, ‘resolveDeltas’, which listens for desired changes in device state via the aws-iot-device-sdk. Since our device is only a mock device, when a command is received, the reported state is immediately updated to reflect the desired state.

EXAMPLE: PUT request is sent to <API_ENDPOINT>/device/myLight with body

{ "isOn": true }

This request is handled by a Lambda using AWS IoT Data to update the desired state of the thing’s shadow.

If the desired state is different than the reported state, a Delta is created. Our long-lived lambda function listens for Deltas and updates the reported state

of the thing’s shadow accordingly. NOTE: If we were controlling a real device, the long-lived lambda function would

issue and verify a successful command to the device before updating the shadow’s reported state.

After our PUT request is successful, if we check the state with a GET request to ‘<API_ENDPOINT>/device/myLight’, we should see that the reported state has changed to

{ "isOn": true }

Step 1: Navigate to API Gateway in AWS console.

Our CloudFormation stack created the API Gateway and Lambdas necessary for GET and PUT requests to our new ‘myLight’ device.

Step 2: Navigate to ‘PUT’ route testing. Navigate to ‘demo-api’. Select the PUT resource for ‘/device’ ‘/{deviceID}’. Click ‘Test’ to open the in-console testing service.

Step 2: Test ‘PUT’ route. Enter ‘myLight’ as {deviceID} Path. Enter the following JSON for the request body and click ‘Test’. { "isOn": true }

You should see a response similar to the following:

Step 2: Test ‘GET’ route. Navigate to the ‘GET’ method. Enter ‘myLight’ as {deviceID} Path and click ‘Test’. You should see the following response.

Step 3: Experiment. Add another attribute via the ‘PUT’ method. e.g. { "dimLevel": 50 } Test if the attribute is added with the ‘GET’ method.

Step 4: Watch thing shadow in AWS console. In the Manage > Things section of IoT Core in the AWS Console, find the thing named ‘myLight’. In the ‘Shadow’ section, you should see the desired and reported state of the mock light. You can see that this is updating when commands are issued from the ‘PUT’ method in API gateway. Try changing "isOn" to false.

=>

TEAR DOWN This section will explain how to delete/remove all the assets and resources created in

this workshop.

Step 1: Delete CloudFormation Stacks. Navigate to CloudFormation in the AWS console and delete the following stacks:

• hello-greengrass • delta-lambda • demo-api • IoTWorkshop

Step 2: Delete IoT Assets.

Navigate to IoT Core in the AWS console. Select Manage > Things Delete ‘myLight’. Delete ‘demoCore’. Select Greengrass > Groups > ‘demoGroup’ Reset deployments (force reset). Delete Group.

Select Secure > Certificates Delete two most recent certificates

Select Secure > Policies Delete ‘myLightPolicy’.

Select ‘demoCorePolicy’ > Versions Delete Version 1

Delete ‘demoCorePolicy’.

Questions? Comments? Feel free to contact: josh@cedrus.digital Thanks!