Interact with shadows in components - Amazon IoT Greengrass
Retrieve and modify shadow statesReact to shadow state changes
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).

Interact with shadows in components

You can develop custom components, including Lambda function components, that use the local shadow service to read and modify local shadow documents and client device shadow documents.

Custom components interact with the local shadow service using the Amazon IoT Greengrass Core IPC libraries in the Amazon IoT Device SDK. The shadow manager component enables the local shadow service on your core device.

To deploy the shadow manager component to a Greengrass core device, create a deployment that includes the aws.greengrass.ShadowManager component.

Note

By default, deploying the shadow manager component enables local shadow operations only. To enable Amazon IoT Greengrass to sync shadow state information for core device shadows or any shadows for client devices to the corresponding cloud shadow documents in Amazon IoT Core, you must create a configuration update for the shadow manager component that includes the synchronize parameter. For more information, see Sync local device shadows with Amazon IoT Core.

Retrieve and modify shadow states

The shadow IPC operations retrieve and update state information in local shadow documents. The shadow manager component handles the storage of these shadow documents on your core device.

To modify local shadow states

  1. Add authorization policies to the recipe for your custom component to allow the component to receive messages on local shadow topics.

    For example authorization policies, see Local shadow IPC authorization policy examples.

  2. Use the shadow IPC operations to retrieve and modify shadow state information. For more information about using shadow IPC operations in component code, see Interact with local shadows.

Note

To enable a core device to interact with client device shadows, you must also configure and deploy the MQTT bridge component. For more information, see Enable shadow manager to communicate with client devices.

React to shadow state changes

Greengrass components use the local publish/subscribe interface to communicate on a core device. To enable a custom component to react to shadow state changes, you can subscribe to the local publish/subscribe topics. This allows the component to receive messages on the local shadow topics, and then act on those messages.

Local shadow topics use the same format as the Amazon IoT device shadow MQTT topics. For more information about shadow topics, see Device Shadow MQTT topics in the Amazon IoT Developer Guide.

To react to local shadow state changes

  1. Add access control policies to the recipe for your custom component to allow the component to receive messages on local shadow topics.

    For example authorization policies, see Local shadow IPC authorization policy examples.

  2. To initiate a custom action in a component, use SubscribeToTopic IPC operations to subscribe to the shadow topics on which you want to receive messages. For more information about using local publish/subscribe IPC operations in component code, see Publish/subscribe local messages.

  3. To invoke a Lambda function, use the event source configuration to provide the name of the shadow topic and specify that it's a local publish/subscribe topic. For information about creating Lambda function components, see Run Amazon Lambda functions.

Note

To enable a core device to interact with client device shadows, you must also configure and deploy the MQTT bridge component. For more information, see Enable shadow manager to communicate with client devices.