Shadow manager - AWS IoT Greengrass

Shadow manager

The shadow manager component (aws.greengrass.ShadowManager) enables the local shadow service on your core device. The local shadow service allows components to use interprocess communication to interact with local shadows. The shadow manager component manages the storage of local shadow documents, and also handles synchronization of local shadow states with the AWS IoT Device Shadow service.

For more information about how Greengrass core devices can interact with shadows, see Interact with device shadows.

Versions

This component has the following versions:

  • 2.2.x

  • 2.1.x

  • 2.0.x

Type

This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

This component uses the same log file as the Greengrass nucleus. For more information, see Monitor AWS IoT Greengrass logs.

For more information, see Component types.

Operating system

This component can be installed on core devices that run the following operating systems:

  • Linux

  • Windows

Requirements

This component has the following requirements:

  • (Optional) To sync shadows to the AWS IoT Device Shadow service, the Greengrass core device's AWS IoT policy must allow the following AWS IoT Core shadow policy actions:

    • iot:GetThingShadow

    • iot:UpdateThingShadow

    • iot:DeleteThingShadow

    For more information about these AWS IoT Core policies, see AWS IoT Core policy actions in the AWS IoT Developer Guide.

    For more information about the minimal AWS IoT policy, see Minimal AWS IoT policy for AWS IoT Greengrass V2 core devices

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

2.2.1

The following table lists the dependencies for version 2.2.1 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.2.0 <2.8.0 Soft
2.1.1 and 2.2.0

The following table lists the dependencies for versions 2.1.1 and 2.2.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.2.0 <2.7.0 Soft
2.0.5 - 2.1.0

The following table lists the dependencies for versions 2.0.5 through 2.1.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.2.0 <2.6.0 Soft
2.0.3 and 2.0.4

The following table lists the dependencies for versions 2.0.3 and 2.0.4 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.2.0 <2.5.0 Soft
2.0.1 and 2.0.2

The following table lists the dependencies for versions 2.0.1 and 2.0.2 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.2.0 <2.4.0 Soft
2.0.0

The following table lists the dependencies for version 2.0.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.2.0 <2.3.0 Soft

For more information about component dependencies, see the component recipe reference.

Configuration

This component provides the following configuration parameters that you can customize when you deploy the component.

2.2.x
strategy

(Optional) The strategy that this component uses to sync shadows between AWS IoT Core and the core device.

This object contains the following information.

type

(Optional) The type of strategy that this component uses to sync shadows between AWS IoT Core and the core device. Choose from the following options:

  • realTime – Sync shadows with AWS IoT Core each time a shadow update occurs.

  • periodic – Sync shadows with AWS IoT Core on a regular interval that you specify with the delay configuration parameter.

Default: realTime

delay

(Optional) The interval in seconds where this component syncs shadows with AWS IoT Core, when you specify the periodic sync strategy.

Note

This parameter is required if you specify the periodic sync strategy.

synchronize

(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.

Note

You must create a configuration update with this property to sync shadows with the AWS Cloud.

This object contains the following information.

coreThing

(Optional) The core device shadows to sync. This object contains the following information.

classic

(Optional) By default, the shadow manager syncs the local state of the classic shadow for your core device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to false.

Default: true

namedShadows

(Optional) The list of named core device shadows to sync.

Warning

The AWS IoT Greengrass service uses the AWSManagedGreengrassV2Deployment named shadow to manage deployments that target individual core devices. This named shadow is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named shadow.

shadowDocuments

(Optional) The list of additional device shadows to sync. Each object in this list contains the following information.

thingName

The thing name of the device for which to sync shadows.

classic

(Optional) If you don't want to sync the classic device shadow for the thingName device, set this to false.

Default: true

namedShadows

(Optional) The list of named device shadows that you want to sync.

direction

(Optional) The direction to sync shadows between the local shadow service and the AWS Cloud. You can configure this option to reduce bandwidth and connections to the AWS Cloud. Choose from the following options:

  • betweenDeviceAndCloud – Synchronize shadows between the local shadow service and the AWS Cloud.

  • deviceToCloud – Send shadow updates from the local shadow service to the AWS Cloud, and ignore shadow updates from the AWS Cloud.

  • cloudToDevice – Receive shadow updates from the AWS Cloud, and don't send shadow updates from the local shadow service to the AWS Cloud.

Default: BETWEEN_DEVICE_AND_CLOUD

rateLimits

(Optional) The settings that determine the rate limits for shadow service requests.

This object contains the following information.

maxOutboundSyncUpdatesPerSecond

(Optional) The maximum number of sync requests per second that the device transmits.

Default: 100 requests/second

maxTotalLocalRequestsRate

(Optional) The maximum number of local IPC requests per second that are sent to the core device.

Default: 200 requests/second

maxLocalRequestsPerSecondPerThing

(Optional) The maximum number of local IPC requests per second that are sent for each connected IoT thing.

Default: 20 requests/second for each thing

Note

These rate limits parameters define the maximum number of requests per second for the local shadow service. The maximum number of requests per second for the AWS IoT Device Shadow service depends on your AWS Region. For more information, see the limits for the AWS IoT Device Shadow Service API in the Amazon Web Services General Reference.

shadowDocumentSizeLimitBytes

(Optional) The maximum allowed size of each JSON state document for local shadows.

If you increase this value, you must also increase the resource limit for the JSON state document for cloud shadows. For more information, see the limits for the AWS IoT Device Shadow Service API in the Amazon Web Services General Reference.

Default: 8192 bytes

Maximum: 30720 bytes

Example: Configuration merge update

The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.

{ "strategy": { "type": "periodic", "delay": 300 }, "synchronize": { "coreThing": { "classic": true, "namedShadows": [ "MyCoreShadowA", "MyCoreShadowB" ] }, "shadowDocuments": [ { "thingName": "MyDevice1", "classic": false, "namedShadows": [ "MyShadowA", "MyShadowB" ] }, { "thingName": "MyDevice2", "classic": true, "namedShadows": [] } ], "direction": "betweenDeviceAndCloud" }, "rateLimits": { "maxOutboundSyncUpdatesPerSecond": 100, "maxTotalLocalRequestsRate": 200, "maxLocalRequestsPerSecondPerThing": 20 }, "shadowDocumentSizeLimitBytes": 8192 }
2.1.x
strategy

(Optional) The strategy that this component uses to sync shadows between AWS IoT Core and the core device.

This object contains the following information.

type

(Optional) The type of strategy that this component uses to sync shadows between AWS IoT Core and the core device. Choose from the following options:

  • realTime – Sync shadows with AWS IoT Core each time a shadow update occurs.

  • periodic – Sync shadows with AWS IoT Core on a regular interval that you specify with the delay configuration parameter.

Default: realTime

delay

(Optional) The interval in seconds where this component syncs shadows with AWS IoT Core, when you specify the periodic sync strategy.

Note

This parameter is required if you specify the periodic sync strategy.

synchronize

(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.

Note

You must create a configuration update with this property to sync shadows with the AWS Cloud.

This object contains the following information.

coreThing

(Optional) The core device shadows to sync. This object contains the following information.

classic

(Optional) By default, the shadow manager syncs the local state of the classic shadow for your core device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to false.

Default: true

namedShadows

(Optional) The list of named core device shadows to sync.

Warning

The AWS IoT Greengrass service uses the AWSManagedGreengrassV2Deployment named shadow to manage deployments that target individual core devices. This named shadow is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named shadow.

shadowDocuments

(Optional) The list of additional device shadows to sync. Each object in this list contains the following information.

thingName

The thing name of the device for which to sync shadows.

classic

(Optional) If you don't want to sync the classic device shadow for the thingName device, set this to false.

Default: true

namedShadows

(Optional) The list of named device shadows that you want to sync.

rateLimits

(Optional) The settings that determine the rate limits for shadow service requests.

This object contains the following information.

maxOutboundSyncUpdatesPerSecond

(Optional) The maximum number of sync requests per second that the device transmits.

Default: 100 requests/second

maxTotalLocalRequestsRate

(Optional) The maximum number of local IPC requests per second that are sent to the core device.

Default: 200 requests/second

maxLocalRequestsPerSecondPerThing

(Optional) The maximum number of local IPC requests per second that are sent for each connected IoT thing.

Default: 20 requests/second for each thing

Note

These rate limits parameters define the maximum number of requests per second for the local shadow service. The maximum number of requests per second for the AWS IoT Device Shadow service depends on your AWS Region. For more information, see the limits for the AWS IoT Device Shadow Service API in the Amazon Web Services General Reference.

shadowDocumentSizeLimitBytes

(Optional) The maximum allowed size of each JSON state document for local shadows.

If you increase this value, you must also increase the resource limit for the JSON state document for cloud shadows. For more information, see the limits for the AWS IoT Device Shadow Service API in the Amazon Web Services General Reference.

Default: 8192 bytes

Maximum: 30720 bytes

Example: Configuration merge update

The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.

{ "strategy": { "type": "periodic", "delay": 300 }, "synchronize": { "coreThing": { "classic": true, "namedShadows": [ "MyCoreShadowA", "MyCoreShadowB" ] }, "shadowDocuments": [ { "thingName": "MyDevice1", "classic": false, "namedShadows": [ "MyShadowA", "MyShadowB" ] }, { "thingName": "MyDevice2", "classic": true, "namedShadows": [] } ] }, "rateLimits": { "maxOutboundSyncUpdatesPerSecond": 100, "maxTotalLocalRequestsRate": 200, "maxLocalRequestsPerSecondPerThing": 20 }, "shadowDocumentSizeLimitBytes": 8192 }
2.0.x
synchronize

(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.

Note

You must create a configuration update with this property to sync shadows with the AWS Cloud.

This object contains the following information.

coreThing

(Optional) The core device shadows to sync. This object contains the following information.

classic

(Optional) By default, the shadow manager syncs the local state of the classic shadow for your core device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to false.

Default: true

namedShadows

(Optional) The list of named core device shadows to sync.

Warning

The AWS IoT Greengrass service uses the AWSManagedGreengrassV2Deployment named shadow to manage deployments that target individual core devices. This named shadow is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named shadow.

shadowDocuments

(Optional) The list of additional device shadows to sync. Each object in this list contains the following information.

thingName

The thing name of the device for which to sync shadows.

classic

(Optional) If you don't want to sync the classic device shadow for the thingName device, set this to false.

Default: true

namedShadows

(Optional) The list of named device shadows that you want to sync.

rateLimits

(Optional) The settings that determine the rate limits for shadow service requests.

This object contains the following information.

maxOutboundSyncUpdatesPerSecond

(Optional) The maximum number of sync requests per second that the device transmits.

Default: 100 requests/second

maxTotalLocalRequestsRate

(Optional) The maximum number of local IPC requests per second that are sent to the core device.

Default: 200 requests/second

maxLocalRequestsPerSecondPerThing

(Optional) The maximum number of local IPC requests per second that are sent for each connected IoT thing.

Default: 20 requests/second for each thing

Note

These rate limits parameters define the maximum number of requests per second for the local shadow service. The maximum number of requests per second for the AWS IoT Device Shadow service depends on your AWS Region. For more information, see the limits for the AWS IoT Device Shadow Service API in the Amazon Web Services General Reference.

shadowDocumentSizeLimitBytes

(Optional) The maximum allowed size of each JSON state document for local shadows.

If you increase this value, you must also increase the resource limit for the JSON state document for cloud shadows. For more information, see the limits for the AWS IoT Device Shadow Service API in the Amazon Web Services General Reference.

Default: 8192 bytes

Maximum: 30720 bytes

Example: Configuration merge update

The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.

{ "synchronize": { "coreThing": { "classic": true, "namedShadows": [ "MyCoreShadowA", "MyCoreShadowB" ] }, "shadowDocuments": [ { "thingName": "MyDevice1", "classic": false, "namedShadows": [ "MyShadowA", "MyShadowB" ] }, { "thingName": "MyDevice2", "classic": true, "namedShadows": [] } ] }, "rateLimits": { "maxOutboundSyncUpdatesPerSecond": 100, "maxTotalLocalRequestsRate": 200, "maxLocalRequestsPerSecondPerThing": 20 }, "shadowDocumentSizeLimitBytes": 8192 }

Local log file

This component uses the same log file as the Greengrass nucleus component.

Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log

To view this component's logs

  • Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root folder.

    Linux
    sudo tail -f /greengrass/v2/logs/greengrass.log
    Windows (PowerShell)
    Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait

Changelog

The following table describes the changes in each version of the component.

Version

Changes

2.2.1

Version updated for Greengrass nucleus version 2.7.0 release.

2.2.0

New features
  • Adds support for the local shadow service over the local publish/subscribe interface. You can now communicate with the local publish/subscribe message broker on shadow MQTT topics to get, update, and delete shadows on the core device. This feature enables you to connect client devices to the local shadow service by using the MQTT bridge to relay messages on shadow topics between client devices and the local publish/subscribe interface.

    This feature requires v2.6.0 or later of the Greengrass nucleus component. To connect client devices to the local shadow service, you must also use v2.2.0 or later of the MQTT bridge component.

  • Adds the direction option that you can configure to customize the direction to sync shadows between the local shadow service and the AWS Cloud. You can configure this option to reduce bandwidth and connections to the AWS Cloud.

2.1.1

Bug fixes and improvements
  • Fixes an issue where the maximum depth in the desired and reported sections of the JSON device shadow state document was 4 levels instead of 5 levels.

  • Version updated for Greengrass nucleus version 2.6.0 release.

2.1.0

New features
  • Adds support for periodic shadow synchronization intervals, so you can configure the core device to reduce bandwidth usage and charges.

2.0.6

This version contains bug fixes and improvements.

2.0.5

Version updated for Greengrass nucleus version 2.5.0 release.

2.0.4

Bug fixes and improvements
  • Fixes an issue that caused shadow manager to delete newly created versions of any shadow that was previously deleted.

  • Updates the DeleteThingShadow IPC operation to increment the shadow version when called.

2.0.3

Version updated for Greengrass nucleus version 2.4.0 release.

2.0.2

Bug fixes and improvements
  • Fixed an issue that caused shadow manager to not recognize the delta property when syncing shadow states from AWS IoT Core.

  • Fixed an issue that sometimes caused sync requests for a shadow to be merged incorrectly.

2.0.1

Version updated for Greengrass nucleus version 2.3.0 release.

2.0.0

Initial version.