End of support notice: On October 7th, 2026, AWS will discontinue support for AWS IoT Greengrass Version 1. After October 7th, 2026, you will no longer be able to access the AWS IoT Greengrass V1 resources. For more information, please visit [Migrate from AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html).
# Module 3 (part 1): Lambda functions on AWS IoT Greengrass
This module shows you how to create and deploy a Lambda function that sends MQTT messages from your AWS IoT Greengrass core device. The module describes Lambda function configurations, subscriptions used to allow MQTT messaging, and deployments to a core device.
[Module 3 (Part 2)](module3-II.md) covers the differences between on-demand and long-lived Lambda functions running on the AWS IoT Greengrass core.
Before you begin, make sure that you have completed [Module 1](module1.md) and [Module 2](module2.md) and have a running AWS IoT Greengrass core device.
**Tip**
Or, to use a script that sets up your core device for you, see [Quick start: Greengrass device setup](quick-start.md). The script can also create and deploy the Lambda function used in this module.
This module should take about 30 minutes to complete.
**Topics**
+ [Create and package a Lambda function](create-lambda.md)
+ [Configure the Lambda function for AWS IoT Greengrass](config-lambda.md)
+ [Deploy cloud configurations to a Greengrass core device](configs-core.md)
+ [Verify the Lambda function is running on the core device](lambda-check.md)
# Create and package a Lambda function
The example Python Lambda function in this module uses the [AWS IoT Greengrass Core SDK](lambda-functions.md#lambda-sdks-core) for Python to publish MQTT messages.
In this step, you:
+ Download the AWS IoT Greengrass Core SDK for Python to your computer (not the AWS IoT Greengrass core device).
+ Create a Lambda function deployment package that contains the function code and dependencies.
+ Use the Lambda console to create a Lambda function and upload the deployment package.
+ Publish a version of the Lambda function and create an alias that points to the version.
To complete this module, Python 3.7 must be installed on your core device.
1. From the [AWS IoT Greengrass Core SDK](what-is-gg.md#gg-core-sdk-download) downloads page, download the AWS IoT Greengrass Core SDK for Python to your computer.
1. Unzip the downloaded package to get the Lambda function code and the SDK.
The Lambda function in this module uses:
+ The `greengrassHelloWorld.py` file in `examples\HelloWorld`. This is your Lambda function code. Every five seconds, the function publishes one of two possible messages to the `hello/world` topic.
+ The `greengrasssdk` folder. This is the SDK.
1. Copy the `greengrasssdk` folder into the `HelloWorld` folder that contains `greengrassHelloWorld.py`.
1. To create the Lambda function deployment package, save `greengrassHelloWorld.py` and the `greengrasssdk` folder to a compressed `zip` file named `hello_world_python_lambda.zip`. The `py` file and `greengrasssdk` folder must be in the root of the directory.
![\[Screenshot showing zipped contents of hello_word_python_lambda.zip.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-017.png)
On UNIX-like systems (including the Mac terminal), you can use the following command to package the file and folder:
```
zip -r hello_world_python_lambda.zip greengrasssdk greengrassHelloWorld.py
```
**Note**
Depending on your distribution, you might need to install `zip` first (for example, by running `sudo apt-get install zip`). The installation command for your distribution might be different.
Now you're ready to create your Lambda function and upload the deployment package.
1. Open the Lambda console and choose **Create function**.
1. Choose **Author from scratch**.
1. Name your function **Greengrass\$1HelloWorld**, and set the remaining fields as follows:
+ For **Runtime**, choose **Python 3.7**.
+ For **Permissions**, keep the default setting. This creates an execution role that grants basic Lambda permissions. This role isn't used by AWS IoT Greengrass.
Choose **Create function**.
1. Upload your Lambda function deployment package:
1. On the **Code** tab, under **Code source**, choose **Upload from**. From the dropdown, choose **.zip file**.
![\[The Upload from dropdown with .zip file highlighted.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/lra-console/upload-deployment-package.png)
1. Choose **Upload**, and then choose your `hello_world_python_lambda.zip` deployment package. Then, choose **Save**.
1. On the **Code** tab for the function, under **Runtime settings**, choose **Edit**, and then enter the following values.
+ For **Runtime**, choose **Python 3.7**.
+ For **Handler**, enter **greengrassHelloWorld.function\$1handler**
![\[The "Runtime settings" section with the "Runtime" field set to "Python 3.7" and the "Handler" field set to "greengrassHelloWorld.function_handler".\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-023-2.png)
1. Choose **Save**.
**Note**
The **Test** button on the AWS Lambda console doesn't work with this function. The AWS IoT Greengrass Core SDK doesn't contain modules that are required to run your Greengrass Lambda functions independently in the AWS Lambda console. These modules (for example, `greengrass_common`) are supplied to the functions after they are deployed to your Greengrass core.
1. Publish the Lambda function:
1. From the **Actions** menu at the top of the page, choose **Publish new version**.
![\[Screenshot of the Actions menu with Publish new version highlighted.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-026.png)
1. For **Version description**, enter **First version**, and then choose **Publish**.
![\[Screenshot with the Version description field set to First version and the Publish button highlighted.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-027.png)
1. Create an [alias](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) for the Lambda function [version](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html):
**Note**
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.
1. From the **Actions** menu at the top of the page, choose **Create alias**.
![\[Screenshot of the Actions menu set to Create alias.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-028.png)
1. Name the alias **GG\$1HelloWorld**, set the version to **1** (which corresponds to the version that you just published), and then choose **Save**.
**Note**
AWS IoT Greengrass doesn't support Lambda aliases for **\$1LATEST** versions.
![\[Screenshot of Create a new alias with the Name field set to GG_HelloWorld, and the Version field set to 1.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-029.png)
# Configure the Lambda function for AWS IoT Greengrass
You are now ready to configure your Lambda function for AWS IoT Greengrass.
In this step, you:
+ Use the AWS IoT console to add the Lambda function to your Greengrass group.
+ Configure group-specific settings for the Lambda function.
+ Add a subscription to the group that allows the Lambda function to publish MQTT messages to AWS IoT.
+ Configure local log settings for the group.
1. In the AWS IoT console navigation pane, under **Manage**, expand **Greengrass devices**, and then choose **Groups (V1)**.
1. Under **Greengrass groups**, choose the group that you created in [Module 2](module2.md).
1. On the group configuration page, choose the **Lambda functions** tab, and then scroll down to the **My Lambda functions** section and choose **Add Lambda function**.
1. Select the name of the Lambda function you created in the previous step (**Greengrass\$1HelloWorld**, not the alias name).
1. For the version, choose **Alias: GG\$1HelloWorld**.
1. In the **Lambda function configuration** section, make the following changes:
+ Set the **System user and group** to **Use group default**.
+ Set the **Lambda function containerization** to **Use group default**.
+ Set **Timeout** to 25 seconds. This Lambda function sleeps for 5 seconds before each invocation.
+ For **Pinned**, choose **True**.
**Note**
A *long-lived* (or *pinned*) Lambda function starts automatically after AWS IoT Greengrass starts and keeps running in its own container. This is in contrast to an *on-demand* Lambda function, which starts when invoked and stops when there are no tasks left to run. For more information, see [Lifecycle configuration for Greengrass Lambda functions](lambda-functions.md#lambda-lifecycle).
1. Choose **Add Lambda function** to save your changes. For information about Lambda function properties, see [Controlling execution of Greengrass Lambda functions by using group-specific configuration](lambda-group-config.md).
Next, create a subscription that allows the Lambda function to send [MQTT](http://mqtt.org/) messages to AWS IoT Core.
A Greengrass Lambda function can exchange MQTT messages with:
+ [Devices](what-is-gg.md#greengrass-devices) in the Greengrass group.
+ [Connectors](connectors.md) in the group.
+ Other Lambda functions in the group.
+ AWS IoT Core.
+ The local shadow service. For more information, see [Module 5: Interacting with device shadows](module5.md).
The group uses subscriptions to control how these entities can communicate with each other. Subscriptions provide predictable interactions and a layer of security.
A subscription consists of a source, target, and topic. The source is the originator of the message. The target is the destination of the message. The topic allows you to filter the data that is sent from the source to the target. The source or target can be a Greengrass device, Lambda function, connector, device shadow, or AWS IoT Core.
**Note**
A subscription is directed in the sense that messages flow in a specific direction: from the source to the target. To allow two-way communication, you must set up two subscriptions.
**Note**
Currently, the subscription topic filter does not allow more than a single `+` character in a topic. The topic filter only allows a single `#` character at the end of a topic.
The `Greengrass_HelloWorld` Lambda function sends messages only to the `hello/world` topic in AWS IoT Core, so you only need to create one subscription from the Lambda function to AWS IoT Core. You create this in the next step.
1. On the group configuration page, choose the **Subscriptions** tab, and then choose **Add subscription**.
For an example that shows you how to create a subscription using the AWS CLI, see [create-subscription-definition](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/greengrass/create-subscription-definition.html) in the *AWS CLI Command Reference*.
1. In the **Source type**, choose **Lambda function** and, for the **Source**, choose **Greengrass\$1HelloWorld**.
1. For the **Target type**, choose **Service** and, for the **Target** select **IoT Cloud**.
1. For **Topic filter**, enter **hello/world**, and then choose **Create subscription**.
1. Configure the group's logging settings. For this tutorial, you configure AWS IoT Greengrass system components and user-defined Lambda functions to write logs to the file system of the core device.
1. On the group configuration page, choose the **Logs** tab.
1. In the **Local logs configuration** section, choose **Edit**.
1. On the **Edit local logs configuration** dialog box, keep the default values for both log levels and storage sizes, and then choose **Save**.
You can use logs to troubleshoot any issues you might encounter when running this tutorial. When troubleshooting issues, you can temporarily change the logging level to **Debug**. For more information, see [Accessing file system logs](greengrass-logs-overview.md#gg-logs-local).
1. If the Java 8 runtime isn't installed on your core device, you must install it or disable stream manager.
**Note**
This tutorial doesn't use stream manager, but it does use the **Default Group creation** workflow that enables stream manager by default. If stream manager is enabled but Java 8 isn't installed, the group deployment fails. For more information, see the [stream manager requirements](stream-manager.md#stream-manager-requirements).
To disable stream manager:
1. On the group settings page, choose the **Lambda functions** tab.
1. Under the **System Lambda functions** section, select **Stream manager** and choose **Edit**.
1. Choose **Disable**, and then choose **Save**.
# Deploy cloud configurations to a Greengrass core device
1. Make sure that your Greengrass core device is connected to the internet. For example, try successfully navigating to a webpage.
1. Make sure that the Greengrass daemon is running on your core device. In your core device terminal, run the following commands to check whether the daemon is running and start it, if needed.
1. To check whether the daemon is running:
```
ps aux | grep -E 'greengrass.*daemon'
```
If the output contains a `root` entry for `/greengrass/ggc/packages/1.11.6/bin/daemon`, then the daemon is running.
1. To start the daemon:
```
cd /greengrass/ggc/core/
sudo ./greengrassd start
```
Now you're ready to deploy the Lambda function and subscription configurations to your Greengrass core device.
1. In the AWS IoT console navigation pane, under **Manage**, expand **Greengrass devices**, and then choose **Groups (V1)**.
1. Under **Greengrass groups**, choose the group that you created in [Module 2](module2.md).
1. On the group configuration page, choose **Deploy**.
1. On the **Lambda functions** tab, in the **System Lambda functions** section, choose **IP detector**.
1. Choose **Edit** and select **Automatically detect and override MQTT broker endpoints**. This enables devices to automatically acquire connectivity information for the core, such as IP address, DNS, and port number. Automatic detection is recommended, but AWS IoT Greengrass also supports manually specified endpoints. You're only prompted for the discovery method the first time that the group is deployed.
The first deployment might take a few minutes. When the deployment is complete, you should see **Successfully completed** in the **Status** column on the **Deployments** page:
**Note**
The deployment status is also displayed below the group's name on the page header.
For troubleshooting help, see [Troubleshooting AWS IoT Greengrass](gg-troubleshooting.md).
# Verify the Lambda function is running on the core device
1. From the navigation pane of the [AWS IoT console](https://console.aws.amazon.com/iot/), under **Test**, choose **MQTT test client**.
1. Choose the **Subscribe to topic** tab.
1. Enter **hello/world** into the **Topic filter** and expand the **Additional configuration**.
1. Enter the information listed in each of the following fields:
+ For **Quality of Service**, choose **0**.
+ For **MQTT payload display**, choose **Display payloads as strings**.
1. Choose **Subscribe**.
Assuming the Lambda function is running on your device, it publishes messages similar to the following to the `hello/world` topic:
![\[Screenshot of message sent to the hello/world topic with message highlighted.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-045.png)
Although the Lambda function continues to send MQTT messages to the `hello/world` topic, don't stop the AWS IoT Greengrass daemon. The remaining modules are written with the assumption that it's running.
You can delete the function and subscription from the group:
+ On the groups configuration page, under the **Lambda functions** tab, select the Lambda function you want to remove and choose **Remove**.
+ On the groups configuration page, under the **Subscriptions** tab, choose the subscription, and then choose **Delete**.
The function and subscription are removed from the core during the next group deployment.