Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Run Lambda functions on the Amazon IoT Greengrass core

Amazon IoT Greengrass provides a containerized Lambda runtime environment for user-defined code that you author in Amazon Lambda. Lambda functions that are deployed to an Amazon IoT Greengrass core run in the core's local Lambda runtime. Local Lambda functions can be triggered by local events, messages from the cloud, and other sources, which brings local compute functionality to client devices. For example, you can use Greengrass Lambda functions to filter device data before transmitting the data to the cloud.

To deploy a Lambda function to a core, you add the function to a Greengrass group (by referencing the existing Lambda function), configure group-specific settings for the function, and then deploy the group. If the function accesses Amazon services, you also must add any required permissions to the Greengrass group role.

You can configure parameters that determine how the Lambda functions run, including permissions, isolation, memory limits, and more. For more information, see Controlling execution of Greengrass Lambda functions by using group-specific configuration.

The following table lists supported Amazon Lambda runtimes and the versions of Amazon IoT Greengrass Core software that they can run on.

* You can run Lambda functions that use these runtimes on supported versions of Amazon IoT Greengrass, but you can't create them in Amazon Lambda. If the runtime on your device is different from the Amazon Lambda runtime specified for that function, you are able to choose your own runtime by using FunctionRuntimeOverride in FunctionDefintionVersion. For more information, see CreateFunctionDefinition. For more information about supported runtimes, see Runtime support policy in the Amazon Lambda Developer Guide.

SDKs for Greengrass Lambda functions

Amazon provides three SDKs that can be used by Greengrass Lambda functions running on an Amazon IoT Greengrass core. These SDKs are contained in different packages, so functions can use them simultaneously. To use an SDK in a Greengrass Lambda function, include it in the Lambda function deployment package that you upload to Amazon Lambda.

For more information about creating a deployment package, see Create and package a Lambda function in the Getting Started tutorial or Creating a deployment package in the Amazon Lambda Developer Guide.

Migrating cloud-based Lambda functions

The Amazon IoT Greengrass Core SDK follows the Amazon SDK programming model, which makes it easy to port Lambda functions that are developed for the cloud to Lambda functions that run on an Amazon IoT Greengrass core.

For example, the following Python Lambda function uses the Amazon SDK for Python (Boto3) to publish a message to the topic some/topic in the cloud:

import boto3

iot_client = boto3.client("iot-data")
response = iot_client.publish(
    topic="some/topic", qos=0, payload="Some payload".encode()
)

To port the function for an Amazon IoT Greengrass core, in the import statement and client initialization, change the boto3 module name to greengrasssdk, as shown in the following example:

import greengrasssdk

iot_client = greengrasssdk.client("iot-data")
iot_client.publish(topic="some/topic", qos=0, payload="Some payload".encode())

The similarity between programming models also makes it possible for you to develop your Lambda functions in the cloud and then migrate them to Amazon IoT Greengrass with minimal effort. Lambda executables don't run in the cloud, so you can't use the Amazon SDK to develop them in the cloud before deployment.

Reference Lambda functions by alias or version

Greengrass groups can reference a Lambda function by alias (recommended) or by version. Using an alias makes it easier to manage code updates because you don't have to change your subscription table or group definition when the function code is updated. Instead, you just point the alias to the new function version. Aliases resolve to version numbers during group deployment. When you use aliases, the resolved version is updated to the version that the alias is pointing to at the time of deployment.

Amazon IoT Greengrass doesn't support Lambda aliases for $LATEST versions. $LATEST versions aren't bound to immutable, published function versions and can be changed at any time, which is counter to the Amazon IoT Greengrass principle of version immutability.

A common practice for keeping your Greengrass Lambda functions updated with code changes is to use an alias named PRODUCTION in your Greengrass group and subscriptions. As you promote new versions of your Lambda function into production, point the alias to the latest stable version and then redeploy the group. You can also use this method to roll back to a previous version.

Communication flows for Greengrass Lambda functions

Greengrass Lambda functions support several methods of communicating with other members of the Amazon IoT Greengrass group, local services, and cloud services (including Amazon services).

Communication using MQTT messages

Lambda functions can send and receive MQTT messages using a publish-subscribe pattern that's controlled by subscriptions.

This communication flow allows Lambda functions to exchange messages with the following entities:

A subscription defines a message source, a message target, and a topic (or subject) that's used to route messages from the source to the target. Messages that are published to a Lambda function are passed to the function's registered handler. Subscriptions enable more security and provide predictable interactions. For more information, see Managed subscriptions in the MQTT messaging workflow.

Other communication flows

Retrieve the input MQTT topic (or subject)

Amazon IoT Greengrass uses subscriptions to control the exchange of MQTT messages between client devices, Lambda functions, and connectors in a group, and with Amazon IoT or the local shadow service. Subscriptions define a message source, message target, and an MQTT topic used to route messages. When the target is a Lambda function, the function's handler is invoked when the source publishes a message. For more information, see Communication using MQTT messages.

The following example shows how a Lambda function can get the input topic from the context that's passed to the handler. It does this by accessing the subject key from the context hierarchy (context.client_context.custom['subject']). The example also parses the input JSON message and then publishes the parsed topic and message.

import greengrasssdk
import logging

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

OUTPUT_TOPIC = 'test/topic_results'

def get_input_topic(context):
    try:
        topic = context.client_context.custom['subject']
    except Exception as e:
        logging.error('Topic could not be parsed. ' + repr(e))
    return topic
    
def get_input_message(event):
    try:
        message = event['test-key']
    except Exception as e:
        logging.error('Message could not be parsed. ' + repr(e))
    return message

def function_handler(event, context):
    try:
        input_topic = get_input_topic(context)
        input_message = get_input_message(event)
        response = 'Invoked on topic "%s" with message "%s"' % (input_topic, input_message)
        logging.info(response)
    except Exception as e:
        logging.error(e)

    client.publish(topic=OUTPUT_TOPIC, payload=response)

    return

To test the function, add it to your group using the default configuration settings. Then, add the following subscriptions and deploy the group. For instructions, see Module 3 (part 1): Lambda functions on Amazon IoT Greengrass.

After the deployment is completed, invoke the function.

Lifecycle configuration for Greengrass Lambda functions

The Greengrass Lambda function lifecycle determines when a function starts and how it creates and uses containers. The lifecycle also determines how variables and preprocessing logic that are outside of the function handler are retained.

Amazon IoT Greengrass supports the on-demand (default) or long-lived lifecycles:

For more information about container reuse, see Understanding Container Reuse in Amazon Lambda in the Amazon Compute Blog.

Lambda executables

This feature is available for Amazon IoT Greengrass Core v1.6 and later.

A Lambda executable is a type of Greengrass Lambda function that you can use to run binary code in the core environment. It lets you execute device-specific functionality natively and benefit from the smaller footprint of compiled code. Lambda executables can be invoked by events, invoke other functions, and access local resources.

Lambda executables support the binary encoding type only (not JSON), but otherwise you can manage them in your Greengrass group and deploy them like other Greengrass Lambda functions. However, the process of creating Lambda executables is different from creating Python, Java, and Node.js Lambda functions:

Lambda executables must implement certain calls and programming patterns in their function code. For example, the main method must:

The following snippet is the main method from the simple_handler.c code example on GitHub.

int main() {
    gg_error err = GGE_SUCCESS;

    err = gg_global_init(0);
    if(err) {
        gg_log(GG_LOG_ERROR, "gg_global_init failed %d", err);
        goto cleanup;
    }

    gg_runtime_start(handler, 0);

cleanup:
    return -1;
}

For more information about requirements, constraints, and other implementation details, see Amazon IoT Greengrass Core SDK for C.

Create a Lambda executable

After you compile your code along with the SDK, use the Amazon Lambda API to create a Lambda function and upload your compiled executable.

The following example uses the create-function CLI command to create a Lambda executable. The command specifies:

aws lambda create-function \
--region aws-region \
--function-name function-name \
--handler executable-name \
--role role-arn \
--zip-file fileb://file-name.zip \
--runtime arn:aws-cn:greengrass:::runtime/function/executable

Next, use the Amazon Lambda API to publish a version and create an alias.

Then, add the Lambda executable to a Greengrass group, configure it to accept binary input data in its group-specific settings, and deploy the group. You can do this in the Amazon IoT Greengrass console or by using the Amazon IoT Greengrass API.