AWS IoT Greengrass Developer Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 432 [warning: Documents this large are best viewed by clicking the View PDF Link!]

AWS IoT Greengrass

Developer Guide

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass: Developer Guide

Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner

that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not

owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by

Amazon.

AWS IoT Greengrass Developer Guide

Table of Contents

What Is AWS IoT Greengrass? .............................................................................................................. 1

AWS IoT Greengrass Core Software .............................................................................................. 2

AWS IoT Greengrass Core Versions ....................................................................................... 2

AWS IoT Greengrass Groups ........................................................................................................ 5

Devices in AWS IoT Greengrass .................................................................................................... 6

SDKs ......................................................................................................................................... 7

Supported Platforms and Requirements ...................................................................................... 14

AWS IoT Greengrass Downloads ................................................................................................. 19

AWS IoT Greengrass Core Software .................................................................................... 19

AWS IoT Greengrass Core SDK Software .............................................................................. 19

AWS IoT Greengrass Docker Software ................................................................................. 20

AWS IoT Greengrass ML SDK Software ................................................................................ 20

We Want to Hear from You ....................................................................................................... 20

AWS IoT Greengrass Core .......................................................................................................... 20

AWS IoT Greengrass Core Configuration File ........................................................................ 21

Endpoints Must Match the Certificate Type .......................................................................... 32

Connect on Port 443 or Through a Network Proxy ............................................................... 32

Write Directory ................................................................................................................ 35

MQTT Message Queue ...................................................................................................... 37

Activate Automatic IP Detection ......................................................................................... 40

Start Greengrass on System Boot ....................................................................................... 42

See Also .......................................................................................................................... 43

Getting Started with AWS IoT Greengrass ........................................................................................... 44

Requirements ........................................................................................................................... 44

Create an AWS Account ............................................................................................................. 45

Module 1: Environment Setup for Greengrass .............................................................................. 45

Setting Up a Raspberry Pi ................................................................................................. 45

Setting Up an Amazon EC2 Instance ................................................................................... 50

Setting Up Other Devices .................................................................................................. 54

Module 2: Installing the Greengrass Core Software ....................................................................... 55

Configure AWS IoT Greengrass on AWS IoT ......................................................................... 56

Start AWS IoT Greengrass on the Core Device ...................................................................... 61

Module 3 (Part 1): Lambda Functions on AWS IoT Greengrass ........................................................ 63

Create and Package a Lambda Function .............................................................................. 64

Configure the Lambda Function for AWS IoT Greengrass ....................................................... 70

Deploy Cloud Configurations to a Core Device ..................................................................... 75

Verify the Lambda Function Is Running on the Device ........................................................... 76

Module 3 (Part 2): Lambda Functions on AWS IoT Greengrass ........................................................ 79

Create and Package the Lambda Function ........................................................................... 79

Configure Long-Lived Lambda Functions for AWS IoT Greengrass ........................................... 81

Test Long-Lived Lambda Functions ..................................................................................... 82

Test On-Demand Lambda Functions ................................................................................... 87

Module 4: Interacting with Devices in an AWS IoT Greengrass Group ............................................... 91

Create AWS IoT Devices in an AWS IoT Greengrass Group ...................................................... 91

Configure Subscriptions .................................................................................................... 95

Install the AWS IoT Device SDK for Python .......................................................................... 96

Test Communications ...................................................................................................... 101

Module 5: Interacting with Device Shadows ............................................................................... 104

Configure Devices and Subscriptions ................................................................................. 105

Download Required Files ................................................................................................. 108

Test Communications (Device Syncs Disabled) .................................................................... 109

Test Communications (Device Syncs Enabled) ..................................................................... 112

Module 6: Accessing Other AWS Services ................................................................................... 114

Configure IAM Roles ....................................................................................................... 115

iii

AWS IoT Greengrass Developer Guide

Create and Configure the Lambda Function ....................................................................... 116

Configure Subscriptions ................................................................................................... 121

Test Communications ...................................................................................................... 122

Module 7: Simulating Hardware Security Integration ................................................................... 124

Install SoftHSM .............................................................................................................. 125

Configure SoftHSM ......................................................................................................... 125

Import the Private Key .................................................................................................... 126

Configure the Greengrass Core ......................................................................................... 126

Test the Configuration .................................................................................................... 128

See Also ........................................................................................................................ 128

OTA Updates of AWS IoT Greengrass Core Software ........................................................................... 129

Greengrass OTA Agent ............................................................................................................ 130

Integration with Init systems .................................................................................................... 132

OTA Self-Update with Managed Respawn .......................................................................... 133

AWS IoT Greengrass Core Update with Managed Respawn ................................................... 133

OTA Agent Self-Update ........................................................................................................... 133

Greengrass Core Software Update ............................................................................................ 134

Reset Deployments ......................................................................................................................... 135

Create Bulk Deployments For Groups ................................................................................................ 137

Prerequisites .......................................................................................................................... 137

Create and Upload the Bulk Deployment Input File ..................................................................... 137

Create and Configure an IAM Execution Role .............................................................................. 139

Allow Your Execution Role Access to Your S3 Bucket ................................................................... 140

Deploy the Groups .................................................................................................................. 141

Test the Deployment .............................................................................................................. 143

Troubleshooting Bulk Deployments ........................................................................................... 144

Troubleshoot input file errors ........................................................................................... 144

Check for concurrent bulk deployments ............................................................................ 145

Check ErrorDetails .......................................................................................................... 145

Check the AWS IoT Greengrass Core Log ........................................................................... 145

Additional Resources .............................................................................................................. 146

Run Local Lambda Functions ........................................................................................................... 147

SDKs ..................................................................................................................................... 147

Migrating Cloud-Based Lambda Functions ......................................................................... 149

Function Aliases and Versions .................................................................................................. 149

Controlling Greengrass Lambda Function Execution .................................................................... 150

Running a Lambda Function as Root ................................................................................. 152

Considerations When Choosing Lambda Function Containerization ........................................ 153

Setting Default Containerization for Lambda Functions in a Group ........................................ 155

Communication Flows ............................................................................................................. 155

Communication Using MQTT Messages ............................................................................. 155

Other Communication Flows ............................................................................................ 156

Lifecycle Configuration ............................................................................................................ 156

Lambda Executables ............................................................................................................... 157

Create a Lambda Executable ............................................................................................ 158

Run AWS IoT Greengrass in a Docker Container .......................................................................... 159

Prerequisites .................................................................................................................. 159

Get the AWS IoT Greengrass Container Image from Amazon ECR .......................................... 160

Create and Configure the Greengrass Group and Core ......................................................... 162

Run AWS IoT Greengrass Locally ...................................................................................... 162

Configure "No container" Containerization for the Group ..................................................... 165

Deploy Lambda Functions to the Docker Container ............................................................. 165

(Optional) Deploy Devices that Interact with Greengrass in the Docker Container ..................... 166

Stopping the AWS IoT Greengrass Docker Container ........................................................... 166

Troubleshooting AWS IoT Greengrass in a Docker Container ................................................. 166

Access Local Resources with Lambda Functions .................................................................................. 169

Supported Resource Types ....................................................................................................... 169

iv

AWS IoT Greengrass Developer Guide

Requirements ......................................................................................................................... 170

Volume Resources Under the /proc Directory ..................................................................... 170

Group Owner File Access Permission ......................................................................................... 170

See Also ........................................................................................................................ 171

Using the CLI ......................................................................................................................... 171

Create Local Resources .................................................................................................... 171

Create the Greengrass Function ........................................................................................ 172

Add the Lambda Function to the Group ............................................................................ 173

Troubleshooting ............................................................................................................. 175

Using the Console .................................................................................................................. 175

Prerequisites .................................................................................................................. 176

Create a Lambda Function Deployment Package ................................................................. 176

Create and Publish a Lambda Function ............................................................................. 180

Add the Lambda Function to the Group ............................................................................ 183

Add a Local Resource to the Group ................................................................................... 186

Add Subscriptions to the Group ....................................................................................... 188

Deploy the Group ........................................................................................................... 190

Test Local Resource Access .............................................................................................. 191

Perform Machine Learning Inference ................................................................................................. 195

How AWS IoT Greengrass ML Inference Works ............................................................................ 195

Machine Learning Resources .................................................................................................... 195

Supported Model Sources ................................................................................................ 196

Requirements ......................................................................................................................... 198

Runtimes and Precompiled Framework Libraries for ML Inference ................................................. 198

Amazon SageMaker Neo deep learning runtime .................................................................. 198

MXNet Versioning ........................................................................................................... 198

MXNet on Raspberry Pi ................................................................................................... 199

TensorFlow Model-Serving Limitations on Raspberry Pi ....................................................... 199

How to Configure Machine Learning Inference ........................................................................... 199

Prerequisites .................................................................................................................. 200

Configure the Raspberry Pi .............................................................................................. 200

Install the MXNet Framework ........................................................................................... 201

Create a Model Package .................................................................................................. 203

Create and Publish a Lambda Function ............................................................................. 203

Add the Lambda Function to the Group ............................................................................ 208

Add Resources to the Group ............................................................................................ 210

Add a Subscription to the Group ...................................................................................... 214

Deploy the Group ........................................................................................................... 215

Test the App .................................................................................................................. 216

Next Steps ..................................................................................................................... 220

Configuring an NVIDIA Jetson TX2 .................................................................................... 220

How to Configure Optimized Machine Learning Inference ............................................................ 220

Prerequisites .................................................................................................................. 200

Configure the Raspberry Pi .............................................................................................. 221

Install the Neo deep learning runtime ............................................................................... 222

Create an Inference Lambda Function ............................................................................... 224

Add the Lambda Function to the Group ............................................................................ 228

Add Neo Optimized Model Resource to the Group .............................................................. 229

Add Your Camera Device Resource to the Group ................................................................. 230

Add Subscriptions to the Group ....................................................................................... 233

Deploy the Group ........................................................................................................... 234

Test the Example ............................................................................................................ 216

Configuring an Intel Atom ............................................................................................... 238

Configuring an NVIDIA Jetson TX2 .................................................................................... 239

Troubleshooting AWS IoT Greengrass ML Inference ............................................................. 218

Next Steps ..................................................................................................................... 242

Deploy Secrets to the Core .............................................................................................................. 243

v

AWS IoT Greengrass Developer Guide

Secrets Encryption .................................................................................................................. 244

Requirements ......................................................................................................................... 244

Specify the Private Key for Secret Encryption ............................................................................. 245

Allow AWS IoT Greengrass to Get Secret Values ......................................................................... 246

See Also ................................................................................................................................ 247

Work with Secret Resources ..................................................................................................... 247

Creating and Managing Secrets ........................................................................................ 247

Using Local Secrets ......................................................................................................... 250

How To Create a Secret Resource (Console) ................................................................................ 252

Prerequisites .................................................................................................................. 253

Create a Secrets Manager Secret ...................................................................................... 253

Add a Secret Resource to a Group .................................................................................... 254

Create a Lambda Function Deployment Package ................................................................. 255

Create a Lambda Function ............................................................................................... 258

Add the Function to the Group ........................................................................................ 260

Attach the Secret Resource to the Function ....................................................................... 261

Add Subscriptions to the Group ....................................................................................... 261

Deploy the Group ........................................................................................................... 262

Test the Function ........................................................................................................... 263

See Also ........................................................................................................................ 265

Integrate with Services and Protocols Using Connectors ...................................................................... 266

Requirements ......................................................................................................................... 267

Using AWS IoT Greengrass Connectors ...................................................................................... 267

Configuration Parameters ........................................................................................................ 269

Parameters Used to Access Group Resources ...................................................................... 269

Updating Connector Parameters ....................................................................................... 269

Inputs and Outputs ................................................................................................................ 270

Input Topics ................................................................................................................... 270

Logging ................................................................................................................................. 270

AWS-Provided Greengrass Connectors ....................................................................................... 271

CloudWatch Metrics ........................................................................................................ 271

Device Defender ............................................................................................................. 277

Image Classification ........................................................................................................ 280

Kinesis Firehose .............................................................................................................. 290

Modbus-RTU Protocol Adapter ......................................................................................... 294

Raspberry Pi GPIO .......................................................................................................... 303

Serial Stream ................................................................................................................. 308

ServiceNow MetricBase Integration ................................................................................... 314

SNS .............................................................................................................................. 320

Splunk Integration .......................................................................................................... 324

Twilio Notifications ......................................................................................................... 328

Get Started with Connectors (Console) ...................................................................................... 335

.................................................................................................................................... 335

Prerequisites .................................................................................................................. 336

Create a Secrets Manager Secret ...................................................................................... 336

Add a Secret Resource to a Group .................................................................................... 337

Add a Connector to the Group ......................................................................................... 338

Create a Lambda Function Deployment Package ................................................................. 339

Create a Lambda Function ............................................................................................... 342

Add a Function to the Group ........................................................................................... 344

Add Subscriptions to the Group ....................................................................................... 344

Deploy the Group ........................................................................................................... 345

Test the Solution ............................................................................................................ 346

See Also ........................................................................................................................ 348

Get Started with Connectors (CLI) ............................................................................................ 348

.................................................................................................................................... 348

Prerequisites .................................................................................................................. 350

vi

AWS IoT Greengrass Developer Guide

Create a Secrets Manager Secret ...................................................................................... 350

Create a Resource Definition and Version ........................................................................... 351

Create a Connector Definition and Version ......................................................................... 351

Create a Lambda Function Deployment Package ................................................................. 352

Create a Lambda Function ............................................................................................... 355

Create a Function Definition and Version ........................................................................... 356

Create a Subscription Definition and Version ...................................................................... 357

Create a Group Version ................................................................................................... 358

Create a Deployment ...................................................................................................... 359

Test the Solution ............................................................................................................ 360

See Also ........................................................................................................................ 362

Greengrass Discovery RESTful API ..................................................................................................... 363

Request ................................................................................................................................. 363

Response ............................................................................................................................... 363

Authorization ......................................................................................................................... 363

Example Discover Response Documents ..................................................................................... 364

Greengrass OPC-UA ........................................................................................................................ 366

Architectural Overview ............................................................................................................ 366

Set Up a Test OPC-UA Server ................................................................................................... 367

Make sure your Greengrass Group is ready ................................................................................. 367

Use Greengrass OPC-UA to Interact with your OPC-UA Server ...................................................... 368

Verify that your Lambda function is receiving OPC-UA Publishes and posting them onto Greengrass ... 370

Next Steps ............................................................................................................................. 370

AWS IoT Greengrass Security ........................................................................................................... 371

Configuring Greengrass Security ............................................................................................... 372

Minimal AWS IoT Policy for the AWS IoT Greengrass Core Device .......................................... 372

Device Connection Workflow .................................................................................................... 374

Greengrass Messaging Workflow .............................................................................................. 375

MQTT Core Server Certificate Rotation ...................................................................................... 375

AWS IoT Greengrass Cipher Suites ............................................................................................ 375

Hardware Security .................................................................................................................. 376

Requirements ................................................................................................................. 377

Hardware Security Configuration ...................................................................................... 377

Provisioning Practices .................................................................................................... 380

Supported Cipher Suites .................................................................................................. 382

Configure OTA Updates ................................................................................................... 382

Backward Compatibility ................................................................................................... 383

Hardware Without PKCS#11 Support ................................................................................ 384

See Also ........................................................................................................................ 384

Monitoring ..................................................................................................................................... 385

CloudWatch Logs .................................................................................................................... 385

File System Logs .................................................................................................................... 385

Default Logging Configuration ................................................................................................. 386

Configure Logging for AWS IoT Greengrass ................................................................................ 386

Configure Logging (Console) ............................................................................................ 387

Configure Logging (API) .................................................................................................. 387

Configuration Example .................................................................................................... 388

Logging Limitations ................................................................................................................ 389

Transactions per Second .................................................................................................. 389

Memory ......................................................................................................................... 389

Clock Skew .................................................................................................................... 389

Disk Usage ..................................................................................................................... 389

Log Loss ........................................................................................................................ 390

Logging AWS IoT Greengrass API Calls with AWS CloudTrail ......................................................... 390

AWS IoT Greengrass Information in CloudTrail ................................................................... 390

Understanding AWS IoT Greengrass Log File Entries ............................................................ 391

CloudTrail Logs ...................................................................................................................... 393

vii

AWS IoT Greengrass Developer Guide

AWS IoT Device Tester for AWS IoT Greengrass User Guide ................................................................. 394

Prerequisites .......................................................................................................................... 394

Download the Latest Version of AWS IoT Device Tester for AWS IoT Greengrass ....................... 394

Create and Configure an AWS Account .............................................................................. 394

Install the AWS Command Line Interface (CLI) .................................................................... 395

Configure the AWS IoT Greengrass Service Role ................................................................. 395

Verify AWS IoT Greengrass Dependencies on the Device Under Test ...................................... 396

Configure the AWS IoT Greengrass Software ...................................................................... 396

Configure Your Host Computer to Access Your Device Under Test .......................................... 397

Root Access ................................................................................................................... 398

Setting Configuration to Run the AWS IoT Greengrass Qualification Suite ...................................... 398

Configure Your AWS Credentials ....................................................................................... 398

Configuring AWS Credentials with a Credentials File ............................................................ 399

Device Configuration ....................................................................................................... 400

Running the Test Suite .................................................................................................... 401

Results and Logs ............................................................................................................ 402

Testing Infrastructure .............................................................................................................. 404

Test Organization ................................................................................................................... 404

Troubleshooting ..................................................................................................................... 405

Troubleshooting Device Configuration ............................................................................... 405

Permissions Policy Template .................................................................................................... 407

Test Group Descriptions .......................................................................................................... 408

Troubleshooting ............................................................................................................................. 410

............................................................................................................................................ 410

Troubleshooting with Logs ....................................................................................................... 415

Troubleshooting Storage Issues ................................................................................................ 418

Troubleshooting Messages ....................................................................................................... 418

Troubleshooting Shadow Synchronization Timeout Issues ............................................................ 419

Document History .......................................................................................................................... 423

Earlier Updates ....................................................................................................................... 424

viii

AWS IoT Greengrass Developer Guide

What Is AWS IoT Greengrass?

AWS IoT Greengrass is software that extends cloud capabilities to local devices. This enables devices to

collect and analyze data closer to the source of information, react autonomously to local events, and

communicate securely with each other on local networks. AWS IoT Greengrass developers can use AWS

Lambda functions and prebuilt connectors (p. 266) to create serverless applications that are deployed

to devices for local execution.

The following diagram shows the basic architecture of AWS IoT Greengrass.

AWS IoT Greengrass makes it possible for customers to build IoT devices and application logic.

Specifically, AWS IoT Greengrass provides cloud-based management of application logic that runs on

devices. Locally deployed Lambda functions and connectors are triggered by local events, messages from

the cloud, or other sources.

In AWS IoT Greengrass, devices securely communicate on a local network and exchange messages

with each other without having to connect to the cloud. AWS IoT Greengrass provides a local pub/sub

message manager that can intelligently buffer messages if connectivity is lost so that inbound and

outbound messages to the cloud are preserved.

AWS IoT Greengrass protects user data:

• Through the secure authentication and authorization of devices.

• Through secure connectivity in the local network.

• Between local devices and the cloud.

Device security credentials function in a group until they are revoked, even if connectivity to the cloud is

disrupted, so that the devices can continue to securely communicate locally.

AWS IoT Greengrass provides secure, over-the-air software updates of Lambda functions.

AWS IoT Greengrass consists of:

• Software distributions

• AWS IoT Greengrass core software

• AWS IoT Greengrass core SDK

• Cloud service

• AWS IoT Greengrass API

1

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Software

• Features

• Lambda runtime

• Shadows implementation

• Message manager

• Group management

• Discovery service

• Over-the-air update agent

• Local resource access

• Machine learning inference

• Local secrets manager

AWS IoT Greengrass Core Software

The AWS IoT Greengrass core software provides the following functionality:

• Deployment and local execution of connectors and Lambda functions.

• Secure, encrypted storage of local secrets and controlled access by connectors and Lambda functions.

• MQTT messaging over the local network between devices, connectors, and Lambda functions using

managed subscriptions.

• MQTT messaging between AWS IoT and devices, connectors, and Lambda functions using managed

subscriptions.

• Secure connections between devices and the cloud using device authentication and authorization.

• Local shadow synchronization of devices. Shadows can be configured to sync with the cloud.

• Controlled access to local device and volume resources.

• Deployment of cloud-trained machine learning models for running local inference.

• Automatic IP address detection that enables devices to discover the Greengrass core device.

• Central deployment of new or updated group configuration. After the configuration data is

downloaded, the core device is restarted automatically.

• Secure, over-the-air software updates of user-defined Lambda functions.

AWS IoT Greengrass core instances are configured through AWS IoT Greengrass APIs that create and

update AWS IoT Greengrass group definitions stored in the cloud.

AWS IoT Greengrass Core Versions

The following tabs describe what's new and changed in AWS IoT Greengrass core software versions.

GGC v1.7.0

Current version.

New features:

• Greengrass connectors provide built-in integration with local infrastructure, device protocols,

AWS, and other cloud services. For more information, see Integrate with Services and Protocols

Using Connectors (p. 266).

• AWS IoT Greengrass extends AWS Secrets Manager to core devices, which makes your passwords,

tokens, and other secrets available to connectors and Lambda functions. Secrets are encrypted in

transit and at rest. For more information, see Deploy Secrets to the Core (p. 243).

2

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Versions

• Support for a hardware root of trust security option. For more information, see the section called

“Hardware Security” (p. 376).

• Isolation and permission settings that allow Lambda functions to run without Greengrass

containers and to use the permissions of a specified user and group. For more information, see the

section called “Controlling Greengrass Lambda Function Execution” (p. 150).

• You can run AWS IoT Greengrass in a Docker container (on Windows, macOS, or Linux) by

configuring your Greengrass group to run with no containerization. For more information, see the

section called “Run AWS IoT Greengrass in a Docker Container” (p. 159).

• MQTT messaging on port 443 with Application Layer Protocol Negotiation (ALPN) or connection

through a network proxy. For more information, see the section called “Connect on Port 443 or

Through a Network Proxy” (p. 32).

• The Amazon SageMaker Neo deep learning runtime, which supports machine learning models

that have been optimized by the Amazon SageMaker Neo deep learning compiler. For information

about the Neo deep learning runtime, see the section called “Runtimes and Precompiled

Framework Libraries for ML Inference” (p. 198).

• Support for Raspbian Stretch (2018-06-27) on Raspberry Pi core devices.

Bug fixes and improvements:

• General performance improvements and bug fixes.

In addition, the following features are available with this release:

• The AWS IoT Device Tester for AWS IoT Greengrass, which you can use to verify that your

CPU architecture, kernel configuration, and drivers work with AWS IoT Greengrass. For more

information, see AWS IoT Device Tester for AWS IoT Greengrass User Guide (p. 394).

• The AWS IoT Greengrass Core Software, AWS IoT Greengrass Core SDK, and AWS IoT Greengrass

Machine Learning SDK packages are available for dowload through Amazon CloudFront. For more

information, see the section called “AWS IoT Greengrass Downloads” (p. 19).

GGC v1.6.0

New features:

• Lambda executables that run binary code on the Greengrass core. Use the new AWS IoT

Greengrass Core SDK for C to write Lambda executables in C and C++. For more information, see

the section called “Lambda Executables” (p. 157).

• Optional local storage message cache that can persist across restarts. You can configure the

storage settings for MQTT messages that are queued for processing. For more information, see the

section called “MQTT Message Queue” (p. 37).

• Configurable maximum reconnect retry interval for when the core device is disconnected. For

more information, see the mqttMaxConnectionRetryInterval property in the section called

“AWS IoT Greengrass Core Configuration File” (p. 21).

• Local resource access to the host /proc directory. For more information, see Access Local Resources

with Lambda Functions (p. 169).

• Configurable write directory. The AWS IoT Greengrass core software can be deployed to read-only

and read-write locations. For more information, see the section called “Write Directory” (p. 35).

Bug fixes and improvements:

• Performance improvement for publishing messages in the Greengrass core and between devices

and the core.

3

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Versions

• Reduced the compute resources required to process logs generated by user-defined Lambda

functions.

GGC v1.5.0

New features:

• AWS IoT Greengrass Machine Learning (ML) Inference is generally available. You can perform ML

inference locally on AWS IoT Greengrass devices using models that are built and trained in the

cloud. For more information, see Perform Machine Learning Inference (p. 195).

• Greengrass Lambda functions now support binary data as input payload, in addition to JSON. To

use this feature, you must upgrade to AWS IoT Greengrass Core SDK version 1.1.0, which you can

download from the Software page in the AWS IoT console.

Bug fixes and improvements:

• Reduced the overall memory footprint.

• Performance improvements for sending messages to the cloud.

• Performance and stability improvements for the download agent, Device Certificate Manager, and

OTA update agent.

• Minor bug fixes.

GGC v1.3.0

New features:

• Over-the-air (OTA) update agent capable of handling cloud-deployed, Greengrass update jobs.

The agent is found under the new /greengrass/ota directory. For more information, see OTA

Updates of AWS IoT Greengrass Core Software (p. 129).

• Local resource access feature allows Greengrass Lambda functions to access local resources, such

as peripheral devices and volumes. For more information, see Access Local Resources with Lambda

Functions (p. 169).

GGC v1.1.0

New features:

• Deployed AWS IoT Greengrass groups can be reset by deleting Lambda functions, subscriptions,

and configurations. For more information, see Reset Deployments (p. 135).

• Support for Node.js 6.10 and Java 8 Lambda runtimes, in addition to Python 2.7.

To migrate from the previous version of the AWS IoT Greengrass core:

• Copy certificates from the /greengrass/configuration/certs folder to /greengrass/

certs.

• Copy /greengrass/configuration/config.json to /greengrass/config/config.json.

• Run /greengrass/ggc/core/greengrassd instead of /greengrass/greengrassd.

• Deploy the group to the new core.

GGC v1.0.0

Initial version.

4

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Groups

AWS IoT Greengrass Groups

An AWS IoT Greengrass group is a collection of settings and components, such as an AWS IoT Greengrass

core, devices, and subscriptions. Groups are used to define a scope of interaction. For example, a group

might represent one floor of a building, one truck, or an entire mining site. The following diagram shows

the components that can make up an Greengrass group.

In the preceding diagram:

A: AWS IoT Greengrass group definition

A collection of information about the AWS IoT Greengrass group.

B: AWS IoT Greengrass group settings

These include:

• AWS IoT Greengrass group role.

• Certification authority and local connection configuration.

• AWS IoT Greengrass core connectivity information.

• Default Lambda runtime environment. For more information, see the section called “Setting

Default Containerization for Lambda Functions in a Group” (p. 155).

• CloudWatch and local logs configuration. For more information, see Monitoring (p. 385).

C: AWS IoT Greengrass core

The AWS IoT thing that represents the AWS IoT Greengrass core. For more information, see the

section called “AWS IoT Greengrass Core” (p. 20).

D: Lambda function definition

A list of Lambda functions that run locally on the core, with associated configuration data. For more

information, see Run Local Lambda Functions (p. 147).

E: Subscription definition

A list of subscriptions that enable communication using MQTT messages. A subscription defines:

5

AWS IoT Greengrass Developer Guide

Devices in AWS IoT Greengrass

• A message source and message target. These can be devices, Lambda functions, connectors, AWS

IoT, and the local shadow service

• A subject, which is an MQTT topic or topic filter that's used to filter message data.

For more information, see the section called “Greengrass Messaging Workflow” (p. 375).

F: Connector definition

A list of connectors that run locally on the core, with associated configuration data. For more

information, see Integrate with Services and Protocols Using Connectors (p. 266).

G: Device definition

A list of AWS IoT things (devices) that are members of the AWS IoT Greengrass group, with

associated configuration data. For more information, see the section called “Devices in AWS IoT

Greengrass” (p. 6).

H: Resource definition

A list of local resources, machine learning resources, and secret resources on the AWS IoT Greengrass

core, with associated configuration data. For more information, see Access Local Resources with

Lambda Functions (p. 169), Perform Machine Learning Inference (p. 195), and Deploy Secrets to the

Core (p. 243).

When deployed, the AWS IoT Greengrass group definition, Lambda functions, connectors, resources, and

subscription table are copied to an AWS IoT Greengrass core device.

Devices in AWS IoT Greengrass

There are two types of devices:

AWS IoT Greengrass cores

A Greengrass core is an AWS IoT device that runs the AWS IoT Greengrass core software, which

enables it to communicate directly with the AWS IoT and AWS IoT Greengrass cloud services. A core

has its own certificate used for authenticating with AWS IoT. It has a device shadow and exists in the

AWS IoT device registry. AWS IoT Greengrass cores run a local Lambda runtime, a deployment agent,

and an IP address tracker that sends IP address information to the AWS IoT Greengrass cloud service

to allow Greengrass devices to automatically discover their group and core connection information.

For more information, see the section called “AWS IoT Greengrass Core” (p. 20).

AWS IoT devices connected to a Greengrass core

These Greengrass devices are added to a Greengrass group and run Amazon FreeRTOS or have the

AWS IoT Device SDK installed. For more information, see AWS IoT Greengrass Discovery Library in

the Amazon FreeRTOS User Guide or AWS IoT SDKs in the AWS IoT Developer Guide.

Greengrass devices connect to an AWS IoT Greengrass core. They can also be configured to

communicate with Lambda functions, connectors, and other devices in the group, and with AWS IoT

or the local shadow service. If the core device loses connectivity to the cloud, devices can continue

to communicate over the local network. Devices can vary in size, from smaller microcontroller-based

devices to large appliances.

The following table shows how these device types are related.

6

AWS IoT Greengrass Developer Guide

SDKs

The AWS IoT Greengrass core device stores certificates in two locations:

• Core device certificate in /greengrass/certs - The core device certificate is named hash.cert.pem (for

example, 86c84488a5.cert.pem). This certificate is used to authenticate the core when connecting

to the AWS IoT and AWS IoT Greengrass services.

• MQTT core server certificate in /greengrass-root/ggc/var/state/server - The MQTT core server

certificate is named server.crt. This certificate is used for mutual authentication between the local

MQTT service (that's on the Greengrass core) and Greengrass devices before messages are exchanged.

SDKs

The following AWS-provided SDKs are used to work with AWS IoT Greengrass:

GGC 1.7.0

AWS SDK

Use the AWS SDK to build applications that interact with any AWS service, including Amazon

S3, Amazon DynamoDB, AWS IoT, AWS IoT Greengrass, and more. In the context of AWS IoT

Greengrass, you can use the AWS SDK in deployed Lambda functions to make direct calls to any

AWS service. For more information, see AWS SDKs (p. 148).

7

AWS IoT Greengrass Developer Guide

SDKs

AWS IoT Device SDK

The AWS IoT Device SDK helps devices connect to AWS IoT or AWS IoT Greengrass services.

Devices must know which AWS IoT Greengrass group they belong to and the IP address of the

AWS IoT Greengrass core that they should connect to.

Although you can use any of the AWS IoT Device SDK platforms to connect to an AWS

IoT Greengrass core, only the C++ and Python SDKs provide AWS IoT Greengrass-specific

functionality, such as access to the AWS IoT Greengrass Discovery Service and AWS IoT

Greengrass core root CA downloads. For more information, see AWS IoT Device SDK.

AWS IoT Greengrass Core SDK

The AWS IoT Greengrass Core SDK enables Lambda functions to interact with the Greengrass

core, publish messages to AWS IoT, interact with the local shadow service, invoke other

deployed Lambda functions, and access secret resources. This SDK is used by Lambda functions

that run on an AWS IoT Greengrass core. For more information, see AWS IoT Greengrass Core

SDK (p. 147).

AWS IoT Greengrass Machine Learning SDK

The AWS IoT Greengrass Machine Learning SDK enables Lambda functions to consume machine

learning models that are deployed to the Greengrass core as machine learning resources. This

SDK is used by Lambda functions that run on an AWS IoT Greengrass core and interact with

a local inference service. For more information, see AWS IoT Greengrass Machine Learning

SDK (p. 148).

GGC 1.6.0

AWS SDKs

Using the AWS SDKs, you can build applications that work with any AWS service, including

Amazon S3, Amazon DynamoDB, AWS IoT, AWS IoT Greengrass, and more. In the context of

AWS IoT Greengrass, you can use the AWS SDK in deployed Lambda functions to make direct

calls to any AWS service. For more information, see the section called “SDKs” (p. 147).

AWS IoT Device SDKs

The AWS IoT Device SDKs helps devices connect to AWS IoT or AWS IoT Greengrass services.

Devices must know which AWS IoT Greengrass group they belong to and the IP address of the

AWS IoT Greengrass core that they should connect to.

Although you can use any of the AWS IoT Device SDKs to connect to an AWS IoT Greengrass

core, only the C++ and Python Device SDKs provide AWS IoT Greengrass-specific functionality,

such as access to the AWS IoT Greengrass Discovery Service and AWS IoT Greengrass core root

CA downloads. For more information, see AWS IoT Device SDK.

AWS IoT Greengrass Core SDK

The AWS IoT Greengrass Core SDK enables Lambda functions to interact with the AWS IoT

Greengrass core on which they run in order to publish messages, interact with the local Device

Shadow service, or invoke other deployed Lambda functions. This SDK is used exclusively for

writing Lambda functions running in the Lambda runtime on an AWS IoT Greengrass core. For

more information, see the section called “SDKs” (p. 147).

GGC v1.5.0

AWS SDKs

Using the AWS SDKs, you can build applications that work with any AWS service, including

Amazon S3, Amazon DynamoDB, AWS IoT, AWS IoT Greengrass, and more. In the context of

8

AWS IoT Greengrass Developer Guide

SDKs

AWS IoT Greengrass, you can use the AWS SDK inside deployed Lambda functions to make

direct calls to any AWS service.

AWS IoT Device SDKs

The AWS IoT Device SDKs helps devices connect to AWS IoT or AWS IoT Greengrass services.

Devices must know which AWS IoT Greengrass group they belong to and the IP address of the

AWS IoT Greengrass core that they should connect to.

Although you can use any of the AWS IoT Device SDKs to connect to an AWS IoT Greengrass

core, only the C++ and Python Device SDKs provide AWS IoT Greengrass-specific functionality,

such as access to the AWS IoT Greengrass Discovery Service and AWS IoT Greengrass core root

CA downloads. For more information, see AWS IoT Device SDK.

AWS IoT Greengrass Core SDK

The AWS IoT Greengrass Core SDK enables Lambda functions to interact with the AWS IoT

Greengrass core on which they run in order to publish messages, interact with the local Device

Shadow service, or invoke other deployed Lambda functions. This SDK is used exclusively for

writing Lambda functions running in the Lambda runtime on an AWS IoT Greengrass core.

Lambda functions running on an AWS IoT Greengrass core can interact with AWS cloud services

directly using the AWS SDK. The AWS IoT Greengrass Core SDK and the AWS SDK are contained

in different packages, so you can use both packages simultaneously. You can download the AWS

IoT Greengrass Core SDK from the Software page of the AWS IoT console.

The AWS IoT Greengrass Core SDK follows the AWS SDK programming model. It allows you to

easily port Lambda functions developed for the cloud to Lambda functions that run on an AWS

IoT Greengrass core. For example, using the AWS SDK, the following Lambda function publishes

a message to the topic "/some/topic" in the cloud:

import boto3

client = boto3.client('iot-data')

response = client.publish(

topic = "/some/topic",

qos = 0,

payload = "Some payload".encode()

)

To port this Lambda function for execution on an AWS IoT Greengrass core, replace the import

boto3 statement with the import greengrasssdk, as shown in the following snippet:

Note

The AWS IoT Greengrass Core SDK only supports sending MQTT messages with QoS =

0.

import greengrasssdk

client = greengrasssdk.client('iot-data')

response = client.publish(

topic='/some/topic',

qos=0,

payload='some payload'.encode()

)

This allows you to test your Lambda functions in the cloud and migrate them to AWS IoT

Greengrass with minimal effort.

Note

The AWS SDK is natively part of the environment of a Lambda function that runs in the

AWS cloud. If you want to use boto3 in a Lambda function that's deployed to an AWS IoT

9

AWS IoT Greengrass Developer Guide

SDKs

Greengrass core, make sure to include the AWS SDK in your package. In addition, if you use

both the AWS IoT Greengrass Core SDK and the AWS SDK in the same package, make sure

that your Lambda functions use the correct namespaces. For more information about how

to create your deployment package, see:

•Creating a Deployment Package (Python)

•Creating a Deployment Package (Node.js)

•Creating a Deployment Package (Java)

GGC v1.3.0

AWS SDKs

Using the AWS SDKs, you can build applications that work with any AWS service, including

Amazon S3, Amazon DynamoDB, AWS IoT, AWS IoT Greengrass, and more. In the context of

AWS IoT Greengrass, you can use the AWS SDK inside deployed Lambda functions to make

direct calls to any AWS service.

AWS IoT Device SDKs

The AWS IoT Device SDKs helps devices connect to AWS IoT or AWS IoT Greengrass services.

Devices must know which AWS IoT Greengrass group they belong to and the IP address of the

AWS IoT Greengrass core that they should connect to.

Although you can use any of the AWS IoT Device SDKs to connect to an AWS IoT Greengrass

core, only the C++ and Python Device SDKs provide AWS IoT Greengrass-specific functionality,

such as access to the AWS IoT Greengrass Discovery Service and AWS IoT Greengrass core root

CA downloads. For more information, see AWS IoT Device SDK.

AWS IoT Greengrass Core SDK

The AWS IoT Greengrass Core SDK enables Lambda functions to interact with the AWS IoT

Greengrass core on which they run in order to publish messages, interact with the local Device

Shadow service, or invoke other deployed Lambda functions. This SDK is used exclusively for

writing Lambda functions running in the Lambda runtime on an AWS IoT Greengrass core.

Lambda functions running on an AWS IoT Greengrass core can interact with AWS cloud services

directly using the AWS SDK. The AWS IoT Greengrass Core SDK and the AWS SDK are contained

in different packages, so you can use both packages simultaneously. You can download the AWS

IoT Greengrass Core SDK from the Software page of the AWS IoT console.

The AWS IoT Greengrass Core SDK follows the AWS SDK programming model. It allows you to

easily port Lambda functions developed for the cloud to Lambda functions that run on an AWS

IoT Greengrass core. For example, using the AWS SDK, the following Lambda function publishes

a message to the topic "/some/topic" in the cloud:

import boto3

client = boto3.client('iot-data')

response = client.publish(

topic = "/some/topic",

qos = 0,

payload = "Some payload".encode()

)

To port this Lambda function for execution on an AWS IoT Greengrass core, replace the import

boto3 statement with the import greengrasssdk, as shown in the following snippet:

Note

The AWS IoT Greengrass Core SDK only supports sending MQTT messages with QoS =

0.

10

AWS IoT Greengrass Developer Guide

SDKs

import greengrasssdk

client = greengrasssdk.client('iot-data')

response = client.publish(

topic='/some/topic',

qos=0,

payload='some payload'.encode()

)

This allows you to test your Lambda functions in the cloud and migrate them to AWS IoT

Greengrass with minimal effort.

Note

The AWS SDK is natively part of the environment of a Lambda function that runs in the

AWS cloud. If you want to use boto3 in a Lambda function that's deployed to an AWS IoT

Greengrass core, make sure to include the AWS SDK in your package. In addition, if you use

both the AWS IoT Greengrass Core SDK and the AWS SDK in the same package, make sure

that your Lambda functions use the correct namespaces. For more information about how

to create your deployment package, see:

•Creating a Deployment Package (Python)

•Creating a Deployment Package (Node.js)

•Creating a Deployment Package (Java)

GGC v1.1.0

AWS SDKs

Using the AWS SDKs, you can build applications that work with any AWS service, including

Amazon S3, Amazon DynamoDB, AWS IoT, AWS IoT Greengrass, and more. In the context of

AWS IoT Greengrass, you can use the AWS SDK inside deployed Lambda functions to make

direct calls to any AWS service.

AWS IoT Device SDKs

The AWS IoT Device SDKs helps devices connect to AWS IoT or AWS IoT Greengrass services.

Devices must know which AWS IoT Greengrass group they belong to and the IP address of the

AWS IoT Greengrass core that they should connect to.

Although you can use any of the AWS IoT Device SDKs to connect to an AWS IoT Greengrass

core, only the C++ and Python Device SDKs provide AWS IoT Greengrass-specific functionality,

such as access to the AWS IoT Greengrass Discovery Service and AWS IoT Greengrass core root

CA downloads. For more information, see AWS IoT Device SDK.

AWS IoT Greengrass Core SDK

The AWS IoT Greengrass Core SDK enables Lambda functions to interact with the AWS IoT

Greengrass core on which they run in order to publish messages, interact with the local Device

Shadow service, or invoke other deployed Lambda functions. This SDK is used exclusively for

writing Lambda functions running in the Lambda runtime on an AWS IoT Greengrass core.

Lambda functions running on an AWS IoT Greengrass core can interact with AWS cloud services

directly using the AWS SDK. The AWS IoT Greengrass Core SDK and the AWS SDK are contained

in different packages, so you can use both packages simultaneously. You can download the AWS

IoT Greengrass Core SDK from the Software page of the AWS IoT console.

The AWS IoT Greengrass Core SDK follows the AWS SDK programming model. It allows you to

easily port Lambda functions developed for the cloud to Lambda functions that run on an AWS

11

AWS IoT Greengrass Developer Guide

SDKs

IoT Greengrass core. For example, using the AWS SDK, the following Lambda function publishes

a message to the topic "/some/topic" in the cloud:

import boto3

client = boto3.client('iot-data')

response = client.publish(

topic = "/some/topic",

qos = 0,

payload = "Some payload".encode()

)

To port this Lambda function for execution on an AWS IoT Greengrass core, replace the import

boto3 statement with the import greengrasssdk, as shown in the following snippet:

Note

The AWS IoT Greengrass Core SDK only supports sending MQTT messages with QoS =

0.

import greengrasssdk

client = greengrasssdk.client('iot-data')

response = client.publish(

topic='/some/topic',

qos=0,

payload='some payload'.encode()

)

This allows you to test your Lambda functions in the cloud and migrate them to AWS IoT

Greengrass with minimal effort.

Note

The AWS SDK is natively part of the environment of a Lambda function that runs in the

AWS cloud. If you want to use boto3 in a Lambda function that's deployed to an AWS IoT

Greengrass core, make sure to include the AWS SDK in your package. In addition, if you use

both the AWS IoT Greengrass Core SDK and the AWS SDK in the same package, make sure

that your Lambda functions use the correct namespaces. For more information about how

to create your deployment package, see:

•Creating a Deployment Package (Python)

•Creating a Deployment Package (Node.js)

•Creating a Deployment Package (Java)

GGC v1.0.0

AWS SDKs

Using the AWS SDKs, you can build applications that work with any AWS service, including

Amazon S3, Amazon DynamoDB, AWS IoT, AWS IoT Greengrass, and more. In the context of

AWS IoT Greengrass, you can use the AWS SDK inside deployed Lambda functions to make

direct calls to any AWS service.

AWS IoT Device SDKs

The AWS IoT Device SDKs helps devices connect to AWS IoT or AWS IoT Greengrass services.

Devices must know which AWS IoT Greengrass group they belong to and the IP address of the

AWS IoT Greengrass core that they should connect to.

12

AWS IoT Greengrass Developer Guide

SDKs

Although you can use any of the AWS IoT Device SDKs to connect to an AWS IoT Greengrass

core, only the C++ and Python Device SDKs provide AWS IoT Greengrass-specific functionality,

such as access to the AWS IoT Greengrass Discovery Service and AWS IoT Greengrass core root

CA downloads. For more information, see AWS IoT Device SDK.

AWS IoT Greengrass Core SDK

The AWS IoT Greengrass Core SDK enables Lambda functions to interact with the AWS IoT

Greengrass core on which they run in order to publish messages, interact with the local Device

Shadow service, or invoke other deployed Lambda functions. This SDK is used exclusively for

writing Lambda functions running in the Lambda runtime on an AWS IoT Greengrass core.

Lambda functions running on an AWS IoT Greengrass core can interact with AWS cloud services

directly using the AWS SDK. The AWS IoT Greengrass Core SDK and the AWS SDK are contained

in different packages, so you can use both packages simultaneously. You can download the AWS

IoT Greengrass Core SDK from the Software page of the AWS IoT console.

The AWS IoT Greengrass Core SDK follows the AWS SDK programming model. It allows you to

easily port Lambda functions developed for the cloud to Lambda functions that run on an AWS

IoT Greengrass core. For example, using the AWS SDK, the following Lambda function publishes

a message to the topic "/some/topic" in the cloud:

import boto3

client = boto3.client('iot-data')

response = client.publish(

topic = "/some/topic",

qos = 0,

payload = "Some payload".encode()

)

To port this Lambda function for execution on an AWS IoT Greengrass core, replace the import

boto3 statement with the import greengrasssdk, as shown in the following snippet:

Note

The AWS IoT Greengrass Core SDK only supports sending MQTT messages with QoS =

0.

import greengrasssdk

client = greengrasssdk.client('iot-data')

response = client.publish(

topic='/some/topic',

qos=0,

payload='some payload'.encode()

)

This allows you to test your Lambda functions in the cloud and migrate them to AWS IoT

Greengrass with minimal effort.

Note

The AWS SDK is natively part of the environment of a Lambda function that runs in the

AWS cloud. If you want to use boto3 in a Lambda function that's deployed to an AWS IoT

Greengrass core, make sure to include the AWS SDK in your package. In addition, if you use

both the AWS IoT Greengrass Core SDK and the AWS SDK in the same package, make sure

that your Lambda functions use the correct namespaces. For more information about how

to create your deployment package, see:

•Creating a Deployment Package (Python)

13

AWS IoT Greengrass Developer Guide

Supported Platforms and Requirements

Supported Platforms and Requirements

The AWS IoT Greengrass core software is supported on the platforms listed here, and requires a few

dependencies.

Note

You can download the core software from the Software page in the AWS IoT Core console or

from the AWS IoT Greengrass Core Software (p. 19) downloads.

GGC v1.7.0

• Supported platforms:

• Architecture: ARMv7l; OS: Linux; Distribution: Raspbian Stretch, 2018-06-29. While several

versions may work with AWS IoT Greengrass, we recommend this as it is the officially supported

distribution.

• Architecture: x86_64; OS: Linux; Distribution: Amazon Linux (amzn-ami-

hvm-2016.09.1.20170119-x86_64-ebs), Ubuntu 14.04 – 16.04

• Architecture: ARMv8 (AArch64); OS: Linux; Distribution: Arch Linux

• Windows, macOS, and Linux platforms can run AWS IoT Greengrass in a Docker container.

For more information, see the section called “Run AWS IoT Greengrass in a Docker

Container” (p. 159).

• The following items are required:

• Minimum 128 MB RAM allocated to the AWS IoT Greengrass core device.

• Linux kernel version 4.4 or greater: while several versions may work with AWS IoT Greengrass,

for optimal security and performance, we recommend version 4.4 or greater.

•Glibc library version 2.14 or greater.

• The /var/run directory must be present on the device.

• AWS IoT Greengrass requires hardlink and softlink protection to be enabled on the device.

Without this, AWS IoT Greengrass can only be run in insecure mode, using the -i flag.

• The ggc_user and ggc_group user and group must be present on the device.

• The following Linux kernel configurations must be enabled on the device:

• Namespace: CONFIG_IPC_NS, CONFIG_UTS_NS, CONFIG_USER_NS, CONFIG_PID_NS

• CGroups: CONFIG_CGROUP_DEVICE, CONFIG_CGROUPS, CONFIG_MEMCG

• Others: CONFIG_POSIX_MQUEUE, CONFIG_OVERLAY_FS,

CONFIG_HAVE_ARCH_SECCOMP_FILTER, CONFIG_SECCOMP_FILTER, CONFIG_KEYS,

CONFIG_SECCOMP

•/dev/stdin, /dev/stdout, and /dev/stderr must be enabled.

• The Linux kernel must support cgroups.

• The memory cgroup must be enabled and mounted to allow AWS IoT Greengrass to set the

memory limit for Lambda functions.

• The root certificate for Amazon S3 and AWS IoT must be present in the system trust store.

• The following items may be optional:

• The devices cgroup must be enabled and mounted if Lambda functions with Local Resource

Access (LRA) (p. 169) are used to open files on the AWS IoT Greengrass core device.

•Python version 2.7 is required if Python Lambda functions are used. If so, ensure that it's added

to your PATH environment variable.

•NodeJS version 6.10 or greater is required if Node.JS Lambda functions are used. If so, ensure

that it's added to your PATH environment variable.

•Java version 8 or greater is required if Java Lambda functions are used. If so, ensure that it's

added to your PATH environment variable.

14

AWS IoT Greengrass Developer Guide

Supported Platforms and Requirements

• The following commands are required for Greengrass OTA Agent (p. 130): wget, realpath,

tar, readlink, basename, dirname, pidof, df, grep, and umount.

GGC v1.6.0

• Supported platforms:

• Architecture: ARMv7l; OS: Linux; Distribution: Raspbian Jessie, 2017-03-02

Note

You can choose to use Raspbian Stretch instead of Jessie. Using Stretch will require

additional memory set-up. For more information, see this step (p. 50).

• Architecture: x86_64; OS: Linux; Distribution: Amazon Linux (amzn-ami-

hvm-2016.09.1.20170119-x86_64-ebs)

• Architecture: x86_64; OS: Linux; Distribution: Ubuntu 14.04 – 16.04

• Architecture: ARMv8 (AArch64); OS: Linux; Distribution: Ubuntu 14.04 – 16.04 (Annapurna

Alpine V2)

• The following items are required:

• Minimum 128 MB RAM allocated to the AWS IoT Greengrass core device.

• Linux kernel version 4.4 or greater: while several versions may work with AWS IoT Greengrass,

for optimal security and performance, we recommend version 4.4 or greater.

•Glibc library version 2.14 or greater.

• The /var/run directory must be present on the device.

• AWS IoT Greengrass requires hardlink and softlink protection to be enabled on the device.

Without this, AWS IoT Greengrass can only be run in insecure mode, using the -i flag.

• The ggc_user and ggc_group user and group must be present on the device.

• The following Linux kernel configurations must be enabled on the device:

• Namespace: CONFIG_IPC_NS, CONFIG_UTS_NS, CONFIG_USER_NS, CONFIG_PID_NS

• CGroups: CONFIG_CGROUP_DEVICE, CONFIG_CGROUPS, CONFIG_MEMCG

• Others: CONFIG_POSIX_MQUEUE, CONFIG_OVERLAY_FS,

CONFIG_HAVE_ARCH_SECCOMP_FILTER, CONFIG_SECCOMP_FILTER, CONFIG_KEYS,

CONFIG_SECCOMP

•/dev/stdin, /dev/stdout, and /dev/stderr must be enabled.

• The Linux kernel must support cgroups.

• The memory cgroup must be enabled and mounted to allow AWS IoT Greengrass to set the

memory limit for Lambda functions.

• The root certificate for Amazon S3 and AWS IoT must be present in the system trust store.

• The following items may be optional:

• The devices cgroup must be enabled and mounted if Lambda functions with Local Resource

Access (LRA) (p. 169) are used to open files on the AWS IoT Greengrass core device.

•Python version 2.7 is required if Python Lambda functions are used. If so, ensure that it's added

to your PATH environment variable.

•NodeJS version 6.10 or greater is required if Node.JS Lambda functions are used. If so, ensure

that it's added to your PATH environment variable.

•Java version 8 or greater is required if Java Lambda functions are used. If so, ensure that it's

added to your PATH environment variable.

•OpenSSL 1.01 or greater is required for Greengrass OTA Agent (p. 130) as well as the following

commands: wget, realpath, tar, readlink, basename, dirname, pidof, df, grep, and

umount.

15

AWS IoT Greengrass Developer Guide

Supported Platforms and Requirements

GGC v1.5.0

• Supported platforms:

• Architecture: ARMv7l; OS: Linux; Distribution: Raspbian Jessie, 2017-03-02

Note

You can choose to use Raspbian Stretch instead of Jessie. Using Stretch will require

additional memory set-up. For more information, see this step (p. 50).

• Architecture: x86_64; OS: Linux; Distribution: Amazon Linux (amzn-ami-

hvm-2016.09.1.20170119-x86_64-ebs)

• Architecture: x86_64; OS: Linux; Distribution: Ubuntu 14.04 – 16.04

• Architecture: ARMv8 (AArch64); OS: Linux; Distribution: Ubuntu 14.04 – 16.04 (Annapurna

Alpine V2)

• The following items are required:

• Minimum 128 MB RAM allocated to the AWS IoT Greengrass core device.

• Linux kernel version 4.4 or greater: while several versions may work with AWS IoT Greengrass,

for optimal security and performance, we recommend version 4.4 or greater.

•Glibc library version 2.14 or greater.

• The /var/run directory must be present on the device.

• AWS IoT Greengrass requires hardlink and softlink protection to be enabled on the device.

Without this, AWS IoT Greengrass can only be run in insecure mode, using the -i flag.

• The ggc_user and ggc_group user and group must be present on the device.

• The following Linux kernel configurations must be enabled on the device:

• Namespace: CONFIG_IPC_NS, CONFIG_UTS_NS, CONFIG_USER_NS, CONFIG_PID_NS

• CGroups: CONFIG_CGROUP_DEVICE, CONFIG_CGROUPS, CONFIG_MEMCG

• Others: CONFIG_POSIX_MQUEUE, CONFIG_OVERLAY_FS,

CONFIG_HAVE_ARCH_SECCOMP_FILTER, CONFIG_SECCOMP_FILTER, CONFIG_KEYS,

CONFIG_SECCOMP

•/dev/stdin, /dev/stdout, and /dev/stderr must be enabled.

• The Linux kernel must support cgroups.

• The memory cgroup must be enabled and mounted to allow AWS IoT Greengrass to set the

memory limit for Lambda functions.

• The root certificate for Amazon S3 and AWS IoT must be present in the system trust store.

• The following items may be optional:

• The devices cgroup must be enabled and mounted if Lambda functions with Local Resource

Access (LRA) (p. 169) are used to open files on the AWS IoT Greengrass core device.

•Python version 2.7 is required if Python Lambda functions are used. If so, ensure that it's added

to your PATH environment variable.

•NodeJS version 6.10 or greater is required if Node.JS Lambda functions are used. If so, ensure

that it's added to your PATH environment variable.

•Java version 8 or greater is required if Java Lambda functions are used. If so, ensure that it's

added to your PATH environment variable.

•OpenSSL 1.01 or greater is required for Greengrass OTA Agent (p. 130) as well as the following

commands: wget, realpath, tar, readlink, basename, dirname, pidof, df, grep, and

umount.

GGC v1.3.0

• Supported platforms:

• Architecture: ARMv7l; OS: Linux; Distribution: Raspbian Jessie, 2017-03-02

16

AWS IoT Greengrass Developer Guide

Supported Platforms and Requirements

• Architecture: x86_64; OS: Linux; Distribution: Amazon Linux (amzn-ami-

hvm-2016.09.1.20170119-x86_64-ebs)

• Architecture: x86_64; OS: Linux; Distribution: Ubuntu 14.04 – 16.04

• Architecture: ARMv8 (AArch64); OS: Linux; Distribution: Ubuntu 14.04 – 16.04 (Annapurna

Alpine V2)

• The following items are required:

• Minimum 128 MB RAM allocated to the AWS IoT Greengrass core device.

• Linux kernel version 4.4 or later. Although several versions might work with AWS IoT Greengrass,

for optimal security and performance, we recommend version 4.4 or later.

•Glibc library version 2.14 or later.

• The /var/run directory must be present on the device.

• AWS IoT Greengrass requires hardlink and softlink protection to be enabled on the device.

Without this, AWS IoT Greengrass can only be run in insecure mode, using the -i flag.

• The ggc_user and ggc_group user and group must be present on the device.

• The following Linux kernel configurations must be enabled on the device:

• Namespace: CONFIG_IPC_NS, CONFIG_UTS_NS, CONFIG_USER_NS, CONFIG_PID_NS

• CGroups: CONFIG_CGROUP_DEVICE, CONFIG_CGROUPS, CONFIG_MEMCG

• Others: CONFIG_POSIX_MQUEUE, CONFIG_OVERLAY_FS,

CONFIG_HAVE_ARCH_SECCOMP_FILTER, CONFIG_SECCOMP_FILTER, CONFIG_KEYS,

CONFIG_SECCOMP

• The sqlite3 package is required for AWS IoT device shadows. Make sure it’s added to your

PATH environment variable.

•/dev/stdin, /dev/stdout, and /dev/stderr must be enabled.

• The Linux kernel must support cgroups.

• The memory cgroup must be enabled and mounted to allow AWS IoT Greengrass to set the

memory limit for Lambda functions.

• The root certificate for Amazon S3 and AWS IoT must be present in the system trust store.

• The following items might be optional:

• The devices cgroup must be enabled and mounted if Lambda functions with local resource

access (LRA) (p. 169) are used to open files on the AWS IoT Greengrass core device.

•Python version 2.7 is required if Python Lambda functions are used. If so, make sure that it's

added to your PATH environment variable.

•Node.js version 6.10 or later is required if Node.js Lambda functions are used. If so, make sure

that it's added to your PATH environment variable.

•Java version 8 or later is required if Java Lambda functions are used. If so, make sure that it's

added to your PATH environment variable.

•OpenSSL 1.01 or later is required for Greengrass OTA Agent (p. 130) as are the following

commands: wget, realpath, tar, readlink, basename, dirname, pidof, df, grep, and

umount.

GGC v1.1.0

• Supported platforms:

• Architecture: ARMv7l; OS: Linux; Distribution: Raspbian Jessie, 2017-03-02

• Architecture: x86_64; OS: Linux; Distribution: Amazon Linux (amzn-ami-

hvm-2016.09.1.20170119-x86_64-ebs)

• Architecture: x86_64; OS: Linux; Distribution: Ubuntu 14.04 – 16.04

• Architecture: ARMv8 (AArch64); OS: Linux; Distribution: Ubuntu 14.04 – 16.04 (Annapurna

Alpine V2) 17

AWS IoT Greengrass Developer Guide

Supported Platforms and Requirements

• The following items are required:

• Minimum 128 MB RAM allocated to the AWS IoT Greengrass core device.

• Linux kernel version 4.4 or later. Although several versions might work with AWS IoT Greengrass,

for optimal security and performance, we recommend version 4.4 or later.

•Glibc library version 2.14 or later.

• The /var/run directory must be present on the device.

• AWS IoT Greengrass requires hardlink and softlink protection to be enabled on the device.

Without this, AWS IoT Greengrass can only be run in insecure mode, using the -i flag.

• The ggc_user and ggc_group user and group must be present on the device.

• The following Linux kernel configurations must be enabled on the device:

• Namespace: CONFIG_IPC_NS, CONFIG_UTS_NS, CONFIG_USER_NS, CONFIG_PID_NS

• CGroups: CONFIG_CGROUP_DEVICE, CONFIG_CGROUPS, CONFIG_MEMCG

• Others: CONFIG_POSIX_MQUEUE, CONFIG_OVERLAY_FS,

CONFIG_HAVE_ARCH_SECCOMP_FILTER, CONFIG_SECCOMP_FILTER, CONFIG_KEYS,

CONFIG_SECCOMP

• The sqlite3 package is required for AWS IoT device shadows. Make sure it’s added to your

PATH environment variable.

•/dev/stdin, /dev/stdout, and /dev/stderr must be enabled.

• The Linux kernel must support cgroups.

• The memory cgroup must be enabled and mounted to allow AWS IoT Greengrass to set the

memory limit for Lambda functions.

• The root certificate for Amazon S3 and AWS IoT must be present in the system trust store.

• The following items might be optional:

•Python version 2.7 is required if Python Lambda functions are used. If so, make sure that it's

added to your PATH environment variable.

•Node.js version 6.10 or later is required if Node.js Lambda functions are used. If so, make sure

that it's added to your PATH environment variable.

•Java version 8 or later is required if Java Lambda functions are used. If so, make sure that it's

added to your PATH environment variable.

GGC v1.0.0

• Supported platforms:

• Architecture: ARMv7l; OS: Linux; Distribution: Raspbian Jessie, 2017-03-02

• Architecture: x86_64; OS: Linux; Distribution: Amazon Linux (amzn-ami-

hvm-2016.09.1.20170119-x86_64-ebs)

• Architecture: x86_64; OS: Linux; Distribution: Ubuntu 14.04 – 16.04

• Architecture: ARMv8 (AArch64); OS: Linux; Distribution: Ubuntu 14.04 – 16.04 (Annapurna

Alpine V2)

• The following items are required:

• Minimum 128 MB RAM allocated to the AWS IoT Greengrass core device.

• Linux kernel version 4.4 or later. Although several versions might work with AWS IoT Greengrass,

for optimal security and performance, we recommend version 4.4 or later.

•Glibc library version 2.14 or later.

• The /var/run directory must be present on the device.

• AWS IoT Greengrass requires hardlink and softlink protection to be enabled on the device.

Without this, AWS IoT Greengrass can only be run in insecure mode, using the -i flag.

• The ggc_user and ggc_group user and group must be present on the device.

• The following Linux kernel configurations must be enabled on the device:

18

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Downloads

• Namespace: CONFIG_IPC_NS, CONFIG_UTS_NS, CONFIG_USER_NS, CONFIG_PID_NS

• CGroups: CONFIG_CGROUP_DEVICE, CONFIG_CGROUPS, CONFIG_MEMCG

• Others: CONFIG_POSIX_MQUEUE, CONFIG_OVERLAY_FS,

CONFIG_HAVE_ARCH_SECCOMP_FILTER, CONFIG_SECCOMP_FILTER, CONFIG_KEYS,

CONFIG_SECCOMP

• The sqlite3 package is required for AWS IoT device shadows. Make sure it’s added to your

PATH environment variable.

•/dev/stdin, /dev/stdout, and /dev/stderr must be enabled.

• The Linux kernel must support cgroups.

• The memory cgroup must be enabled and mounted to allow AWS IoT Greengrass to set the

memory limit for Lambda functions.

• The root certificate for Amazon S3 and AWS IoT must be present in the system trust store.

• The following items might be optional:

•Python version 2.7 is required if Python Lambda functions are used. If so, make sure that it's

added to your PATH environment variable.

AWS IoT Greengrass Downloads

You can use the following information to locate and download software for use with AWS IoT

Greengrass.

AWS IoT Greengrass Core Software

AWS IoT Greengrass Software extends AWS functionality onto a AWS IoT Greengrass core device,

enabling local Devices to act locally on the data they generate.

v1.7.0

•Architecture: AArch64, OS: Linux.

•Architecture: ARMv7l, OS: Linux.

•Architecture: x86_64; OS: Linux.

v1.6.0

•Architecture: AArch64; OS: Linux.

•Architecture: ARMv7l; OS: Linux.

•Architecture: x86_64; OS: Linux.

•Architecture: x86_64; OS: Ubuntu.

AWS IoT Greengrass Core SDK Software

The AWS IoT Greengrass Core SDK (p. 147) enables Lambda functions to interact with the AWS IoT

Greengrass core on which they run.

v1.3.0

•Java 8.

•Node JS 6.10.

19

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Docker Software

•Python 2.7.

v1.2.0

•Java 8.

•Node JS 6.10.

•Python 2.7.

AWS IoT Greengrass Docker Software

The AWS IoT Greengrass Docker Software download enables you to run AWS IoT Greengrass in a Docker

container. Instructions are provided in the Docker file.

v1.7.0

•Docker v1.7.0.

AWS IoT Greengrass ML SDK Software

The AWS IoT Greengrass Machine Learning SDK (p. 148) enables the Lambda functions you author to

consume the machine learning model available on the device.

v1.0.0

•Python 2.7.

We Want to Hear from You

We welcome your feedback. To contact us, visit the AWS IoT Greengrass Forum.

Configure the AWS IoT Greengrass Core

An AWS IoT Greengrass core is an AWS IoT thing (device). Like other AWS IoT devices, a core exists in the

registry, has a device shadow, and uses a device certificate to authenticate with AWS IoT. The core device

runs the AWS IoT Greengrass core software, which enables it to manage local processes for Greengrass

groups, such as communication, shadow sync, and token exchange.

The AWS IoT Greengrass core software provides the following functionality:

• Deployment and local execution of connectors and Lambda functions.

• Secure, encrypted storage of local secrets and controlled access by connectors and Lambda functions.

• MQTT messaging over the local network between devices, connectors, and Lambda functions using

managed subscriptions.

• MQTT messaging between AWS IoT and devices, connectors, and Lambda functions using managed

subscriptions.

• Secure connections between devices and the cloud using device authentication and authorization.

• Local shadow synchronization of devices. Shadows can be configured to sync with the cloud.

• Controlled access to local device and volume resources.

• Deployment of cloud-trained machine learning models for running local inference.

20

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

• Automatic IP address detection that enables devices to discover the Greengrass core device.

• Central deployment of new or updated group configuration. After the configuration data is

downloaded, the core device is restarted automatically.

• Secure, over-the-air software updates of user-defined Lambda functions.

AWS IoT Greengrass Core Configuration File

The configuration file for the AWS IoT Greengrass core software is the config.json file, which is

located in the /greengrass-root/config directory.

Note

greengrass-root represents the path where the AWS IoT Greengrass core software is

installed on your device. If you installed the software by following the Getting Started (p. 44)

tutorial, then this is the /greengrass directory.

If you use the Easy group creation option from the AWS IoT Greengrass console, then the

config.json file is deployed to the core device in a working state.

You can review the contents of this file by running the following command:

cat /greengrass-root/config/config.json

The following is an example config.json file.

GGC v1.7.0

This is the config.json file that's generated when the Greengrass group and core are created with

the Easy group creation option in the AWS IoT Greengrass console.

{

"coreThing" : {

"caPath" : "root.ca.pem",

"certPath" : "hash.cert.pem",

"keyPath" : "hash.private.key",

"thingArn" : "arn:aws:iot:region:account-id:thing/core-thing-name",

"iotHost" : "host-prefix-ats.iot.region.amazonaws.com",

"ggHost" : "greengrass-ats.iot.region.amazonaws.com",

"keepAlive" : 600

},

"runtime" : {

"cgroup" : {

"useSystemd" : "yes"

}

},

"managedRespawn" : false,

"crypto" : {

"principals" : {

"SecretsManager" : {

"privateKeyPath" : "file:///greengrass/certs/hash.private.key"

},

"IoTCertificate" : {

"privateKeyPath" : "file:///greengrass/certs/hash.private.key",

"certificatePath" : "file:///greengrass/certs/hash.cert.pem"

}

},

"caPath" : "file:///greengrass/certs/root.ca.pem"

}

}

The config.json file supports the following properties:

21

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

coreThing

Field Description Notes

caPath The path to the AWS IoT

root CA relative to the

/greengrass-root/certs

directory.

For backward compatibility

with versions prior to 1.7.0.

This property is ignored when

the crypto is present.

Note

Make sure that your

endpoints correspond

to your certificate

type (p. 32).

certPath The path to the core device

certificate relative to the

/greengrass-root/certs

directory.

For backward compatibility

with versions prior to 1.7.0.

This property is ignored when

the crypto is present.

keyPath The path to the core private

key relative to /greengrass-

root/certs directory.

For backward compatibility

with versions prior to 1.7.0.

This property is ignored when

the crypto is present.

thingArn The Amazon Resource Name

(ARN) of the AWS IoT thing

that represents the AWS IoT

Greengrass core device.

Find this for your core in the

AWS IoT Greengrass console

under Cores, or by running

the aws greengrass list-

core-definitions CLI

command.

iotHost Your AWS IoT endpoint. Find this in the AWS IoT Core

console under Settings, or

by running the aws iot

describe-endpoint --

endpoint-type iot:Data-

ATS CLI command.

This assumes that you're using

an Amazon Trust Services

(ATS) endpoint. For more

information, see the Server

Authentication in AWS IoT Core

documentation.

Note

Make sure that your

endpoints correspond

to your certificate

type (p. 32).

ggHost Your AWS IoT Greengrass

endpoint.

This is your iotHost

endpoint with the host prefix

replaced by greengrass (for

example, greengrass-

ats.iot.region.amazonaws.com).

Use the same region as

iotHost.

22

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

Field Description Notes

Note

Make sure that your

endpoints correspond

to your certificate

type (p. 32).

iotMqttPort Optional. The port number to

use for MQTT communication

with AWS IoT.

Valid values are 8883 or 443.

The default value is 8883. For

more information, Connect on

Port 443 or Through a Network

Proxy (p. 32).

keepAlive Optional. The MQTT

KeepAlive period, in seconds.

The default value is 600.

networkProxy Optional. An object that

defines a proxy server to

connect to.

This can be an HTTP or

HTTPS proxy. For more

information, Connect on Port

443 or Through a Network

Proxy (p. 32).

runtime

Field Description Notes

cgroup

useSystemd Indicates whether your device

uses systemd.

Valid values are

yes or no. Run the

check_ggc_dependencies

script in Module 1 (p. 45)

to see if your device uses

systemd.

crypto

The crypto object is added in v1.7.0. It introduces properties that support private key storage on a

hardware security module (HSM) through PKCS#11 and local secret storage. For more information,

see the section called “Hardware Security” (p. 376) and Deploy Secrets to the Core (p. 243).

Configurations for private key storage on HSMs or in the file system are supported.

Field Description Notes

caPath The absolute path to the AWS

IoT root CA.

Must be a file URI of the form:

file:///absolute/path/

to/file.

Note

Make sure that your

endpoints correspond

to your certificate

type (p. 32).

PKCS11

23

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

Field Description Notes

OpenSSLEngine Optional. The absolute path to

the OpenSSL engine .so file

to enable PKCS#11 support on

OpenSSL. This is used by the

Greengrass OTA update agent.

Must be a path to a file on the

file system.

P11Provider The absolute path to the

PKCS#11 implementation's

libdl-loadable library.

Must be a path to a file on the

file system.

slotLabel The slot label that's used to

identify the hardware module.

Must conform to PKCS#11

label specifications.

slotUserPin The user pin that's used to

authenticate the Greengrass

core to the module.

Must have sufficient

permissions to perform C_Sign

with the configured private

keys.

principals

IoTCertificate The certificate and private key that the core uses to make

requests to AWS IoT.

IoTCertificate

.privateKeyPath

The path to the core private

key.

For file system storage, must

be a file URI of the form:

file:///absolute/path/

to/file.

For HSM storage, must be an

RFC 7512 PKCS#11 path that

specifies the object label.

IoTCertificate

.certificatePath

The absolute path to the core

device certificate.

Must be a file URI of the form:

file:///absolute/path/

to/file.

MQTTServerCertificate Optional. The private key that the core uses in combination with

the certificate to act as an MQTT server or gateway.

24

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

Field Description Notes

MQTTServerCertificate

.privateKeyPath

The path to the local MQTT

server private key.

Use this value to specify your

own private key for the local

MQTT server.

For file system storage, must

be a file URI of the form:

file:///absolute/path/

to/file.

For HSM storage, must be an

RFC 7512 PKCS#11 path that

specifies the object label.

If this property is omitted, AWS

IoT Greengrass rotates the key

based your rotation settings.

If specified, the customer is

responsible for rotating the

key.

SecretsManager The private key that secures the data key used for encryption.

For more information, see Deploy Secrets to the Core (p. 243).

SecretsManager

.privateKeyPath

The path to the local secrets

manager private key.

For file system storage, must

be a file URI of the form:

file:///absolute/path/

to/file.

For HSM storage, must be an

RFC 7512 PKCS#11 path that

specifies the object label. The

private key must be generated

using the PKCS#1 v1.5 padding

mechanism.

The following configuration properties are also supported:

Field Description Notes

mqttMaxConnectionRetryIntervalOptional. The maximum

interval (in seconds) between

MQTT connection retries if the

connection is dropped.

Specify this value as an

unsigned integer. The default is

60.

managedRespawn Optional. Indicates that the

OTA agent needs to run

custom code before an update.

Valid values are true or

false. For more information,

see OTA Updates of AWS

IoT Greengrass Core

Software (p. 129).

writeDirectory Optional. The write directory

where AWS IoT Greengrass

creates all read-write

resources.

For more information, see

Configure a Write Directory for

AWS IoT Greengrass (p. 35).

25

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

GGC v1.6.0

{

"coreThing": {

"caPath": "root-ca-pem",

"certPath": "cloud-pem-crt",

"keyPath": "cloud-pem-key",

"thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name",

"iotHost": "host-prefix.iot.region.amazonaws.com",

"ggHost": "greengrass.iot.region.amazonaws.com",

"keepAlive": 600,

"mqttMaxConnectionRetryInterval": 60

},

"runtime": {

"cgroup": {

"useSystemd": "yes|no"

}

},

"managedRespawn": true,

"writeDirectory": "/write-directory"

}

Note

If you use the Easy group creation option from the AWS IoT Greengrass console, then

the config.json file is deployed to the core device in a working state that specifies the

default configuration.

The config.json file supports the following properties:

Field Description Notes

caPath The path to the AWS IoT

root CA relative to the

/greengrass-root/certs

directory.

Save the file under

/greengrass-root/certs.

certPath The path to the AWS IoT

Greengrass core certificate

relative to the /greengrass-

root/certs directory.

Save the file under

/greengrass-root/certs.

keyPath The path to the AWS IoT

Greengrass core private key

relative to /greengrass-

root/certs directory.

Save the file under

/greengrass-root/certs.

thingArn The Amazon Resource Name

(ARN) of the AWS IoT thing

that represents the AWS IoT

Greengrass core device.

You can find this for your core

in the AWS IoT Greengrass

console under Cores, or by

running the aws greengrass

list-core-definitions CLI

command.

iotHost Your AWS IoT endpoint. Find this in the AWS IoT Core

console under Settings, or

by running the aws iot

describe-endpoint CLI

command.

26

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

Field Description Notes

ggHost Your AWS IoT Greengrass

endpoint.

This value uses the format

greengrass.iot.region.amazonaws.com.

Use the same region as

iotHost.

keepAlive The MQTT KeepAlive period,

in seconds.

This is an optional value. The

default is 600.

mqttMaxConnectionRetryIntervalThe maximum interval (in

seconds) between MQTT

connection retries if the

connection is dropped.

Specify this value as an

unsigned integer. This is an

optional value. The default is

60.

useSystemd Indicates whether your device

uses systemd.

Valid values are

yes or no. Run the

check_ggc_dependencies

script in Module 1 (p. 45)

to see if your device uses

systemd.

managedRespawn An optional over-the-air (OTA)

updates feature, this indicates

that the OTA agent needs to

run custom code before an

update.

Valid values are true or

false. For more information,

see OTA Updates of AWS

IoT Greengrass Core

Software (p. 129).

writeDirectory The write directory where AWS

IoT Greengrass creates all read-

write resources.

This is an optional value.

For more information, see

Configure a Write Directory for

AWS IoT Greengrass (p. 35).

GGC v1.5.0

{

"coreThing": {

"caPath": "root-ca-pem",

"certPath": "cloud-pem-crt",

"keyPath": "cloud-pem-key",

"thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name",

"iotHost": "host-prefix.iot.region.amazonaws.com",

"ggHost": "greengrass.iot.region.amazonaws.com",

"keepAlive": 600

},

"runtime": {

"cgroup": {

"useSystemd": "yes|no"

}

},

"managedRespawn": true

}

The config.json file exists in /greengrass-root/config and contains the following

parameters:

27

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

Field Description Notes

caPath The path to the AWS IoT

root CA relative to the

/greengrass-root/certs

folder.

Save the file under the

/greengrass-root/certs

folder.

certPath The path to the AWS IoT

Greengrass core certificate

relative to the /greengrass-

root/certs folder.

Save the file under the

/greengrass-root/certs

folder.

keyPath The path to the AWS IoT

Greengrass core private key

relative to /greengrass-

root/certs folder.

Save the file under the

/greengrass-root/certs

folder.

thingArn The Amazon Resource Name

(ARN) of the AWS IoT thing

that represents the AWS IoT

Greengrass core.

Find this for your core in

the AWS IoT Greengrass

console under Cores, or by

running the aws greengrass

list-core-definitions

command.

iotHost Your AWS IoT endpoint. Find this in the AWS IoT Core

console under Settings, or

by running the aws iot

describe-endpoint

command.

ggHost Your AWS IoT Greengrass

endpoint.

This value uses the format

greengrass.iot.region.amazonaws.com.

Use the same region as

iotHost.

keepAlive The MQTT KeepAlive period,

in seconds.

This is an optional value. The

default value is 600 seconds.

useSystemd Indicates whether your device

uses systemd.

Values are yes or no. Use the

dependency script in Module

1 (p. 45) to see if your

device uses systemd.

managedRespawn An optional over-the-air (OTA)

updates feature, this indicates

that the OTA agent needs to

run custom code before an

update.

For more information,

see OTA Updates of AWS

IoT Greengrass Core

Software (p. 129).

GGC v1.3.0

{

"coreThing": {

"caPath": "root-ca-pem",

"certPath": "cloud-pem-crt",

"keyPath": "cloud-pem-key",

"thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name",

"iotHost": "host-prefix.iot.region.amazonaws.com",

28

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

"ggHost": "greengrass.iot.region.amazonaws.com",

"keepAlive": 600

},

"runtime": {

"cgroup": {

"useSystemd": "yes|no"

}

},

"managedRespawn": true

}

The config.json file exists in /greengrass-root/config and contains the following

parameters:

Field Description Notes

caPath The path to the AWS IoT

root CA relative to the

/greengrass-root/certs

folder.

Save the file under the

/greengrass-root/certs

folder.

certPath The path to the AWS IoT

Greengrass core certificate

relative to the /greengrass-

root/certs folder.

Save the file under the

/greengrass-root/certs

folder.

keyPath The path to the AWS IoT

Greengrass core private key

relative to /greengrass-

root/certs folder.

Save the file under the

/greengrass-root/certs

folder.

thingArn The Amazon Resource Name

(ARN) of the AWS IoT thing

that represents the AWS IoT

Greengrass core.

You can find this value in the

AWS IoT Greengrass console

under the definition for your

AWS IoT thing.

iotHost Your AWS IoT endpoint. You can find this value in the

AWS IoT Core console under

Settings.

ggHost Your AWS IoT Greengrass

endpoint.

You can find this value in the

AWS IoT Core console under

Settings with greengrass.

prepended.

keepAlive The MQTT KeepAlive period,

in seconds.

This is an optional value. The

default value is 600 seconds.

useSystemd A binary flag, if your device

uses systemd.

Values are yes or no. Use the

dependency script in Module

1 (p. 45) to see if your

device uses systemd.

managedRespawn An optional over-the-air (OTA)

updates feature, this indicates

that the OTA agent needs to

run custom code before an

update.

For more information,

see OTA Updates of AWS

IoT Greengrass Core

Software (p. 129).

29

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

GGC v1.1.0

{

"coreThing": {

"caPath": "root-ca-pem",

"certPath": "cloud-pem-crt",

"keyPath": "cloud-pem-key",

"thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name",

"iotHost": "host-prefix.iot.region.amazonaws.com",

"ggHost": "greengrass.iot.region.amazonaws.com",

"keepAlive": 600

},

"runtime": {

"cgroup": {

"useSystemd": "yes|no"

}

}

}

The config.json file exists in /greengrass-root/config and contains the following

parameters:

Field Description Notes

caPath The path to the AWS IoT

root CA relative to the

/greengrass-root/certs

folder.

Save the file under the

/greengrass-root/certs

folder.

certPath The path to the AWS IoT

Greengrass core certificate

relative to the /greengrass-

root/certs folder.

Save the file under the

/greengrass-root/certs

folder.

keyPath The path to the AWS IoT

Greengrass core private key

relative to the /greengrass-

root/certs folder.

Save the file under the

/greengrass-root/certs

folder.

thingArn The Amazon Resource Name

(ARN) of the AWS IoT thing

that represents the AWS IoT

Greengrass core.

You can find this value in the

AWS IoT Greengrass console

under the definition for your

AWS IoT thing.

iotHost Your AWS IoT endpoint. You can find this value in the

AWS IoT Core console under

Settings.

ggHost Your AWS IoT Greengrass

endpoint.

You can find this value in the

AWS IoT Core console under

Settings with greengrass.

prepended.

keepAlive The MQTT KeepAlive period,

in seconds.

This is an optional value. The

default value is 600 seconds.

useSystemd A binary flag, if your device

uses systemd.

Values are yes or no. Use the

dependency script in Module

1 (p. 45) to see if your

device uses systemd.

30

AWS IoT Greengrass Developer Guide

AWS IoT Greengrass Core Configuration File

GGC v1.0.0

In AWS IoT Greengrass Core v1.0.0, config.json is deployed to greengrass-root/

configuration.

{

"coreThing": {

"caPath": "root-ca-pem",

"certPath": "cloud-pem-crt",

"keyPath": "cloud-pem-key",

"thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name",

"iotHost": "host-prefix.iot.region.amazonaws.com",

"ggHost": "greengrass.iot.region.amazonaws.com",

"keepAlive": 600

},

"runtime": {

"cgroup": {

"useSystemd": "yes|no"

}

}

}

The config.json file exists in /greengrass-root/configuration and contains the following

parameters:

Field Description Notes

caPath The path to the AWS IoT

root CA relative to the

/greengrass-root/

configuration/certs

folder.

Save the file under the

/greengrass-root/

configuration/certs

folder.

certPath The path to the AWS IoT

Greengrass core certificate

relative to the /greengrass-

root/configuration/

certs folder.

Save the file under the

/greengrass-root/

configuration/certs

folder.

keyPath The path to the AWS IoT

Greengrass core private key

relative to the /greengrass-

root/configuration/

certs folder.

Save the file under the

/greengrass-root/

configuration/certs

folder.

thingArn The Amazon Resource Name

(ARN) of the AWS IoT thing

that represents the AWS IoT

Greengrass core.

You can find this value in the

AWS IoT Greengrass console

under the definition for your

AWS IoT hing.

iotHost Your AWS IoT endpoint. You can find this value in the

AWS IoT Core console under

Settings.

ggHost Your AWS IoT Greengrass

endpoint.

You can find this value in the

AWS IoT Core console under

Settings with greengrass.

prepended.

31

AWS IoT Greengrass Developer Guide

Endpoints Must Match the Certificate Type

Field Description Notes

keepAlive The MQTT KeepAlive period,

in seconds.

This is an optional value. The

default value is 600 seconds.

useSystemd A binary flag if your device

uses systemd.

Values are yes or no. Use the

dependency script in Module

1 (p. 45) to see if your

device uses systemd.

Endpoints Must Match the Certificate Type

Your AWS IoT and AWS IoT Greengrass endpoints must correspond to the certificate type of your

root CA. For example, if you're using an Amazon Trust Services (ATS) certificate (preferred), the

coreThing.iotHost and coreThing.ggHost properties must include the ats segment (for example,

abcde1234uwxyz-ats.iot.us-west-2.amazonaws.com).

If you're using a legacy endpoint, either create an ATS endpoint and download an appropriate certificate

(preferred) or make sure that your endpoints correspond to your certificate. For more information, see

the Server Authentication in AWS IoT Core documentation.

You can find your AWS IoT endpoint in the AWS IoT Core console under Settings, or by running the aws

iot describe-endpoint CLI command with the appropriate --endpoint-type parameter. For

example:

• To return an ATS signed data endpoint, run aws iot describe-endpoint --endpoint-type

iot:Data-ATS.

• To return a VeriSign signed data endpoint (legacy), run aws iot describe-endpoint --

endpoint-type iot:Data.

Your AWS IoT Greengrass endpoint is your iotHost endpoint with the host prefix replaced by greengrass

(for example, greengrass-ats.iot.region.amazonaws.com). This uses the same region as

iotHost.

If your endpoints and certificate do not match, authentication attempts between AWS IoT and AWS IoT

Greengrass fail.

Connect on Port 443 or Through a Network Proxy

This feature is available for AWS IoT Greengrass Core v1.7.0 only.

AWS IoT Greengrass communicates with AWS IoT using the MQTT messaging protocol with TLS client

authentication. By convention, MQTT over TLS uses port 8883. However, as a security measure, restrictive

environments might limit inbound and outbound traffic to a small range of TCP ports. For example, a

corporate firewall might open port 443 for HTTPS traffic, but close other ports that are used for less

common protocols, such as port 8883 for MQTT traffic. Other restrictive environments might require all

traffic to go through an HTTP proxy before connecting to the internet.

To enable communication in these scenarios, AWS IoT Greengrass allows the following configurations:

•MQTT with TLS client authentication on port 443. If your network allows connections to port 443,

you can configure the core to use port 443 for MQTT traffic instead of the default port 8883. This can

be a direct connection to port 443 or a connection through a network proxy server.

32

AWS IoT Greengrass Developer Guide

Connect on Port 443 or Through a Network Proxy

AWS IoT Greengrass uses the Application Layer Protocol Network (ALPN) TLS extension to enable this

connection. As with the default configuration, MQTT over TLS on port 443 uses certificate-based client

authentication.

•Connection through a network proxy. You can configure a network proxy server to act as an

intermediary for connecting to the AWS IoT Greengrass core. Only basic authentication and HTTP and

HTTPS proxies are supported.

The proxy configuration is passed to user-defined Lambda functions through the http_proxy,

https_proxy, and no_proxy environment variables. If a function specifies these variables, AWS IoT

Greengrass doesn't override them.

To Configure MQTT on Port 443

This procedure allows the core to use port 443 for MQTT messaging. When using this configuration, AWS

IoT Greengrass specifies the x-amzn-mqtt-ca header in the TLS handshake, which is expected by AWS

IoT. For more information, see Protocols in the AWS IoT Developer Guide.

1. Run the following command to stop the AWS IoT Greengrass daemon:

cd /greengrass-root/ggc/core/

sudo ./greengrassd stop

2. Open greengrass-root/config/config.json for editing as the su user.

3. In the coreThing object, add the iotMqttPort property and set the value to 443, as shown in the

following example.

{

"coreThing" : {

"caPath" : "root.ca.pem",

"certPath" : "12345abcde.cert.pem",

"keyPath" : "12345abcde.private.key",

"thingArn" : "arn:aws:iot:us-west-2:123456789012:thing/core-thing-name",

"iotHost" : "abcd123456wxyz-ats.iot.us-west-2.amazonaws.com",

"iotMqttPort" : 443,

"ggHost" : "greengrass-ats.iot.us-west-2.amazonaws.com",

"keepAlive" : 600

},

...

}

4. Start the daemon.

cd /greengrass-root/ggc/core/

sudo ./greengrassd start



To Configure a Network Proxy

This procedure allows AWS IoT Greengrass to connect to the internet through an HTTP or HTTPS

network proxy.

1. Run the following command to stop the AWS IoT Greengrass daemon:

cd /greengrass-root/ggc/core/

sudo ./greengrassd stop

33

AWS IoT Greengrass Developer Guide

Connect on Port 443 or Through a Network Proxy

2. Open greengrass-root/config/config.json for editing as the su user.

3. In the coreThing object, add the networkProxy object, as shown in the following example.

{

"coreThing" : {

"caPath" : "root.ca.pem",

"certPath" : "12345abcde.cert.pem",

"keyPath" : "12345abcde.private.key",

"thingArn" : "arn:aws:iot:us-west-2:123456789012:thing/core-thing-name",

"iotHost" : "abcd123456wxyz-ats.iot.us-west-2.amazonaws.com",

"ggHost" : "greengrass-ats.iot.us-west-2.amazonaws.com",

"keepAlive" : 600,

"networkProxy": {

"noProxyAddresses" : "http://128.12.34.56,www.mywebsite.com",

"proxy" : {

"url" : "https://my-proxy-server:1100",

"username" : "Mary_Major",

"password" : "pass@word1357"

}

}

},

...

}

4. Start the daemon.

cd /greengrass-root/ggc/core/

sudo ./greengrassd start

Use the networkProxy object to specify information about the network proxy. This object has the

following properties.

networkProxy object

Field Description

noProxyAddresses Optional. A comma-separated

list of IP addresses or host

names that are exempt from the

proxy.

proxy The proxy to connect to. A proxy

has the following properties.

•url. The URL of the

proxy server, in the

format scheme://

userinfo@host:port.

•scheme. The scheme. Must

be http or https.

•userinfo. Optional. The

user name and password

information. If specified, the

username and password

fields are ignored.

•host. The host name or IP

address of the proxy server.

34

AWS IoT Greengrass Developer Guide

Write Directory

Field Description

•port. Optional. The port

number. If not specified, the

following default values are

used:

•http: 80

•https: 443

•username. Optional. The user

name to use to authenticate

to the proxy server.

•password. Optional.

The password to use to

authenticate to the proxy

server.

Configure a Write Directory for AWS IoT Greengrass

This feature is available for AWS IoT Greengrass Core v1.6.0 and later.

By default, the AWS IoT Greengrass core software is deployed under a single root directory where AWS

IoT Greengrass performs all read and write operations. However, you can configure AWS IoT Greengrass

to use a separate directory for all write operations, including creating directories and files. In this case,

AWS IoT Greengrass uses two top-level directories:

• The greengrass-root directory, which you can leave as read-write or optionally make read-only.

This contains the AWS IoT Greengrass core software and other critical components that should remain

immutable during runtime, such as certificates and config.json.

• The specified write directory. This contains writable content, such as logs, state information, and

deployed user-defined Lambda functions.

This configuration results in the following directory structure.

Greengrass root directory

greengrass-root/

|-- certs/

| |-- root.ca.pem

| |-- hash.cert.pem

| |-- hash.private.key

| |-- hash.public.key

|-- config/

| |-- config.json

|-- ggc/

| |-- packages/

| |-- package-version/

| |-- bin/

| |-- daemon

| |-- greengrassd

| |-- lambda/

| |-- LICENSE/

| |-- release_notes_package-version.html

| |-- runtime/

| |-- java8/

| |-- nodejs6.10/

| |-- python2.7/

35

AWS IoT Greengrass Developer Guide

Write Directory

| |-- core/

Write Directory

write-directory/

|-- packages/

| |-- package-version/

| |-- ggc_root/

| |-- rootfs_nosys/

| |-- rootfs_sys/

| |-- var/

|-- deployment/

| |-- group/

| |-- group.json

| |-- lambda/

| |-- mlmodel/

|-- var/

| |-- log/

| |-- state/



To Configure a Write Directory

1. Run the following command to stop the AWS IoT Greengrass daemon:

cd /greengrass-root/ggc/core/

sudo ./greengrassd stop

2. Open greengrass-root/config/config.json for editing as the su user.

3. Add writeDirectory as a parameter and specify the path to the target directory, as shown in the

following example.

{

"coreThing": {

"caPath": "root-CA.pem",

"certPath": "hash.pem.crt",

...

},

...

"writeDirectory" : "/write-directory"

}

Note

You can update the writeDirectory setting as often as you want. After the setting is

updated, AWS IoT Greengrass uses the newly specified write directory at the next start, but

doesn't migrate content from the previous write directory.

4. Now that your write directory is configured, you can optionally make the greengrass-

root directory read-only. For instructions, see To Make the Greengrass Root Directory Read-

Only (p. 37).

Otherwise, start the AWS IoT Greengrass daemon:

cd /greengrass-root/ggc/core/

sudo ./greengrassd start



36

AWS IoT Greengrass Developer Guide

MQTT Message Queue

To Make the Greengrass Root Directory Read-Only

1. Grant required access to the AWS IoT Greengrass:

Note

This step is required only if you want to make the Greengrass root directory read-only. The

write directory must be configured before you begin this procedure.

a. Give read and write permissions to the config.json owner.

sudo chmod 0600 /greengrass-root/config/config.json

b. Make ggc_user the owner of the certs and system Lambda directories.

sudo chown -R ggc_user:ggc_group /greengrass-root/certs/

sudo chown -R ggc_user:ggc_group /greengrass-root/ggc/packages/1.7.0/lambda/

2. Make the greengrass-root directory read-only by using your preferred mechanism.

Note

One way to make the greengrass-root directory read-only is to mount the directory

as read-only. However, to apply over-the-air (OTA) updates to core software in a

mounted directory, the directory must first be unmounted, and then remounted after the

update. You can add these umount and mount operations to the ota_pre_update and

ota_post_update scripts. For more information about OTA updates, see the section called

“Greengrass OTA Agent” (p. 130) and the section called “AWS IoT Greengrass Core Update

with Managed Respawn” (p. 133).

3. Start the daemon.

cd /greengrass-root/ggc/core/

sudo ./greengrassd start

If the permissions from step 1 aren't set correctly, then the daemon won't start.

MQTT Message Queue

MQTT messages that are destined for cloud targets are queued to await processing. Queued messages

are processed in first in first out (FIFO) order. After a message is processed and published to the cloud,

the message is removed from the queue. AWS IoT Greengrass manages the queue by using a system-

defined GGCloudSpooler Lambda function.

Configure the MQTT Message Queue

This feature is available for AWS IoT Greengrass Core v1.6.0 and later.

You can configure AWS IoT Greengrass to store unprocessed messages in memory or in a local storage

cache. Unlike in-memory storage, the local storage cache has the ability to persist across core restarts

(for example, after a group deployment or a device reboot), so AWS IoT Greengrass can continue to

process the messages. You can also configure the storage size.

Note

Versions 1.5.0 and earlier use in-memory storage with a queue size of 2.5 MB. You cannot

configure storage settings for earlier versions.

The following environment variables for the GGCloudSpooler Lambda function are used to define

storage settings.

•GG_CONFIG_STORAGE_TYPE. The location of the message queue. The following are valid values:

37

AWS IoT Greengrass Developer Guide

MQTT Message Queue

•FileSystem. Store unprocessed messages in the local storage cache. When the core restarts,

queued messages are retained for processing. Messages are removed after they are processed.

•Memory (default). Store unprocessed messages in memory. When the core restarts, queued

messages are lost.

This option is optimized for devices with restricted hardware capabilities. When using this

configuration, we recommend that you deploy groups or restart the device when the service

disruption is the lowest.

•GG_CONFIG_MAX_SIZE_BYTES. The storage size, in bytes. This value can be any non-negative integer

greater than or equal to 262144 (256 KB); a smaller size prevents the AWS IoT Greengrass core

software from starting. The default size is 2.5 MB. When the size limit is reached, the oldest queued

messages are replaced by new messages.

To Cache Messages in Local Storage

To configure AWS IoT Greengrass to cache messages to the file system so they persist across core

restarts, you create a function definition version where the GGCloudSpooler function specifies the

FileSystem storage type. You must use the AWS IoT Greengrass API to configure the local storage

cache. You can't do this in the console.

The following procedure uses the create-function-definition-version CLI command to

configure the spooler to save queued messages to the file system. It also configures a 2.6 MB queue size.

Note

This procedure assumes that you're updating the configuration of the latest group version of an

existing group.

1. Get the IDs of the target Greengrass group and group version.

aws greengrass list-groups

Note

The list-groups command only returns 50 groups at a time. If you have more than 50

groups, specify the max-results option with the desired number of results (such as 100) to

find your group:

aws greengrass list-groups --max-results 100

2. Copy the Id and LatestVersion properties of your target group from the output.

3. Get the latest group version.

• Replace group-id with the Id that you copied.

• Replace latest-group-version-id with the LatestVersion that you copied.

aws greengrass get-group-version \

--group-id group-id \

--group-version-id latest-group-version-id

4. From the Definition object in the output, copy the CoreDefinitionVersionArn and the ARNs

of all other group components except FunctionDefinitionVersionArn. You use these values

when you create a new group version.

5. From the FunctionDefinitionVersionArn in the output, copy the ID of the function definition.

The ID is the GUID that follows the functions segment in the ARN.

38

AWS IoT Greengrass Developer Guide

MQTT Message Queue

Note

You can optionally create a function definition by running the create-function-

definition command, and then copy the ID from the output.

6. Add a function definition version to the function definition.

• Replace function-definition-id with the Id that you copied for the function definition.

• Replace arbitrary-function-id with a name for the function, such as spooler-function.

• Add any Lambda functions that you want to include in this version to the functions array. You

can use the get-function-definition-version command to get the Greengrass Lambda

functions from an existing function definition version.

Warning

Make sure that you specify a value for GG_CONFIG_MAX_SIZE_BYTES that's greater than

or equal to 262144. A smaller size prevents the AWS IoT Greengrass core software from

starting.

aws greengrass create-function-definition-version \

--function-definition-id function-definition-id \

--functions '[{"FunctionArn":

"arn:aws:lambda:::function:GGCloudSpooler:1","FunctionConfiguration": {"Environment":

{"Variables":

{"GG_CONFIG_MAX_SIZE_BYTES":"2621440","GG_CONFIG_STORAGE_TYPE":"FileSystem"}},"Executable":

"spooler","MemorySize": 32768,"Pinned": true,"Timeout": 3},"Id": "arbitrary-function-

id"}]'

7. Copy the Arn of the function definition version from the output.

8. Create a group version that contains the system-defined Lambda function.

• Replace group-id with the Id for the group.

• Replace core-definition-version-arn with the CoreDefinitionVersionArn that you

copied from the latest group version.

• Replace function-definition-version-arn with the Arn that you copied for the new

function definition version.

• Replace the ARNs for other group components (for example,

SubscriptionDefinitionVersionArn or DeviceDefinitionVersionArn) that you copied

from the latest group version.

• Remove any unused parameters. For example, remove the --resource-definition-version-

arn if your group version doesn't contain any resources.

aws greengrass create-group-version \

--group-id group-id \

--core-definition-version-arn core-definition-version-arn \

--function-definition-version-arn function-definition-version-arn \

--device-definition-version-arn device-definition-version-arn \

--logger-definition-version-arn logger-definition-version-arn \

--resource-definition-version-arn resource-definition-version-arn \

--subscription-definition-version-arn subscription-definition-version-arn

9. Copy the Version from the output. This is the ID of the new group version.

10. Deploy the group.

• Replace group-id with the Id that you copied for the group.

• Replace group-version-id with the Version that you copied for the new group version.

39

AWS IoT Greengrass Developer Guide

Activate Automatic IP Detection

aws greengrass create-deployment \

--group-id group-id \

--group-version-id group-version-id \

--deployment-type NewDeployment

To update the storage settings, you use the AWS IoT Greengrass API to create a new function definition

version that contains the GGCloudSpooler function with the updated configuration. Then add the

function definition version to a new group version (along with your other group components) and deploy

the group version. If you want to restore the default configuration, you can create a function definition

version that doesn't include the GGCloudSpooler function.

This system-defined Lambda function isn't visible in the console. However, after the function is added to

the latest group version, it's included in deployments that you make from the console (unless you use the

API to replace or remove it).

Activate Automatic IP Detection

You can configure AWS IoT Greengrass to enable automatic discovery of your AWS IoT Greengrass core

using the IPDetector system lambda function. This feature can also be enabled by choosing Automatic

detection when deploying your group from the console for the first time, or from the group settings

page in the console at any time.

The following procedure uses the create-function-definition-version CLI command to

configure automatic discovery of the Greengrass core.

Note

This procedure assumes that you're updating the configuration of the latest group version of an

existing group.

1. Get the IDs of the target Greengrass group and group version.

aws greengrass list-groups

Note

The list-groups command only returns 50 groups at a time. If you have more than 50

groups, specify the max-results option with the desired number of results (such as 100) to

find your group:

aws greengrass list-groups --max-results 100

2. Copy the Id and LatestVersion properties of your target group from the output.

3. Get the latest group version.

• Replace group-id with the Id that you copied.

• Replace latest-group-version-id with the LatestVersion that you copied.

aws greengrass get-group-version \

--group-id group-id \

--group-version-id latest-group-version-id

4. From the Definition object in the output, copy the CoreDefinitionVersionArn and the ARNs

of all other group components except FunctionDefinitionVersionArn. You use these values

when you create a new group version.

40

AWS IoT Greengrass Developer Guide

Activate Automatic IP Detection

5. From the FunctionDefinitionVersionArn in the output, copy the ID of the function definition

and the function definition version:

arn:aws:greengrass:region:account-id:/greengrass/groups/function-definition-id/

versions/function-definition-version-id

Note

You can optionally create a function definition by running the create-function-

definition command, and then copy the ID from the output.

6. Use the get-function-definition-version command to get the current definition state.

Use the function-definition-id you copied for the function definiton. For example,

4d941bc7-92a1-4f45-8d64-EXAMPLEf76c3.

aws greengrass get-function-definition-version

--function-definition-id function-definition-id

--function-definition-version-id function-definition-version-id

Make a note of the listed function configurations. You will need to include these when creating a

new function definition version in order to prevent loss of your current definition settings.

7. Add a function definition version to the function definition.

• Replace function-definition-id with the Id that you copied for the function definition. For

example, 4d941bc7-92a1-4f45-8d64-EXAMPLEf76c3.

• Replace arbitrary-function-id with a name for the function, such as auto-detection-

function.

• Add all Lambda functions that you want to include in this version to the functions array, such as

any listed in the previous step.

aws greengrass create-function-definition-version \

--function-definition-id function-definition-id \

--functions

'[{"FunctionArn":"arn:aws:lambda:::function:GGIPDetector:1","Id":"arbitrary-function-

id","FunctionConfiguration":{"Pinned":true,"MemorySize":32768,"Timeout":3}}]'\

--region us-west-2

8. Copy the Arn of the function definition version from the output.

9. Create a group version that contains the system-defined Lambda function.

• Replace group-id with the Id for the group.

• Replace core-definition-version-arn with the CoreDefinitionVersionArn that you

copied from the latest group version.

• Replace function-definition-version-arn with the Arn that you copied for the new

function definition version.

• Replace the ARNs for other group components (for example,

SubscriptionDefinitionVersionArn or DeviceDefinitionVersionArn) that you copied

from the latest group version.

• Remove any unused parameters. For example, remove the --resource-definition-version-

arn if your group version doesn't contain any resources.

aws greengrass create-group-version \

41

AWS IoT Greengrass Developer Guide

Start Greengrass on System Boot

--group-id group-id \

--core-definition-version-arn core-definition-version-arn \

--function-definition-version-arn function-definition-version-arn \

--device-definition-version-arn device-definition-version-arn \

--logger-definition-version-arn logger-definition-version-arn \

--resource-definition-version-arn resource-definition-version-arn \

--subscription-definition-version-arn subscription-definition-version-arn

10. Copy the Version from the output. This is the ID of the new group version.

11. Deploy the group.

• Replace group-id with the Id that you copied for the group.

• Replace group-version-id with the Version that you copied for the new group version.

aws greengrass create-deployment \

--group-id group-id \

--group-version-id group-version-id \

--deployment-type NewDeployment

If you want to manually input the IP address of your AWS IoT Greengrass core, you can complete this

tutorial with a different function definition that does not include the IPDetector function. This will

prevent the detection function from locating and automatically inputting your AWS IoT Greengrass core

IP address.

This system-defined Lambda function isn't visible in the Lambda console. After the function is added to

the latest group version, it's included in deployments that you make from the console (unless you use the

API to replace or remove it).

Configure the Init System to Start the Greengrass

Daemon

It's a good practice to set up your init system to start the Greengrass daemon during boot, especially

when managing large fleets of devices.

There are different types of init system, such as initd, systemd, and SystemV, and they use similar

configuration parameters. The following example is a service file for systemd. The Type parameter is

set to forking because greengrassd (which is used to start Greengrass) forks the Greengrass daemon

process, and the Restart parameter is set to on-failure to direct systemd to restart Greengrass if

Greengrass enters a failed state.

Note

To see if your device uses systemd, run the check_ggc_dependencies script as described

in Module 1 (p. 45). Then to use systemd, make sure that the useSystemd parameter in

config.json (p. 21) is set to yes.

[Unit]

Description=Greengrass Daemon

[Service]

Type=forking

PIDFile=/var/run/greengrassd.pid

Restart=on-failure

ExecStart=/greengrass/ggc/core/greengrassd start

ExecReload=/greengrass/ggc/core/greengrassd restart

ExecStop=/greengrass/ggc/core/greengrassd stop

[Install]

42

AWS IoT Greengrass Developer Guide

See Also

WantedBy=multi-user.target

For information about how to create and enable a service file for systemd on a Raspberry Pi, see

SYSTEMD in the Raspberry Pi documentation.

See Also

•the section called “Hardware Security” (p. 376)

43

AWS IoT Greengrass Developer Guide

Requirements

Getting Started with AWS IoT

Greengrass

This tutorial includes six modules, each designed to show you AWS IoT Greengrass basics and help you

get started in as few steps as possible. This tutorial covers:

• The AWS IoT Greengrass programming model.

• Fundamental concepts, such as AWS IoT Greengrass cores, groups, and subscriptions.

• The deployment process for running AWS Lambda functions at the edge.

Requirements

To complete this tutorial, you need the following:

• A Mac, Windows PC, or UNIX-like system.

• An Amazon Web Services (AWS) account. If you don’t have one, see the section called “Create an AWS

Account” (p. 45).

• The use of an AWS Region that supports AWS IoT Greengrass. For the list of supported regions for

AWS IoT Greengrass, see AWS Regions and Endpoints in the AWS General Reference.

Important

Make a note of your AWS Region to ensure that it is consistently used throughout this tutorial.

Inadvertently switching regions during the tutorial can create problems. The last exercise in

this tutorial assumes you are using the US East (N. Virgina) Region.

• A Raspberry Pi 3 Model B with a 8 GB microSD card, or an Amazon EC2 instance. Because AWS IoT

Greengrass is intended to be used with physical hardware, we recommend that you use a Raspberry Pi.

The architecture of your Pi must be armv7l or later.

Note

Run the following command to get the model of your Rasberry Pi:

cat /proc/cpuinfo

Near the bottom of the listing, make a note of the value of the Revision attribute and then

consult the Which Pi have I got? table. For example, if the value of Revision is a02082, the

table shows the Pi is a 3 Model B.

Run the following command to determine the architecture of your Raspberry Pi:

uname -m

The result must be greater than or equal to armv71.

• Basic familiarity with Python 2.7.

Although this tutorial focuses on running AWS IoT Greengrass on a Raspberry Pi or an Amazon

EC2 instance, other platforms are supported. For more information, see Supported Platforms and

Requirements (p. 14).

44

AWS IoT Greengrass Developer Guide

Create an AWS Account

Create an AWS Account

If you don't have an AWS account, follow these steps:

1. Open the AWS home page, and choose Create an AWS Account.

Note

If you've signed in to AWS recently, you might see Sign In to the Console instead.

2. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call and

entering a PIN using your phone keypad.

Important

Before you begin, make sure that your account has administrative privileges.

Module 1: Environment Setup for Greengrass

This module shows you how to get an out-of-the-box Raspberry Pi, Amazon EC2 instance, or other device

ready to be used by AWS IoT Greengrass.

Important

Use the Filter View drop-down list in the upper-right corner of this webpage to choose your

platform.

This module should take less than 30 minutes to complete.

Setting Up a Raspberry Pi

If you are setting up a Raspberry Pi for the first time, you must follow all of these steps. Otherwise, you

can skip to step 9. However, we recommend that you re-image your Raspberry Pi with the operating

system as recommended in step 2.

1. Download and install an SD card formatter such as SD Memory Card Formatter or PiBakery. Insert

the SD card into your computer. Start the program and choose the drive where you have inserted

your SD card. You can perform a quick format of the SD card.

2. Download the Raspbian Stretch operating system as a .zip file.

3. Using an SD card-writing tool (such as Etcher), follow the tool's instructions to flash the downloaded

zip file onto the SD card. Because the operating system image is large, this step might take some

time. Eject your SD card from your computer, and insert the microSD card into your Raspberry Pi.

4. For the first boot, we recommend that you connect the Raspberry Pi to a monitor (through HDMI),

a keyboard, and a mouse. Next, connect your Pi to a micro USB power source and the Raspbian

operating system should start up.

5. You might want to configure the Pi's keyboard layout before you continue. To do so, choose the

Raspberry icon in the upper-right, choose Preferences and then choose Mouse and Keyboard

Settings. Next, on the Keyboard tab, choose Keyboard Layout, and then choose an appropriate

keyboard variant.

6. Next, connect your Raspberry Pi to the internet through a Wi-Fi network or an Ethernet cable.

Note

Connect your Raspberry Pi to the same network that your computer is connected to, and be

sure that both your computer and Raspberry Pi have internet access before you continue. If

you're in a work environment or behind a firewall, you might need to connect your Pi and

your computer to the guest network to get both devices on the same network. However,

this approach might disconnect your computer from local network resources, such as your

45

AWS IoT Greengrass Developer Guide

Setting Up a Raspberry Pi

intranet. One solution is to connect the Pi to the guest Wi-Fi network and to connect your

computer to the guest Wi-Fi network and your local network through an Ethernet cable. In

this configuration, your computer should be able to connect to the Raspberry Pi through

the guest Wi-Fi network and your local network resources through the Ethernet cable.

7. You must set up SSH on your Pi to remotely connect to it. On your Raspberry Pi, open a terminal

window and run the following command:

sudo raspi-config

You should see the following:

Scroll down and choose Interfacing Options and then choose P2 SSH. When prompted, choose Yes.

(Use the Tab key followed by Enter). SSH should now be enabled. Choose OK. Use the Tab key to

choose Finish and then press Enter. Lastly, reboot your Pi by running the following command:

sudo reboot

8. On your Raspberry Pi, run the following command in the terminal:

hostname -I

This returns the IP address of your Raspberry Pi.

Note

For the following, if you receive an ECDSA key fingerprint message (Are you sure you

want to continue connecting (yes/no)?), enter yes. The default password for the

Raspberry Pi is raspberry.

If you are using macOS, open a terminal window and enter the following:

ssh pi@IP-address

IP-address is the IP address of your Raspberry Pi that you obtained by using the hostname -I

command.

If you are using Windows, you need to install and configure PuTTY. Expand Connection, choose

Data, and make sure that Prompt is selected:

46

AWS IoT Greengrass Developer Guide

Setting Up a Raspberry Pi

Next, choose Session, enter the IP address of the Raspberry Pi, and then choose Open using default

settings.

47

AWS IoT Greengrass Developer Guide

Setting Up a Raspberry Pi

If a PuTTY security alert is displayed, choose Yes.

The default Raspberry Pi login and password are pi and raspberry, respectively.

48

AWS IoT Greengrass Developer Guide

Setting Up a Raspberry Pi

Note

If your computer is connected to a remote network using VPN, you might have difficulty

connecting from the computer to the Raspberry Pi using SSH.

9. You are now ready to set up the Raspberry Pi for AWS IoT Greengrass. First, run the following

commands from a local Raspberry Pi terminal window or an SSH terminal window:

sudo adduser --system ggc_user

sudo addgroup --system ggc_group

10. If you are running Raspbian Jessie, run the following commands to update the Linux kernel version

of your Raspberry Pi.

sudo apt-get install rpi-update

sudo rpi-update b81a11258fc911170b40a0b09bbd63c84bc5ad59

Although several kernel versions might work with AWS IoT Greengrass, for the best security and

performance, we recommend that you use the kernel version indicated in step 2. To activate the new

firmware, reboot your Raspberry Pi:

sudo reboot

After about a minute, reconnect to the Raspberry Pi using SSH. Next, run the following command to

ensure you have the correct kernel version:

uname -a

You should receive output similar to the following. In this example, the Linux Raspberry Pi version

information is 4.9.30:

11. To improve security on the Pi device, enable hardlink and softlink protection on the operating

system at start up.

a. Navigate to the 98-rpi.conf file.

cd /etc/sysctl.d

ls

Note

If you don't see the 98-rpi.conf file, follow the instructions in the README.sysctl

file.

b. Use a text editor (such as Leafpad, GNU nano, or vi) to add the following two lines to the end

of the file. You might need to use the sudo command to edit as root (for example, sudo nano

98-rpi.conf).

fs.protected_hardlinks = 1

fs.protected_symlinks = 1

c. Reboot the Pi.

sudo reboot

49

AWS IoT Greengrass Developer Guide

Setting Up an Amazon EC2 Instance

After about a minute, connect to the Pi using SSH and then run the following command to

confirm the change:

sudo sysctl -a 2> /dev/null | grep fs.protected

You should see fs.protected_hardlinks = 1 and fs.protected_symlinks = 1.

12. Edit your command line boot file to enable and mount memory cgroups. This allows AWS IoT

Greengrass to set the memory limit for Lambda functions. Without this, the Greengrass daemon is

unable to run.

a. Navigate to your boot directory.

cd /boot/

b. Use a text editor to open cmdline.txt. Add the following line to the end of the file.

cgroup_enable=memory cgroup_memory=1

c. Now reboot the Pi.

sudo reboot

Your Raspberry Pi should now be ready for AWS IoT Greengrass.

13. To make sure that you have all required dependencies, download and run the Greengrass

dependency checker from the AWS IoT Greengrass Samples repository on GitHub. These commands

unzip and run the dependency checker script in the Downloads directory.

cd /home/pi/Downloads

wget https://github.com/aws-samples/aws-greengrass-samples/raw/master/greengrass-

dependency-checker-GGCv1.7.0.zip

unzip greengrass-dependency-checker-GGCv1.7.0.zip

cd greengrass-dependency-checker-GGCv1.7.0

sudo modprobe configs

sudo ./check_ggc_dependencies | more

Where more appears, press the Spacebar key to display another screen of text.

Important

This tutorial uses the AWS IoT Device SDK for Python. The check_ggc_dependencies

script might produce warnings about the missing optional Node v6.10 and Java 8

prerequisites. You can ignore these warnings.

For information about the modprobe command, run man modprobe in the terminal.

Your Raspberry Pi configuration is complete. Continue to the section called “Module 2: Installing the

Greengrass Core Software” (p. 55).

Setting Up an Amazon EC2 Instance

1. Sign in to the AWS Management Console and launch an Amazon EC2 instance using an Amazon

Linux AMI. For information about Amazon EC2 instances, see the Amazon EC2 Getting Started Guide.

2. After your Amazon EC2 instance is running, enable port 8883 to allow incoming MQTT

communications so that other devices can connect with the AWS IoT Greengrass core.

50

AWS IoT Greengrass Developer Guide

Setting Up an Amazon EC2 Instance

a. In the navigation pane of the Amazon EC2 console, choose Security Groups.

b. Select the security group for the instance that you just launched, and then choose the Inbound

tab.

51