Develop Amazon IoT Greengrass components - Amazon IoT Greengrass
Component lifecycleComponent types
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).

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.

    You can define recipes in JSON or YAML format.

  • 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

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 the RUNNING 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 the ERRORED state three times without a successful run, the component becomes BROKEN.

  • 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.