Creating a flow in an AWS IoT Greengrass group with devices - AWS IoT Things Graph

Creating a flow in an AWS IoT Greengrass group with devices

This topic walks you through the steps to create and deploy a simple workflow (flow) that consists of a Raspberry Pi connected to three devices: an Aukru HC-SR501 motion sensor, a Raspberry Pi camera, and a Raspberry Pi screen.

The flow in this example is triggered when the motion sensor detects motion. The motion sensor sends a message to the camera, which takes a picture and sends it to the screen for display.

If you don't want to buy the devices used in this example, you can run three Python scripts that mimic the functions of the devices. This topic shows you how to run the flow with both the real and mock devices.

Find the code for the mock devices in the MockDevices.zip or the MockDevices-v2.zip file. The first file contains scripts that use the AWS IoT Device SDK for Python v1. The second file contains scripts that use the AWS IoT Device SDK for Python v2. You can run these scripts on any Linux environment, such as a Raspberry Pi or an Amazon EC2 instance, on which Python 2.7 is installed.

Prerequisites

To create this example, you need the following AWS resources:

To create this example with real devices, you need the following hardware resources:

Set up your Raspberry Pi

To run the workflow with real devices, you need to set up your Raspberry Pi with those devices. If you're creating this example with the mock devices, skip ahead to Create an AWS IoT Greengrass Group.

Now you've configured your Raspberry Pi to communicate with the motion sensor, camera, and screen.

Create an AWS IoT Greengrass group

Note

For information about using AWS CloudFormation to create and manage AWS IoT Greengrass groups and resources, see AWS IoT Greengrass resource types reference.

If you're creating this example with real devices, install AWS IoT Greengrass on the same Raspberry Pi to which you attached your motion sensor, camera, and screen.

If you're using mock devices, install AWS IoT Greengrass on the same Linux environment where you run the Python scripts.

Perform the steps in Setting up your environment on the appropriate device or computer. Make sure that you've created an IAM role for AWS IoT Greengrass (step 4 in the Create an AWS IoT Greengrass Group procedure in that topic). Attach the AmazonS3FullAccess policy to give it access to your S3 bucket.

Note

The AWS IoT Greengrass group and Amazon S3 bucket that you use in this example must be created in the same AWS Region. The AWS IoT Things Graph entities that you create must also be in the same Region as these resources.

Create things

Open the AWS IoT console and create three things: one thing for your motion sensor, and two things for the camera and screen that are attached to your Raspberry Pi.

For instructions on how to create things in the registry, see Register a device in the registry. Be sure to create and activate certificates for each thing.

In the AWS IoT console, on the Greengrass tab, select your group, choose Devices, and then add the three new things to your AWS IoT Greengrass group.

For more information about AWS IoT concepts, see What is AWS IoT?

Set up your mock devices

To run the workflow (flow) with mock devices, you need to install the AWS IoT Greengrass Core SDK, and then copy the Python scripts in the MockDevices.zip or the MockDevices-v2.zip file to your Linux environment.

If you're creating this example with real devices, skip ahead to Create and Deploy the Flow.

  1. Install the AWS IoT Device SDK for Python.

  2. Download and extract the MockDevices.zip or the MockDevices-v2.zip file. The extracted directory contains three files named ms.py, camera.py, and screen.py.

  3. Create folders named ms, camera, and screen.

  4. Copy the ms.py file into the ms directory, the camera.py file into the camera directory, and the screen.py file into the screen directory.

  5. Copy the certificate and private key for each of the three things that you created into the appropriate directory on your Linux environment. Also copy the root certificate authority (CA) for AWS IoT into each directory. For example, the motion sensor certificate and private key should be in the ms directory, with the root CA for AWS IoT and the ms.py file.

    If you haven't created and activated certificates for your things, follow the steps in Register a device in the registry. Make sure to attach a policy to each certificate.

Create and publish the flow

To create this flow with the AWS CLI instead of the AWS IoT Things Graph console, follow the instructions in Creating a flow with devices by using the AWS CLI.

  1. Open the AWS IoT Things Graph console, and then choose Create flow.

  2. Create a flow.

    In the Flow configuration pane that appears, name your flow (such as SecurityFlow). Choose Create flow.

  3. Add the device models to the flow.

    Search for the MotionSensor device mode. Select the device model and drag it into the flow designer. Do the same for the Camera and Screen device models.

  4. Connect the device models.

    In the flow designer, select the edge of the MotionSensor device model and connect it to the Camera device model. Also connect the Camera device model to the Screen device model.

    
              
                Camera and Screen device models connected by a straight line.
  5. Update the motion sensor trigger.

    In the trigger editor that appears in the right pane, for Condition, choose StateChanged. For Action, choose ThingsGraph.startFlow.

  6. Update the camera device model action.

    1. In the flow designer, select the Camera device model.

    2. In the action editor that appears in the right pane, choose No action configured.

    3. For Action, choose capture.

    4. Expand Output, and then enter cameraResult.

  7. Update the screen device action.

    1. In the flow designer, select the Screen device model.

    2. In the action editor that appears in the right pane, choose No action configured.

    3. For Action, choose display.

    4. Expand Inputs, and then choose Define Input.

    5. For Inputs, enter ${cameraResult.lastClickedImage}.

  8. Publish the flow.

    Choose Publish at the upper right of the page. This creates the flow and adds it to the list of flows that can be deployed.

Associate things to device models

  1. Select the menu icon at the upper left of the page. Choose Things.

    On the Things page, choose the motion sensor thing that you created earlier. Then choose Associate with device.

  2. On the Select device model page, choose HCSR501MotionSensor. Choose Associate. This step associates the HCSR501MotionSensor motion sensor thing in your registry with the motion sensor device model in your flow. The HCSR501MotionSensor device implements the capability of the motion sensor device model.

  3. After you return to the Select device model page, refresh the page to verify that the motion sensor thing is associate with the HCSR501MotionSensor device. Repeat the previous two steps for the RaspberryPiCamera and RaspberryPiScreen devices.

Create and deploy the flow configuration

  1. Create the flow configuration.

    Select the menu icon at the upper left of the page, and then choose Flows to return to the Flows page. Select the box next to the flow that you just created, and then choose Create flow configuration.

  2. Name the flow configuration.

    A flow configuration contains the details that are specific to a single deployment. On the Describe flow configuration page, select your flow and enter a flow configuration name. The flow configuration name can't contain spaces.

    Choose Greengrass, and then choose Next.

  3. Configure the target.

    On the Configure target page, enter the name of your Amazon S3 bucket and the AWS IoT Greengrass group to which your AWS IoT Greengrass core device belongs. Amazon S3 buckets are globally unique, so your bucket name will be different from the one in the following screen shot. Choose Next.

  4. Select things for your deployment.

    The Map Things page provides an interface for selecting the specific things to include in your deployment. The menus under each device model in your deployment contain all of the things that you associated with the device model. Because you're getting started, the menus for each device model on this page will include only one thing (the thing that you've associated with each device model).

    On the Map Things page, for motionSensor, select the motion sensor thing that you created earlier. Select the screen and camera things for the Camera and Screen device models. Choose Next.

  5. View the trigger.

    On the Set up triggers page, the GraphQL that defines the motion event trigger appears in the editor. This GraphQL specifies the event that triggers the flow. When the motion sensor detects a person moving, the ThingsGraph.startFlow function initiates the flow. You don't need to edit this code.

    Choose Review.

  6. Review and create.

    On the Review and create page, review the information you entered for your flow configuration. Choose Create.

  7. Deploy.

    When the Flow configuration created message appears, choose Deploy now.

    Refresh the Deployments page to verify that the flow has deployed. After a successful deployment, the Deployments page displays Deployed in target in the Status column.

Run the flow with real devices

If you created this example with mock devices, skip ahead to Run the Flow with Mock Devices.

Turn on your Raspberry Pi, motion sensor, camera, and screen. Position the motion sensor and camera so that they are directly in front of you. Wave your hand over the motion sensor. The camera takes a picture of you and displays it on the screen.

Run the flow with mock devices

To run the Python scripts for each mock device, you need to know your AWS IoT custom endpoint. This enables you to connect to AWS IoT.

To find this endpoint, open the AWS IoT console (https://console.aws.amazon.com/iot/), and then choose Settings. You can also find the endpoint by using the aws iot describe-endpoint AWS CLI command.

If you're using an Amazon Trust Services (ATS) root CA, use the following AWS CLI command to find your custom endpoint. For more information about certificates and ATS endpoints, see X.509 certificates and AWS IoT.

aws iot describe-endpoint --endpoint-type iot:Data-ATS

Follow these steps to run all three Python scripts and observe the mock devices interacting in the flow.

Note

You don't need to pass your custom endpoint as a parameter for the scripts that use the AWS IoT Device SDK for Python v2.

  1. Open three terminal sessions on your Linux environment. In one terminal, navigate to the ms directory. To run the ms.py script, run the following command.

    python ms.py -e custom endpoint -r root CA file path -c certificate file path -k private key file path -n motion sensor thing name

    After the script starts running, it displays the following output every 10 seconds. This indicates that the mock motion sensor has detected motion.

    Published topic motion sensor thing name/motion: {"isMotionDetected": true}
  2. In the second terminal, navigate to the camera directory. Run the camera.py script by using the following command.

    python camera.py -e custom endpoint -r root CA file path -c certificate file path -k private key file path -n camera thing name

    After the script starts running, it displays the following output every 10 seconds. This indicates that the motion sensor trigger has prompted the mock camera to capture an image and publish it to the /capture/finished MQTT topic.

    Received message on topic camera thing name/capture: {} 2019-02-11 21:37:33,430 - AWSIoTPythonSDK.core.protocol.mqtt_core - INFO - Performing sync publish... Published topic camera thing name/capture/finished: {"lastClickedImage": "https://images-na.ssl-images-amazon.com/images/I/41+K4pC74XL._AC_US218_.jpg"}
  3. In the third terminal, navigate to the screen directory. Run the screen.py script by using the following command.

    python screen.py -e custom endpoint -r root CA file path -c certificate file path -k private key file path -n screen thing name

    After the script starts running, it displays the following output every 10 seconds. This indicates that the mock screen has received the image from the mock camera.

    Received message on topic screen thing name/display: {"imageUri":"https://images-na.ssl-images-amazon.com/images/I/51rMLSWgwRL._AC_US218_.jpg"}

Delete the flow and flow configuration (optional)

For instructions on how to undeploy a flow configuration, and delete the flow configuration and flow that you've created, see Deleting flow configurations and Deleting systems, flows, and namespaces in Lifecycle management for AWS IoT Things Graph entities, flows, systems, and deployments.