Develop Amazon IoT Greengrass components
You can develop and test components on your Greengrass core device. As a result, you can create and iterate your Amazon IoT Greengrass software without interacting with the Amazon Web Services Cloud. When you finish a version of your component, you can upload it to Amazon IoT Greengrass in the cloud, so you and your team can deploy the component to other devices in your fleet. For more information about how to deploy components, see Deploy Amazon IoT Greengrass components to devices.
Every component is composed of a recipe and artifacts.
-
Recipes
Every component contains a recipe file, which defines its metadata. The recipe also specifies the component's configuration parameters, component dependencies, lifecycle, and platform compatibility. The component lifecycle defines the commands that install, run, and shut down the component. For more information, see Amazon IoT Greengrass component recipe reference.
-
Artifacts
Components can have any number of artifacts, which are component binaries. Artifacts can include scripts, compiled code, static resources, and any other files that a component consumes. Components can also consume artifacts from component dependencies.
Amazon IoT Greengrass provides pre-built components that you can use in your applications and deploy to your devices. For example, you can use the stream manager component to upload data to various Amazon services, or you can use the CloudWatch metrics component to publish custom metrics to Amazon CloudWatch. For more information, see Amazon-provided components.
Amazon IoT Greengrass curates an index of Greengrass components, called the Greengrass Software Catalog. This catalog tracks Greengrass components that are developed by the Greengrass community. From this catalog, you can download, modify, and deploy components to create your Greengrass applications. For more information, see Community components.
The Amazon IoT Greengrass Core software runs components as the system user and group, such as
ggc_user
and ggc_group
, that you configure on the core device. This
means that components have the permissions of that system user. If you use a system user without
a home directory, then components can't use run commands or code that use a home directory. This
means that you can't use the pip install some-library --user
command to install
Python packages for example. If you followed the getting started
tutorial to set up your core device, then your system user doesn't have a home
directory. For more information about how to configure the user and group that run components,
see Configure the user that runs components.
Note
Amazon IoT Greengrass uses semantic versions for components. Semantic versions follow a
major.minor.patch number
system. For example, version 1.0.0
represents the first major release for a
component. For more information, see the semantic version
specification
Topics
- Component lifecycle
- Component types
- Create Amazon IoT Greengrass components
- Test Amazon IoT Greengrass components with local deployments
- Publish components to deploy to your core devices
- Interact with Amazon services
- Run a Docker container
- Amazon IoT Greengrass component recipe reference
- Component environment variable reference
Component lifecycle
The component lifecycle defines the stages that the Amazon IoT Greengrass Core software
uses to install and run components. Each stage defines a script and other information that
specifies how the component behaves. For example, when you install a component, the Amazon IoT Greengrass Core
software runs the Install
lifecycle script for that component. Components on core
devices have the following lifecycle states:
-
NEW
– The component's recipe and artifacts are loaded on the core device, but the component isn't installed. After a component enters this state, it runs its install script. -
INSTALLED
– The component is installed on the core device. The component enters this state after it runs its install script. -
STARTING
– The component is starting on the core device. The component enters this state when it runs its startup script. If the startup succeeds, the component enters theRUNNING
state. -
RUNNING
– The component is running on the core device. The component enters this state when it runs its run script or when it has active background processes from its startup script. -
FINISHED
– The component ran successfully and completed its run. -
STOPPING
– The component is stopping. The component enters this state when it runs its shutdown script. -
ERRORED
– The component encountered an error. When the component enters this state, it runs its recover script. Then, the component restarts to try returning to normal use. If the component enters theERRORED
state three times without a successful run, the component becomesBROKEN
. -
BROKEN
– The component encountered errors multiple times and can't recover. You must deploy the component again to fix it.
Component types
The component type specifies how the Amazon IoT Greengrass Core software runs the component. Components can have the following types:
-
Nucleus (
aws.greengrass.nucleus
)The Greengrass nucleus is the component that provides the minimum functionality of the Amazon IoT Greengrass Core software. For more information, see Greengrass nucleus.
-
Plugin (
aws.greengrass.plugin
)The Greengrass nucleus runs a plugin component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change the version of a plugin component on a core device. To install and run plugin components, you must configure the Greengrass nucleus to run as a system service. For more information, see Configure the Greengrass nucleus as a system service.
Several components that are provided by Amazon are plugin components, which enables them to interface directly with the Greengrass nucleus. Plugin components use the same log file as the Greengrass nucleus. For more information, see Monitor Amazon IoT Greengrass logs.
-
Generic (
aws.greengrass.generic
)The Greengrass nucleus runs a generic component's lifecycle scripts, if the component defines a lifecycle.
This type is the default type for custom components.
-
Lambda (
aws.greengrass.lambda
)The Greengrass nucleus runs a Lambda function component using the Lambda launcher component.
When you create a component from a Lambda function, the component has this type. For more information, see Run Amazon Lambda functions.
Note
We don't recommend that you specify the component type in a recipe. Amazon IoT Greengrass sets the type for you when you create a component.