AWS IoT Greengrass Developer Guide

User Manual:

Open the PDF directly: View PDF 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 Conguration File ........................................................................ 21
Endpoints Must Match the Certicate 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
Congure 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 Congurations 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
Congure Subscriptions .................................................................................................... 95
Install the AWS IoT Device SDK for Python .......................................................................... 96
Test Communications ...................................................................................................... 101
Module 5: Interacting with Device Shadows ............................................................................... 104
Congure 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
Congure IAM Roles ....................................................................................................... 115
iii
AWS IoT Greengrass Developer Guide
Create and Congure the Lambda Function ....................................................................... 116
Congure Subscriptions ................................................................................................... 121
Test Communications ...................................................................................................... 122
Module 7: Simulating Hardware Security Integration ................................................................... 124
Install SoftHSM .............................................................................................................. 125
Congure SoftHSM ......................................................................................................... 125
Import the Private Key .................................................................................................... 126
Congure the Greengrass Core ......................................................................................... 126
Test the Conguration .................................................................................................... 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 Congure 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 inputle 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 Conguration ............................................................................................................ 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 Congure 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 Congure Machine Learning Inference ........................................................................... 199
Prerequisites .................................................................................................................. 200
Congure 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
Conguring an NVIDIA Jetson TX2 .................................................................................... 220
How to Congure Optimized Machine Learning Inference ............................................................ 220
Prerequisites .................................................................................................................. 200
Congure 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
Conguring an Intel Atom ............................................................................................... 238
Conguring 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
Conguration 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 Classication ........................................................................................................ 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 Notications ......................................................................................................... 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 Denition and Version ........................................................................... 351
Create a Connector Denition and Version ......................................................................... 351
Create a Lambda Function Deployment Package ................................................................. 352
Create a Lambda Function ............................................................................................... 355
Create a Function Denition and Version ........................................................................... 356
Create a Subscription Denition 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
Conguring Greengrass Security ............................................................................................... 372
Minimal AWS IoT Policy for the AWS IoT Greengrass Core Device .......................................... 372
Device Connection Workow .................................................................................................... 374
Greengrass Messaging Workow .............................................................................................. 375
MQTT Core Server Certicate Rotation ...................................................................................... 375
AWS IoT Greengrass Cipher Suites ............................................................................................ 375
Hardware Security .................................................................................................................. 376
Requirements ................................................................................................................. 377
Hardware Security Conguration ...................................................................................... 377
Provisioning Practices .................................................................................................... 380
Supported Cipher Suites .................................................................................................. 382
Congure 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 Conguration ................................................................................................. 386
Congure Logging for AWS IoT Greengrass ................................................................................ 386
Congure Logging (Console) ............................................................................................ 387
Congure Logging (API) .................................................................................................. 387
Conguration 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 Congure an AWS Account .............................................................................. 394
Install the AWS Command Line Interface (CLI) .................................................................... 395
Congure the AWS IoT Greengrass Service Role ................................................................. 395
Verify AWS IoT Greengrass Dependencies on the Device Under Test ...................................... 396
Congure 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
Congure Your AWS Credentials ....................................................................................... 398
Conguring AWS Credentials with a Credentials File ............................................................ 399
Device Conguration ....................................................................................................... 400
Running the Test Suite .................................................................................................... 401
Results and Logs ............................................................................................................ 402
Testing Infrastructure .............................................................................................................. 404
Test Organization ................................................................................................................... 404
Troubleshooting ..................................................................................................................... 405
Troubleshooting Device Conguration ............................................................................... 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