AWS Greengrass
Developer Guide

What Is AWS Greengrass?

AWS Greengrass is software that extends AWS cloud capabilities to local devices, making it possible for them to collect and analyze data closer to the source of information, while also securely communicating with each other on local networks. More specifically, developers who use AWS Greengrass can author serverless code (AWS Lambda functions) in the cloud and conveniently deploy it to devices for local execution of applications.

The following diagram shows the basic architecture of AWS Greengrass.

AWS Greengrass makes it possible for customers to use Lambda functions to build IoT devices and application logic. Specifically, AWS Greengrass provides cloud-based management of applications that can be deployed for local execution. Locally deployed Lambda functions are triggered by local events, messages from the cloud, or other sources.

In AWS Greengrass, devices securely communicate on a local network and exchange messages with each other without having to connect to the cloud. AWS 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 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 within 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 Greengrass provides secure, over-the-air software updates of Lambda functions.

AWS Greengrass consists of:

  • Software distributions

    • AWS Greengrass core software

    • AWS Greengrass core SDK

  • Cloud service

    • AWS Greengrass API

  • Features

    • Lambda runtime

    • Thing shadows implementation

    • Message manager

    • Group management

    • Discovery service

Greengrass Core Software

The AWS Greengrass core software provides the following functionality:

  • Allows deployment and execution of local applications created using Lambda functions and managed through the deployment API.

  • Enables local messaging between devices over a secure network using a managed subscription scheme through the MQTT protocol.

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

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

The AWS Greengrass core software consists of:

  • A message manager that routes messages between devices, Lambda functions, and AWS IoT.

  • A Lambda runtime that runs user-defined Lambda functions.

  • An implementation of the Thing Shadows service that provides a local copy of thing shadows, which represent your devices. Thing shadows can be configured to sync with the cloud.

  • A deployment agent that is notified of new or updated AWS Greengrass group configuration. When new or updated configuration is detected, the deployment agent downloads the configuration data and restarts the AWS Greengrass core.

AWS Greengrass core instances are configured through AWS Greengrass APIs that create and update AWS Greengrass group definitions stored in the cloud.

AWS Greengrass Groups

An AWS Greengrass group definition is a collection of settings for AWS Greengrass core devices and the devices that communicate with them. The following diagram shows the objects that make up an AWS Greengrass group.

In the preceding diagram:

A: AWS Greengrass group definition

A collection of information about the AWS Greengrass group.

B: AWS Greengrass group settings

These include:

  • AWS Greengrass group role.

  • Log configuration.

  • Certification authority and local connection configuration.

  • AWS Greengrass core connectivity information.

C: AWS Greengrass core

The AWS IoT thing that represents the AWS Greengrass core.

D: Lambda function definition

A list of Lambda functions to be deployed to the AWS Greengrass core of the group.

E: Subscription definition

A collection of subscriptions to be deployed to the AWS Greengrass group that contains:

  • A message rule ID, a unique identifier for the message routing subscription.

  • A message source, an ARN that identifies the source of the message. Valid values are a thing ARN, Lambda function, or "cloud".

  • A subject, an MQTT topic or topic filter used to filter message data.

  • A target, an ARN that identifies the destination for messages published by the message source. Valid values are a thing ARN, Lambda function, or "cloud".

F: Device definition

A list containing an AWS Greengrass core and AWS IoT things that are members of the AWS Greengrass group and associated configuration data. This data specifies which devices are AWS Greengrass cores and which devices should sync thing shadow data with AWS IoT.

When deployed, the AWS Greengrass group definition, Lambda functions, and subscription table are copied to an AWS Greengrass core device.

Devices in AWS Greengrass

There are two types of devices:

  • AWS Greengrass cores.

  • AWS IoT devices connected to an AWS Greengrass core.

An AWS Greengrass core is an AWS IoT device that runs specialized AWS Greengrass software that communicates directly with the AWS IoT and AWS Greengrass cloud services. It is an AWS IoT device with its own certificate used for authenticating with AWS IoT. It has a device shadow and exists in the AWS IoT device registry. AWS Greengrass cores run a local Lambda runtime, a deployment agent, and an IP address tracker that sends IP address information to the AWS Greengrass cloud service to allow AWS IoT devices to automatically discover their group and core connection information.

Any AWS IoT device can connect to an AWS Greengrass core. An AWS Greengrass core runs software written with the AWS IoT Device SDK.

The following table shows how these device types are related.


The following SDKs are used when working with AWS Greengrass:


Using the AWS SDKs, you can build applications that work with any AWS service, including Amazon S3, Amazon DynamoDB, AWS IoT, AWS Greengrass, and more. In the context of AWS 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 you connect your device to AWS IoT or AWS Greengrass services. Devices must know to which AWS Greengrass group they belong and the IP address of the AWS Greengrass core to which they should connect.

Although you can use any of the AWS IoT Device SDKs to connect to an AWS Greengrass core, only the C++ Device SDK provides AWS Greengrass-specific functionality, such as access to the AWS Greengrass Discovery Service and AWS Greengrass core root CA downloads. For more information, see AWS IoT Device SDK.

AWS Greengrass Core SDK

The AWS Greengrass Core SDK enables Lambda functions to interact with the AWS Greengrass core on which they run in order to publish messages, interact with the local Thing Shadows service, or invoke other deployed Lambda functions. This SDK is used exclusively for writing Lambda functions running in the Lambda runtime on an AWS Greengrass core. Lambda functions running on an AWS Greengrass core can interact with AWS cloud services directly using the AWS SDK. The AWS Greengrass Core SDK and the AWS SDK are contained in different packages, so you can use both packages simultaneously. You can download the AWS Greengrass Core SDK from the Software section of the AWS IoT console.

The AWS 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 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 Greengrass core, replace the import boto3 statement with the import greengrasssdk, as shown in the following snippet:

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 Greengrass with minimal effort.


The AWS Greengrass Core SDK only supports sending MQTT messages with QoS = 0. The AWS SDK is natively part of the environment when executing a Lambda function in the AWS cloud. If you want to use boto3 in a Lambda function deployed on an AWS Greengrass core, make sure to include the AWS SDK in your package. In addition, if you choose to use both the AWS Greengrass Core SDK and the AWS SDK simultaneously in the same package, your Lambda functions must use the correct namespace. For more information about how to create your deployment package, see the AWS Lambda documentation.